StatusCode.h

Go to the documentation of this file.

/***********************************************************************************\
* (c) Copyright 1998-2025 CERN for the benefit of the LHCb and ATLAS collaborations *
*                                                                                   *
* This software is distributed under the terms of the Apache version 2 licence,     *
* copied verbatim in the file "LICENSE".                                            *
*                                                                                   *
* In applying this licence, CERN does not waive the privileges and immunities       *
* granted to it by virtue of its status as an Intergovernmental Organization        *
* or submit itself to any jurisdiction.                                             *
\***********************************************************************************/
#pragma once
 
#include <boost/preprocessor/facilities/overload.hpp>
#include <functional>
#include <ostream>
#include <type_traits>
#include <utility>
 
#include <GaudiKernel/Kernel.h>
 
template <typename T>
struct is_StatusCode_enum : std::false_type {};

class
#if !defined( __CLING__ )
    [[nodiscard]]
#endif
    StatusCode final {
public:
  typedef unsigned long code_t; 
 
  enum class ErrorCode : code_t { FAILURE = 0, SUCCESS = 1, RECOVERABLE = 2 };

  struct Category {
    constexpr Category() noexcept = default;
    virtual ~Category() {}

    virtual const char* name() const = 0;

    virtual std::string message( code_t code ) const { return "UNKNOWN(" + std::to_string( code ) + ")"; }

    virtual bool isSuccess( code_t code ) const { return code == static_cast<code_t>( ErrorCode::SUCCESS ); }

    virtual bool isRecoverable( code_t code ) const { return code == static_cast<code_t>( ErrorCode::RECOVERABLE ); }
  };

  static const Category& default_category() noexcept;
 
  // Provide shorthands for default code values
  constexpr const static auto SUCCESS     = ErrorCode::SUCCESS;
  constexpr const static auto FAILURE     = ErrorCode::FAILURE;
  constexpr const static auto RECOVERABLE = ErrorCode::RECOVERABLE;

  StatusCode() = default;

  template <typename T>
    requires( is_StatusCode_enum<T>::value )
  StatusCode( T sc ) noexcept : StatusCode{ static_cast<StatusCode::code_t>( sc ), is_StatusCode_enum<T>::instance } {}

  explicit StatusCode( code_t code, const StatusCode::Category& cat ) noexcept : m_cat( &cat ), m_code( code ) {}

  explicit StatusCode( code_t code ) noexcept : StatusCode( code, default_category() ) {}

  StatusCode( const StatusCode& rhs ) noexcept = default;

  StatusCode( StatusCode&& rhs ) noexcept = default;

  ~StatusCode() = default;
 
  StatusCode& operator=( const StatusCode& rhs ) noexcept = default;
 
  bool isSuccess() const;
  bool isFailure() const { return !isSuccess(); }
  bool isRecoverable() const;

  explicit operator bool() const { return isSuccess(); }

  code_t getCode() const { return m_code; }

  const StatusCode& ignore() const { return *this; }
  StatusCode&       ignore() { return *this; }

  template <typename F, typename... ARGS>
  StatusCode andThen( F&& f, ARGS&&... args ) const {
    if ( isFailure() ) return *this;
    return i_invoke( std::forward<F>( f ), std::forward<ARGS>( args )... );
  }

  template <typename F, typename... ARGS>
  StatusCode orElse( F&& f, ARGS&&... args ) const {
    if ( isSuccess() ) return *this;
    return i_invoke( std::forward<F>( f ), std::forward<ARGS>( args )... );
  }

  const StatusCode& orThrow( std::string_view message, std::string_view tag ) const {
    if ( isFailure() ) i_doThrow( message, tag );
    return *this;
  }

  const StatusCode& orThrow( std::string_view tag = "" ) const {
    if ( isFailure() ) i_doThrow( message(), tag ); // make sure `message()` is only called on error path
    return *this;
  }

  const StatusCode::Category& getCategory() const { return *m_cat; }

  std::string message() const { return getCategory().message( m_code ); }
 
  friend std::ostream& operator<<( std::ostream& s, const StatusCode& sc ) {
    s << sc.message();
    return s;
  }

  friend bool operator==( const StatusCode& lhs, const StatusCode& rhs );
  friend bool operator!=( const StatusCode& lhs, const StatusCode& rhs ) { return !( lhs == rhs ); }

  friend bool operator<( const StatusCode& lhs, const StatusCode& rhs ) {
    return ( lhs.m_cat < rhs.m_cat || ( lhs.m_cat == rhs.m_cat && lhs.m_code < rhs.m_code ) );
  }

  StatusCode& operator&=( const StatusCode& rhs );
  StatusCode& operator|=( const StatusCode& rhs ); 
  //
  friend StatusCode operator&( StatusCode lhs, const StatusCode& rhs ) { return lhs &= rhs; }

  friend StatusCode operator|( StatusCode lhs, const StatusCode& rhs ) { return lhs |= rhs; }

  friend bool& operator&=( bool& lhs, const StatusCode& sc ) { return lhs &= sc.isSuccess(); }

  friend bool& operator|=( bool& lhs, const StatusCode& sc ) { return lhs |= sc.isSuccess(); }
 
private:
  const Category* m_cat{ &default_category() };                        
  code_t          m_code{ static_cast<code_t>( ErrorCode::SUCCESS ) }; 
 
  ErrorCode default_value() const; 

  [[noreturn]] void i_doThrow( std::string_view message, std::string_view tag ) const;

  template <typename... ARGS, std::invocable<ARGS...> F> // requires ( std::is_invocable_v<F, ARGS...> )
  StatusCode i_invoke( F&& f, ARGS&&... args ) const {
    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;
    }
  }
};
 
/*
 * Macros to declare/implement StatusCode enums/categories
 */

#define STATUSCODE_ENUM_DECL( ENUM )                                                                                   \
  template <>                                                                                                          \
  struct is_StatusCode_enum<ENUM> : std::true_type {                                                                   \
    static const StatusCode::Category& instance;                                                                       \
  };

#define STATUSCODE_ENUM_IMPL( ... ) BOOST_PP_OVERLOAD( STATUSCODE_ENUM_IMPL_, __VA_ARGS__ )( __VA_ARGS__ )
 
#define STATUSCODE_ENUM_IMPL_1( ENUM )                                                                                 \
  const StatusCode::Category& is_StatusCode_enum<ENUM>::instance = StatusCode::default_category();
 
#define STATUSCODE_ENUM_IMPL_2( ENUM, CATEGORY )                                                                       \
  const StatusCode::Category& is_StatusCode_enum<ENUM>::instance = CATEGORY{};
 
// Declare the default StatusCode enum
STATUSCODE_ENUM_DECL( StatusCode::ErrorCode )
 
/*
 * Inline methods
 */
 
inline const StatusCode::Category& StatusCode::default_category() noexcept {
  return is_StatusCode_enum<StatusCode::ErrorCode>::instance;
}
 
inline bool StatusCode::isSuccess() const {
  return ( m_code == static_cast<code_t>( ErrorCode::SUCCESS ) || m_cat->isSuccess( m_code ) );
}
 
inline bool StatusCode::isRecoverable() const { return m_cat->isRecoverable( m_code ); }
 
inline StatusCode::ErrorCode StatusCode::default_value() const {
  auto r = isSuccess() ? ErrorCode::SUCCESS : ( isRecoverable() ? ErrorCode::RECOVERABLE : ErrorCode::FAILURE );
  return r;
}
 
inline bool operator==( const StatusCode& lhs, const StatusCode& rhs ) {
  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 ) );
}
 
inline StatusCode& StatusCode::operator&=( const StatusCode& rhs ) {
  // 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;
}
 
inline StatusCode& StatusCode::operator|=( const StatusCode& rhs ) {
  // 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;
}