diff --git a/doc/BOOST_THROW_EXCEPTION.html b/doc/BOOST_THROW_EXCEPTION.html new file mode 100644 index 0000000..d96f297 --- /dev/null +++ b/doc/BOOST_THROW_EXCEPTION.html @@ -0,0 +1,57 @@ + + + + + BOOST_THROW_EXCEPTION + + + +
+
+
+
+ +

Boost Exception

+
+ + + +

BOOST_THROW_EXCEPTION

+
+

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

This macro takes an exception object, records BOOST_CURRENT_FUNCTION, __FILE__ and __LINE__ in it, and forwards it to throw_exception. To recover this information at the catch site, use get_error_info; the information is also included in the message returned by diagnostic_information.

+
Boost Exception
+boost/throw_exception.hpp
+
+ + + + +
+
+
+ + diff --git a/doc/boost-exception.html b/doc/boost-exception.html index 58540c2..cb3f045 100644 --- a/doc/boost-exception.html +++ b/doc/boost-exception.html @@ -33,11 +33,10 @@
  • Documentation
    1. Class exception
    2. Transporting of Arbitrary Data to the Catch Site
      1. error_info
        2. -
      2. operator<</exception
        3. -
      3. operator<</tuple
        4. +
      4. exception/operator<<
        5. +
      5. tuple/operator<<
      6. get_error_info
      7. enable_error_info
        8. -
      8. BOOST_ERROR_INFO
    3. N2179 Transporting of Exceptions between Threads
      1. exception_ptr
        2. @@ -49,13 +48,15 @@
    4. diagnostic_information
      5. -
    5. throw_exception
      6. +
    6. throw_exception, BOOST_THROW_EXCEPTION
      7. +
    7. Configuration Macros
    8. Headers
      1. boost/exception.hpp
        2. -
      2. boost/exception/diagnostic_information.hpp
        3. -
      3. boost/exception/enable_current_exception.hpp
        4. +
      4. boost/exception/diagnostic_information.hpp
        5. +
      5. boost/exception/enable_current_exception.hpp
      6. boost/exception/enable_error_info.hpp
      7. boost/exception/error_info.hpp
      8. boost/exception/exception.hpp
        9. +
      9. boost/exception/get_error_info.hpp
      10. boost/exception/info.hpp
      11. boost/exception/info_tuple.hpp
      12. boost/exception_ptr.hpp
        13. @@ -74,16 +75,19 @@ boost class exception { - public: - - virtual char const * diagnostic_information() const throw(); - 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 @@ -96,23 +100,11 @@ boost error_info( value_type const & ); }; - template <class ErrorInfo,class E> - shared_ptr<typename ErrorInfo::value_type const> get_error_info( E const & x ); - - 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; - - #define BOOST_ERROR_INFO\ - ::boost::throw_function(BOOST_CURRENT_FUNCTION) <<\ - ::boost::throw_file(__FILE__) <<\ - ::boost::throw_line((int)__LINE__) - template <class E, class Tag, class T> - E const & operator<<( E const & x, error_info<Tag,T> const & v ); + 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, + E const & operator<<( E const & x, tuple< error_info<Tag1,T1>, ..., @@ -121,7 +113,7 @@ boost template <class T> ---unspecified--- enable_error_info( T const & x ); - std::string diagnostic_information( std::exception const & x ); + std::string diagnostic_information( boost::exception const & x ); class unknown_exception: @@ -142,18 +134,30 @@ boost 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
 
-    #ifdef BOOST_NO_EXCEPTIONS
-    
+namespace
+boost
+    {
+#ifdef BOOST_NO_EXCEPTIONS
     void throw_exception( std::exception const & e ); // user defined
-    
-    #else
-    
+#else
     template <class E>
     void throw_exception( E const & e );
-    
-    #endif
-    }
        +#endif         + }

        Class exception

        exception

        @@ -164,10 +168,6 @@ boost class exception { - public: - - virtual char const * diagnostic_information() const throw(); - protected: exception(); @@ -176,37 +176,9 @@ boost }; }

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

        +

        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.

        -

        exception::exception

        -
        -
        exception();
-exception( exception const & x );
        -

        Effects:

        -
        • Default constructor: initializes an empty boost::exception object.
          • -
        • Copy constructor: initializes a boost::exception object which shares with x all data added through operator<<, including data that is added at a future time.
          • -
        -

        Throws:

        -

        Nothing.

        -

        exception::~exception

        -
        -
        ~exception();
        -

        Effects:

        -

        Frees all resources associated with a boost::exception object.

        -

        Throws:

        -

        Nothing.

        -

        exception::diagnostic_information

        -
        -
        virtual char const * diagnostic_information() const throw();
        -

        Returns:

        -

        A string representation of all data stored in the boost::exception object by the operator<< function. See "Diagnostic Information" for details.

        -

        Throws:

        -

        Nothing.

        -

        Notes:

        -
        -

      Transporting of Arbitrary Data to the Catch Site

      +

    Transporting of Arbitrary Data to the Catch Site

    error_info

    #include <boost/exception/info.hpp>

    @@ -227,21 +199,21 @@ boost

    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.

    +

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

    -

    operator<</exception

    +

    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 );
+    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.

    @@ -251,14 +223,14 @@ boost

    x.

    Throws:

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

    -

    operator<</tuple

    +

    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,
+    E const & operator<<( E const & x,
         tuple<
             error_info<Tag1,T1>,
             ...,
@@ -274,7 +246,7 @@ boost
 
    std::bad_alloc, or any exception emitted by T1..TN copy constructor.

    get_error_info

    -

    #include <boost/exception/info.hpp>

    +

    #include <boost/exception/get_error_info.hpp>

    namespace
 boost
     {
@@ -284,13 +256,16 @@ boost

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

    @@ -301,29 +276,13 @@ boost ---unspecified--- enable_error_info( T const & x ); }

    Requirements:

    -

    T must be a user-defined type with accessible no-throw copy constructor as per (15.5.1).

    +

    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.

    -

    BOOST_ERROR_INFO

    -
    -

    #include <boost/exception/info.hpp>

    -
    namespace
-boost
-    {
-    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;
-    
-    #define BOOST_ERROR_INFO\
-        ::boost::throw_function(BOOST_CURRENT_FUNCTION) <<\
-        ::boost::throw_file(__FILE__) <<\
-        ::boost::throw_line((int)__LINE__)
-    }
    -

    This macro is designed to be used with operator<< when throwing a boost::exception, to store information about the location of the throw statement. It can be chained with other error_infos in a single throw expression.

    Transporting of Exceptions between Threads

    exception_ptr

    @@ -336,9 +295,14 @@ boost

    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>

    +

    #include <boost/exception/enable_current_exception.hpp>

    namespace
 boost
     {
@@ -346,7 +310,7 @@ boost
     ---unspecified--- enable_current_exception( T const & e );
     }

    Requirements:

    -

    T must be of user-defined type with an accessible no-throw copy constructor.

    +

    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:

    @@ -392,7 +356,15 @@ boost exception_ptr copy_exception( T const & e ); }

    Effects:

    -

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

    +

    As if

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

    rethrow_exception

    #include <boost/exception_ptr.hpp>

    @@ -423,14 +395,23 @@ boost

    Printing Diagnostic Information

    diagnostic_information

    -

    #include <boost/exception/diagnostic_information.hpp>

    +

    #include <boost/exception/diagnostic_information.hpp> 

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

    Returns:

    -

    If dynamic_cast<boost::exception const *>(&x) is not null, the returned string is initialized by a call to exception::diagnostic_information; otherwise, the returned string combines the output of x.what() and typeid(x).name().

    +

    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.

    +

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

    Throwing Exceptions

    throw_exception

    @@ -438,16 +419,12 @@ boost 
    namespace
 boost
     {
-    #ifdef BOOST_NO_EXCEPTIONS
-    
+#ifdef BOOST_NO_EXCEPTIONS
     void throw_exception( std::exception const & e ); // user defined
-    
-    #else
-    
+#else
     template <class E>
     void throw_exception( E const & e );
-    
-    #endif
+#endif
     }

    Requirements:

    E must derive publicly from std::exception.

    @@ -455,7 +432,9 @@ boost
    • 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.

    +