# Boost Exception

## Introduction

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.

## Contents

1. Tutorial
   1. Transporting of Arbitrary Data to the Catch Site
   2. Diagnostic Information
   3. Integrating Boost Exception in Existing Exception Class Hierarchies
   4. Transporting of Exceptions Between Threads
2. Documentation
   1. Class exception
   2. Transporting of Arbitrary Data to the Catch Site
      1. error_info
      2. exception/operator<<
      3. tuple/operator<<
      4. get_error_info
      5. enable_error_info
   3. N2179 Transporting of Exceptions between Threads
      1. exception_ptr
      2. enable_current_exception
      3. current_exception
      4. copy_exception
      5. rethrow_exception
      6. unknown_exception
   4. diagnostic_information
   5. throw_exception, BOOST_THROW_EXCEPTION
   6. Configuration Macros
   7. Headers
      1. boost/exception.hpp
      2. boost/exception/diagnostic_information.hpp
      3. boost/exception/enable_current_exception.hpp
      4. boost/exception/enable_error_info.hpp
      5. boost/exception/error_info.hpp
      6. boost/exception/exception.hpp
      7. boost/exception/get_error_info.hpp
      8. boost/exception/info.hpp
      9. boost/exception/info_tuple.hpp
      10. boost/exception_ptr.hpp
      11. boost/throw_exception.hpp
3. Index

## Synopsis

#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 & v );
            value_type const & value() 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 & );

        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
        }

## Class exception

### exception

#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.

## Transporting of Arbitrary Data to the Catch Site

### error_info

#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 & v );
            value_type const & value() const;
            };
        }

#### Requirements:

T must have accessible copy constructor and must not be a reference (there is no requirement that T's copy constructor does not throw.)

#### Description:

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.

#### Note:

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>.

### exception/operator<<

#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 );
        }

#### Requirements:

E must be boost::exception, or a type that derives (indirectly) from boost::exception.

#### Effects:

Stores a copy of v into x. If x already contains data of type error_info<Tag,T>, that data is overwritten.

#### Returns:

x.

#### Throws:

std::bad_alloc, or any exception emitted by the T copy constructor.

### tuple/operator<<

#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 );
        }

#### Requirements:

E must be boost::exception, or a type that derives (indirectly) from boost::exception.

#### Effects:

Equivalent to x << v.get<0>() << ... << v.get<N>().

#### Returns:

x.

#### Throws:

std::bad_alloc, or any exception emitted by T1..TN copy constructor.

### get_error_info

#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 );
        }

#### Requirements:

- ErrorInfo must be an instance of the error_info template.
- E must be polymorphic.
- The get_error_info function must not be called outside of a catch block.

#### Returns:

- If dynamic_cast<boost::exception const *>(&x) is 0, or if x does not store an object of type ErrorInfo, the returned value is an empty shared_ptr.
- Otherwise, the returned shared_ptr points to the stored value (use operator<< to store values in exception objects.) The shared_ptr is valid even after x has been destroyed.

#### Throws:

Nothing.

#### Note:

The interface of get_error_info may be affected by the build configuration macros.

### enable_error_info

#include <boost/exception/enable_error_info.hpp>

    namespace
    boost
        {
        template <class T>
        ---unspecified--- enable_error_info( T const & x );
        }

#### Requirements:

T must be a class with an accessible no-throw copy constructor as per (15.5.1).

#### Returns:

- If T derives from boost::exception, the returned object is of type T and is a copy of x.
- Otherwise, the returned object is of an unspecified type that derives publicly from both T and boost::exception. The T sub-object is initialized from x by the T copy constructor.

#### Throws:

Nothing.

## Transporting of Exceptions between Threads

### exception_ptr

#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.

#### Thread safety

- It is legal for multiple threads to hold exception_ptr references to the same exception object.
- It is illegal for multiple threads to modify the same exception_ptr object concurrently.
- While calling current_exception makes a copy of the current exception object, it is still possible for the two copies to share internal state. Therefore, in general it is not safe to call rethrow_exception concurrently to throw the same exception object into multiple threads.

### enable_current_exception

#include <boost/exception/enable_current_exception.hpp>

    namespace
    boost
        {
        template <class T>
        ---unspecified--- enable_current_exception( T const & e );
        }

#### Requirements:

T must be a class with an accessible no-throw copy constructor.

#### Returns:

An object of unspecified type which derives publicly from T. That is, the returned object can be intercepted by a catch(T &).

#### Description:

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.

#### Note:

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.

### current_exception

#include <boost/exception_ptr.hpp>

    namespace
    boost
        {
        exception_ptr current_exception();
        }

#### Requirements:

The current_exception function must not be called outside of a catch block.

#### Returns:

- An exception_ptr that refers to the currently handled exception or a copy of the currently handled exception.
- If the function needs to allocate memory and the attempt fails, it returns an exception_ptr that refers to an instance of std::bad_alloc.

#### Throws:

Nothing.

#### Notes:

- It is unspecified whether the return values of two successive calls to current_exception refer to the same exception object.
- Correct implementation of current_exception may require compiler support, unless enable_current_exception was used at the time the currently handled exception object was passed to throw. If enable_current_exception was not used, and if the compiler does not provide the necessary support, then current_exception may return an exception_ptr that refers to an instance of unknown_exception. In this case, if the original exception object derives from boost::exception, then the boost::exception sub-object of the unknown_exception object is initialized by the boost::exception copy constructor.

### copy_exception

#include <boost/exception_ptr.hpp>

    namespace
    boost
        {
        template <class T>
        exception_ptr copy_exception( T const & e );
        }

#### Effects:

As if

    try
        {
        throw enable_current_exception(e);
        }
    catch(...)
        {
        return current_exception();
        }

### rethrow_exception

#include <boost/exception_ptr.hpp>

    namespace
    boost
        {
        void rethrow_exception( exception_ptr const & ep );
        }

#### Precondition:

ep shall not be null.

#### Throws:

The exception to which ep refers.

### unknown_exception

#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.

## Printing Diagnostic Information

### diagnostic_information

#include <boost/exception/diagnostic_information.hpp>

    namespace
    boost
        {
        std::string diagnostic_information( boost::exception const & );
        }

#### Returns:

This function returns a string value that is automatically composed from the string representations of all error_info objects stored in a boost::exception through operator<<, along with other diagnostic information relevant to the exception.

The string representation of each error_info object is deduced by a function call that is bound at the time the error_info<Tag,T> template is instantiated. The following overload resolutions are attempted in order:

1. Unqualified call to to_string(x), where x is of type error_info<Tag,T> (the return value is expected to be of type std::string.)
2. Unqualified call to to_string(x.value()) (the return value is expected to be of type std::string.)
3. Unqualified call to s << x.value(), where s is a std::ostringstream.

The first successfully bound function is used at the time diagnostic_information is called; if all 3 overload resolutions are unsuccessful, the system is unable to convert the error_info object to string, and an unspecified stub string value is used without issuing a compile error.

#### Notes:

- The format of the returned string is unspecified.
- The returned string is not user-friendly.
- If dynamic_cast<std::exception const *>(&x) is not null, the returned string includes the output from std::exception::what.
- The returned string may include additional platform-specific diagnostic information.

#### Example:

this is a possible output from the diagnostic_information function, as used in libs/exception/example/example_io.cpp:

    libs\exception\example\example_io.cpp(83): Throw in function class boost::shared_ptr<struct _iobuf> __cdecl my_fopen(const char *,const char *)
    Dynamic exception type: class boost::exception_detail::clone_impl<class fopen_error>
    std::exception::what: example_io error
    [struct tag_errno *] = 2, OS says "No such file or directory"
    [struct tag_file_name *] = tmp1.txt
    [struct tag_function *] = fopen
    [struct tag_open_mode *] = rb

## Throwing Exceptions

### throw_exception

#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
        }

#### Requirements:

E must derive publicly from std::exception.

#### Effects:

- If BOOST_NO_EXCEPTIONS is not defined, boost::throw_exception(e) is equivalent to throw boost::enable_current_exception(boost::enable_error_info(e)), unless BOOST_EXCEPTION_DISABLE is defined, in which case boost::throw_exception(e) is equivalent to throw e;
- If BOOST_NO_EXCEPTIONS is defined, the function is left undefined, and the user is expected to supply an appropriate definition. Callers of throw_exception are allowed to assume that the function never returns; therefore, if the user-defined throw_exception returns, the behavior is undefined.

## Acknowledgements

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.