CHERI::ErrorOr< T, IsSealed > Class Template Reference

Helper for a value that encodes either a pointer or an error value in a pointer-sized value, discriminated by the tag bit. More...

#include <cheri.hh>

Public Member Functions
	ErrorOr (T *pointer)
	Construct from a pointer.
	ErrorOr (Capability< T, IsSealed > pointer)
	Construct from a CHERI::Capability.
	ErrorOr (int error)
	Initialise the value with an error value.
bool	is_error ()
	Returns true if this holds an error value, false otherwise.
auto	either (auto &&onT, auto &&onE)
	Generic eliminator for ErrorOr<T> values.
int	as_error ()
	If this holds an error value, return it, otherwise return 0.
T *	as_pointer ()
	If this holds a pointer, return it, otherwise return nullptr.
T *	as_raw ()
	Returns the underlying pointer, which may be an untagged capability with integer error value.
auto	as_raw_capability ()
	Returns the underlying pointer, which may be an untagged capability with integer error value, in its CHERI::Capability<> wrapper, which includes the IsSealed flag.
auto	and_then (auto &&function)
	Monadic helper modelled on std::optional.
auto	and_then (auto &&function)
int	and_then (auto &&function)
	Variant on and_then that returns an int: either the value returned by the callback, or the error value held by *this.
auto	or_else (auto &&function)
	Monadic helper modelled on std::optional.
auto	or_else (auto &&function)

Detailed Description

template<typename T, bool IsSealed = false>
class CHERI::ErrorOr< T, IsSealed >

Helper for a value that encodes either a pointer or an error value in a pointer-sized value, discriminated by the tag bit.

This is a non-owning pointer type.

Definition at line 1596 of file cheri.hh.

Constructor & Destructor Documentation

ErrorOr() [1/3]

template<typename T, bool IsSealed = false>

CHERI::ErrorOr< T, IsSealed >::ErrorOr ( T * pointer )

inline

Construct from a pointer.

This may be a C API that uses the convention of holding a pointer or an error value. You may call this constructor with an invalid pointer.

Definition at line 1607 of file cheri.hh.

ErrorOr() [2/3]

template<typename T, bool IsSealed = false>

CHERI::ErrorOr< T, IsSealed >::ErrorOr ( Capability< T, IsSealed > pointer )

inline

Construct from a CHERI::Capability.

This may be a C API that uses the convention of holding a pointer or an error value. You may call this constructor with an invalid pointer.

Definition at line 1614 of file cheri.hh.

ErrorOr() [3/3]

template<typename T, bool IsSealed = false>

CHERI::ErrorOr< T, IsSealed >::ErrorOr ( int error )

inline

Initialise the value with an error value.

By convention, error numbers are negated in CHERIoT RTOS.

Definition at line 1623 of file cheri.hh.

Member Function Documentation

and_then() [1/3]

template<typename T, bool IsSealed = false>

int CHERI::ErrorOr< T, IsSealed >::and_then ( auto && function )

inline

Variant on and_then that returns an int: either the value returned by the callback, or the error value held by *this.

This is useful for propagating error values in functions that return an int (e.g. where negative values indicate errors and zero or positive values indicate success).

Definition at line 1775 of file cheri.hh.

References either().

and_then() [2/3]

template<typename T, bool IsSealed = false>

auto CHERI::ErrorOr< T, IsSealed >::and_then ( auto && function )

inline

Definition at line 1749 of file cheri.hh.

and_then() [3/3]

template<typename T, bool IsSealed = false>

auto CHERI::ErrorOr< T, IsSealed >::and_then ( auto && function )

inline

Monadic helper modelled on std::optional.

Takes a reference to a callable object that accepts a T* or something that can be implicitly cast to a T*. The return value for the argument should be either void (in which case and_then returns *this) or an ErrorOr<U>

The callback is invoked if and only if this holds a valid pointer.

Definition at line 1740 of file cheri.hh.

References either().

as_error()

template<typename T, bool IsSealed = false>

int CHERI::ErrorOr< T, IsSealed >::as_error ( )

inline

If this holds an error value, return it, otherwise return 0.

CHERIoT RTOS follows the C convention of using 0 to indicate success, but this may result in ambiguity. Use is_error if this ambiguity matters.

Definition at line 1688 of file cheri.hh.

References either().

as_pointer()

template<typename T, bool IsSealed = false>

T * CHERI::ErrorOr< T, IsSealed >::as_pointer ( )

inline

If this holds a pointer, return it, otherwise return nullptr.

This ensures that all values that are not valid pointers are mapped to null.

Definition at line 1698 of file cheri.hh.

as_raw()

template<typename T, bool IsSealed = false>

T * CHERI::ErrorOr< T, IsSealed >::as_raw ( )

inline

Returns the underlying pointer, which may be an untagged capability with integer error value.

For type safety, prefer as_pointer or as_error.

Definition at line 1712 of file cheri.hh.

as_raw_capability()

template<typename T, bool IsSealed = false>

auto CHERI::ErrorOr< T, IsSealed >::as_raw_capability ( )

inlinenodiscard

Returns the underlying pointer, which may be an untagged capability with integer error value, in its CHERI::Capability<> wrapper, which includes the IsSealed flag.

For type safety, prefer as_pointer or as_error.

Definition at line 1726 of file cheri.hh.

either()

template<typename T, bool IsSealed = false>

auto CHERI::ErrorOr< T, IsSealed >::either ( auto && onT, auto && onE )

inline

Generic eliminator for ErrorOr<T> values.

Read x.either(t, e) as "either calls t with x's value or e with x's error". That is, either takes two callbacks, the first of which is called with non-error T * values, and the second of which is called with int error values. The return type of the latter (the error handler) must be convertable to the return type of the former (the T * handler).

Definition at line 1645 of file cheri.hh.

References is_error().

Referenced by and_then(), as_error(), and or_else().

is_error()

template<typename T, bool IsSealed = false>

bool CHERI::ErrorOr< T, IsSealed >::is_error ( )

inline

Returns true if this holds an error value, false otherwise.

Definition at line 1632 of file cheri.hh.

Referenced by either().

or_else() [1/2]

template<typename T, bool IsSealed = false>

auto CHERI::ErrorOr< T, IsSealed >::or_else ( auto && function )

inline

Definition at line 1800 of file cheri.hh.

or_else() [2/2]

template<typename T, bool IsSealed = false>

auto CHERI::ErrorOr< T, IsSealed >::or_else ( auto && function )

inline

Monadic helper modelled on std::optional.

Takes a reference to a callable object that accepts an int. The return value for the argument should be either void (in which case or_else returns *this) or something that can implicitly cast to an ErrorOr<T>.

The callback is invoked if and only if this holds an error value.

Definition at line 1792 of file cheri.hh.

References either().

---

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

• sdk/include/cheri.hh