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

Collaboration diagram for StatusCode:

Classes
class	Category

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) noexcept
	Constructor from enum type (allowing implicit conversion) More...

	StatusCode (code_t code, const StatusCode::Category &cat) noexcept
	Constructor from code_t and category (explicit conversion only) More...

	StatusCode (code_t code) noexcept
	Constructor from code_t in the default category (explicit conversion only) More...

	StatusCode (const StatusCode &rhs) noexcept=default
	Copy constructor. More...

	StatusCode (StatusCode &&rhs) noexcept=default
	Move constructor. More...

	~StatusCode ()=default
	Destructor. More...

StatusCode &	operator= (const StatusCode &rhs) noexcept=default

bool	isSuccess () const

bool	isFailure () const

bool	isRecoverable () const

	operator bool () const
	Shorthand for isSuccess() More...

code_t	getCode () const
	Retrieve value. More...

const StatusCode &	ignore () const
	Allow discarding a StatusCode without warning. 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...

const StatusCode &	orThrow (std::string_view message, std::string_view tag) const
	Throw a GaudiException in case of failures. More...

const StatusCode &	orThrow (std::string_view tag="") const
	Throw a GaudiException in case of failures. More...

const StatusCode::Category &	getCategory () const
	Retrieve category. 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 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	i_doThrow (std::string_view message, std::string_view 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...

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

StatusCode	operator& (StatusCode lhs, const StatusCode &rhs)
	Ternary AND operator. More...

StatusCode	operator\| (StatusCode lhs, const StatusCode &rhs)
	Ternary OR operator. More...

bool &	operator&= (bool &lhs, const StatusCode &sc)
	Boolean AND assignment operator. More...

bool &	operator\|= (bool &lhs, const StatusCode &sc)
	Boolean OR assignment operator. 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.

69 : 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 )

inlinenoexcept

Constructor from enum type (allowing implicit conversion)

Definition at line 109 of file StatusCode.h.

109 : 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.

112 : 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.

115 : 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.

221 { return *m_cat; }

◆ getCode()

code_t StatusCode::getCode ( ) const

inline

Retrieve value.

Definition at line 136 of file StatusCode.h.

136 { 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 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 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.

140 { 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.

139 { return *this; }

◆ isFailure()

bool StatusCode::isFailure ( ) const

inline

Definition at line 129 of file StatusCode.h.

129 { return !isSuccess(); }

◆ isRecoverable()

bool StatusCode::isRecoverable ( ) const

inline

Definition at line 318 of file StatusCode.h.

318 { 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.

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

◆ operator bool()

StatusCode::operator bool ( ) const

inlineexplicit

Shorthand for isSuccess()

Definition at line 133 of file StatusCode.h.

133 { 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 Function Documentation

◆ operator!=

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

friend

Definition at line 235 of file StatusCode.h.

235 { return !( lhs == rhs ); }

◆ operator&

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

friend

Ternary AND operator.

Definition at line 247 of file StatusCode.h.

247 { return lhs &= rhs; }

◆ operator&=

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

friend

Boolean AND assignment operator.

Definition at line 253 of file StatusCode.h.

253 { 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.

250 { return lhs |= rhs; }

◆ operator|=

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

friend

Boolean OR assignment operator.

Definition at line 256 of file StatusCode.h.

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

Member Data Documentation

◆ FAILURE

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

staticconstexpr

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

◆ RECOVERABLE

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

staticconstexpr

Definition at line 102 of file StatusCode.h.

◆ SUCCESS

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

staticconstexpr

Definition at line 100 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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ code_t

Member Enumeration Documentation

◆ ErrorCode

Constructor & Destructor Documentation

◆ StatusCode() [1/6]

◆ StatusCode() [2/6]

◆ StatusCode() [3/6]

◆ StatusCode() [4/6]

◆ StatusCode() [5/6]

◆ StatusCode() [6/6]

◆ ~StatusCode()

Member Function Documentation

◆ andThen()

◆ default_category()

◆ default_value()

◆ getCategory()

◆ getCode()

◆ i_doThrow()

◆ i_invoke()

◆ ignore() [1/2]

◆ ignore() [2/2]

◆ isFailure()

◆ isRecoverable()

◆ isSuccess()

◆ message()

◆ operator bool()

◆ operator&=()

◆ operator=()

◆ operator|=()

◆ orElse()

◆ orThrow() [1/2]

◆ orThrow() [2/2]

Friends And Related Function Documentation

◆ operator!=

◆ operator&

◆ operator&=

◆ operator<

◆ operator<<

◆ operator==

◆ operator|

◆ operator|=

Member Data Documentation

◆ FAILURE

◆ m_cat

◆ m_code

◆ RECOVERABLE

◆ SUCCESS