Asylo
Public Member Functions | Static Public Member Functions | List of all members
asylo::error::ErrorSpace Class Referenceabstract

All implementations of error spaces are derived from this abstract class. More...

#include <error_space.h>

Inheritance diagram for asylo::error::ErrorSpace:
Inheritance graph
[legend]

Public Member Functions

 ErrorSpace ()=default
 
 ErrorSpace (const ErrorSpace &other)=delete
 
virtual ~ErrorSpace ()=default
 
ErrorSpaceoperator= (const ErrorSpace &other)=delete
 
virtual std::string SpaceName () const =0
 Gets a name that uniquely identifies the error space. More...
 
virtual std::string String (int code) const =0
 Gets a string that describes the error code within the space. More...
 
virtual GoogleError GoogleErrorCode (int code) const =0
 Converts code to an appropriate value in the GoogleError enum. More...
 

Static Public Member Functions

static ErrorSpace const * Find (const std::string &name)
 Finds and returns an ErrorSpace singleton pointer whose SpaceName() equals name. More...
 

Detailed Description

All implementations of error spaces are derived from this abstract class.

At a conceptual level, an ErrorSpace provides a mechanism for classifying error codes into distinct categories and mapping those errors to human readable strings. It also provides a mechanism for converting error codes from arbitrary error spaces to the Google canonical error space.

At the implementation level, an error space consists of an error code enum and an associated implementation of the abstract ErrorSpace interface. The ErrorSpace interface declares three pure virtual methods. An ErrorSpace interface implementation is bound to the error code enum via a compile-time polymorphic function GetErrorSpace(), which can be used to retrieve a singleton pointer to the error space associated with a particular enum.

Thus, to implement a new error space, the implementer must provide three components:

  1. An enum type that is not associated with any current ErrorSpace implementation.
  2. An implementation of the ErrorSpace interface.
  3. An implementation of an appropriately-typed GetErrorSpace() function.

The error-space library maintains a global map of singletons for all the error-space implementations loaded into the current address space. This map can be queried to retrieve singleton pointers associated with a given name using the ErrorSpace::Find(const string &name) method. To enable seamless bookkeeping of such singletons, the error-space infrastructure defines an intermediate template class called ErrorSpaceImplementationHelper, which is derived from the ErrorSpace abstract class. Any error-space implementation derived from this class is automatically tracked in the error-space singleton global map. The helper class also provides an absl::flat_hash_map-based implementation of the SpaceName() and String() methods, and as a result, error-space implementations derived from this class do not need to provide their own implementation of these methods. It is strongly recommended that all error-space implementations be derived from the ErrorSpaceImplementationHelper. While it is possible to correctly implement an error space without deriving from this class, such an implementation will have to be aware of the error-space infrastructure, and consequently, will be fragile.

Below is an example of implementing a new enum Foo, and associating it with the ErrorSpace implementation FooErrorSpace.

First, define the enum type.

enum Foo {
OK = 0, // A value of 0 must always map to OK status in the error space.
...
};

Next implement the FooErrorSpace class by deriving it from ErrorSpaceImplementationHelper<FooErrorSpace>.

class FooErrorSpace : public ErrorSpaceImplementationHelper<FooErrorSpace> {
public:
using code_type = Foo; // Error-space implementation must define the
// code_type type-alias that aliases to the
// underlying enum.
// No need to provide implementation of ErrorSpace interface, as
// ErrorSpaceImplementationHelper<FooErrorSpace> provides such
// implementation.
friend ErrorSpace const *GetErrorSpace(ErrorSpaceAdlTag<Foo> tag);
private:
FooErrorSpace() : ErrorSpaceImplementationHelper<FooErrorSpace>{
"FooErrorSpace"} {
AddTranslationMapEntry(...);
...
}
};

Finally, bind the ErrorSpace implementation to the enum by defining appropriate GetErrorSpace() function.

ErrorSpace const *GetErrorSpace(ErrorSpaceAdlTag<Foo> tag) {
// Must return a singleton pointer of FooErrorSpace
...
}

See GoogleErrorSpace for an example implementation.

Constructor & Destructor Documentation

◆ ErrorSpace() [1/2]

asylo::error::ErrorSpace::ErrorSpace ( )
default

◆ ErrorSpace() [2/2]

asylo::error::ErrorSpace::ErrorSpace ( const ErrorSpace other)
delete

◆ ~ErrorSpace()

virtual asylo::error::ErrorSpace::~ErrorSpace ( )
virtualdefault

Member Function Documentation

◆ Find()

static ErrorSpace const* asylo::error::ErrorSpace::Find ( const std::string &  name)
static

Finds and returns an ErrorSpace singleton pointer whose SpaceName() equals name.

Parameters
nameThe name to search for.
Returns
A singleton pointer to an ErrorSpace on success, nullptr on failure.

◆ GoogleErrorCode()

virtual GoogleError asylo::error::ErrorSpace::GoogleErrorCode ( int  code) const
pure virtual

Converts code to an appropriate value in the GoogleError enum.

Parameters
codeThe error code in this error space to convert to GoogleError.
Returns
The GoogleError interpretation of code.

Implemented in asylo::error::ErrorSpaceImplementationHelper< ErrorSpaceT >, asylo::error::ErrorSpaceImplementationHelper< GoogleErrorSpace >, and asylo::error::ErrorSpaceImplementationHelper< PosixErrorSpace >.

◆ operator=()

ErrorSpace& asylo::error::ErrorSpace::operator= ( const ErrorSpace other)
delete

◆ SpaceName()

virtual std::string asylo::error::ErrorSpace::SpaceName ( ) const
pure virtual

◆ String()

virtual std::string asylo::error::ErrorSpace::String ( int  code) const
pure virtual

Gets a string that describes the error code within the space.

Parameters
codeThe error code to interpret within the error space.
Returns
A description for the input code.

Implemented in asylo::error::ErrorSpaceImplementationHelper< ErrorSpaceT >, asylo::error::ErrorSpaceImplementationHelper< GoogleErrorSpace >, and asylo::error::ErrorSpaceImplementationHelper< PosixErrorSpace >.


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