caf::error Class Reference

A serializable type for storing error codes with category and optional, human-readable context information. More...

#include <error.hpp>

Inheritance diagram for caf::error:

Public Member Functions
	error (none_t) noexcept
	error (error &&) noexcept=default
error &	operator= (error &&) noexcept=default
	error (const error &)
error &	operator= (const error &)
template<class Enum , class = std::enable_if_t<is_error_code_enum_v<Enum>>>
	error (Enum code)
template<class Enum , class = std::enable_if_t<is_error_code_enum_v<Enum>>>
	error (Enum code, message context)
template<class Enum , class = std::enable_if_t<is_error_code_enum_v<Enum>>>
	error (Enum code, std::string msg)
template<class Enum >
	error (error_code< Enum > code)
template<class E >
error &	operator= (E error_value)
template<class E >
error &	operator= (error_code< E > code)
uint8_t	code () const noexcept
	Returns the category-specific error code, whereas 0 means "no error".
type_id_t	category () const noexcept
	Returns the type_id of the category for this error.
const message &	context () const noexcept
	Returns context information to this error.
std::string_view	what () const noexcept
	Returns a human-readable string representation of this error if available.
	operator bool () const noexcept
	Returns *this != none.
bool	operator! () const noexcept
	Returns *this == none.
bool	empty () const noexcept
	Returns whether this error was default-constructed.
int	compare (const error &) const noexcept
int	compare (uint8_t code, type_id_t category) const noexcept
template<class Enum , class... Ts>
error	or_else (Enum code, Ts &&... args) const &
	Returns a copy of this if !empty() or else returns a new error from given arguments.
template<class Enum , class... Ts>
error	or_else (Enum code, Ts &&... args) &&
	Returns a copy of this if !empty() or else returns a new error from given arguments.
void	reset () noexcept
	Reverts this error to "not an error" as if calling *this = error{}.

Friends
template<class Inspector >
bool	inspect (Inspector &f, error &x)

Related Symbols
(Note that these are not member symbols.)
CAF_CORE_EXPORT std::string	to_string (const error &x)
template<class Enum >
std::enable_if_t< is_error_code_enum_v< Enum >, error >	make_error (Enum code)
template<class Enum , class T , class... Ts>
std::enable_if_t< is_error_code_enum_v< Enum >, error >	make_error (Enum code, T &&x, Ts &&... xs)
bool	operator== (const error &x, none_t)
bool	operator== (none_t, const error &x)
template<class Enum >
std::enable_if_t< is_error_code_enum_v< Enum >, bool >	operator== (const error &x, Enum y)
template<class Enum >
std::enable_if_t< is_error_code_enum_v< Enum >, bool >	operator== (Enum x, const error &y)
bool	operator!= (const error &x, none_t)
bool	operator!= (none_t, const error &x)
template<class Enum >
std::enable_if_t< is_error_code_enum_v< Enum >, bool >	operator!= (const error &x, Enum y)
template<class Enum >
std::enable_if_t< is_error_code_enum_v< Enum >, bool >	operator!= (Enum x, const error &y)

Detailed Description

A serializable type for storing error codes with category and optional, human-readable context information.

Unlike error handling classes from the C++ standard library, this type is serializable. It consists of an 8-bit code, a 64-bit atom constant, plus optionally a message to store additional information.

Why not std::error_code or std::error_condition?

First, the standard does not define the values for std::errc. This means serializing error conditions (which are meant to be portable) is not safe in a distributed setting unless all machines are running the same operating system and version of the C++ standard library.

Second, the standard library primitives, unlike exceptions, do not offer an API for attaching additional context to an error. The error handling API offered by the standard is meant to wrap C system calls in a (source code) portable way. In a distributed setting, an error may not occur locally. In this case, an error code and category alone is often not satisfactory information when signalling errors back to end users. The additional context also enables composition of errors by modifying the message details as needed.

Why is there no string() member function?

The C++ standard library uses category singletons and virtual dispatching to correlate error codes to descriptive strings. However, singletons are a poor choice when it comes to serialization. CAF uses type IDs and meta objects instead.

Member Function Documentation

category()

type_id_t caf::error::category ( ) const

noexcept

Returns the type_id of the category for this error.

Precondition

*this != none

code()

uint8_t caf::error::code ( ) const

noexcept

Returns the category-specific error code, whereas 0 means "no error".

Precondition

*this != none

context()

const message & caf::error::context ( ) const

noexcept

Returns context information to this error.

Precondition

*this != none

what()

std::string_view caf::error::what ( ) const

noexcept

Returns a human-readable string representation of this error if available.

Otherwise, returns an empty string.

Note

The string representation is extracted from the embedded context if it contains a single string element.

---

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

• libcaf_core/caf/error.hpp
• libcaf_core/caf/error.cpp