WPILibC++  2020.3.2-60-g3011ebe
wpi::Error Class Reference

Lightweight error class with error context and mandatory checking. More...

#include <Error.h>

Inheritance diagram for wpi::Error:
wpi::ErrorSuccess

Public Member Functions

 Error (const Error &Other)=delete
 
 Error (Error &&Other) noexcept
 Move-construct an error value. More...
 
 Error (std::unique_ptr< ErrorInfoBase > Payload)
 Create an error value. More...
 
Erroroperator= (const Error &Other)=delete
 
Erroroperator= (Error &&Other) noexcept
 Move-assign an error value. More...
 
 ~Error ()
 Destroy a Error. More...
 
 operator bool ()
 Bool conversion. More...
 
template<typename ErrT >
bool isA () const
 Check whether one error is a subclass of another.
 
const void * dynamicClassID () const
 Returns the dynamic class id of this error, or null if this is a success value.
 

Static Public Member Functions

static ErrorSuccess success ()
 Create a success value.
 

Protected Member Functions

 Error ()
 Create a success value. Prefer using 'Error::success()' for readability.
 

Friends

class ErrorList
 
class FileError
 
template<typename T >
class Expected
 
template<typename... HandlerTs>
Error handleErrors (Error E, HandlerTs &&... Handlers)
 Pass the ErrorInfo(s) contained in E to their respective handlers. More...
 
raw_ostreamoperator<< (raw_ostream &OS, const Error &E)
 

Detailed Description

Lightweight error class with error context and mandatory checking.

Instances of this class wrap a ErrorInfoBase pointer. Failure states are represented by setting the pointer to a ErrorInfoBase subclass instance containing information describing the failure. Success is represented by a null pointer value.

Instances of Error also contains a 'Checked' flag, which must be set before the destructor is called, otherwise the destructor will trigger a runtime error. This enforces at runtime the requirement that all Error instances be checked or returned to the caller.

There are two ways to set the checked flag, depending on what state the Error instance is in. For Error instances indicating success, it is sufficient to invoke the boolean conversion operator. E.g.:

Error foo(<...>);
if (auto E = foo(<...>))
return E; // <- Return E if it is in the error state.
// We have verified that E was in the success state. It can now be safely
// destroyed.

A success value can not be dropped. For example, just calling 'foo(<...>)' without testing the return value will raise a runtime error, even if foo returns success.

For Error instances representing failure, you must use either the handleErrors or handleAllErrors function with a typed handler. E.g.:

class MyErrorInfo : public ErrorInfo<MyErrorInfo> {
// Custom error info.
};
Error foo(<...>) { return make_error<MyErrorInfo>(...); }
auto E = foo(<...>); // <- foo returns failure with MyErrorInfo.
auto NewE =
[](const MyErrorInfo &M) {
// Deal with the error.
},
[](std::unique_ptr<OtherError> M) -> Error {
if (canHandle(*M)) {
// handle error.
return Error::success();
}
// Couldn't handle this error instance. Pass it up the stack.
return Error(std::move(M));
);
// Note - we must check or return NewE in case any of the handlers
// returned a new error.

The handleAllErrors function is identical to handleErrors, except that it has a void return type, and requires all errors to be handled and no new errors be returned. It prevents errors (assuming they can all be handled) from having to be bubbled all the way to the top-level.

All Error instances must be checked before destruction, even if they're moved-assigned or constructed from Success values that have already been checked. This enforces checking through all levels of the call stack.

Constructor & Destructor Documentation

◆ Error() [1/2]

wpi::Error::Error ( Error &&  Other)
inlinenoexcept

Move-construct an error value.

The newly constructed error is considered unchecked, even if the source error had been checked. The original error becomes a checked Success value, regardless of its original state.

◆ Error() [2/2]

wpi::Error::Error ( std::unique_ptr< ErrorInfoBase Payload)
inline

Create an error value.

Prefer using the 'make_error' function, but this constructor can be useful when "re-throwing" errors from handlers.

◆ ~Error()

wpi::Error::~Error ( )
inline

Destroy a Error.

Fails with a call to abort() if the error is unchecked.

Member Function Documentation

◆ operator bool()

wpi::Error::operator bool ( )
inlineexplicit

Bool conversion.

Returns true if this Error is in a failure state, and false if it is in an accept state. If the error is in a Success state it will be considered checked.

◆ operator=()

Error& wpi::Error::operator= ( Error &&  Other)
inlinenoexcept

Move-assign an error value.

The current error must represent success, you you cannot overwrite an unhandled error. The current error is then considered unchecked. The source error becomes a checked success value, regardless of its original state.

Friends And Related Function Documentation

◆ handleErrors

template<typename... HandlerTs>
Error handleErrors ( Error  E,
HandlerTs &&...  Handlers 
)
friend

Pass the ErrorInfo(s) contained in E to their respective handlers.

Any unhandled errors (or Errors returned by handlers) are re-concatenated and returned. Because this function returns an error, its result must also be checked or returned. If you intend to handle all errors use handleAllErrors (which returns void, and will abort() on unhandled errors) instead.


The documentation for this class was generated from the following file:
wpi::Error::Error
Error()
Create a success value. Prefer using 'Error::success()' for readability.
Definition: Error.h:171
wpi::Error::handleErrors
friend Error handleErrors(Error E, HandlerTs &&... Handlers)
Pass the ErrorInfo(s) contained in E to their respective handlers.
Definition: Error.h:807
wpi::Error::success
static ErrorSuccess success()
Create a success value.
Definition: Error.h:296