My Project
unity::Exception Class Referenceabstract

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

#include <unity/Exception.h>

Inheritance diagram for unity::Exception:
Collaboration diagram for unity::Exception:

Public Member Functions

virtual char const * what () const noexcept
 Returns a string describing the exception, including any exceptions that were nested or chained. More...
 
virtual std::exception_ptr self () const =0
 Returns a std::exception_ptr to this. More...
 
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). More...
 
std::string to_string (std::string const &indent=" ") const
 Returns a string describing the exception, including any exceptions that were nested or chained. More...
 
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. More...
 
std::exception_ptr remember (std::exception_ptr earlier_exception)
 Adds an exception to the exception history chain. More...
 
std::exception_ptr get_earlier () const noexcept
 Returns the previous exception. More...
 

Protected Member Functions

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

Detailed Description

Abstract base class for all Unity exceptions.

This class is the base class for all Unity 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

unity::Exception::Exception ( std::string const &  name,
std::string const &  reason 
)
protected

Constructs an exception instance.

Parameters
nameThe fully-qualified name of the exception, such as "unity::SyscallException". The name must not be empty.
reasonAny additional details about the exception, such as an error message and the values of any members of the exception.

Member Function Documentation

exception_ptr unity::Exception::get_earlier ( ) const
noexcept

Returns the previous exception.

Returns
Returns the next-older remembered exception, or nullptr, if none.
string unity::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.

exception_ptr unity::Exception::remember ( std::exception_ptr  earlier_exception)

Adds an exception to the exception history chain.

Parameters
earlier_exceptionThe 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.
virtual std::exception_ptr unity::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 unity::ResourceException, unity::SyscallException, unity::FileException, unity::ShutdownException, unity::LogicException, and unity::InvalidArgumentException.

string unity::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
indentThis 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).
string unity::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_levelThis controls the indent level. The value 0 indicates the outermost level (no indent).
indentThis 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.
char const * unity::Exception::what ( ) const
virtualnoexcept

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: