macros for messaging and checking status codes More...

#include "CxxUtils/AthUnlikelyMacros.h"
#include <type_traits>
#include <AsgMessaging/MsgHelpers.h>
#include <AsgMessaging/StatusCode.h>
#include "CxxUtils/checker_macros.h"
#include "CxxUtils/normalizeFunctionName.h"
#include <atomic>

Include dependency graph for Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h:

Classes
struct	asg::CheckHelper< T >
	this is an internal traits class for status codes used by the ANA_CHECK* macros More...

struct	asg::CheckHelper< StatusCode >

struct	asg::CheckHelper< int >

struct	asg::CheckHelper< bool >

struct	asg::CheckHelper< T * >

Namespaces
	asg

	asg::detail

Macros
#define	ANA_MSG_HEADER(NAME)
	for standalone code this creates a new message category More...

#define	ASG_TOOLS_MSG_STREAM(NAME, TITLE) static thread_local MsgStream NAME {::asg::MsgHelpers::pkgMsgStream (TITLE)};

#define	ANA_MSG_SOURCE(NAME, TITLE)
	the source code part of ANA_MSG_SOURCE More...

#define	MSGSTREAM_FNAME ""

#define	ASG_TOOLS_MSGSTREAM_FNAME ""

#define	ASG_TOOLS_MSGSTREAM_PREFIX __FILE__ << ":" << __LINE__ << " (" << ASG_TOOLS_MSGSTREAM_FNAME << "): "
	Common prefix for the non-usual messages. More...

#define	ANA_MSG_LVL_SERIOUS(lvl, xmsg) msg( lvl ) << ASG_TOOLS_MSGSTREAM_PREFIX << xmsg << endmsg
	Macro used to print "serious" messages. More...

#define	ANA_MSG_LVL_NOCHK(lvl, xmsg) msg( lvl ) << xmsg << endmsg
	Macro used to print "regular" messages. More...

#define	ANA_MSG_LVL(lvl, xmsg)
	Macro used to print "protected" messages. More...

#define	ANA_MSG_VERBOSE(xmsg) ANA_MSG_LVL( MSG::VERBOSE, xmsg )
	Macro printing verbose messages. More...

#define	ANA_MSG_DEBUG(xmsg) ANA_MSG_LVL( MSG::DEBUG, xmsg )
	Macro printing debug messages. More...

#define	ANA_MSG_INFO(xmsg) ANA_MSG_LVL_NOCHK( MSG::INFO, xmsg )
	Macro printing info messages. More...

#define	ANA_MSG_WARNING(xmsg) ANA_MSG_LVL_NOCHK( MSG::WARNING, xmsg )
	Macro printing warning messages. More...

#define	ANA_MSG_ERROR(xmsg) ANA_MSG_LVL_SERIOUS( MSG::ERROR, xmsg )
	Macro printing error messages. More...

#define	ANA_MSG_FATAL(xmsg) ANA_MSG_LVL_SERIOUS( MSG::FATAL, xmsg )
	Macro printing fatal messages. More...

#define	ANA_MSG_ALWAYS(xmsg) ANA_MSG_LVL_NOCHK( MSG::ALWAYS, xmsg )
	Macro printing messages that should always appear. More...

#define	ANA_CHECK_SET_TYPE(TYPE) typedef TYPE AsgToolsCheckResultType;
	set the type for ANA_CHECK to report failures More...

#define	ANA_CHECK(EXP)
	check whether the given expression was successful More...

#define	ANA_CHECK_THROW(EXP)
	check whether the given expression was successful, throwing an exception on failure More...

Typedefs
typedef StatusCode	AsgToolsCheckResultType
	the return type used by ANA_CHECK More...

Functions
void	asg::detail::throw_check_fail (const std::string &str)
	throw an error for a failed check More...

Detailed Description

macros for messaging and checking status codes

Author: Nils Krumnack The core of this file is the macro ANA_CHECK. With it, a simple main might look like this:
int main ()

{

using namespace asg::msgUserCode;

ANA_CHECK_SET_TYPE (int);

ANA_CHECK (xAOD::Init());

return 0;

}

For the most part ANA_CHECK works just like ATH_CHECK, except it works for any kind of status code (and other things like bool). By default it will return a regular StatusCode object, but you can make it return a different type by specifying ANA_CHECK_SET_TYPE at the beginning of the function. In the example I use it to return an int instead.

Unfortunately the example will compile without that line, but it will not work as expected, i.e. when you return StatusCode::FAILURE it will convert to a value of 0, which the shell interprets as success. There is very little I can do about that from my side, as that is the intrinsic behavior of StatusCode itself. So it is very important that you remember to put that line in.

If you have a function that needs to indicate failure, but can't do so via a status code (e.g. a constructor) you can use the macro ANA_CHECK_THROW, which will throw an exception instead. However, where possible a status code is preferred.

If this is actually a unit test and you already had the chance to update it to GoogleTest, then there are also macros ASSERT_SUCCESS, ASSERT_FAILURE, EXPECT_SUCCESS and EXPECT_FAILURE defined that integrate with the GoogleTest reporting system.

The other thing needed in the above example is the using namespace line. This makes the standard messaging macros available in functions that are not member functions of a tool. Or almost: It works fine in RootCore, but for dual-use code you need to use ANA_MSG_* instead of ATH_MSG_* for sending messages yourself.

The msgUserCode category I used here is meant for things like main functions, etc. If you want to use this for other standalone functions you may consider making your own category (or indeed several). For that you put in one of your headers the line:

ANA_MSG_HEADER (msgMyCategory)

and then in one of the source files:

ANA_MSG_SOURCE (msgMyCategory, "MyCategory")

That way users get the chosen label as part of the messages. Plus they can actually set the message level separately for each category.

Definition in file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

Macro Definition Documentation

◆ ANA_CHECK

#define ANA_CHECK ( EXP )

Value:

  { const auto sc__ = EXP;                      \
    typedef typename std::decay<decltype(sc__)>::type scType__;     \
    if (ATH_UNLIKELY(!::asg::CheckHelper<scType__>::isSuccess (sc__))) { \
      ANA_MSG_ERROR ("Failed to call \"" << #EXP << "\"");      \
      return ::asg::CheckHelper<AsgToolsCheckResultType>::failureCode(); \
    } }

check whether the given expression was successful

This works like ATH_CHECK except it can handle all kinds of status codes, not just the regular ones. In particular the user can also set the type of the status code returned via ANA_CHECK_SET_TYPE

Definition at line 325 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_CHECK_SET_TYPE

#define ANA_CHECK_SET_TYPE ( TYPE ) typedef TYPE AsgToolsCheckResultType;

set the type for ANA_CHECK to report failures

normally ANA_CHECK will report failures via a StatusCode object, but this macro can be called inside a function to tell it to report via a different type.

Definition at line 315 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_CHECK_THROW

#define ANA_CHECK_THROW ( EXP )

Value:

  { const auto sc__ = EXP;                      \
    typedef typename std::decay<decltype(sc__)>::type scType__;     \
    if (ATH_UNLIKELY(!::asg::CheckHelper<scType__>::isSuccess (sc__))) { \
      std::ostringstream str;                       \
      str << #EXP;                          \
      ANA_MSG_ERROR ("Failed to call \"" << str.str() << "\", throwing exception"); \
      ::asg::detail::throw_check_fail (str.str());          \
    } }

check whether the given expression was successful, throwing an exception on failure

This works like ANA_CHECK except it throws when an error occurs. This is meant for situations in which we perform a check inside a function that does not return a StatusCode.

Definition at line 340 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_MSG_ALWAYS

#define ANA_MSG_ALWAYS ( xmsg ) ANA_MSG_LVL_NOCHK( MSG::ALWAYS, xmsg )

Macro printing messages that should always appear.

Definition at line 299 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_MSG_DEBUG

#define ANA_MSG_DEBUG ( xmsg ) ANA_MSG_LVL( MSG::DEBUG, xmsg )

Macro printing debug messages.

Definition at line 289 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_MSG_ERROR

#define ANA_MSG_ERROR ( xmsg ) ANA_MSG_LVL_SERIOUS( MSG::ERROR, xmsg )

Macro printing error messages.

Definition at line 295 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_MSG_FATAL

#define ANA_MSG_FATAL ( xmsg ) ANA_MSG_LVL_SERIOUS( MSG::FATAL, xmsg )

Macro printing fatal messages.

Definition at line 297 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_MSG_HEADER

#define ANA_MSG_HEADER ( NAME )

Value:

  namespace NAME {              \
  MsgStream& msg ();                \
  MsgStream& msg (MSG::Level level);        \
  bool msgLvl (MSG::Level lvl);         \
  void setMsgLevel (MSG::Level level); }

for standalone code this creates a new message category

The idea is that this provides a way to use the "standard" messaging macros in code that doesn't inherit from AsgTools. All you have to do is put

using namespace NAME;

at the beginning of a function and then you can use the messaging macros as if you were inside an AsgTool.

Or almost, in RootCore this works just fine, but in Athena ATH_MSG_* is defined slightly differently so that this won't work. To that end we are providing ANA_MSG_* macros that work with this, and in both RootCore and Athena. This way you can also use ATH_CHECK/ANA_CHECK in your code.

Besides allowing to use the standard messaging macros, you can also set the message level similar to how you'd do it for an AsgTool:

NAME::setMsgLevel (MSG::DEBUG);

See also: ANA_MSG_SOURCE

Definition at line 114 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_MSG_INFO

#define ANA_MSG_INFO ( xmsg ) ANA_MSG_LVL_NOCHK( MSG::INFO, xmsg )

Macro printing info messages.

Definition at line 291 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_MSG_LVL

#define ANA_MSG_LVL	(	lvl,
		xmsg
	)

Value:

   do {                                         \
      if( msg().level() <= lvl ) {             \
         ANA_MSG_LVL_NOCHK( lvl, xmsg );        \
      }                                         \
   } while( 0 )

Macro used to print "protected" messages.

Definition at line 279 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_MSG_LVL_NOCHK

#define ANA_MSG_LVL_NOCHK	(	lvl,
		xmsg
	)	msg( lvl ) << xmsg << endmsg

Macro used to print "regular" messages.

Definition at line 275 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_MSG_LVL_SERIOUS

#define ANA_MSG_LVL_SERIOUS	(	lvl,
		xmsg
	)	msg( lvl ) << ASG_TOOLS_MSGSTREAM_PREFIX << xmsg << endmsg

Macro used to print "serious" messages.

Definition at line 271 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_MSG_SOURCE

#define ANA_MSG_SOURCE	(	NAME,
		TITLE
	)

Value:

  namespace NAME                \
  {                     \
    MsgStream& msg ()               \
    {                                           \
      ASG_TOOLS_MSG_STREAM (result, TITLE); \
      return result;                \
    }                       \
                        \
    MsgStream& msg (MSG::Level level)       \
    {                       \
      return msg() << level;            \
    }                       \
                                                \
    bool msgLvl (MSG::Level lvl)                \
    {                       \
      if (msg().level() <= lvl)                 \
      {                                         \
        msg() << lvl;                           \
        return true;                            \
      } else                                    \
      {                                         \
        return false;                           \
      }                                         \
    }                       \
                        \
    void setMsgLevel (MSG::Level level)     \
    {                       \
      ::asg::MsgHelpers::setPkgMsgLevel (TITLE, level); \
    }                       \
  }

the source code part of ANA_MSG_SOURCE

For every message category that you introduce via ANA_MSG_SOURCE you have to add this in one of your source files, to add the source code needed for its function implementations

Definition at line 134 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_MSG_VERBOSE

#define ANA_MSG_VERBOSE ( xmsg ) ANA_MSG_LVL( MSG::VERBOSE, xmsg )

Macro printing verbose messages.

Definition at line 287 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ANA_MSG_WARNING

#define ANA_MSG_WARNING ( xmsg ) ANA_MSG_LVL_NOCHK( MSG::WARNING, xmsg )

Macro printing warning messages.

Definition at line 293 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ASG_TOOLS_MSG_STREAM

#define ASG_TOOLS_MSG_STREAM	(	NAME,
		TITLE
	)	static thread_local MsgStream NAME {::asg::MsgHelpers::pkgMsgStream (TITLE)};

Definition at line 125 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ASG_TOOLS_MSGSTREAM_FNAME

#define ASG_TOOLS_MSGSTREAM_FNAME ""

Definition at line 257 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ ASG_TOOLS_MSGSTREAM_PREFIX

#define ASG_TOOLS_MSGSTREAM_PREFIX __FILE__ << ":" << __LINE__ << " (" << ASG_TOOLS_MSGSTREAM_FNAME << "): "

Common prefix for the non-usual messages.

The idea is that a regular user usually only wants to see DEBUG, INFO and some WARNING messages. So those should be reasonably short. On the other hand serious warnings (ERROR, FATAL) messages should be as precise as possible to make debugging the issue easier.

Definition at line 267 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

◆ MSGSTREAM_FNAME

#define MSGSTREAM_FNAME ""

Definition at line 249 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

Typedef Documentation

◆ AsgToolsCheckResultType

typedef StatusCode AsgToolsCheckResultType

the return type used by ANA_CHECK

this defaults to the regular StatusCode, but can be overriden via ANA_CHECK_SET_TYPE

Definition at line 306 of file Control/AthToolSupport/AsgMessaging/AsgMessaging/MessageCheck.h.

Classes

Namespaces

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ANA_CHECK

◆ ANA_CHECK_SET_TYPE

◆ ANA_CHECK_THROW

◆ ANA_MSG_ALWAYS

◆ ANA_MSG_DEBUG

◆ ANA_MSG_ERROR

◆ ANA_MSG_FATAL

◆ ANA_MSG_HEADER

◆ ANA_MSG_INFO

◆ ANA_MSG_LVL

◆ ANA_MSG_LVL_NOCHK

◆ ANA_MSG_LVL_SERIOUS

◆ ANA_MSG_SOURCE

◆ ANA_MSG_VERBOSE

◆ ANA_MSG_WARNING

◆ ASG_TOOLS_MSG_STREAM

◆ ASG_TOOLS_MSGSTREAM_FNAME

◆ ASG_TOOLS_MSGSTREAM_PREFIX

◆ MSGSTREAM_FNAME

Typedef Documentation

◆ AsgToolsCheckResultType