StatusCode Class Reference

This class is used for returning status codes from appropriate routines. More...

#include <GaudiKernel/StatusCode.h>

Collaboration diagram for StatusCode:

Classes
class	Category
	The category assigned to a StatusCode. More...
class	ScopedDisableChecking
	Simple RAII class to ignore unchecked StatusCode instances in a scope. More...

Public Types
enum	ErrorCode : code_t { ErrorCode::FAILURE = 0, ErrorCode::SUCCESS = 1, ErrorCode::RECOVERABLE = 2 }
typedef unsigned long	code_t
	type of StatusCode value More...

Public Member Functions
	StatusCode ()=default
	Default constructor. More...
template<typename T , typename = typename std::enable_if<is_StatusCode_enum<T>::value>::type>
	StatusCode (T sc, bool checked=false) noexcept
	Constructor from enum type (allowing implicit conversion) More...
	StatusCode (code_t code, const StatusCode::Category &cat=default_category(), bool checked=false) noexcept
	Constructor from code_t in the default category (explicit conversion only) More...
	StatusCode (code_t code, bool checked) noexcept
	Constructor from code_t and category (explicit conversion only) More...
	StatusCode (const StatusCode &rhs) noexcept
	Copy constructor. More...
	StatusCode (StatusCode &&rhs) noexcept
	Move constructor. More...
	~StatusCode ()
	Destructor. More...
StatusCode &	operator= (const StatusCode &rhs) noexcept
bool	isSuccess () const
bool	isFailure () const
bool	isRecoverable () const
	operator bool () const
	Shorthand for isSuccess() More...
code_t	getCode () const
	Retrieve value ("checks" the StatusCode) More...
const StatusCode &	setChecked (bool checked=true) const
	Check/uncheck StatusCode. More...
StatusCode &	setChecked (bool checked=true)
const StatusCode &	ignore () const
	Ignore/check StatusCode. More...
StatusCode &	ignore ()
bool	checked () const
	Has the StatusCode been checked? More...
const StatusCode::Category &	getCategory () const
	Retrieve category (does not "check" the StatusCode) More...
std::string	message () const
	Description (or name) of StatusCode value. More...
StatusCode &	operator&= (const StatusCode &rhs)
	Ternary logic operator with RECOVERABLE being the "third" state. More...
StatusCode &	operator|= (const StatusCode &rhs)
	Ternary logic operator with RECOVERABLE being the "third" state. More...

Static Public Member Functions
static const Category &	default_category () noexcept
	Default Gaudi StatusCode category. More...
static GAUDI_API void	enableChecking ()
static GAUDI_API void	disableChecking ()
static GAUDI_API bool	checkingEnabled ()

Static Public Attributes
constexpr static const auto	SUCCESS = ErrorCode::SUCCESS
constexpr static const auto	FAILURE = ErrorCode::FAILURE
constexpr static const auto	RECOVERABLE = ErrorCode::RECOVERABLE

Private Member Functions
ErrorCode	default_value () const
	Project onto the default StatusCode values. More...
void	check ()
	Do StatusCode check. More...

Private Attributes
const Category *	m_cat {&default_category()}
	The status code category. More...
code_t	m_code {static_cast<code_t>( ErrorCode::SUCCESS )}
	The status code value. More...
bool	m_checked {false}
	If the StatusCode has been checked. More...

Static Private Attributes
static bool	s_checking
	Global flag to control if StatusCode need to be checked. More...

Friends
std::ostream &	operator<< (std::ostream &s, const StatusCode &sc)
bool	operator== (const StatusCode &lhs, const StatusCode &rhs)
	Check if StatusCode value and category are the same. More...
bool	operator!= (const StatusCode &lhs, const StatusCode &rhs)
bool	operator< (const StatusCode &lhs, const StatusCode &rhs)
	Comparison (values are grouped by category first) More...

Detailed Description

This class is used for returning status codes from appropriate routines.

A StatusCode is comprised of an (integer) value and a category (similar to std::error_code). By default StatusCodes are created within a default StatusCode::Category, which defines the isSuccess(), isFailure() and isRecoverable() behaviour depending on the value of the StatusCode. This behaviour can be modified by defining a custom StatusCode::Category and overriding the respective methods.

To define a new StatusCode::Category, do the following:

• Define an enum class with the values of the StatusCode
• Register the enum with STATUSCODE_ENUM_DECL( MyEnum )
• Derive your category from StatusCode::Category and implement/override the relevant methods
• Register the new category with STATUSCODE_ENUM_IMPL( MyEnum, MyCategory ) in a .cpp file

Combining StatusCodes

• The bitwise logic operators (&, |, &=, |=) can be used to combine StatusCodes and follows three-valued (ternary) logic with RECOVERABLE being the third state. No short-circuiting is applied:

  StatusCode sc = sc1 & sc2;
  sc |= sc3;

• The boolean logic operators (&&, ||) perform regular two-valued logic only considering success/failure. The usual short-circuiting applies:

  bool b = sc1 && sc2;

Note

The StatusCode values 0 and 1 are considered FAILURE/SUCCESS for all categories, i.e.

• operator==() and operator!=() ignore the category for these two values
• isSuccess() and isFailure() cannot be overridden for these two values

Remarks

See https://akrzemi1.wordpress.com/2017/07/12/your-own-error-code for details on the underlying design

Definition at line 50 of file StatusCode.h.

Member Typedef Documentation

typedef unsigned long StatusCode::code_t

type of StatusCode value

Definition at line 52 of file StatusCode.h.

Member Enumeration Documentation

enum StatusCode::ErrorCode : code_t

strong

Enumerator
FAILURE
SUCCESS
RECOVERABLE

Definition at line 54 of file StatusCode.h.

: code_t { FAILURE = 0, SUCCESS = 1, RECOVERABLE = 2 };

Constructor & Destructor Documentation

StatusCode::StatusCode ( )

default

Default constructor.

template<typename T , typename = typename std::enable_if<is_StatusCode_enum<T>::value>::type>

StatusCode::StatusCode ( T  sc, bool  checked = false  )

inlinenoexcept

Constructor from enum type (allowing implicit conversion)

Definition at line 94 of file StatusCode.h.

                                                    {
    *this     = StatusCode( static_cast<StatusCode::code_t>( sc ), is_StatusCode_enum<T>::instance );
    m_checked = checked;
  }

StatusCode::StatusCode ( code_t  code, const StatusCode::Category &  cat = default_category(), bool  checked = false  )

inlineexplicitnoexcept

Constructor from code_t in the default category (explicit conversion only)

Definition at line 100 of file StatusCode.h.

      : m_cat( &cat ), m_code( code ), m_checked( checked ) {}

StatusCode::StatusCode ( code_t  code, bool  checked  )

inlineexplicitnoexcept

Constructor from code_t and category (explicit conversion only)

Definition at line 105 of file StatusCode.h.

: StatusCode( code, default_category(), checked ) {}

StatusCode::StatusCode ( const StatusCode &  rhs )

inlinenoexcept

Copy constructor.

Definition at line 108 of file StatusCode.h.

                                               : m_cat( rhs.m_cat ), m_code( rhs.m_code ), m_checked( rhs.m_checked ) {
    rhs.m_checked = true;
  }

StatusCode::StatusCode ( StatusCode &&  rhs )

inlinenoexcept

Move constructor.

Definition at line 113 of file StatusCode.h.

                                          : m_cat( rhs.m_cat ), m_code( rhs.m_code ), m_checked( rhs.m_checked ) {
    rhs.m_checked = true;
  }

StatusCode::~StatusCode ( )

inline

Destructor.

Definition at line 118 of file StatusCode.h.

                {
    if ( UNLIKELY( s_checking ) ) check();
  }

Member Function Documentation

void StatusCode::check ( )

private

Do StatusCode check.

Fix-Me:

: (MCl) use backTrace(std::string&, const int, const int) instead

Definition at line 48 of file StatusCode.cpp.

                       {

  if ( !m_checked && !GaudiException::s_proc &&
#if __cplusplus > 201402L // c++17
       !std::uncaught_exceptions()
#else
       !std::uncaught_exception()
#endif
  ) {

    auto msg = Gaudi::svcLocator()->as<IMessageSvc>();
    auto scs = Gaudi::svcLocator()->service<IStatusCodeSvc>( "StatusCodeSvc" );

    const size_t depth = 21;
    void*        addresses[depth];

    std::string lib, fnc;
    void*       addr = nullptr;
    if ( System::backTrace( addresses, depth ) ) {

      for ( size_t idx : {2, 3} ) {
        // When running address sanitizer builds with -fno-omit-frame-pointer
        // StatusCode::check() might appear as the function name, so skip.
        if ( System::getStackLevel( addresses[idx], addr, fnc, lib ) && fnc != "StatusCode::~StatusCode()" &&
             fnc != "StatusCode::check()" ) {
          if ( scs ) {
            scs->regFnc( fnc, lib );
          } else {
            MsgStream log( msg, "StatusCode" );
            log << MSG::WARNING << "Unchecked in " << fnc << " (" << lib << ")" << endmsg;
          }
          break;
        }
      }
    }
  }
}

bool StatusCode::checked ( ) const

inline

Has the StatusCode been checked?

Definition at line 163 of file StatusCode.h.

{ return m_checked; }

bool StatusCode::checkingEnabled ( )

static

Definition at line 46 of file StatusCode.cpp.

{ return s_checking; }

const StatusCode::Category & StatusCode::default_category ( )

inlinestaticnoexcept

Default Gaudi StatusCode category.

Definition at line 263 of file StatusCode.h.

                                                                       {
  return is_StatusCode_enum<StatusCode::ErrorCode>::instance;
}

StatusCode::ErrorCode StatusCode::default_value ( ) const

inlineprivate

Project onto the default StatusCode values.

Definition at line 277 of file StatusCode.h.

                                                           {
  bool save_checked = m_checked; // Preserve checked status
  auto r    = isSuccess() ? ErrorCode::SUCCESS : ( isRecoverable() ? ErrorCode::RECOVERABLE : ErrorCode::FAILURE );
  m_checked = save_checked;
  return r;
}

void StatusCode::disableChecking ( )

static

Definition at line 44 of file StatusCode.cpp.

{ s_checking = false; }

void StatusCode::enableChecking ( )

static

Definition at line 42 of file StatusCode.cpp.

{ s_checking = true; }

const StatusCode::Category& StatusCode::getCategory ( ) const

inline

Retrieve category (does not "check" the StatusCode)

Definition at line 166 of file StatusCode.h.

{ return *m_cat; }

code_t StatusCode::getCode ( ) const

inline

Retrieve value ("checks" the StatusCode)

Definition at line 137 of file StatusCode.h.

                         {
    m_checked = true;
    return m_code;
  }

const StatusCode& StatusCode::ignore ( ) const

inline

Ignore/check StatusCode.

Definition at line 153 of file StatusCode.h.

                                   {
    setChecked( true );
    return *this;
  }

StatusCode& StatusCode::ignore ( )

inline

Definition at line 157 of file StatusCode.h.

                       {
    setChecked( true );
    return *this;
  }

bool StatusCode::isFailure ( ) const

inline

Definition at line 130 of file StatusCode.h.

{ return !isSuccess(); }

bool StatusCode::isRecoverable ( ) const

inline

Definition at line 272 of file StatusCode.h.

                                            {
  m_checked = true;
  return m_cat->isRecoverable( m_code );
}

bool StatusCode::isSuccess ( ) const

inline

Definition at line 267 of file StatusCode.h.

                                        {
  m_checked = true;
  return ( m_code == static_cast<code_t>( ErrorCode::SUCCESS ) || m_cat->isSuccess( m_code ) );
}

std::string StatusCode::message ( ) const

inline

Description (or name) of StatusCode value.

Definition at line 169 of file StatusCode.h.

{ return getCategory().message( m_code ); }

StatusCode::operator bool ( ) const

inlineexplicit

Shorthand for isSuccess()

Definition at line 134 of file StatusCode.h.

{ return isSuccess(); }

StatusCode & StatusCode::operator&= ( const StatusCode &  rhs )

inline

Ternary logic operator with RECOVERABLE being the "third" state.

Definition at line 293 of file StatusCode.h.

                                                                 {
  // Ternary AND lookup matrix
  static constexpr StatusCode::code_t AND[3][3] = {{0, 0, 0}, {0, 1, 2}, {0, 2, 2}};

  StatusCode::code_t l = static_cast<StatusCode::code_t>( default_value() );
  StatusCode::code_t r = static_cast<StatusCode::code_t>( rhs.default_value() );
  m_code               = AND[l][r];
  rhs.m_checked        = true;
  return *this;
}

StatusCode& StatusCode::operator= ( const StatusCode &  rhs )

inlinenoexcept

Definition at line 122 of file StatusCode.h.

                                                          {
    m_cat     = rhs.m_cat;
    m_code    = rhs.m_code;
    m_checked = std::exchange( rhs.m_checked, true );
    return *this;
  }

StatusCode & StatusCode::operator|= ( const StatusCode &  rhs )

inline

Ternary logic operator with RECOVERABLE being the "third" state.

Definition at line 304 of file StatusCode.h.

                                                                 {
  // Ternary OR lookup matrix
  static constexpr StatusCode::code_t OR[3][3] = {{0, 1, 2}, {1, 1, 1}, {2, 1, 2}};

  StatusCode::code_t l = static_cast<StatusCode::code_t>( default_value() );
  StatusCode::code_t r = static_cast<StatusCode::code_t>( rhs.default_value() );
  m_code               = OR[l][r];
  rhs.m_checked        = true;
  return *this;
}

const StatusCode& StatusCode::setChecked ( bool  checked = true ) const

inline

Check/uncheck StatusCode.

Definition at line 143 of file StatusCode.h.

                                                            {
    m_checked = checked;
    return *this;
  }

StatusCode& StatusCode::setChecked ( bool  checked = true )

inline

Definition at line 147 of file StatusCode.h.

                                                {
    m_checked = checked;
    return *this;
  }

Friends And Related Function Documentation

bool operator!= ( const StatusCode &  lhs, const StatusCode &  rhs  )

friend

Definition at line 180 of file StatusCode.h.

{ return !( lhs == rhs ); }

bool operator< ( const StatusCode &  lhs, const StatusCode &  rhs  )

friend

Comparison (values are grouped by category first)

Definition at line 183 of file StatusCode.h.

                                                                        {
    lhs.m_checked = true;
    rhs.m_checked = true;
    return ( lhs.m_cat < rhs.m_cat || ( lhs.m_cat == rhs.m_cat && lhs.m_code < rhs.m_code ) );
  }

std::ostream& operator<< ( std::ostream &  s, const StatusCode &  sc  )

friend

Definition at line 171 of file StatusCode.h.

                                                                       {
    s << sc.message();
    return s;
  }

bool operator== ( const StatusCode &  lhs, const StatusCode &  rhs  )

friend

Check if StatusCode value and category are the same.

Note

For code values 0(FAILURE) and 1(SUCCESS) the category is ignored

e.g. sc==StatusCode::SUCCESS is equivalent to sc.isSuccess() for all categories

Definition at line 284 of file StatusCode.h.

                                                                       {
  lhs.m_checked = true;
  rhs.m_checked = true;
  return ( lhs.m_code == rhs.m_code ) &&
         ( lhs.m_code == static_cast<StatusCode::code_t>( StatusCode::ErrorCode::SUCCESS ) ||
           lhs.m_code == static_cast<StatusCode::code_t>( StatusCode::ErrorCode::FAILURE ) ||
           ( lhs.m_cat == rhs.m_cat ) );
}

Member Data Documentation

constexpr const StatusCode::ErrorCode StatusCode::FAILURE = ErrorCode::FAILURE

static

Definition at line 86 of file StatusCode.h.

const Category* StatusCode::m_cat {&default_category()}

private

The status code category.

Definition at line 224 of file StatusCode.h.

bool StatusCode::m_checked {false}

mutableprivate

If the StatusCode has been checked.

Definition at line 226 of file StatusCode.h.

code_t StatusCode::m_code {static_cast<code_t>( ErrorCode::SUCCESS )}

private

The status code value.

Definition at line 225 of file StatusCode.h.

constexpr const StatusCode::ErrorCode StatusCode::RECOVERABLE = ErrorCode::RECOVERABLE

static

Definition at line 87 of file StatusCode.h.

bool StatusCode::s_checking

staticprivate

Global flag to control if StatusCode need to be checked.

Definition at line 227 of file StatusCode.h.

constexpr const StatusCode::ErrorCode StatusCode::SUCCESS = ErrorCode::SUCCESS

static

Definition at line 85 of file StatusCode.h.

---

The documentation for this class was generated from the following files:

• GaudiKernel/GaudiKernel/StatusCode.h
• GaudiKernel/src/Lib/StatusCode.cpp