...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
The purpose of Boost Exception is to ease the design of exception class hierarchies and to help write exception handling and error reporting code.
It supports transporting of arbitrary data to the catch site, which is otherwise tricky due to the no-throw requirements (15.5.1) for exception types. Data can be added to any exception object, either directly in the throw-expression (15.1), or at a later time as the exception object propagates up the call stack.
The ability to add data to exception objects after they have been passed to throw is important, because often some of the information needed to handle an exception is unavailable in the context where the failure is detected.
Boost Exception also supports N2179-style copying of exception objects, implemented non-intrusively and automatically by the boost::throw_exception function.
#include <boost/exception.hpp>
namespace boost { class exception { protected: exception(); exception( exception const & x ); ~exception(); }; template <class Tag,class T> class error_info; typedef error_info<struct tag_throw_function,char const *> throw_function; typedef error_info<struct tag_throw_file,char const *> throw_file; typedef error_info<struct tag_throw_line,int> throw_line; template <class Tag,class T> class error_info { public: typedef T value_type; error_info( value_type const & ); }; template <class E, class Tag, class T> E const & operator<<( E const & x, error_info<Tag,T> const & v ); template <class E, class Tag1, class T1, ..., class TagN, class TN> E const & operator<<( E const & x, tuple< error_info<Tag1,T1>, ..., error_info<TagN,TN> > const & v ); template <class T> ---unspecified--- enable_error_info( T const & x ); std::string diagnostic_information( boost::exception const & x ); class unknown_exception: public std::exception public boost::exception { ---unspecified--- }; typedef ---unspecified--- exception_ptr; template <class T> exception_ptr copy_exception( T const & e ); exception_ptr current_exception(); void rethrow_exception( exception_ptr const & ep ); template <class T> ---unspecified--- enable_current_exception( T const & e ); }
#include <boost/throw_exception.hpp>
#if !defined( BOOST_NO_EXCEPTIONS ) && !defined( BOOST_EXCEPTION_DISABLE )
#include <boost/exception/exception.hpp>
#include <boost/current_function.hpp>
#define BOOST_THROW_EXCEPTION(x)\
::boost::throw_exception( ::boost::enable_error_info(x) <<\
::boost::throw_function(BOOST_CURRENT_FUNCTION) <<\
::boost::throw_file(__FILE__) <<\
::boost::throw_line((int)__LINE__) )
#else
#define BOOST_THROW_EXCEPTION(x) ::boost::throw_exception(x)
#endif
namespace
boost
{
#ifdef BOOST_NO_EXCEPTIONS
void throw_exception( std::exception const & e ); // user defined
#else
template <class E>
void throw_exception( E const & e );
#endif
}
#include <boost/exception/exception.hpp>
namespace
boost
{
class
exception
{
protected:
exception();
exception( exception const & x );
~exception();
};
}
Class boost::exception is designed to be used as a universal base for user-defined exception types.
An object of any type deriving from boost::exception can store data of arbitrary types, using the error_info wrapper and operator<<.
To retrieve data from a boost::exception object, use the get_error_info function template.
#include <boost/exception/info.hpp>
namespace
boost
{
template <class Tag,class T>
class
error_info
{
public:
typedef T value_type;
error_info( value_type const & );
};
}
T must have accessible copy constructor and must not be a reference (there is no requirement that T's copy constructor does not throw.)
This class template is used to associate a Tag type with a value type T. Objects of type error_info<Tag,T> can be passed to operator<< to be stored in objects of type boost::exception.
The header <boost/exception/error_info.hpp> provides a declaration of the error_info template, which is sufficient for the purpose of typedefing an instance for specific Tag and T, like this:
#include <boost/exception/error_info.hpp> typedef boost::error_info<struct tag_errno,int> errno_info;
Of course, to actually add an error_info object to exceptions using operator<<, or to retrieve it using get_error_info, you must first #include <boost/exception/info.hpp>.
#include <boost/exception/info.hpp>
namespace
boost
{
template <class E, class Tag, class T>
E const & operator<<( E const & x, error_info<Tag,T> const & v );
}
E must be boost::exception, or a type that derives (indirectly) from boost::exception.
Stores a copy of v into x. If x already contains data of type error_info<Tag,T>, that data is overwritten.
x.
std::bad_alloc, or any exception emitted by the T copy constructor.
#include <boost/exception/info_tuple.hpp>
namespace
boost
{
template <class E, class Tag1, class T1, ..., class TagN, class TN>
E const & operator<<( E const & x,
tuple<
error_info<Tag1,T1>,
...,
error_info<TagN,TN> > const & v );
}
E must be boost::exception, or a type that derives (indirectly) from boost::exception.
Equivalent to x << v.get<0>() << ... << v.get<N>().
x.
std::bad_alloc, or any exception emitted by T1..TN copy constructor.
#include <boost/exception/get_error_info.hpp>
namespace
boost
{
template <class ErrorInfo,class E>
shared_ptr<typename ErrorInfo::value_type const> get_error_info( E const & x );
}
Nothing.
The interface of get_error_info may be affected by the build configuration macros.
#include <boost/exception/enable_error_info.hpp>
namespace
boost
{
template <class T>
---unspecified--- enable_error_info( T const & x );
}
T must be a class with an accessible no-throw copy constructor as per (15.5.1).
Nothing.
#include <boost/exception_ptr.hpp>
namespace
boost
{
typedef ---unspecified--- exception_ptr;
}
The exception_ptr type can be used to refer to a copy of an exception object. It is Default Constructible, Copy Constructible, Assignable and Equality Comparable; exception_ptr's operations do not throw.
Two instances of exception_ptr are equivalent and compare equal if and only if they refer to the same exception.
The default constructor of exception_ptr produces the null value of the type. The null value is equivalent only to itself.
#include <boost/exception/enable_current_exception.hpp>
namespace
boost
{
template <class T>
---unspecified--- enable_current_exception( T const & e );
}
T must be a class with an accessible no-throw copy constructor.
An object of unspecified type which derives publicly from T. That is, the returned object can be intercepted by a catch(T &).
This function is designed to be used directly in a throw-expression to enable the exception_ptr support in Boost Exception. For example:
class
my_exception:
public std::exception
{
};
....
throw boost::enable_current_exception(my_exception());
Unless enable_current_exception is called at the time an exception object is used in a throw-expression, an attempt to copy it using current_exception may return an exception_ptr which refers to an instance of unknown_exception. See current_exception for details.
Instead of using the throw keyword directly, it is preferable to call boost::throw_exception. This is guaranteed to throw an exception that derives from boost::exception and supports the exception_ptr functionality.
#include <boost/exception_ptr.hpp>
namespace
boost
{
exception_ptr current_exception();
}
The current_exception function must not be called outside of a catch block.
Nothing.
#include <boost/exception_ptr.hpp>
namespace
boost
{
template <class T>
exception_ptr copy_exception( T const & e );
}
As if
try { throw enable_current_exception(e); } catch(...) { return current_exception(); }
#include <boost/exception_ptr.hpp>
namespace
boost
{
void rethrow_exception( exception_ptr const & ep );
}
ep shall not be null.
The exception to which ep refers.
#include <boost/exception_ptr.hpp>
namespace
boost
{
class
unknown_exception:
public std::exception
public boost::exception
{
---unspecified---
};
}
This type is used by the exception_ptr support in Boost Exception. Please see current_exception.
#include <boost/exception/diagnostic_information.hpp>
namespace
boost
{
std::string diagnostic_information( boost::exception const & x );
}
This function iterates over all data objects stored in the boost::exception through operator<<. The returned string is constructed by converting each data object to string and then concatenating these strings together.
When the error_info<Tag,T> template is instantiated, the system attempts overload resolution for an unqualified call to to_string(x), where x is of type T. If this is successful, the to_string overload is expected to return std::string and is used to convert objects of type T to string.
Otherwise, the system attempts overload resolution for s << x, where s is a std::ostringstream and x is of type T. If this is successful, the operator<< overload is used to convert objects of type T to string.
Otherwise the system is unable to convert objects of type T to string, and an unspecified stub string value is used without issuing a compile error.
#include <boost/throw_exception.hpp>
namespace
boost
{
#ifdef BOOST_NO_EXCEPTIONS
void throw_exception( std::exception const & e ); // user defined
#else
template <class E>
void throw_exception( E const & e );
#endif
}
E must derive publicly from std::exception.
Peter Dimov has been continuously influencing the design and evolution of Boost Exception. Also thanks to Tobias Schwinger, Tom Brinkman, Pavel Vozenilek and everyone who participated in the review process.