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 = std::enable_if_t<is_StatusCode_enum<T>::value>>
	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 ()
template<typename F , typename... ARGS>
StatusCode	andThen (F &&f, ARGS &&... args) const
	Chain code blocks making the execution conditional a success result. More...
template<typename F , typename... ARGS>
StatusCode	orElse (F &&f, ARGS &&... args) const
	Chain code blocks making the execution conditional a failure result. More...
StatusCode	orThrow (std::string message, std::string tag) const
	Throw a GaudiException in case of failures. More...
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...
void	i_doThrow (std::string message, std::string tag) const
	Helper function to avoid circular dependency between GaudiException.h and StatusCode.h. More...
template<typename F , typename... ARGS, typename = std::enable_if_t<std::is_invocable_v<F, ARGS...>>>
StatusCode	i_invoke (F &&f, ARGS &&... args) const
	Helper to invoke a callable and return the resulting StatusCode or this, if the callable returns void. 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 61 of file StatusCode.h.

Member Typedef Documentation

code_t

typedef unsigned long StatusCode::code_t

type of StatusCode value

Definition at line 67 of file StatusCode.h.

Member Enumeration Documentation

ErrorCode

enum StatusCode::ErrorCode : code_t

strong

Enumerator
FAILURE
SUCCESS
RECOVERABLE

Definition at line 69 of file StatusCode.h.

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

Constructor & Destructor Documentation

StatusCode() [1/6]

StatusCode::StatusCode ( )

default

Default constructor.

StatusCode() [2/6]

template<typename T , typename = std::enable_if_t<is_StatusCode_enum<T>::value>>

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

inlinenoexcept

Constructor from enum type (allowing implicit conversion)

Definition at line 109 of file StatusCode.h.

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

StatusCode() [3/6]

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 115 of file StatusCode.h.

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

StatusCode() [4/6]

StatusCode::StatusCode ( code_t  code, bool  checked  )

inlineexplicitnoexcept

Constructor from code_t and category (explicit conversion only)

Definition at line 120 of file StatusCode.h.

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

StatusCode() [5/6]

StatusCode::StatusCode ( const StatusCode &  rhs )

inlinenoexcept

Copy constructor.

Definition at line 123 of file StatusCode.h.

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

StatusCode() [6/6]

StatusCode::StatusCode ( StatusCode &&  rhs )

inlinenoexcept

Move constructor.

Definition at line 128 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 ( )

inline

Destructor.

Definition at line 133 of file StatusCode.h.

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

Member Function Documentation

andThen()

template<typename F , typename... ARGS>

StatusCode StatusCode::andThen ( F &&  f, ARGS &&...  args  ) const

inline

Chain code blocks making the execution conditional a success result.

The chained execution stops on the first non-success StatusCode in the chain and returns it, or continues until the end and returns the last produced StatusCode.

For example:

StatusCode myFunction() {
  return subFunction()
      .andThen([]() {
        do_something();
      })
      .andThen(anotherFunction)
      .andThen([]() {
        if (is_special_case())
          return do_something_else();
        return StatusCode::SUCCESS;
      });
}

Definition at line 198 of file StatusCode.h.

                                                       {
    if ( isFailure() ) return *this;
    return i_invoke( std::forward<F>( f ), std::forward<ARGS>( args )... );
  }

check()

void StatusCode::check ( )

private

Do StatusCode check.

Fix-Me:

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

Definition at line 59 of file StatusCode.cpp.

                       {

  if ( !m_checked && !GaudiException::s_proc && !std::uncaught_exceptions() ) {

    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;
        }
      }
    }
  }
}

checked()

bool StatusCode::checked ( ) const

inline

Has the StatusCode been checked?

Definition at line 246 of file StatusCode.h.

{ return m_checked; }

checkingEnabled()

bool StatusCode::checkingEnabled ( )

static

Definition at line 57 of file StatusCode.cpp.

{ return s_checking; }

default_category()

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

inlinestaticnoexcept

Default Gaudi StatusCode category.

Definition at line 361 of file StatusCode.h.

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

default_value()

StatusCode::ErrorCode StatusCode::default_value ( ) const

inlineprivate

Project onto the default StatusCode values.

Definition at line 375 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;
}

disableChecking()

void StatusCode::disableChecking ( )

static

Definition at line 55 of file StatusCode.cpp.

{ s_checking = false; }

enableChecking()

void StatusCode::enableChecking ( )

static

Definition at line 53 of file StatusCode.cpp.

{ s_checking = true; }

getCategory()

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

inline

Retrieve category (does not "check" the StatusCode)

Definition at line 249 of file StatusCode.h.

{ return *m_cat; }

getCode()

code_t StatusCode::getCode ( ) const

inline

Retrieve value ("checks" the StatusCode)

Definition at line 152 of file StatusCode.h.

                         {
    m_checked = true;
    return m_code;
  }

i_doThrow()

void StatusCode::i_doThrow ( std::string  message, std::string  tag  ) const

private

Helper function to avoid circular dependency between GaudiException.h and StatusCode.h.

Definition at line 92 of file StatusCode.cpp.

                                                                   {
  throw GaudiException{std::move( message ), std::move( tag ), *this};
}

i_invoke()

template<typename F , typename... ARGS, typename = std::enable_if_t<std::is_invocable_v<F, ARGS...>>>

StatusCode StatusCode::i_invoke ( F &&  f, ARGS &&...  args  ) const

inlineprivate

Helper to invoke a callable and return the resulting StatusCode or this, if the callable returns void.

Definition at line 320 of file StatusCode.h.

                                                        {
    if constexpr ( std::is_invocable_r_v<StatusCode, F, ARGS...> ) {
      return std::invoke( std::forward<F>( f ), std::forward<ARGS>( args )... );
    } else {
      // static_assert( std::is_same_v<void,std::invoke_result_t<F,ARGS...>>); // how paranoid should this be?
      std::invoke( std::forward<F>( f ), std::forward<ARGS>( args )... );
      return *this;
    }
  }

ignore() [1/2]

const StatusCode& StatusCode::ignore ( ) const

inline

Ignore/check StatusCode.

Definition at line 168 of file StatusCode.h.

                                   {
    setChecked( true );
    return *this;
  }

ignore() [2/2]

StatusCode& StatusCode::ignore ( )

inline

Definition at line 172 of file StatusCode.h.

                       {
    setChecked( true );
    return *this;
  }

isFailure()

bool StatusCode::isFailure ( ) const

inline

Definition at line 145 of file StatusCode.h.

{ return !isSuccess(); }

isRecoverable()

bool StatusCode::isRecoverable ( ) const

inline

Definition at line 370 of file StatusCode.h.

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

isSuccess()

bool StatusCode::isSuccess ( ) const

inline

Definition at line 365 of file StatusCode.h.

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

message()

std::string StatusCode::message ( ) const

inline

Description (or name) of StatusCode value.

Definition at line 252 of file StatusCode.h.

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

operator bool()

StatusCode::operator bool ( ) const

inlineexplicit

Shorthand for isSuccess()

Definition at line 149 of file StatusCode.h.

{ return isSuccess(); }

operator&=()

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

inline

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

Definition at line 391 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;
}

operator=()

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

inlinenoexcept

Definition at line 137 of file StatusCode.h.

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

operator|=()

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

inline

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

Definition at line 402 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;
}

orElse()

template<typename F , typename... ARGS>

StatusCode StatusCode::orElse ( F &&  f, ARGS &&...  args  ) const

inline

Chain code blocks making the execution conditional a failure result.

Inverse of StatusCode::andThen(), the passed function gets invoked only if if the StatusCode is a failure, in which case it either pass it on or overrides it, If the StatusCode is a success, it is passed on.

For example:

StatusCode myFunction() {
  return subFunction()
      .andThen([]() {
        do_something();
      })
      .orElse(reportProblem);
}

Definition at line 220 of file StatusCode.h.

                                                      {
    if ( isSuccess() ) return *this;
    return i_invoke( std::forward<F>( f ), std::forward<ARGS>( args )... );
  }

orThrow()

StatusCode StatusCode::orThrow ( std::string  message, std::string  tag  ) const

inline

Throw a GaudiException in case of failures.

It can be chained with StatusCode::then, behaving as a pass-through for a success StatusCode, while for non-success a GaudiException is thrown, propagating the failure into the exception (using the StatusCode field of the exception).

For example:

void myFunction() {
  doSomething()
      .andThen( doSomethingElse )
      .orThrow( "some error", "myFunction" )
      .andThen( moreActions )
      .orThrow( "too bad, we were nearly there", "myFunction" );
}

Definition at line 241 of file StatusCode.h.

                                                               {
    return orElse( &StatusCode::i_doThrow, this, std::move( message ), std::move( tag ) );
  }

setChecked() [1/2]

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

inline

Check/uncheck StatusCode.

Definition at line 158 of file StatusCode.h.

                                                            {
    m_checked = checked;
    return *this;
  }

setChecked() [2/2]

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

inline

Definition at line 162 of file StatusCode.h.

                                                {
    m_checked = checked;
    return *this;
  }

Friends And Related Function Documentation

operator!=

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

friend

Definition at line 263 of file StatusCode.h.

{ return !( lhs == rhs ); }

operator<

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

friend

Comparison (values are grouped by category first)

Definition at line 266 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 ) );
  }

operator<<

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

friend

Definition at line 254 of file StatusCode.h.

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

operator==

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 382 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

FAILURE

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

static

Definition at line 101 of file StatusCode.h.

m_cat

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

private

The status code category.

Definition at line 307 of file StatusCode.h.

m_checked

bool StatusCode::m_checked {false}

mutableprivate

If the StatusCode has been checked.

Definition at line 309 of file StatusCode.h.

m_code

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

private

The status code value.

Definition at line 308 of file StatusCode.h.

RECOVERABLE

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

static

Definition at line 102 of file StatusCode.h.

s_checking

bool StatusCode::s_checking

staticprivate

Global flag to control if StatusCode need to be checked.

Definition at line 310 of file StatusCode.h.

SUCCESS

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

static

Definition at line 100 of file StatusCode.h.

---

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

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