StatusCode Class Reference

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

#include </builds/gaudi/Gaudi/GaudiKernel/include/GaudiKernel/StatusCode.h>

Collaboration diagram for StatusCode:

Classes
struct	Category
	The category assigned to a StatusCode. More...

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

Public Member Functions
	StatusCode ()=default
	Default constructor.
template<typename T> requires ( is_StatusCode_enum<T>::value )
	StatusCode (T sc) noexcept
	Constructor from enum type (allowing implicit conversion)
	StatusCode (code_t code, const StatusCode::Category &cat) noexcept
	Constructor from code_t and category (explicit conversion only)
	StatusCode (code_t code) noexcept
	Constructor from code_t in the default category (explicit conversion only)
	StatusCode (const StatusCode &rhs) noexcept=default
	Copy constructor.
	StatusCode (StatusCode &&rhs) noexcept=default
	Move constructor.
	~StatusCode ()=default
	Destructor.
StatusCode &	operator= (const StatusCode &rhs) noexcept=default
bool	isSuccess () const
bool	isFailure () const
bool	isRecoverable () const
	operator bool () const
	Shorthand for isSuccess()
code_t	getCode () const
	Retrieve value.
const StatusCode &	ignore () const
	Allow discarding a StatusCode without warning.
StatusCode &	ignore ()
template<typename F, typename... ARGS>
StatusCode	andThen (F &&f, ARGS &&... args) const
	Chain code blocks making the execution conditional a success result.
template<typename F, typename... ARGS>
StatusCode	orElse (F &&f, ARGS &&... args) const
	Chain code blocks making the execution conditional a failure result.
const StatusCode &	orThrow (std::string_view message, std::string_view tag) const
	Throw a GaudiException in case of failures.
const StatusCode &	orThrow (std::string_view tag="") const
	Throw a GaudiException in case of failures.
const StatusCode::Category &	getCategory () const
	Retrieve category.
std::string	message () const
	Description (or name) of StatusCode value.
StatusCode &	operator&= (const StatusCode &rhs)
	Ternary logic operator with RECOVERABLE being the "third" state.
StatusCode &	operator|= (const StatusCode &rhs)
	Ternary logic operator with RECOVERABLE being the "third" state.

Static Public Member Functions
static const Category &	default_category () noexcept
	Default Gaudi StatusCode category.

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.
void	i_doThrow (std::string_view message, std::string_view tag) const
	Helper function to avoid circular dependency between GaudiException.h and StatusCode.h.
template<typename... ARGS, std::invocable< ARGS... > F>
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.

Private Attributes
const Category *	m_cat { &default_category() }
	The status code category.
code_t	m_code { static_cast<code_t>( ErrorCode::SUCCESS ) }
	The status code value.

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.
bool	operator!= (const StatusCode &lhs, const StatusCode &rhs)
bool	operator< (const StatusCode &lhs, const StatusCode &rhs)
	Comparison (values are grouped by category first)
StatusCode	operator& (StatusCode lhs, const StatusCode &rhs)
	Ternary AND operator.
StatusCode	operator| (StatusCode lhs, const StatusCode &rhs)
	Ternary OR operator.
bool &	operator&= (bool &lhs, const StatusCode &sc)
	Boolean AND assignment operator.
bool &	operator|= (bool &lhs, const StatusCode &sc)
	Boolean OR assignment operator.

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

Member Typedef Documentation

code_t

typedef unsigned long StatusCode::code_t

type of StatusCode value

Definition at line 66 of file StatusCode.h.

Member Enumeration Documentation

ErrorCode

enum class StatusCode::ErrorCode : code_t

strong

Enumerator
FAILURE
SUCCESS
RECOVERABLE

Definition at line 68 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>
requires ( is_StatusCode_enum<T>::value )

StatusCode::StatusCode ( T sc )

inlinenoexcept

Constructor from enum type (allowing implicit conversion)

Definition at line 109 of file StatusCode.h.

: StatusCode{ static_cast<StatusCode::code_t>( sc ), is_StatusCode_enum<T>::instance } {}

StatusCode() [3/6]

StatusCode::StatusCode ( code_t code, const StatusCode::Category & cat )

inlineexplicitnoexcept

Constructor from code_t and category (explicit conversion only)

Definition at line 112 of file StatusCode.h.

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

StatusCode() [4/6]

StatusCode::StatusCode ( code_t code )

inlineexplicitnoexcept

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

Definition at line 115 of file StatusCode.h.

: StatusCode( code, default_category() ) {}

StatusCode() [5/6]

StatusCode::StatusCode ( const StatusCode & rhs )

defaultnoexcept

Copy constructor.

StatusCode() [6/6]

StatusCode::StatusCode ( StatusCode && rhs )

defaultnoexcept

Move constructor.

~StatusCode()

StatusCode::~StatusCode ( )

default

Destructor.

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

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

default_category()

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

inlinestaticnoexcept

Default Gaudi StatusCode category.

Definition at line 310 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 320 of file StatusCode.h.

                                                           {
  auto r = isSuccess() ? ErrorCode::SUCCESS : ( isRecoverable() ? ErrorCode::RECOVERABLE : ErrorCode::FAILURE );
  return r;
}

getCategory()

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

inline

Retrieve category.

Definition at line 221 of file StatusCode.h.

{ return *m_cat; }

getCode()

code_t StatusCode::getCode ( ) const

inline

Retrieve value.

Definition at line 136 of file StatusCode.h.

{ return m_code; }

i_doThrow()

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

private

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

Definition at line 49 of file StatusCode.cpp.

                                                                             {
  throw GaudiException{ std::string{ message }, std::string{ tag }, *this };
}

i_invoke()

template<typename... ARGS, std::invocable< ARGS... > F>

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 269 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]

StatusCode & StatusCode::ignore ( )

inline

Definition at line 140 of file StatusCode.h.

{ return *this; }

ignore() [2/2]

const StatusCode & StatusCode::ignore ( ) const

inline

Allow discarding a StatusCode without warning.

Definition at line 139 of file StatusCode.h.

{ return *this; }

isFailure()

bool StatusCode::isFailure ( ) const

inline

Definition at line 129 of file StatusCode.h.

{ return !isSuccess(); }

isRecoverable()

bool StatusCode::isRecoverable ( ) const

inline

Definition at line 318 of file StatusCode.h.

{ return m_cat->isRecoverable( m_code ); }

isSuccess()

bool StatusCode::isSuccess ( ) const

inline

Definition at line 314 of file StatusCode.h.

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

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

operator bool()

StatusCode::operator bool ( ) const

inlineexplicit

Shorthand for isSuccess()

Definition at line 133 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 332 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];
  return *this;
}

operator=()

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

defaultnoexcept

operator|=()

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

inline

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

Definition at line 342 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];
  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 185 of file StatusCode.h.

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

orThrow() [1/2]

const StatusCode & StatusCode::orThrow ( std::string_view message, std::string_view 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 206 of file StatusCode.h.

                                                                                {
    if ( isFailure() ) i_doThrow( message, tag );
    return *this;
  }

orThrow() [2/2]

const StatusCode & StatusCode::orThrow ( std::string_view tag = "" ) const

inline

Throw a GaudiException in case of failures.

See above, but in this case the message is not specified explicitly, but taken from message()

Definition at line 215 of file StatusCode.h.

                                                             {
    if ( isFailure() ) i_doThrow( message(), tag ); // make sure `message()` is only called on error path
    return *this;
  }

Friends And Related Symbol Documentation

operator!=

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

friend

Definition at line 235 of file StatusCode.h.

{ return !( lhs == rhs ); }

operator&

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

friend

Ternary AND operator.

Definition at line 247 of file StatusCode.h.

{ return lhs &= rhs; }

operator&=

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

friend

Boolean AND assignment operator.

Definition at line 253 of file StatusCode.h.

{ return lhs &= sc.isSuccess(); }

operator<

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

friend

Comparison (values are grouped by category first)

Definition at line 238 of file StatusCode.h.

                                                                        {
    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 226 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 325 of file StatusCode.h.

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

operator|

StatusCode operator| ( StatusCode lhs, const StatusCode & rhs )

friend

Ternary OR operator.

Definition at line 250 of file StatusCode.h.

{ return lhs |= rhs; }

operator|=

bool & operator|= ( bool & lhs, const StatusCode & sc )

friend

Boolean OR assignment operator.

Definition at line 256 of file StatusCode.h.

{ return lhs |= sc.isSuccess(); }

Member Data Documentation

FAILURE

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

staticconstexpr

Definition at line 100 of file StatusCode.h.

m_cat

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

private

The status code category.

Definition at line 259 of file StatusCode.h.

{ &default_category() };                        

m_code

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

private

The status code value.

Definition at line 260 of file StatusCode.h.

{ static_cast<code_t>( ErrorCode::SUCCESS ) }; 

RECOVERABLE

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

staticconstexpr

Definition at line 101 of file StatusCode.h.

SUCCESS

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

staticconstexpr

Definition at line 99 of file StatusCode.h.

---

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

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