StatusCode.h

Go to the documentation of this file.

/***********************************************************************************\
* (c) Copyright 1998-2019 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.                                             *
\***********************************************************************************/
#ifndef GAUDIKERNEL_STATUSCODE_H
#define GAUDIKERNEL_STATUSCODE_H

#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 __cplusplus >= 201703L && !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, typename = std::enable_if_t<is_StatusCode_enum<T>::value>>
  StatusCode( T sc, bool checked = false ) noexcept {
    *this     = StatusCode( static_cast<StatusCode::code_t>( sc ), is_StatusCode_enum<T>::instance );
    m_checked = checked;
  }

  explicit StatusCode( code_t code, const StatusCode::Category& cat = default_category(),
                       bool checked = false ) noexcept
      : m_cat( &cat ), m_code( code ), m_checked( checked ) {}

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

  StatusCode( const StatusCode& rhs ) noexcept : m_cat( rhs.m_cat ), m_code( rhs.m_code ), m_checked( rhs.m_checked ) {
    rhs.m_checked = true;
  }

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

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

  StatusCode& operator=( const StatusCode& rhs ) noexcept {
    m_cat     = rhs.m_cat;
    m_code    = rhs.m_code;
    m_checked = std::exchange( rhs.m_checked, true );
    return *this;
  }

  bool isSuccess() const;
  bool isFailure() const { return !isSuccess(); }
  bool isRecoverable() const;

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

  code_t getCode() const {
    m_checked = true;
    return m_code;
  }

  const StatusCode& setChecked( bool checked = true ) const {
    m_checked = checked;
    return *this;
  }
  StatusCode& setChecked( bool checked = true ) {
    m_checked = checked;
    return *this;
  }

  const StatusCode& ignore() const {
    setChecked( true );
    return *this;
  }
  StatusCode& ignore() {
    setChecked( true );
    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 )... );
  }

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

  bool checked() const { return m_checked; }

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

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

  static GAUDI_API void enableChecking();
  static GAUDI_API void disableChecking();
  static GAUDI_API bool checkingEnabled();

  class ScopedDisableChecking {
    bool m_enabled;

  public:
    ScopedDisableChecking() : m_enabled( StatusCode::checkingEnabled() ) {
      if ( m_enabled ) StatusCode::disableChecking();
    }
    ~ScopedDisableChecking() {
      if ( m_enabled ) StatusCode::enableChecking();
    }
  };

private:
  const Category* m_cat{&default_category()};                        
  code_t          m_code{static_cast<code_t>( ErrorCode::SUCCESS )}; 
  mutable bool    m_checked{false};                                  
  static bool     s_checking; 

  ErrorCode default_value() const; 
  void      check();               

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

  template <typename F, typename... ARGS, typename = std::enable_if_t<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 {
  m_checked = true;
  return ( m_code == static_cast<code_t>( ErrorCode::SUCCESS ) || m_cat->isSuccess( m_code ) );
}

inline bool StatusCode::isRecoverable() const {
  m_checked = true;
  return m_cat->isRecoverable( m_code );
}

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

inline bool operator==( const StatusCode& lhs, const StatusCode& rhs ) {
  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 ) );
}

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];
  rhs.m_checked        = true;
  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];
  rhs.m_checked        = true;
  return *this;
}

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

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

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

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

#endif // GAUDIKERNEL_STATUSCODE_H