Loading...
Searching...
No Matches
lomiri::Exception Class Referenceabstract

Abstract base class for all Lomiri exceptions. More...

`#include <lomiri/Exception.h>`

Inheritance diagram for lomiri::Exception:
[legend]
Collaboration diagram for lomiri::Exception:
[legend]

## Public Member Functions

char const * | what () const noexcept override
| Returns a string describing the exception, including any exceptions that were nested or chained.
virtual std::exception_ptr | self () const =0
| Returns a `std::exception_ptr` to `this`.
std::string | name () const
| Returns the name set by the derived class's constructor.
std::string | reason () const
| Returns the reason set by the derived class's constructor (empty string if none).
std::string | to_string (std::string const &indent=" ") const
| Returns a string describing the exception, including any exceptions that were nested or chained.
std::string | to_string (int indent_level, std::string const &indent) const
| Returns a string describing the exception, including any exceptions that were nested or chained.
std::exception_ptr | remember (std::exception_ptr earlier_exception)
| Adds an exception to the exception history chain.
std::exception_ptr | get_earlier () const noexcept
| Returns the previous exception.

## Protected Member Functions

| Exception (std::string const &name, std::string const &reason)
| Constructs an exception instance.

## Detailed Description

Abstract base class for all Lomiri exceptions.

This class is the base class for all Lomiri exceptions. Besides providing a common base class for structured exception handling, this class provides features to capture nested exceptions (for exceptions that are re-thrown) and to chain exceptions into an exception history that allows a number of exceptions to be remembered before throwing a new exception.

The exception nesting is provided by the derivation from `std::nested_exception`. If you catch an exception and throw another exception from the catch handler, the caught exception is automatically preserved; you can access nested exceptions by calling the `nested_ptr()` and `rethrow_nested()` member functions of `std::nested_exception`.

In addition, you can remember one or more exceptions by calling remember(). This is useful in situations where you need to perform a number of actions that may fail with an error code, and you do not want to throw an exception until all of the actions have been attempted. This is particularly useful in shutdown scenarios, where it is often impossible to recover from an error, but it is still desirable to try to shut down as much as possible before reporting or logging the errors:

void
shutdown()
{
using namespace std;
exception_ptr ep;
try
{
shutdown_action_1();
}
catch (SomeException const&)
{
ep = make_exception_ptr(current_exception());
}
try
{
shutdown_action_2();
}
catch (SomeOtherException const&)
{
ep = e.remember(ep);
}
int err = shutdown_action_3();
if (err != 0)
{
try
{
throw YetAnotherException(err);
}
catch (YetAnotherException const& e)
{
ep = e.remember(ep);
}
}
if (ep)
{
rethrow_exception(ep);
}
}

Calling what() on a caught exception returns a string with the entire exception history (both nested and chained).

## Constructor & Destructor Documentation

## Exception()

lomiri::Exception::Exception | ( | std::string const & | name,
|  | std::string const & | reason )

protected

Constructs an exception instance.

Parameters

  name | The fully-qualified name of the exception, such as "lomiri::SyscallException". The name must not be empty.
  reason | Any additional details about the exception, such as an error message and the values of any members of the exception.

## Member Function Documentation

## get_earlier()

exception_ptr lomiri::Exception::get_earlier | ( |  | ) | const

noexcept

Returns the previous exception.

Returns
  Returns the next-older remembered exception, or `nullptr`, if none.

## reason()

string lomiri::Exception::reason | ( |  | ) | const

Returns the reason set by the derived class's constructor (empty string if none).

Derived classes should include any other state information, such as the value of data members or other relevant detail in the `reason` string they pass to the protected constructor.

## remember()

exception_ptr lomiri::Exception::remember | ( | std::exception_ptr | earlier_exception | ) |

Adds an exception to the exception history chain.

Parameters

  earlier_exception

  The parameter must be a `nullptr` or a `std::exception_ptr` to an exception that was remembered earlier. This allows a sequence of exceptions to be remembered without having to throw them and is useful, for example, in shutdown scenarios where any one of a sequence of steps can fail, but we want to continue and try all the following steps and only throw after all of them have been tried. In this case, each step that fails can add itself to the sequence of remembered exceptions, and finally throw something like `ShutdownException`.

Returns
  A `std::exception_ptr` to `this`.

## self()

virtual std::exception_ptr lomiri::Exception::self | ( |  | ) | const

pure virtual

Returns a `std::exception_ptr` to `this`.

Note
  Derived exceptions must implement this member function so the implemention of remember() (provided by this abstract base class) can return a `std::exception_ptr` to its own derived exception.

Implemented in lomiri::FileException, lomiri::InvalidArgumentException, lomiri::LogicException, lomiri::ResourceException, lomiri::ShutdownException, and lomiri::SyscallException.

## to_string() [1/2]

string lomiri::Exception::to_string | ( | int | indent_level,
|  | std::string const & | indent ) const

Returns a string describing the exception, including any exceptions that were nested or chained.

Nested exceptions are indented according to their nesting level. If the exception contains chained exceptions, these are shown in oldest-to-newest order.

Parameters

  indent_level | This controls the indent level. The value `0` indicates the outermost level (no indent).
  indent | This controls the amount of indenting per level. The passed string is prependended `indent_level` times to each line.

Returns
  The string describing the exception.

Note
  This member function has a default implementation, so derived classes do not need to override it unless they want to change the formatting of the returned string.

## to_string() [2/2]

string lomiri::Exception::to_string | ( | std::string const & | indent = " " | ) | const

Returns a string describing the exception, including any exceptions that were nested or chained.

Nested exceptions are indented according to their nesting level. If the exception contains chained exceptions, these are shown in oldest-to-newest order.

Parameters

  indent | This controls the amount of indenting per level. The default indent is four spaces.

Returns
  The string describing the exception.

Note
  The default implementation of this member function calls `to_string(0, indent)`.

## what()

char const * lomiri::Exception::what | ( |  | ) | const

override noexcept

Returns a string describing the exception, including any exceptions that were nested or chained.

Returns
  The return value is the same string that is returned by calling to_string(). The returned pointer remains valid until the next call to what(), or until the exception is destroyed.

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

- include/lomiri/Exception.h
- src/lomiri/Exception.cpp