Helpers for checking error return status codes and reporting errors. More...

#include "GaudiKernel/StatusCode.h"
#include "GaudiKernel/MsgStream.h"
#include "GaudiKernel/IMessageSvc.h"
#include "boost/preprocessor/facilities/overload.hpp"
#include <string>
#include <atomic>

Include dependency graph for Control/AthenaKernel/AthenaKernel/errorcheck.h:

Classes
class	errorcheck::ReportMessage
	Helper class to use to report a message. More...

Namespaces
	errorcheck

Macros
#define	ERRORCHECK_FNAME ""

#define	ATLAS_PACKAGE_NAME nullptr

#define	ERRORCHECK_ARGS __LINE__, __FILE__, ERRORCHECK_FNAME, ATLAS_PACKAGE_NAME

#define	REPORT_ERROR_WITH_CONTEXT(SC, CONTEXT_NAME)
	Report an error, with an explicitly specified context name. More...

#define	REPORT_MESSAGE_WITH_CONTEXT(LVL, CONTEXT_NAME) errorcheck::ReportMessage (LVL, ERRORCHECK_ARGS, CONTEXT_NAME).msgstream()
	Report a message, with an explicitly specified context name. More...

#define	REPORT_ERROR(SC) REPORT_ERROR_WITH_CONTEXT(SC, errorcheck::context_name (this))
	Report an error. More...

#define	REPORT_MESSAGE(LVL) REPORT_MESSAGE_WITH_CONTEXT(LVL, errorcheck::context_name (this))
	Report a message. More...

#define	CHECK_FAILED(EXP, CONTEXT_NAME, SC, RET)
	Internal macro, used when a CHECK macro detects a failure. More...

#define	CHECK_WITH_CONTEXT(...) BOOST_PP_OVERLOAD(CHECK_WITH_CONTEXT_, __VA_ARGS__)(__VA_ARGS__)
	Evaluate an expression and check for errors, with an explicitly specified context name. More...

#define	CHECK_WITH_CONTEXT_2(EXP, CONTEXT_NAME)

#define	CHECK_WITH_CONTEXT_3(EXP, CONTEXT_NAME, RET)

#define	CHECK(...) BOOST_PP_OVERLOAD(CHECK_, __VA_ARGS__)(__VA_ARGS__)
	Evaluate an expression and check for errors. More...

#define	CHECK_1(EXP) CHECK_WITH_CONTEXT(EXP, errorcheck::context_name(this))

#define	CHECK_2(EXP, RET) CHECK_WITH_CONTEXT(EXP, errorcheck::context_name(this), RET)

#define	CHECK_CODE_WITH_CONTEXT(EXP, CONTEXT_NAME, CODE)
	Evaluate an expression and check for errors, with an explicitly specified context name. More...

#define	CHECK_CODE(EXP, CODE) CHECK_CODE_WITH_CONTEXT(EXP, errorcheck::context_name(this), CODE)
	Evaluate an expression and check for errors. More...

#define	CHECK_RECOVERABLE_WITH_CONTEXT(EXP, CONTEXT_NAME) CHECK_CODE_WITH_CONTEXT(EXP, CONTEXT_NAME, StatusCode::RECOVERABLE)
	Evaluate an expression and check for errors, with an explicitly specified context name. More...

#define	CHECK_RECOVERABLE(EXP) CHECK_RECOVERABLE_WITH_CONTEXT(EXP, errorcheck::context_name(this))
	Evaluate an expression and check for errors. More...

#define	CHECK_FATAL_WITH_CONTEXT(EXP, CONTEXT_NAME) CHECK_CODE_WITH_CONTEXT(EXP, CONTEXT_NAME, StatusCode::FAILURE)
	Evaluate an expression and check for errors, with an explicitly specified context name. More...

#define	CHECK_FATAL(EXP) CHECK_FATAL_WITH_CONTEXT(EXP, errorcheck::context_name(this))
	Evaluate an expression and check for errors. More...

Functions
std::string	errorcheck::context_name (const INamedInterface *context)
	Return the context name from a context (`this`) pointer. More...

std::string	errorcheck::context_name (const void *context)
	Return the context name from a context (`this`) pointer. More...

Detailed Description

Helpers for checking error return status codes and reporting errors.

Author: scott snyder snyde.nosp@m.r@bn.nosp@m.l.gov

Date: Jan, 2006 A typical sequence of code for calling something in Atlas that returns a StatusCode looks something like this:

StatusCode sc = something();
if (! sc.isSuccess() ) {
  log << "Some error message" << endmsg;
  return sc;
}

This has several undesirable properties. First, it is overly verbose. 80% of the code in this example is devoted to error handling; if there are many of these, it becomes difficult to read what the code is actually doing.

Second, there is no standardization of the error messages produced, and they are sometimes difficult to trace back to the actual offending source code.

Third, code like this typically gets written by cut-and-paste, which is notoriously error-prone.

This header defines some helpers to address these issues.

For the simple case, you can use the macro CHECK. This macro encapsulates the actions shown in the example above; it could be rewritten as

CHECK( something() );

The error message produced by this will contain the text of the expression that failed, the failed StatusCode, the source file and line, the name of the containing function, and the algorithm/tool/service name. Note that in order to get this last name, the macro uses the this pointer; this means that this macro cannot be used in contexts where this is not available. In this case, use the macro CHECK_WITH_CONTEXT, which allows an explicit specification of the context name:

CHECK_WITH_CONTEXT( something(), "algname" );

In some cases, a simple check of the StatusCode is not enough and CHECK cannot be used. One can still avail oneself of the standardized error reporting provided here with the macro REPORT_ERROR, which takes a StatusCode as an argument. Additional text can be added with the output streaming operator, as for MsgStream. (No need to use endmsg.)

StatusCode sc = something();
if ( ! sc.isSuccess() && ! failure_is_ok ) {
  REPORT_ERROR (sc) << "something()";
  return sc;
}

This will report the same kind of error as CHECK would.

CHECK will return the failing status code to the caller and log the appropriate type of error message. If you need to control what gets returned to the caller, you can use CHECK_RECOVERABLE and CHECK_FATAL (and the corresponding _WITH_CONTEXT) versions. If these macros detect a failure, they always return a RECOVERABLE or FATAL status to the caller, respectively. In addition, CHECK_CODE and CHECK_CODE_WITH_CONTEXT may be used to return an arbitrary status code to the caller.

Like CHECK, REPORT_ERROR requires that this be available. If this is not the case, then as before there is also a macro REPORT_ERROR_WITH_CONTEXT that takes the context name explicitly:

StatusCode sc = something();
if ( ! sc.isSuccess() && ! failure_is_ok ) {
  REPORT_ERROR_WITH_CONTEXT (sc, "algname") << "something()";
  return sc;
}

In addition, there are REPORT_MESSAGE and REPORT_MESSAGE_WITH_CONTEXT macros. These do not take a StatusCode argument, but do take a logging level argument, so you can emit messages other than errors. Example:

REPORT_MESSAGE (MSG::INFO) << "Something happened."

In the case where you want to change the source line, file, function, etc., from what's provided by default, you can instantiate an instance of errorcheck::ReportMessage directly. This may also be used if you need to use multiple statements to generate the output message. The message will be issued when then object is destroyed. Example:

{
  errorcheck::ReportMessage msg (MSG::INFO, ERRORCHECK_ARGS, "context");
  msg << "testing ";
  for (int i=1; i<=3; i++)
    msg << i << " ";
}

Definition in file Control/AthenaKernel/AthenaKernel/errorcheck.h.

Macro Definition Documentation

◆ ATLAS_PACKAGE_NAME

#define ATLAS_PACKAGE_NAME nullptr

Definition at line 319 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ CHECK

#define CHECK ( ... ) BOOST_PP_OVERLOAD(CHECK_, __VA_ARGS__)(__VA_ARGS__)

Evaluate an expression and check for errors.

this must be available to get the context name.

Parameters

EXP	The expression to evaluate.
RET	(optional) return value different from EXP

This macro will evaluate EXP, which should return a StatusCode. If the status is not successful, then an error message will be produced, and the failing StatusCode (or RET) will be returned to the caller.

Definition at line 423 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ CHECK_1

#define CHECK_1 ( EXP ) CHECK_WITH_CONTEXT(EXP, errorcheck::context_name(this))

Definition at line 426 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ CHECK_2

#define CHECK_2	(	EXP,
		RET
	)	CHECK_WITH_CONTEXT(EXP, errorcheck::context_name(this), RET)

Definition at line 427 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ CHECK_CODE

#define CHECK_CODE	(	EXP,
		CODE
	)	CHECK_CODE_WITH_CONTEXT(EXP, errorcheck::context_name(this), CODE)

Evaluate an expression and check for errors.

this must be available to get the context name.

Parameters

EXP	The expression to evaluate.
CODE	The status code to return on failure.

This macro will evaluate EXP, which should return a StatusCode. If the status is not successful, then an error message will be produced, and CODE will be returned to the caller.

Definition at line 461 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ CHECK_CODE_WITH_CONTEXT

#define CHECK_CODE_WITH_CONTEXT	(	EXP,
		CONTEXT_NAME,
		CODE
	)

Value:

    do {  \
    StatusCode sc__ = (EXP);                                          \
    if (! sc__.isSuccess()) {                                         \
      sc__ = CODE;                                                    \
      CHECK_FAILED(EXP, CONTEXT_NAME, sc__, sc__);                    \
    }                                                                 \
  } while (0)

Evaluate an expression and check for errors, with an explicitly specified context name.

Parameters

EXP	The expression to evaluate.
CONTEXT_NAME	The name of the current context.
CODE	The status code to return on failure.

This macro will evaluate EXP, which should return a StatusCode. If the status is not successful, then an error message will be produced, and CODE will be returned to the caller.

Definition at line 442 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ CHECK_FAILED

#define CHECK_FAILED	(	EXP,
		CONTEXT_NAME,
		SC,
		RET
	)

Value:

      do {     \
      errorcheck::ReportMessage (MSG::ERROR,              \
                                 ERRORCHECK_ARGS,         \
                                 CONTEXT_NAME,            \
                                 SC) . msgstream()        \
                                   << #EXP;               \
      return RET;                                         \
  } while(0)

Internal macro, used when a CHECK macro detects a failure.

Output an appropriate error message and return the given value

Definition at line 375 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ CHECK_FATAL

#define CHECK_FATAL ( EXP ) CHECK_FATAL_WITH_CONTEXT(EXP, errorcheck::context_name(this))

Evaluate an expression and check for errors.

this must be available to get the context name.

Parameters

EXP	The expression to evaluate.

This macro will evaluate EXP, which should return a StatusCode. If the status is not successful, then an error message will be produced, and FAILURE will be returned to the caller.

Definition at line 515 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ CHECK_FATAL_WITH_CONTEXT

#define CHECK_FATAL_WITH_CONTEXT	(	EXP,
		CONTEXT_NAME
	)	CHECK_CODE_WITH_CONTEXT(EXP, CONTEXT_NAME, StatusCode::FAILURE)

Evaluate an expression and check for errors, with an explicitly specified context name.

Parameters

EXP	The expression to evaluate.
CONTEXT_NAME	The name of the current context.

This macro will evaluate EXP, which should return a StatusCode. If the status is not successful, then an error message will be produced, and FAILURE will be returned to the caller.

Definition at line 502 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ CHECK_RECOVERABLE

#define CHECK_RECOVERABLE ( EXP ) CHECK_RECOVERABLE_WITH_CONTEXT(EXP, errorcheck::context_name(this))

Evaluate an expression and check for errors.

this must be available to get the context name.

Parameters

EXP	The expression to evaluate.

This macro will evaluate EXP, which should return a StatusCode. If the status is not successful, then an error message will be produced, and RECOVERABLE will be returned to the caller.

Definition at line 488 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ CHECK_RECOVERABLE_WITH_CONTEXT

#define CHECK_RECOVERABLE_WITH_CONTEXT	(	EXP,
		CONTEXT_NAME
	)	CHECK_CODE_WITH_CONTEXT(EXP, CONTEXT_NAME, StatusCode::RECOVERABLE)

Evaluate an expression and check for errors, with an explicitly specified context name.

Parameters

EXP	The expression to evaluate.
CONTEXT_NAME	The name of the current context.

This macro will evaluate EXP, which should return a StatusCode. If the status is not successful, then an error message will be produced, and RECOVERABLE will be returned to the caller.

Definition at line 475 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ CHECK_WITH_CONTEXT

#define CHECK_WITH_CONTEXT ( ... ) BOOST_PP_OVERLOAD(CHECK_WITH_CONTEXT_, __VA_ARGS__)(__VA_ARGS__)

Evaluate an expression and check for errors, with an explicitly specified context name.

Parameters

EXP	The expression to evaluate.
CONTEXT_NAME	The name of the current context.
RET	(optional) return value different from EXP

This macro will evaluate EXP, which should return a StatusCode. If the status is not successful, then an error message will be produced, and the failing StatusCode (or RET) will be returned to the caller.

Definition at line 397 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ CHECK_WITH_CONTEXT_2

#define CHECK_WITH_CONTEXT_2	(	EXP,
		CONTEXT_NAME
	)

Value:

    do {       \
    StatusCode sc__(EXP);                                  \
    if (! sc__.isSuccess())                                \
      CHECK_FAILED(EXP, CONTEXT_NAME, sc__, sc__);         \
  } while (0)

Definition at line 400 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ CHECK_WITH_CONTEXT_3

#define CHECK_WITH_CONTEXT_3	(	EXP,
		CONTEXT_NAME,
		RET
	)

Value:

    do {  \
    StatusCode sc__(EXP);                                  \
    if (! sc__.isSuccess())                                \
      CHECK_FAILED(EXP, CONTEXT_NAME, sc__, RET);          \
  } while (0)

Definition at line 406 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ ERRORCHECK_ARGS

#define ERRORCHECK_ARGS __LINE__, __FILE__, ERRORCHECK_FNAME, ATLAS_PACKAGE_NAME

Definition at line 324 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ ERRORCHECK_FNAME

#define ERRORCHECK_FNAME ""

Definition at line 314 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ REPORT_ERROR

#define REPORT_ERROR ( SC ) REPORT_ERROR_WITH_CONTEXT(SC, errorcheck::context_name (this))

Report an error.

this must be available to get the context name.

Parameters

SC	The `StatusCode`.

Additional text may be appended with the output stream operator.

Definition at line 356 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ REPORT_ERROR_WITH_CONTEXT

#define REPORT_ERROR_WITH_CONTEXT	(	SC,
		CONTEXT_NAME
	)

Value:

errorcheck::ReportMessage (MSG::ERROR, ERRORCHECK_ARGS, CONTEXT_NAME, SC) \

. msgstream()

Report an error, with an explicitly specified context name.

Parameters

SC	The `StatusCode`.
CONTEXT_NAME	The name of the current context.

Additional text may be appended with the output stream operator.

Definition at line 334 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ REPORT_MESSAGE

#define REPORT_MESSAGE ( LVL ) REPORT_MESSAGE_WITH_CONTEXT(LVL, errorcheck::context_name (this))

Report a message.

this must be available to get the context name.

Parameters

LVL	The error logging level.

Additional text may be appended with the output stream operator.

Definition at line 366 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

◆ REPORT_MESSAGE_WITH_CONTEXT

#define REPORT_MESSAGE_WITH_CONTEXT	(	LVL,
		CONTEXT_NAME
	)	errorcheck::ReportMessage (LVL, ERRORCHECK_ARGS, CONTEXT_NAME).msgstream()

Report a message, with an explicitly specified context name.

Parameters

LVL	The error logging level.
CONTEXT_NAME	The name of the current context.

Additional text may be appended with the output stream operator.

Definition at line 346 of file Control/AthenaKernel/AthenaKernel/errorcheck.h.

Classes

Namespaces

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ATLAS_PACKAGE_NAME

◆ CHECK

◆ CHECK_1

◆ CHECK_2

◆ CHECK_CODE

◆ CHECK_CODE_WITH_CONTEXT

◆ CHECK_FAILED

◆ CHECK_FATAL

◆ CHECK_FATAL_WITH_CONTEXT

◆ CHECK_RECOVERABLE

◆ CHECK_RECOVERABLE_WITH_CONTEXT

◆ CHECK_WITH_CONTEXT

◆ CHECK_WITH_CONTEXT_2

◆ CHECK_WITH_CONTEXT_3

◆ ERRORCHECK_ARGS

◆ ERRORCHECK_FNAME

◆ REPORT_ERROR

◆ REPORT_ERROR_WITH_CONTEXT

◆ REPORT_MESSAGE

◆ REPORT_MESSAGE_WITH_CONTEXT