From bf515d83cab5c2f6bc9ba8c0aa12214366636e16 Mon Sep 17 00:00:00 2001 From: Emil Dotchevski Date: Tue, 4 Mar 2008 01:41:17 +0000 Subject: [PATCH] boost exception [SVN r43485] --- doc/BOOST_ERROR_INFO.html | 51 +++ doc/adding_data_at_throw.html | 73 ++++ doc/adding_data_later.html | 116 +++++ doc/boost-exception.html | 410 ++++++++++++++++++ doc/clone_exception.html | 55 +++ doc/cloning.html | 98 +++++ doc/cloning_and_rethrowing.html | 75 ++++ doc/enable_error_info.html | 52 +++ doc/enable_exception_cloning.html | 65 +++ doc/error_info.html | 73 ++++ doc/exception.html | 97 +++++ doc/exception_cloning_hpp.html | 40 ++ doc/exception_constructors.html | 45 ++ doc/exception_destructor.html | 42 ++ doc/exception_enable_error_info_hpp.html | 37 ++ ...xception_enable_exception_cloning_hpp.html | 37 ++ doc/exception_error_info_group_hpp.html | 37 ++ doc/exception_error_info_hpp.html | 40 ++ doc/exception_error_info_value_hpp.html | 41 ++ doc/exception_exception_hpp.html | 37 ++ doc/exception_hpp.html | 45 ++ doc/exception_ptr.html | 50 +++ doc/exception_what.html | 45 ++ doc/get_error_info.html | 52 +++ doc/grouping_data.html | 62 +++ doc/logging.html | 60 +++ doc/name_idx.html | 68 +++ doc/operator_shl_exception.html | 67 +++ doc/reno.css | 218 ++++++++++ doc/rethrow_exception.html | 47 ++ doc/shade-l.png | Bin 0 -> 948 bytes doc/shade-r.png | Bin 0 -> 946 bytes doc/throw_exception.html | 54 +++ doc/throw_exception_hpp.html | 37 ++ doc/transporting_data.html | 182 ++++++++ doc/unknown_exception.html | 53 +++ doc/using_enable_cloning.html | 54 +++ doc/using_enable_error_info.html | 66 +++ doc/valid-css.png | Bin 0 -> 5130 bytes doc/valid-xhtml.png | Bin 0 -> 5805 bytes example/Jamfile | 15 + example/cloning_1.cpp | 22 + example/cloning_2.cpp | 39 ++ example/enable_error_info.cpp | 35 ++ example/error_info_1.cpp | 36 ++ example/error_info_2.cpp | 49 +++ example/example_io.cpp | 215 +++++++++ example/info_tuple.cpp | 31 ++ example/logging.cpp | 25 ++ include/boost/exception/cloning.hpp | 58 +++ .../boost/exception/detail/cloning_base.hpp | 27 ++ .../boost/exception/detail/counted_base.hpp | 38 ++ include/boost/exception/enable_error_info.hpp | 69 +++ .../exception/enable_exception_cloning.hpp | 148 +++++++ include/boost/exception/error_info.hpp | 16 + include/boost/exception/exception.hpp | 90 ++++ include/boost/exception/info.hpp | 233 ++++++++++ include/boost/exception/info_tuple.hpp | 64 +++ include/boost/exception/to_string.hpp | 27 ++ include/boost/exception/to_string_stub.hpp | 148 +++++++ test/Jamfile | 20 + test/boost_error_info_test.cpp | 40 ++ test/cloning_test.cpp | 42 ++ test/enable_error_info_test.cpp | 49 +++ test/errno_test.cpp | 33 ++ test/error_info_test.cpp | 217 +++++++++ test/exception_fail.cpp | 12 + test/exception_test.cpp | 35 ++ test/helper1.cpp | 21 + test/helper1.hpp | 19 + test/helper2.cpp | 53 +++ test/helper2.hpp | 47 ++ test/throw_exception_test.cpp | 71 +++ test/to_string_test.cpp | 97 +++++ test/unknown_exception_test.cpp | 84 ++++ test/what_test.cpp | 27 ++ 76 files changed, 4933 insertions(+) create mode 100644 doc/BOOST_ERROR_INFO.html create mode 100644 doc/adding_data_at_throw.html create mode 100644 doc/adding_data_later.html create mode 100644 doc/boost-exception.html create mode 100644 doc/clone_exception.html create mode 100644 doc/cloning.html create mode 100644 doc/cloning_and_rethrowing.html create mode 100644 doc/enable_error_info.html create mode 100644 doc/enable_exception_cloning.html create mode 100644 doc/error_info.html create mode 100644 doc/exception.html create mode 100644 doc/exception_cloning_hpp.html create mode 100644 doc/exception_constructors.html create mode 100644 doc/exception_destructor.html create mode 100644 doc/exception_enable_error_info_hpp.html create mode 100644 doc/exception_enable_exception_cloning_hpp.html create mode 100644 doc/exception_error_info_group_hpp.html create mode 100644 doc/exception_error_info_hpp.html create mode 100644 doc/exception_error_info_value_hpp.html create mode 100644 doc/exception_exception_hpp.html create mode 100644 doc/exception_hpp.html create mode 100644 doc/exception_ptr.html create mode 100644 doc/exception_what.html create mode 100644 doc/get_error_info.html create mode 100644 doc/grouping_data.html create mode 100644 doc/logging.html create mode 100644 doc/name_idx.html create mode 100644 doc/operator_shl_exception.html create mode 100644 doc/reno.css create mode 100644 doc/rethrow_exception.html create mode 100644 doc/shade-l.png create mode 100644 doc/shade-r.png create mode 100644 doc/throw_exception.html create mode 100644 doc/throw_exception_hpp.html create mode 100644 doc/transporting_data.html create mode 100644 doc/unknown_exception.html create mode 100644 doc/using_enable_cloning.html create mode 100644 doc/using_enable_error_info.html create mode 100644 doc/valid-css.png create mode 100644 doc/valid-xhtml.png create mode 100644 example/Jamfile create mode 100644 example/cloning_1.cpp create mode 100644 example/cloning_2.cpp create mode 100644 example/enable_error_info.cpp create mode 100644 example/error_info_1.cpp create mode 100644 example/error_info_2.cpp create mode 100644 example/example_io.cpp create mode 100644 example/info_tuple.cpp create mode 100644 example/logging.cpp create mode 100644 include/boost/exception/cloning.hpp create mode 100644 include/boost/exception/detail/cloning_base.hpp create mode 100644 include/boost/exception/detail/counted_base.hpp create mode 100644 include/boost/exception/enable_error_info.hpp create mode 100644 include/boost/exception/enable_exception_cloning.hpp create mode 100644 include/boost/exception/error_info.hpp create mode 100644 include/boost/exception/exception.hpp create mode 100644 include/boost/exception/info.hpp create mode 100644 include/boost/exception/info_tuple.hpp create mode 100644 include/boost/exception/to_string.hpp create mode 100644 include/boost/exception/to_string_stub.hpp create mode 100644 test/Jamfile create mode 100644 test/boost_error_info_test.cpp create mode 100644 test/cloning_test.cpp create mode 100644 test/enable_error_info_test.cpp create mode 100644 test/errno_test.cpp create mode 100644 test/error_info_test.cpp create mode 100644 test/exception_fail.cpp create mode 100644 test/exception_test.cpp create mode 100644 test/helper1.cpp create mode 100644 test/helper1.hpp create mode 100644 test/helper2.cpp create mode 100644 test/helper2.hpp create mode 100644 test/throw_exception_test.cpp create mode 100644 test/to_string_test.cpp create mode 100644 test/unknown_exception_test.cpp create mode 100644 test/what_test.cpp diff --git a/doc/BOOST_ERROR_INFO.html b/doc/BOOST_ERROR_INFO.html new file mode 100644 index 0000000..c3f2ef9 --- /dev/null +++ b/doc/BOOST_ERROR_INFO.html @@ -0,0 +1,51 @@ + + + + + BOOST_ERROR_INFO + + + +
+
+
+
+ +

Boost Exception

+
+

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.

+

See also:

+ + +
+
+
+ + diff --git a/doc/adding_data_at_throw.html b/doc/adding_data_at_throw.html new file mode 100644 index 0000000..7e4af8a --- /dev/null +++ b/doc/adding_data_at_throw.html @@ -0,0 +1,73 @@ + + + + + Tutorial: Adding of Arbitrary Data at the Point of the Throw + + + +
+
+
+
+ +

Boost Exception

+
+

Adding of Arbitrary Data at the Point of the Throw

+

The following example demonstrates how errno can be stored in exception objects using Boost Exception:

+
#include <boost/exception.hpp>
+#include <errno.h>
+#include <iostream>
+
+typedef boost::error_info<struct tag_errno,int> errno_info; //(1)
+
+class my_error: public boost::exception, public std::exception { }; //(2)
+
+void
+f()
+    {
+    throw my_error() << errno_info(errno); //(3)
+    }
+
+

First, we instantiate the error_info template using a unique identifier -- tag_errno, and the type of the info it identifies -- int. This provides compile-time type safety for the various values stored in exception objects.

+

Second, we define class my_error, which derives from boost::exception.

+

Finally, (3) illustrates how the typedef from (1) can be used with operator<<() to store values in exception objects at the point of the throw.

+

The stored errno value can be recovered at a later time like this:

+
// ...continued
+
+void
+g()
+    {
+    try
+        {
+        f();
+        }
+    catch(
+    my_error & x )
+        {
+        if( boost::shared_ptr<int const> err=boost::get_error_info<errno_info>(x) )
+            std::cerr << "Error code: " << *err;
+        }
+    }
+

The get_error_info() function template is instantiated with the typedef from (1), and is passed an exception object of any type that derives publicly from boost::exception. If the exception object contains the requested value, the returned shared_ptr will point to it; otherwise an empty shared_ptr is returned.

+

See also:

+ + +
+
+
+ + diff --git a/doc/adding_data_later.html b/doc/adding_data_later.html new file mode 100644 index 0000000..eea907a --- /dev/null +++ b/doc/adding_data_later.html @@ -0,0 +1,116 @@ + + + + + Tutorial: Adding of Arbitrary Data to Active Exception Objects + + + +
+
+
+
+ +

Boost Exception

+
+

Adding of Arbitrary Data to Active Exception Objects

+

Sometimes the throw site does not have all the information that is needed at the catch site to make sense of what went wrong. Here is an example:

+
#include <stdio.h>
+#include <string>
+        
+class
+file_read_error
+    {
+    public:
+
+    explicit
+    file_read_error( std::string const & fn ):
+        fn_(fn)
+        {
+        };
+
+    std::string const &
+    file_name() const
+        {
+        return fn_;
+        }
+
+    private:
+
+    std::string fn_;
+    };
+
+void
+file_read( FILE * f, void * buffer, size_t size )
+    {
+    if( size!=fread(buffer,1,size,f) )
+        throw file_read_error("????");
+    }
+

We have defined an exception class file_read_error which can store a file name, so that when we catch a file_read_error object, we know which file the failure is related to. However, the file_read function does not have the file name at the time of the throw; all it has is a FILE handle.

+

One possible solution is to not use FILE handles directly. We could have our own class file which stores both a FILE handle and a file name, and pass that to file_read(). However, this could be problematic if we communicate with 3rd party code that does not use our class file (probably because they have their own similar class.)

+

A better solution is to make class file_read_error derive (possibly indirectly) from boost::exception, and free the file_read() function from the burden of storing the file name in exceptions it throws:

+
#include <boost/exception.hpp>
+#include <stdio.h>
+#include <errno.h>
+
+typedef boost::error_info<struct tag_errno,int> errno_info;
+
+class file_read_error: public boost::exception { };
+
+void
+file_read( FILE * f, void * buffer, size_t size )
+    {
+    if( size!=fread(buffer,1,size,f) )
+        throw file_read_error() << errno_info(errno);
+    }
+

If file_read() detects a failure, it throws an exception which contains the information that is available at the time, namely the errno. Other relevant information, such as the file name, can be added in a context higher up the call stack, where it is known naturally:

+
#include <boost/exception.hpp>
+#include <boost/shared_ptr.hpp>
+#include <stdio.h>
+#include <string>
+
+typedef boost::error_info<struct tag_file_name,std::string> file_name_info;
+
+boost::shared_ptr<FILE> file_open( char const * file_name, char const * mode );
+void file_read( FILE * f, void * buffer, size_t size );
+
+void
+parse_file( char const * file_name )
+    {
+    boost::shared_ptr<FILE> f = file_open(file_name,"rb");
+    assert(f);
+    try
+        {
+        char buf[1024];
+        file_read( f.get(), buf, sizeof(buf) );
+        }
+    catch(
+    boost::exception & e )
+        {
+        e << file_name_info(file_name);
+        throw;
+        }
+    }
+

The above function is (almost) exception-neutral -- if an exception is emitted by any function call within the try block, parse_file() does not need to do any real work, but it intercepts any boost::exception object, stores the file name, and re-throws using a throw-expression with no operand (15.1.6). The rationale for catching any boost::exception object is that the file name is relevant to any failure that occurs in parse_file(), even if the failure is unrelated to file I/O.

+

As usual, the stored data can be retrieved using get_error_info().

+

See also:

+ + +
+
+
+ + diff --git a/doc/boost-exception.html b/doc/boost-exception.html new file mode 100644 index 0000000..daa815a --- /dev/null +++ b/doc/boost-exception.html @@ -0,0 +1,410 @@ + + + + + Boost Exception + + + +
+
+
+
+ +

Boost Exception

+
+

Abstract

+

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 classes. 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 cloning of exception objects, implemented non-intrusively and automatically by the boost::throw_exception() function.

+

Note:

+

Boost Exception was accepted as a Boost library on November 7, 2007; however it has not yet been part of an official Boost release.

+

Contents

+
  1. Tutorial +
  2. +
  3. Documentation +
  4. +
  5. Index
  6. +
  7. Download
  8. +
  9. Browse source code
  10. +
+

Synopsis

+

#include <boost/exception.hpp>

+
namespace
+boost
+    {
+    class
+    exception
+        {
+        public:
+
+        virtual char const * what() const throw();
+
+        protected:
+
+        exception();
+        exception( exception const & x );
+        ~exception();
+
+        private:
+
+        ---unspecified---
+        };
+
+    template <class Tag,class T>
+    class
+    error_info
+        {
+        public:
+
+        typedef T value_type;
+
+        error_info( value_type const & );
+
+        private:
+
+        ---unspecified---
+        };
+
+    template <class E, class Tag1, class T1>
+    E const & operator<<( E const & x, error_info<Tag1,T1> 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 ErrorInfo,class E>
+    shared_ptr<typename ErrorInfo::value_type const> get_error_info( E const & x );
+
+    template <class T>
+    ---unspecified--- enable_error_info( T 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__)
+
+    typedef ---unspecified--- exception_ptr;
+
+    template <class T>
+    ---unspecified--- enable_exception_cloning( T const & e );
+
+    template <class T>
+    exception_ptr clone_exception( T const & e );
+    void rethrow_exception( exception_ptr const & ep );
+
+    class
+    unknown_exception:
+        public std::exception
+        public boost::exception
+        {
+        ---unspecified---
+        };
+
+#ifdef BOOST_NO_EXCEPTIONS
+    void throw_exception( std::exception const & e ); // user defined
+#else
+    template <class E>
+    void throw_exception( E const & e );
+#endif
+    }
+

exception

+

#include <boost/exception/exception.hpp>

+
namespace
+boost
+    {
+    class
+    exception
+        {
+        public:
+
+        virtual char const * what() const throw();
+
+        protected:
+
+        exception();
+        exception( exception const & x );
+        ~exception();
+
+        private:
+
+        ---unspecified---
+        };
+    }
+

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.

+

exception constructors

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

+

Effects:

+

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

+

Throws:

+

Nothing.

+

exception::what()

+
        virtual char const * what() const throw();
+

Returns:

+

An string representation of all data stored in the boost::exception object by the operator<<() function. See "Tutorial: Logging of boost::exception Objects" for details.

+

Throws:

+

Nothing.

+

Note:

+

The return value remains valid until the exception object from which it is obtained is destroyed or modified.

+

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 & );
+
+        private:
+
+        ---unspecified---
+        };
+    }
+

Requirements:

+

T must have accessible copy constructor and must not be a reference.

+

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 errno_info object to exceptions using operator<<(), or to retrieve it using get_error_info(), you must first #include <boost/exception/info.hpp>.

+

operator<<()

+

#include <boost/exception/info.hpp> 
#include <boost/exception/info_tuple.hpp>

+
namespace
+boost
+    {
+    template <class E, class Tag1, class T1>
+    E const & operator<<( E const & x, error_info<Tag1,T1> 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 );
+    }
+

Requirements:

+

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

+

Effects:

+
  • The first overload stores a copy of v into x. If x already contains data of type error_info<Tag1,T1>, that data is overwritten.
  • +
  • The boost::tuple overload is 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/info.hpp>

+
namespace
+boost
+    {
+    template <class ErrorInfo,class E>
+    shared_ptr<typename ErrorInfo::value_type const> get_error_info( E const & x );
+    }
+

Requirements:

+

The type of the x object must derive from boost::exception; ErrorInfo must be an instance of the error_info template.

+

Returns:

+

If x does not store an object of type ErrorInfo, returns an empty shared_ptr; otherwise returns pointer to the stored value. Use operator<<() to store values in exception objects.

+

Throws:

+

Nothing.

+

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 user-defined type with accessible no-throw copy constructor.

+

Returns:

+

An object of unspecified type with no-throw copy semantics, which derives publicly from both T, and class boost::exception. The T sub-object is initialized from x by the T copy constructor. If T already derives from boost::exception, then the type of the returned object does not derive boost::exception.

+

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

+

#include <boost/exception/cloning.hpp>

+
namespace
+boost
+    {
+    typedef ---unspecified--- exception_ptr;
+    }
+

The exception_ptr type can be used to refer to a copy of a boost::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.

+

enable_exception_cloning()

+

#include <boost/exception/enable_exception_cloning.hpp>

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

Requirements:

+

T must have 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 cloning support in Boost Exception. For example:

+
class
+my_exception:
+    public std::exception
+    {
+    };
+
+....
+throw boost::enable_exception_cloning(my_exception());
+

Unless enable_exception_cloning() is called at the time an exception object is used in a throw-expression, any attempt to copy it using clone_exception() returns an exception_ptr which refers to an instance of unknown_exception.

+

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

+

clone_exception()

+

#include <boost/exception/cloning.hpp>

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

Requirements:

+

T must be polymorphic.

+

Returns:

+
+

Note:

+

It is unspecified whether the return values of two successive calls to clone_exception() refer to the same exception object.

+

rethrow_exception()

+

#include <boost/exception/cloning.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/cloning.hpp>

+
namespace
+boost
+    {
+    class
+    unknown_exception:
+        public std::exception
+        public boost::exception
+        {
+        ---unspecified---
+        };
+    }
+

This type is used by the cloning support in Boost Exception.

+

To allow an exception to be cloned, enable_exception_cloning() must be used at the time the exception object is passed to throw. Otherwise, calling clone_exception() returns an exception_ptr which refers to an instance of unknown_exception.

+

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

Effects:

+
  • If BOOST_NO_EXCEPTIONS is not defined, boost::throw_exception(e) is equivalent to throw boost::enable_exception_cloning(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.
  • +
+
+
+
+
+ + diff --git a/doc/clone_exception.html b/doc/clone_exception.html new file mode 100644 index 0000000..a594a56 --- /dev/null +++ b/doc/clone_exception.html @@ -0,0 +1,55 @@ + + + + + clone_exception + + + +
+
+
+
+ +

Boost Exception

+
+

clone_exception()

+

#include <boost/exception/cloning.hpp>

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

Requirements:

+

T must be polymorphic.

+

Returns:

+
+

Note:

+

It is unspecified whether the return values of two successive calls to clone_exception() refer to the same exception object.

+

See also:

+ + +
+
+
+ + diff --git a/doc/cloning.html b/doc/cloning.html new file mode 100644 index 0000000..1075b14 --- /dev/null +++ b/doc/cloning.html @@ -0,0 +1,98 @@ + + + + + Tutorial: Transporting of Exceptions between Threads + + + +
+
+
+
+ +

Boost Exception

+
+

Transporting of Exceptions between Threads

+

Boost Exception supports transporting of exception objects between threads through cloning. This system is similar to N2179, but because Boost Exception can not rely on language support, the use of enable_exception_cloning() at the time of the throw is required in order to use cloning.

+

Note:

+

All exceptions emitted by the familiar function boost::throw_exception() are guaranteed to derive from boost::exception and to support cloning.

+

Using enable_exception_cloning() at the Time of the Throw

+

Here is how cloning can be enabled in a throw-expression (15.1):

+
#include <boost/exception/enable_exception_cloning.hpp>
+#include <boost/exception/info.hpp>
+#include <stdio.h>
+#include <errno.h>
+
+typedef boost::error_info<struct tag_errno,int> errno_info;
+
+class file_read_error: public boost::exception { };
+
+void
+file_read( FILE * f, void * buffer, size_t size )
+    {
+    if( size!=fread(buffer,1,size,f) )
+        throw boost::enable_exception_cloning(file_read_error()) <<
+            errno_info(errno);
+    }
+

Cloning and Re-throwing an Exception

+

When you catch a boost::exception, you can call clone_exception() to get an exception_ptr object:

+
#include <boost/exception/cloning.hpp>
+#include <boost/thread.hpp>
+#include <boost/bind.hpp>
+
+void do_work(); //throws cloning-enabled boost::exceptions
+
+void
+worker_thread( boost::exception_ptr & error )
+    {
+    try
+        {
+        do_work();
+        error = boost::exception_ptr();
+        }
+    catch(
+    boost::exception & e )
+        {
+        error = boost::clone_exception(e);
+        }
+    }
+

In the above example, note that clone_exception() captures the original type of the exception object, even though e refers to the base type boost::exception. This original type can be thrown again using the rethrow_exception() function:

+
// ...continued
+
+void
+work()
+    {
+    boost::exception_ptr error;
+    boost::thread t( boost::bind(worker_thread,boost::ref(error)) );
+    t.join();
+    if( error )
+        boost::rethrow_exception(error);
+    }
+

Clone_exception() could fail to copy the original exception object in the following cases:

+
+

Regardless, the use of clone_exception() and rethrow_exception() in the above examples is well-formed.

+

See also:

+ + +
+
+
+ + diff --git a/doc/cloning_and_rethrowing.html b/doc/cloning_and_rethrowing.html new file mode 100644 index 0000000..e7a53eb --- /dev/null +++ b/doc/cloning_and_rethrowing.html @@ -0,0 +1,75 @@ + + + + + Tutorial: Cloning and Re-throwing an Exception + + + +
+
+
+
+ +

Boost Exception

+
+

Cloning and Re-throwing an Exception

+

When you catch a boost::exception, you can call clone_exception() to get an exception_ptr object:

+
#include <boost/exception/cloning.hpp>
+#include <boost/thread.hpp>
+#include <boost/bind.hpp>
+
+void do_work(); //throws cloning-enabled boost::exceptions
+
+void
+worker_thread( boost::exception_ptr & error )
+    {
+    try
+        {
+        do_work();
+        error = boost::exception_ptr();
+        }
+    catch(
+    boost::exception & e )
+        {
+        error = boost::clone_exception(e);
+        }
+    }
+

In the above example, note that clone_exception() captures the original type of the exception object, even though e refers to the base type boost::exception. This original type can be thrown again using the rethrow_exception() function:

+
// ...continued
+
+void
+work()
+    {
+    boost::exception_ptr error;
+    boost::thread t( boost::bind(worker_thread,boost::ref(error)) );
+    t.join();
+    if( error )
+        boost::rethrow_exception(error);
+    }
+

Clone_exception() could fail to copy the original exception object in the following cases:

+
+

Regardless, the use of clone_exception() and rethrow_exception() in the above examples is well-formed.

+

See also:

+ + +
+
+
+ + diff --git a/doc/enable_error_info.html b/doc/enable_error_info.html new file mode 100644 index 0000000..d976583 --- /dev/null +++ b/doc/enable_error_info.html @@ -0,0 +1,52 @@ + + + + + enable_error_info + + + +
+
+
+
+ +

Boost Exception

+
+

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 user-defined type with accessible no-throw copy constructor.

+

Returns:

+

An object of unspecified type with no-throw copy semantics, which derives publicly from both T, and class boost::exception. The T sub-object is initialized from x by the T copy constructor. If T already derives from boost::exception, then the type of the returned object does not derive boost::exception.

+

Throws:

+

Nothing.

+

See also:

+ + +
+
+
+ + diff --git a/doc/enable_exception_cloning.html b/doc/enable_exception_cloning.html new file mode 100644 index 0000000..4e55e33 --- /dev/null +++ b/doc/enable_exception_cloning.html @@ -0,0 +1,65 @@ + + + + + enable_exception_cloning + + + +
+
+
+
+ +

Boost Exception

+
+

enable_exception_cloning()

+

#include <boost/exception/enable_exception_cloning.hpp>

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

Requirements:

+

T must have 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 cloning support in Boost Exception. For example:

+
class
+my_exception:
+    public std::exception
+    {
+    };
+
+....
+throw boost::enable_exception_cloning(my_exception());
+

Unless enable_exception_cloning() is called at the time an exception object is used in a throw-expression, any attempt to copy it using clone_exception() returns an exception_ptr which refers to an instance of unknown_exception.

+

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

+

See also:

+ + +
+
+
+ + diff --git a/doc/error_info.html b/doc/error_info.html new file mode 100644 index 0000000..9a7a743 --- /dev/null +++ b/doc/error_info.html @@ -0,0 +1,73 @@ + + + + + error_info + + + +
+
+
+
+ +

Boost Exception

+
+

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 & );
+
+        private:
+
+        ---unspecified---
+        };
+    }
+

Requirements:

+

T must have accessible copy constructor and must not be a reference.

+

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 errno_info object to exceptions using operator<<(), or to retrieve it using get_error_info(), you must first #include <boost/exception/info.hpp>.

+

See also:

+ + +
+
+
+ + diff --git a/doc/exception.html b/doc/exception.html new file mode 100644 index 0000000..67c53c3 --- /dev/null +++ b/doc/exception.html @@ -0,0 +1,97 @@ + + + + + exception + + + +
+
+
+
+ +

Boost Exception

+
+

exception

+

#include <boost/exception/exception.hpp>

+
namespace
+boost
+    {
+    class
+    exception
+        {
+        public:
+
+        virtual char const * what() const throw();
+
+        protected:
+
+        exception();
+        exception( exception const & x );
+        ~exception();
+
+        private:
+
+        ---unspecified---
+        };
+    }
+

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.

+

exception constructors

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

+

Effects:

+

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

+

Throws:

+

Nothing.

+

exception::what()

+
        virtual char const * what() const throw();
+

Returns:

+

An string representation of all data stored in the boost::exception object by the operator<<() function. See "Tutorial: Logging of boost::exception Objects" for details.

+

Throws:

+

Nothing.

+

Note:

+

The return value remains valid until the exception object from which it is obtained is destroyed or modified.

+

See also:

+ + +
+
+
+ + diff --git a/doc/exception_cloning_hpp.html b/doc/exception_cloning_hpp.html new file mode 100644 index 0000000..d0f3bc3 --- /dev/null +++ b/doc/exception_cloning_hpp.html @@ -0,0 +1,40 @@ + + + + + boost/exception/cloning.hpp + + + +
+
+
+
+ +

Boost Exception

+
+

boost/exception/cloning.hpp

+

This header file contains the following definitions/declarations:

+ + +
+
+
+ + diff --git a/doc/exception_constructors.html b/doc/exception_constructors.html new file mode 100644 index 0000000..4db8bbc --- /dev/null +++ b/doc/exception_constructors.html @@ -0,0 +1,45 @@ + + + + + exception::exception + + + +
+
+
+
+ +

Boost Exception

+
+

exception constructors

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

+

See also:

+ + +
+
+
+ + diff --git a/doc/exception_destructor.html b/doc/exception_destructor.html new file mode 100644 index 0000000..f9d7c02 --- /dev/null +++ b/doc/exception_destructor.html @@ -0,0 +1,42 @@ + + + + + exception::~exception + + + +
+
+
+
+ +

Boost Exception

+
+

exception destructor

+

Effects:

+

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

+

Throws:

+

Nothing.

+

See also:

+ + +
+
+
+ + diff --git a/doc/exception_enable_error_info_hpp.html b/doc/exception_enable_error_info_hpp.html new file mode 100644 index 0000000..bd79472 --- /dev/null +++ b/doc/exception_enable_error_info_hpp.html @@ -0,0 +1,37 @@ + + + + + boost/exception/enable_error_info.hpp + + + +
+
+
+
+ +

Boost Exception

+
+

boost/exception/enable_error_info.hpp

+

This header file contains the following definitions/declarations:

+ + +
+
+
+ + diff --git a/doc/exception_enable_exception_cloning_hpp.html b/doc/exception_enable_exception_cloning_hpp.html new file mode 100644 index 0000000..1b95e8f --- /dev/null +++ b/doc/exception_enable_exception_cloning_hpp.html @@ -0,0 +1,37 @@ + + + + + boost/exception/enable_exception_cloning.hpp + + + +
+
+
+
+ +

Boost Exception

+
+

boost/exception/enable_exception_cloning.hpp

+

This header file contains the following definitions/declarations:

+ + +
+
+
+ + diff --git a/doc/exception_error_info_group_hpp.html b/doc/exception_error_info_group_hpp.html new file mode 100644 index 0000000..6cd43d2 --- /dev/null +++ b/doc/exception_error_info_group_hpp.html @@ -0,0 +1,37 @@ + + + + + boost/exception/info_tuple.hpp + + + +
+
+
+
+ +

Boost Exception

+
+

boost/exception/info_tuple.hpp

+

This header file contains the following definitions/declarations:

+ + +
+
+
+ + diff --git a/doc/exception_error_info_hpp.html b/doc/exception_error_info_hpp.html new file mode 100644 index 0000000..88bc361 --- /dev/null +++ b/doc/exception_error_info_hpp.html @@ -0,0 +1,40 @@ + + + + + boost/exception/info.hpp + + + +
+
+
+
+ +

Boost Exception

+
+

boost/exception/info.hpp

+

This header file contains the following definitions/declarations:

+ + +
+
+
+ + diff --git a/doc/exception_error_info_value_hpp.html b/doc/exception_error_info_value_hpp.html new file mode 100644 index 0000000..0566385 --- /dev/null +++ b/doc/exception_error_info_value_hpp.html @@ -0,0 +1,41 @@ + + + + + boost/exception/error_info.hpp + + + +
+
+
+
+ +

Boost Exception

+
+

boost/exception/error_info.hpp

+

This header file contains the following declaration:

+
namespace
+boost
+    {
+    template <class Tag, class T>
+    class error_info;
+    }
+ +
+
+
+ + diff --git a/doc/exception_exception_hpp.html b/doc/exception_exception_hpp.html new file mode 100644 index 0000000..041b60a --- /dev/null +++ b/doc/exception_exception_hpp.html @@ -0,0 +1,37 @@ + + + + + boost/exception/exception.hpp + + + +
+
+
+
+ +

Boost Exception

+
+

boost/exception/exception.hpp

+

This header file contains the following definitions/declarations:

+ + +
+
+
+ + diff --git a/doc/exception_hpp.html b/doc/exception_hpp.html new file mode 100644 index 0000000..4861124 --- /dev/null +++ b/doc/exception_hpp.html @@ -0,0 +1,45 @@ + + + + + boost/exception.hpp + + + +
+
+
+
+ +

Boost Exception

+
+

boost/exception.hpp

+

This header file includes all other header files of Boost Exception:

+ + +
+
+
+ + diff --git a/doc/exception_ptr.html b/doc/exception_ptr.html new file mode 100644 index 0000000..afbe332 --- /dev/null +++ b/doc/exception_ptr.html @@ -0,0 +1,50 @@ + + + + + exception_ptr + + + +
+
+
+
+ +

Boost Exception

+
+

exception_ptr

+

#include <boost/exception/cloning.hpp>

+
namespace
+boost
+    {
+    typedef ---unspecified--- exception_ptr;
+    }
+

The exception_ptr type can be used to refer to a copy of a boost::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.

+

See also:

+ + +
+
+
+ + diff --git a/doc/exception_what.html b/doc/exception_what.html new file mode 100644 index 0000000..bd0d44b --- /dev/null +++ b/doc/exception_what.html @@ -0,0 +1,45 @@ + + + + + exception::what + + + +
+
+
+
+ +

Boost Exception

+
+

exception::what()

+
        virtual char const * what() const throw();
+

Returns:

+

An string representation of all data stored in the boost::exception object by the operator<<() function. See "Tutorial: Logging of boost::exception Objects" for details.

+

Throws:

+

Nothing.

+

Note:

+

The return value remains valid until the exception object from which it is obtained is destroyed or modified.

+

See also:

+ + +
+
+
+ + diff --git a/doc/get_error_info.html b/doc/get_error_info.html new file mode 100644 index 0000000..8f7a5b9 --- /dev/null +++ b/doc/get_error_info.html @@ -0,0 +1,52 @@ + + + + + get_error_info + + + +
+
+
+
+ +

Boost Exception

+
+

get_error_info()

+

#include <boost/exception/info.hpp>

+
namespace
+boost
+    {
+    template <class ErrorInfo,class E>
+    shared_ptr<typename ErrorInfo::value_type const> get_error_info( E const & x );
+    }
+

Requirements:

+

The type of the x object must derive from boost::exception; ErrorInfo must be an instance of the error_info template.

+

Returns:

+

If x does not store an object of type ErrorInfo, returns an empty shared_ptr; otherwise returns pointer to the stored value. Use operator<<() to store values in exception objects.

+

Throws:

+

Nothing.

+

See also:

+ + +
+
+
+ + diff --git a/doc/grouping_data.html b/doc/grouping_data.html new file mode 100644 index 0000000..2802cd9 --- /dev/null +++ b/doc/grouping_data.html @@ -0,0 +1,62 @@ + + + + + Tutorial: Adding Grouped Data to Exceptions + + + +
+
+
+
+ +

Boost Exception

+
+

Adding Grouped Data to Exceptions

+

The code snippet below demonstrates how boost::tuple can be used to bundle the name of the function that failed, together with the reported errno so that they can be added to exception objects more conveniently together:

+
#include <boost/exception/info_tuple.hpp>
+#include <boost/shared_ptr.hpp>
+#include <stdio.h>
+#include <string>
+#include <errno>
+
+typedef boost::error_info<struct tag_file_name,std::string> file_name_info;
+typedef boost::error_info<struct tag_function,char const *> function_info;
+typedef boost::error_info<struct tag_errno,int> errno_info;
+typedef boost::tuple<function_info,errno_info> clib_failure;
+
+class file_open_error: public boost::exception { };
+
+boost::shared_ptr<FILE>
+file_open( char const * name, char const * mode )
+    {
+    if( FILE * f=fopen(name,mode) )
+        return boost::shared_ptr<FILE>(f,fclose);
+    else
+        throw file_open_error() <<
+            file_name_info(name) <<
+            clib_failure("fopen",errno);
+    }
+

Note that the members of a boost::tuple are stored separately in exception objects; they can only be retrieved individually, using get_error_info().

+

See also:

+ + +
+
+
+ + diff --git a/doc/logging.html b/doc/logging.html new file mode 100644 index 0000000..36f169f --- /dev/null +++ b/doc/logging.html @@ -0,0 +1,60 @@ + + + + + Tutorial: Logging of boost::exception Objects + + + +
+
+
+
+ +

Boost Exception

+
+

Logging of boost::exception Objects

+

Class boost::exception provides a virtual member function what(), with a signature identical to the familiar std::exception::what() function. The default implementation returns a string value that is not presentable as a friendly user message, but because it is generated automatically, it is useful for debugging or logging purposes. Here is an example:

+
#include <boost/exception.hpp>
+#include <iostream>
+
+void f(); //throws unknown types that derive from boost::exception.
+
+void
+g()
+    {
+    try
+        {
+        f();
+        }
+    catch(
+    boost::exception & e )
+        {
+        std::cerr << e.what();
+        }
+    }
+

The what() member 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 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.

+

See also:

+ + +
+
+
+ + diff --git a/doc/name_idx.html b/doc/name_idx.html new file mode 100644 index 0000000..a96aa6c --- /dev/null +++ b/doc/name_idx.html @@ -0,0 +1,68 @@ + + + + + Index + + + +
+ +
+ + diff --git a/doc/operator_shl_exception.html b/doc/operator_shl_exception.html new file mode 100644 index 0000000..52884ee --- /dev/null +++ b/doc/operator_shl_exception.html @@ -0,0 +1,67 @@ + + + + + operator<</exception + + + +
+
+
+
+ +

Boost Exception

+
+

operator<<()

+

#include <boost/exception/info.hpp> 
#include <boost/exception/info_tuple.hpp>

+
namespace
+boost
+    {
+    template <class E, class Tag1, class T1>
+    E const & operator<<( E const & x, error_info<Tag1,T1> 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 );
+    }
+

Requirements:

+

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

+

Effects:

+
  • The first overload stores a copy of v into x. If x already contains data of type error_info<Tag1,T1>, that data is overwritten.
  • +
  • The boost::tuple overload is equivalent to x << v.get<0>() << ... << v.get<N>().
  • +
+

Returns:

+

x.

+

Throws:

+

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

+

See also:

+ + +
+
+
+ + diff --git a/doc/reno.css b/doc/reno.css new file mode 100644 index 0000000..a25252c --- /dev/null +++ b/doc/reno.css @@ -0,0 +1,218 @@ +body +{ + font-family: Trebuchet, Verdana, Arial, Helvetica, Sans; + font-size: 10pt; + margin: 0; + padding: 0; + background-position: left; + background-image: url( 'left.png' ); + background-repeat: repeat-y; +} + +.RenoPageList, +ol, +ul +{ + clear: both; +} + +.RenoPageList +{ + margin:0; +} + +h1 +{ + font-size: 24pt; + clear: left; + padding-top: 5pt; + padding-bottom: 5pt; + margin-top: 0; + margin-bottom: 0; +} + +h2 +{ + font-size: 18pt; + clear: left; + padding-top: 20pt; + padding-bottom: 5pt; + margin-top: 0; + margin-bottom: 0; +} + +h3 +{ + font-size: 14pt; + clear: left; + padding-top: 15pt; + padding-bottom: 5pt; + margin-top: 0; + margin-bottom: 0; +} + +h4 +{ + font-size: 10pt; + float: left; + clear: left; + padding-top: 5pt; + padding-bottom: 0; + margin-top: 0; + margin-bottom: 0; + margin-right: 4pt; +} + +p +{ + font-size: 10pt; + padding-top: 5pt; + padding-bottom: 5pt; + margin-top: 0; + margin-bottom: 0; + clear:right; +} + +pre +{ + border-top: 1px solid #000000; + border-bottom: 1px solid #000000; + border-left: 0; + border-right: 0; + font-size: 10pt; + background-color: #F0F0F0; + padding-top: 5pt; + padding-bottom: 5pt; + padding-left: 5pt; + padding-right: 5pt; + margin-top: 10pt; + margin-bottom: 10pt; + clear: both; +} + +ol,ul +{ + padding-top: 0; + padding-bottom: 0; + margin-top: 0; + margin-bottom: 0; +} + +ul li +{ + padding-top: 5pt; + padding-bottom: 5pt; + margin-top: 0; + margin-bottom: 0; +} + +.RenoIndex h3 +{ + margin: 20pt 0 5pt 0; + padding: 2pt; + display: inline; + border: 1.5pt solid #A0A0A0; + float: left; + clear: both; + width: 15pt; + text-align: center; + background-color: #EAEAEA; +} + +.RenoIndex p +{ + clear: both; + margin: 0; + padding: 0; +} + +.RenoHookUnbound, +.RenoHookBound +{ + background-position: left center; + background-image: url('link.gif'); + background-repeat: no-repeat; + padding-left: 10pt; +} + +.RenoIncludeDIV +{ + padding: 0; + margin: 0; +} + +.RenoError +{ + background-color: red; + color: white; + display: inline; +} + +a +{ + text-decoration: underline; + color: #0000AA; +} + +tt +{ + font-size: 10pt; +} + +hr +{ + border: 0; + color: black; + background-color: black; + height: 1px; +} + +blockquote +{ + padding-top: 0; + padding-bottom: 0; + padding-right: 0; + padding-left: 20pt; + margin: 0; +} + +#boost_logo +{ + float:right; +} + +#footer +{ +} + +.logo_pic +{ + border:0; +} + +.logo +{ + float:right; + margin-left: 6pt; + margin-right: -4pt; +} + +.body-0 +{ + min-width: 40em; + padding-left: 30px; + background: url(shade-l.png) repeat-y left; +} +.body-1 +{ + padding-right: 30px; + background: url(shade-r.png) repeat-y right; +} +.body-2 +{ + background-color: white; + padding: 0 8pt 0 8pt; + margin-left: 0; + border-top: solid 2.5pt #717171; + border-bottom: solid 3pt #717171; +} diff --git a/doc/rethrow_exception.html b/doc/rethrow_exception.html new file mode 100644 index 0000000..cf2cca9 --- /dev/null +++ b/doc/rethrow_exception.html @@ -0,0 +1,47 @@ + + + + + rethrow_exception + + + +
+
+
+
+ +

Boost Exception

+
+

rethrow_exception()

+

#include <boost/exception/cloning.hpp>

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

Precondition:

+

ep shall not be null.

+

Throws:

+

The exception to which ep refers.

+

See also:

+ + +
+
+
+ + diff --git a/doc/shade-l.png b/doc/shade-l.png new file mode 100644 index 0000000000000000000000000000000000000000..a11fa0b44f175bc868faf39ae36de89c466cb72a GIT binary patch literal 948 zcmeAS@N?(olHy`uVBq!ia0y~yV31>AU|`{3W?*1gx41r+fq|JJz$e6&0Sp)!8JU=v zn3tIk~vFxVgD`czAeudHMMG`1$z-1Ox;H1%-r!goTAg zL_|bIMa9I##KpxWBqSsyC8eaKq@|^0WMpJzW##1LAqtgWqWY;0_8ZSCyr?CtFx92^`S9i5zoD;^X5J5)u*<6O)pXl9Q8DQc_Y=Q`6GY($mv3GBPqVGqbX? zva_>ua&mHWbMx}@^7Hcx3JMAf3yX@1ii?X&N=iygOUug2%FD|uDk>@~E32xis;jGO zYHDh0YwPOj>g($p8X6iK8=IP%nwy(jT3T9LTie>&+S}VZIyyQ#JG;8Ny1To3dU|?$ zd;9wO`uqDQOqein;>1alCQY6^dCHV2Q>RXyHf`GU>C zHEY+dUAJ!C`t|EKY}l}IK79Ddkt0Ws9zAyK*zx1XPnAmsE?vHS`O1|mSFc{ZcJ12r>(_7GxN-C5&0Du_ z-M)SM&Ye4V@7}$4@813U_a8iX@bKZoM~@yoe*E~!lP6D~K7ID=+4JYmU%Ytn^5x4{ zuU@@={rb(DH*ep*efRF&`}glZeE9J3&?&!0bk|Ni~=?_bk_r)3Nb42&f~e!&b5&u*lFI7!~_E({&4vK|Z!44efX zk;M!Q+`=Ht$S`Y;1Oo$ugQtsQNX49Fi_%|LPEJ^5G!!@3Qwdc4gjOwUj&E zfBucTVeyfN8l0AU|`{3W?*1gx41r+fq|JJz$e6&0Sp)!8JU=v zn3tIk~vFxVgD`czAeudHMMG`1$z-1Ox;H1%-r!goTAg zL_|bIMa9I##KpxWBqSsyC8eaKq@|^0WMpJzW##1LAqtgWqWY;0_8ZSCyr?CtFx92^`S9i5zoD;^X5J5)u*<6O)pXl9Q8DQc_Y=Q`6GY($mv3GBPqVGqbX? zva_>ua&mHWbMx}@^7Hcx3JMAf3yX@1ii?X&N=iygOUug2%FD|uDk>@~E32xis;jGO zYHDh0YwPOj>g($p8X6iK8=IP%nwy(jT3T9LTie>&+S}VZIyyQ#JG;8Ny1To3dU|?$ zd;9wO`uqDQOqein;>1alCQY6^dCHV2Q>RXyHf`GU>C zHEY+dUAJ!C`t|EKY}l}IK79Ddkt0Ws9zAyK*zx1XPnAmsE?vHS`O1|mSFc{ZcJ12r>(_7GxN-C5&0Du_ z-M)SM&Ye4V@7}$4@813U_a8iX@bKZoM~@yoe*E~!lP6D~K7ID=+4JYmU%Ytn^5x4{ zuU@@={rb(DH*ep*efRF&`}glZeE9J3&?&!0bk|Ni~=?_bk_r)3Nb42&f~e!&b5&u*lFI7!~_E({&4vK|Z!44efX zk;M!Q+`=Ht$S`Y;1Oo$uou`XqNX49Fjdd%s-_A0~z1F0veLe5arrPWG{<8DQ+Eu-| z@ljaaZ=Ti3fRMoJmn;*t^j;q7+V!lDGx)@1UWNqwz@>W*%2tB%o~Nsy%Q~loCIEUX BvZVk3 literal 0 HcmV?d00001 diff --git a/doc/throw_exception.html b/doc/throw_exception.html new file mode 100644 index 0000000..1a33afd --- /dev/null +++ b/doc/throw_exception.html @@ -0,0 +1,54 @@ + + + + + throw_exception + + + +
+
+
+
+ +

Boost Exception

+
+

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

Effects:

+
  • If BOOST_NO_EXCEPTIONS is not defined, boost::throw_exception(e) is equivalent to throw boost::enable_exception_cloning(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.
  • +
+

See also:

+ + +
+
+
+ + diff --git a/doc/throw_exception_hpp.html b/doc/throw_exception_hpp.html new file mode 100644 index 0000000..9d27d25 --- /dev/null +++ b/doc/throw_exception_hpp.html @@ -0,0 +1,37 @@ + + + + + boost/throw_exception.hpp + + + +
+
+
+
+ +

Boost Exception

+
+

boost/exception/throw_exception.hpp

+

This header file contains the following definitions/declarations:

+ + +
+
+
+ + diff --git a/doc/transporting_data.html b/doc/transporting_data.html new file mode 100644 index 0000000..6f7efaf --- /dev/null +++ b/doc/transporting_data.html @@ -0,0 +1,182 @@ + + + + + Tutorial: Transporting of Arbitrary Data to the Catch Site + + + +
+
+
+
+ +

Boost Exception

+
+

Transporting of Arbitrary Data to the Catch Site

+

All exception types that derive from boost::exception can be used as type-safe containers of arbitrary data objects, while complying with the no-throw requirements (15.5.1) of the ANSI C++ standard for exception classes. Data can be added to a boost::exception at the time of the throw, or at a later time.

+

Adding of Arbitrary Data at the Point of the Throw

+

The following example demonstrates how errno can be stored in exception objects using Boost Exception:

+
#include <boost/exception.hpp>
+#include <errno.h>
+#include <iostream>
+
+typedef boost::error_info<struct tag_errno,int> errno_info; //(1)
+
+class my_error: public boost::exception, public std::exception { }; //(2)
+
+void
+f()
+    {
+    throw my_error() << errno_info(errno); //(3)
+    }
+
+

First, we instantiate the error_info template using a unique identifier -- tag_errno, and the type of the info it identifies -- int. This provides compile-time type safety for the various values stored in exception objects.

+

Second, we define class my_error, which derives from boost::exception.

+

Finally, (3) illustrates how the typedef from (1) can be used with operator<<() to store values in exception objects at the point of the throw.

+

The stored errno value can be recovered at a later time like this:

+
// ...continued
+
+void
+g()
+    {
+    try
+        {
+        f();
+        }
+    catch(
+    my_error & x )
+        {
+        if( boost::shared_ptr<int const> err=boost::get_error_info<errno_info>(x) )
+            std::cerr << "Error code: " << *err;
+        }
+    }
+

The get_error_info() function template is instantiated with the typedef from (1), and is passed an exception object of any type that derives publicly from boost::exception. If the exception object contains the requested value, the returned shared_ptr will point to it; otherwise an empty shared_ptr is returned.

+

Adding of Arbitrary Data to Active Exception Objects

+

Sometimes the throw site does not have all the information that is needed at the catch site to make sense of what went wrong. Here is an example:

+
#include <stdio.h>
+#include <string>
+        
+class
+file_read_error
+    {
+    public:
+
+    explicit
+    file_read_error( std::string const & fn ):
+        fn_(fn)
+        {
+        };
+
+    std::string const &
+    file_name() const
+        {
+        return fn_;
+        }
+
+    private:
+
+    std::string fn_;
+    };
+
+void
+file_read( FILE * f, void * buffer, size_t size )
+    {
+    if( size!=fread(buffer,1,size,f) )
+        throw file_read_error("????");
+    }
+

We have defined an exception class file_read_error which can store a file name, so that when we catch a file_read_error object, we know which file the failure is related to. However, the file_read function does not have the file name at the time of the throw; all it has is a FILE handle.

+

One possible solution is to not use FILE handles directly. We could have our own class file which stores both a FILE handle and a file name, and pass that to file_read(). However, this could be problematic if we communicate with 3rd party code that does not use our class file (probably because they have their own similar class.)

+

A better solution is to make class file_read_error derive (possibly indirectly) from boost::exception, and free the file_read() function from the burden of storing the file name in exceptions it throws:

+
#include <boost/exception.hpp>
+#include <stdio.h>
+#include <errno.h>
+
+typedef boost::error_info<struct tag_errno,int> errno_info;
+
+class file_read_error: public boost::exception { };
+
+void
+file_read( FILE * f, void * buffer, size_t size )
+    {
+    if( size!=fread(buffer,1,size,f) )
+        throw file_read_error() << errno_info(errno);
+    }
+

If file_read() detects a failure, it throws an exception which contains the information that is available at the time, namely the errno. Other relevant information, such as the file name, can be added in a context higher up the call stack, where it is known naturally:

+
#include <boost/exception.hpp>
+#include <boost/shared_ptr.hpp>
+#include <stdio.h>
+#include <string>
+
+typedef boost::error_info<struct tag_file_name,std::string> file_name_info;
+
+boost::shared_ptr<FILE> file_open( char const * file_name, char const * mode );
+void file_read( FILE * f, void * buffer, size_t size );
+
+void
+parse_file( char const * file_name )
+    {
+    boost::shared_ptr<FILE> f = file_open(file_name,"rb");
+    assert(f);
+    try
+        {
+        char buf[1024];
+        file_read( f.get(), buf, sizeof(buf) );
+        }
+    catch(
+    boost::exception & e )
+        {
+        e << file_name_info(file_name);
+        throw;
+        }
+    }
+

The above function is (almost) exception-neutral -- if an exception is emitted by any function call within the try block, parse_file() does not need to do any real work, but it intercepts any boost::exception object, stores the file name, and re-throws using a throw-expression with no operand (15.1.6). The rationale for catching any boost::exception object is that the file name is relevant to any failure that occurs in parse_file(), even if the failure is unrelated to file I/O.

+

As usual, the stored data can be retrieved using get_error_info().

+

Adding Grouped Data to Exceptions

+

The code snippet below demonstrates how boost::tuple can be used to bundle the name of the function that failed, together with the reported errno so that they can be added to exception objects more conveniently together:

+
#include <boost/exception/info_tuple.hpp>
+#include <boost/shared_ptr.hpp>
+#include <stdio.h>
+#include <string>
+#include <errno>
+
+typedef boost::error_info<struct tag_file_name,std::string> file_name_info;
+typedef boost::error_info<struct tag_function,char const *> function_info;
+typedef boost::error_info<struct tag_errno,int> errno_info;
+typedef boost::tuple<function_info,errno_info> clib_failure;
+
+class file_open_error: public boost::exception { };
+
+boost::shared_ptr<FILE>
+file_open( char const * name, char const * mode )
+    {
+    if( FILE * f=fopen(name,mode) )
+        return boost::shared_ptr<FILE>(f,fclose);
+    else
+        throw file_open_error() <<
+            file_name_info(name) <<
+            clib_failure("fopen",errno);
+    }
+

Note that the members of a boost::tuple are stored separately in exception objects; they can only be retrieved individually, using get_error_info().

+

See also:

+ + +
+
+
+ + diff --git a/doc/unknown_exception.html b/doc/unknown_exception.html new file mode 100644 index 0000000..ccc7ddb --- /dev/null +++ b/doc/unknown_exception.html @@ -0,0 +1,53 @@ + + + + + unknown_exception + + + +
+
+
+
+ +

Boost Exception

+
+

unknown_exception

+

#include <boost/exception/cloning.hpp>

+
namespace
+boost
+    {
+    class
+    unknown_exception:
+        public std::exception
+        public boost::exception
+        {
+        ---unspecified---
+        };
+    }
+

This type is used by the cloning support in Boost Exception.

+

To allow an exception to be cloned, enable_exception_cloning() must be used at the time the exception object is passed to throw. Otherwise, calling clone_exception() returns an exception_ptr which refers to an instance of unknown_exception.

+

See also:

+ + +
+
+
+ + diff --git a/doc/using_enable_cloning.html b/doc/using_enable_cloning.html new file mode 100644 index 0000000..6dfd236 --- /dev/null +++ b/doc/using_enable_cloning.html @@ -0,0 +1,54 @@ + + + + + Tutorial: Using enable_exception_cloning() at the Time of the Throw + + + +
+
+
+
+ +

Boost Exception

+
+

Using enable_exception_cloning() at the Time of the Throw

+

Here is how cloning can be enabled in a throw-expression (15.1):

+
#include <boost/exception/enable_exception_cloning.hpp>
+#include <boost/exception/info.hpp>
+#include <stdio.h>
+#include <errno.h>
+
+typedef boost::error_info<struct tag_errno,int> errno_info;
+
+class file_read_error: public boost::exception { };
+
+void
+file_read( FILE * f, void * buffer, size_t size )
+    {
+    if( size!=fread(buffer,1,size,f) )
+        throw boost::enable_exception_cloning(file_read_error()) <<
+            errno_info(errno);
+    }
+

See also:

+ + +
+
+
+ + diff --git a/doc/using_enable_error_info.html b/doc/using_enable_error_info.html new file mode 100644 index 0000000..e732e7f --- /dev/null +++ b/doc/using_enable_error_info.html @@ -0,0 +1,66 @@ + + + + + Tutorial: Integrating Boost Exception in Existing Exception Class Hierarchies + + + +
+
+
+
+ +

Boost Exception

+
+

Integrating Boost Exception in Existing Exception Class Hierarchies

+

Some exception hierarchies can not be modified to make boost::exception a base type. For this case, the enable_error_info() function template can be used to make exception objects derive from boost::exception anyway. Here is an example:

+
#include <boost/exception.hpp>
+#include <stdexcept>
+
+typedef boost::error_info<struct tag_std_range_min,size_t> std_range_min;
+typedef boost::error_info<struct tag_std_range_max,size_t> std_range_max;
+typedef boost::error_info<struct tag_std_range_index,size_t> std_range_index;
+
+template <class T>
+class
+my_container
+    {
+    public:
+
+    size_t size() const;
+
+    T const &
+    operator[]( size_t i ) const
+        {
+        if( i > size() )
+            throw boost::enable_error_info(std::range_error("Index out of range")) <<
+                std_range_min(0) <<
+                std_range_max(size()) <<
+                std_range_index(i);
+        //....
+        }
+    };
+
+

Enable_error_info<T> returns an object of unspecified type which is guaranteed to derive from both boost::exception and T. This makes it possible to use operator<<() to store additional information in the exception object. The exception can be intercepted as T &, therefore existing exception handling will not break. It can also be intercepted as boost::exception &, so that more information can be added to the exception at a later time.

+

See also:

+ + +
+
+
+ + diff --git a/doc/valid-css.png b/doc/valid-css.png new file mode 100644 index 0000000000000000000000000000000000000000..931bacfe9fcd25a55261b9e3b4883f215cc74c7a GIT binary patch literal 5130 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 literal 0 HcmV?d00001 diff --git a/doc/valid-xhtml.png b/doc/valid-xhtml.png new file mode 100644 index 0000000000000000000000000000000000000000..7b127151886262d93fb0685978a9b973027f244e GIT binary patch literal 5805 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 literal 0 HcmV?d00001 diff --git a/example/Jamfile b/example/Jamfile new file mode 100644 index 0000000..a5f4e8c --- /dev/null +++ b/example/Jamfile @@ -0,0 +1,15 @@ +# Boost Exception Library example Jamfile +# +# Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. +# +# Distributed under the Boost Software License, Version 1.0. (See accompanying +# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +exe example_io : example_io.cpp ; +obj error_info_1 : error_info_1.cpp ; +obj error_info_2 : error_info_2.cpp ; +obj cloning_1 : cloning_1.cpp ; +obj cloning_2 : cloning_2.cpp ; +obj info_tuple : info_tuple.cpp ; +obj enable_error_info : enable_error_info.cpp ; +obj logging : logging.cpp ; diff --git a/example/cloning_1.cpp b/example/cloning_1.cpp new file mode 100644 index 0000000..b3b9d90 --- /dev/null +++ b/example/cloning_1.cpp @@ -0,0 +1,22 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +//This example shows how to enable cloning when throwing a boost::exception. + +#include +#include +#include +#include + +typedef boost::error_info errno_info; + +class file_read_error: public boost::exception { }; + +void +file_read( FILE * f, void * buffer, size_t size ) + { + if( size!=fread(buffer,1,size,f) ) + throw boost::enable_exception_cloning(file_read_error()) << errno_info(errno); + } diff --git a/example/cloning_2.cpp b/example/cloning_2.cpp new file mode 100644 index 0000000..2686004 --- /dev/null +++ b/example/cloning_2.cpp @@ -0,0 +1,39 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +//This example shows how to transport cloning-enabled boost::exceptions between threads. + +#include +#include +#include + +void do_work(); //throws cloning-enabled boost::exceptions + +void +worker_thread( boost::exception_ptr & error ) + { + try + { + do_work(); + error = boost::exception_ptr(); + } + catch( + boost::exception & e ) + { + error = boost::clone_exception(e); + } + } + +// + +void +work() + { + boost::exception_ptr error; + boost::thread t( boost::bind(worker_thread,boost::ref(error)) ); + t.join(); + if( error ) + boost::rethrow_exception(error); + } diff --git a/example/enable_error_info.cpp b/example/enable_error_info.cpp new file mode 100644 index 0000000..0be25b3 --- /dev/null +++ b/example/enable_error_info.cpp @@ -0,0 +1,35 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +//This example shows how to throw exception objects that support +//transporting of arbitrary data to the catch site, even for types +//that do not derive from boost::exception. + +#include +#include + +typedef boost::error_info std_range_min; +typedef boost::error_info std_range_max; +typedef boost::error_info std_range_index; + +template +class +my_container + { + public: + + size_t size() const; + + T const & + operator[]( size_t i ) const + { + if( i > size() ) + throw boost::enable_error_info(std::range_error("Index out of range")) << + std_range_min(0) << + std_range_max(size()) << + std_range_index(i); + //.... + } + }; diff --git a/example/error_info_1.cpp b/example/error_info_1.cpp new file mode 100644 index 0000000..415cc3e --- /dev/null +++ b/example/error_info_1.cpp @@ -0,0 +1,36 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +//This example shows how to add data to boost::exception objects at the +//point of the throw, and how to retrieve that data at the point of the catch. + +#include +#include +#include + +typedef boost::error_info errno_info; //(1) + +class my_error: public boost::exception, public std::exception { }; //(2) + +void +f() + { + throw my_error() << errno_info(errno); //(3) + } + +void +g() + { + try + { + f(); + } + catch( + my_error & x ) + { + if( boost::shared_ptr err=boost::get_error_info(x) ) + std::cerr << "Error code: " << *err; + } + } diff --git a/example/error_info_2.cpp b/example/error_info_2.cpp new file mode 100644 index 0000000..c95aa62 --- /dev/null +++ b/example/error_info_2.cpp @@ -0,0 +1,49 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +//This example shows how to add arbitrary data to active exception objects. + +#include +#include +#include +#include + +// + +typedef boost::error_info errno_info; + +class file_read_error: public boost::exception { }; + +void +file_read( FILE * f, void * buffer, size_t size ) + { + if( size!=fread(buffer,1,size,f) ) + throw file_read_error() << errno_info(errno); + } + +// + +typedef boost::error_info file_name_info; + +boost::shared_ptr file_open( char const * file_name, char const * mode ); +void file_read( FILE * f, void * buffer, size_t size ); + +void +parse_file( char const * file_name ) + { + boost::shared_ptr f = file_open(file_name,"rb"); + assert(f); + try + { + char buf[1024]; + file_read( f.get(), buf, sizeof(buf) ); + } + catch( + boost::exception & e ) + { + e << file_name_info(file_name); + throw; + } + } diff --git a/example/example_io.cpp b/example/example_io.cpp new file mode 100644 index 0000000..57d31de --- /dev/null +++ b/example/example_io.cpp @@ -0,0 +1,215 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +//This program simulates errors on copying simple data files. +//It demonstrates how the proposed Boost exception library can be used. +// +//The documentation for boost::exception can be found at: +// +// http://www.revergestudios.com/boost-exception/boost-exception.htm. +// +//The output from this program can vary depending on the compiler/OS combination. + +#include +#include +#include +#include +#include +#include +#include + +typedef boost::error_info errno_info; +typedef boost::error_info > file_stream_info; +typedef boost::error_info open_mode_info; //The open mode of a failed fopen request. +typedef boost::error_info file_name_info; //The file name of a failed file operation. +typedef boost::error_info file_name_src_info; //The source file name of a failed copy operation. +typedef boost::error_info file_name_dst_info; //The destination file name of a failed copy operation. +typedef boost::error_info function_info; //The name of the C function which reported the failure. + +char const data[] = "example"; +size_t const data_size = sizeof(data); + +class +error: //Base for all exception objects we throw. + public std::exception, + public boost::exception + { + public: + + char const * + what() const throw() + { + return boost::exception::what(); + } + + protected: + + ~error() throw() + { + } + }; + +class open_error: public error { }; +class read_error: public error { }; +class write_error: public error { }; + +class fopen_error: public open_error { }; +class fread_error: public read_error { }; +class fwrite_error: public write_error { }; + + +boost::shared_ptr +my_fopen( char const * name, char const * mode ) + { + if( FILE * f = ::fopen(name,mode) ) + return boost::shared_ptr(f,fclose); + else + throw fopen_error() << BOOST_ERROR_INFO << + errno_info(errno) << + file_name_info(name) << + open_mode_info(mode) << + function_info("fopen"); + } + +void +my_fread( void * buffer, size_t size, size_t count, boost::shared_ptr const & stream ) + { + assert(stream); + if( count!=fread(buffer,size,count,stream.get()) || ferror(stream.get()) ) + throw fread_error() << BOOST_ERROR_INFO << + function_info("fread") << + errno_info(errno) << + file_stream_info(boost::weak_ptr(stream)); + } + +void +my_fwrite( void const * buffer, size_t size, size_t count, boost::shared_ptr const & stream ) + { + assert(stream); + if( count!=fwrite(buffer,size,count,stream.get()) || ferror(stream.get()) ) + throw fwrite_error() << BOOST_ERROR_INFO << + function_info("fwrite") << + errno_info(errno) << + file_stream_info(boost::weak_ptr(stream)); + } + +void +reset_file( char const * file_name ) + { + (void) my_fopen(file_name,"wb"); + } + +void +create_data( char const * file_name ) + { + boost::shared_ptr f = my_fopen(file_name,"wb"); + my_fwrite( data, 1, data_size, f ); + } + +void +copy_data( char const * src_file_name, char const * dst_file_name ) + { + boost::shared_ptr src = my_fopen(src_file_name,"rb"); + boost::shared_ptr dst = my_fopen(dst_file_name,"wb"); + try + { + char buffer[data_size]; + my_fread( buffer, 1, data_size, src ); + my_fwrite( buffer, 1, data_size, dst ); + } + catch( + boost::exception & x ) + { + if( boost::shared_ptr const> f=boost::get_error_info(x) ) + if( boost::shared_ptr fs = f->lock() ) + { + if( fs==src ) + x << file_name_info(src_file_name); + else if( fs==dst ) + x << file_name_info(dst_file_name); + } + x << + file_name_src_info(src_file_name) << + file_name_dst_info(dst_file_name); + throw; + } + } + +void +dump_copy_info( boost::exception const & x ) + { + if( boost::shared_ptr src = boost::get_error_info(x) ) + std::cout << "Source file name: " << *src << "\n"; + if( boost::shared_ptr dst = boost::get_error_info(x) ) + std::cout << "Destination file name: " << *dst << "\n"; + } + +void +dump_file_info( boost::exception const & x ) + { + if( boost::shared_ptr fn = boost::get_error_info(x) ) + std::cout << "Source file name: " << *fn << "\n"; + } + +void +dump_clib_info( boost::exception const & x ) + { + if( boost::shared_ptr err=boost::get_error_info(x) ) + std::cout << "OS error: " << *err << "\n"; + if( boost::shared_ptr fn=boost::get_error_info(x) ) + std::cout << "Failed function: " << *fn << "\n"; + } + +void +dump_all_info( boost::exception const & x ) + { + std::cout << "-------------------------------------------------\n"; + dump_copy_info(x); + dump_file_info(x); + dump_clib_info(x); + std::cout << "\nOutput from what():\n"; + std::cout << x.what(); + } + +int +main() + { + try + { + create_data( "tmp1.txt" ); + copy_data( "tmp1.txt", "tmp2.txt" ); //This should succeed. + + reset_file( "tmp1.txt" ); //Creates empty file. + try + { + copy_data( "tmp1.txt", "tmp2.txt" ); //This should fail, tmp1.txt is empty. + } + catch( + read_error & x ) + { + std::cout << "\nCaught 'read_error' exception.\n"; + dump_all_info(x); + } + + remove( "tmp1.txt" ); + remove( "tmp2.txt" ); + try + { + copy_data( "tmp1.txt", "tmp2.txt" ); //This should fail, tmp1.txt does not exist. + } + catch( + open_error & x ) + { + std::cout << "\nCaught 'open_error' exception.\n"; + dump_all_info(x); + } + } + catch( + boost::exception & x ) + { + std::cout << "\nCaught unexpected boost::exception!\n"; + dump_all_info(x); + } + } diff --git a/example/info_tuple.cpp b/example/info_tuple.cpp new file mode 100644 index 0000000..53c1aa0 --- /dev/null +++ b/example/info_tuple.cpp @@ -0,0 +1,31 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +//This example shows how boost::error_info_group can be used to bundle +//the name of the function that fails together with the reported errno. + +#include +#include +#include +#include +#include + +typedef boost::error_info file_name_info; +typedef boost::error_info function_info; +typedef boost::error_info errno_info; +typedef boost::tuple clib_failure; + +class file_open_error: public boost::exception { }; + +boost::shared_ptr +file_open( char const * name, char const * mode ) + { + if( FILE * f=fopen(name,mode) ) + return boost::shared_ptr(f,fclose); + else + throw file_open_error() << + file_name_info(name) << + clib_failure("fopen",errno); + } diff --git a/example/logging.cpp b/example/logging.cpp new file mode 100644 index 0000000..7dde008 --- /dev/null +++ b/example/logging.cpp @@ -0,0 +1,25 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +//This example shows to print all data contained in a boost::exception. + +#include +#include + +void f(); //throws unknown types that derive from boost::exception. + +void +g() + { + try + { + f(); + } + catch( + boost::exception & e ) + { + std::cerr << e.what(); + } + } diff --git a/include/boost/exception/cloning.hpp b/include/boost/exception/cloning.hpp new file mode 100644 index 0000000..7e18892 --- /dev/null +++ b/include/boost/exception/cloning.hpp @@ -0,0 +1,58 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#ifndef UUID_FA5836A2CADA11DC8CD47C8555D89593 +#define UUID_FA5836A2CADA11DC8CD47C8555D89593 + +#include +#include +#include + +namespace +boost + { + class + unknown_exception: + public exception, + public std::exception + { + public: + + explicit + unknown_exception() + { + } + + explicit + unknown_exception( boost::exception const & x ): + boost::exception(x) + { + } + }; + + typedef intrusive_ptr exception_ptr; + + template + exception_ptr + clone_exception( T const & e ) + { + if( boost::exception_detail::cloning_base const * cb = dynamic_cast(&e) ) + if( exception_detail::clone_base const * c = cb->clone() ) + return exception_ptr(c); + if( boost::exception const * be = dynamic_cast(&e) ) + return exception_ptr(exception_detail::make_clone(unknown_exception(*be))); + else + return exception_ptr(exception_detail::make_clone(unknown_exception())); + } + + inline + void + rethrow_exception( exception_ptr const & p ) + { + p->rethrow(); + } + } + +#endif diff --git a/include/boost/exception/detail/cloning_base.hpp b/include/boost/exception/detail/cloning_base.hpp new file mode 100644 index 0000000..1bc0412 --- /dev/null +++ b/include/boost/exception/detail/cloning_base.hpp @@ -0,0 +1,27 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#ifndef UUID_F7D5662CCB0F11DCA353CAC656D89593 +#define UUID_F7D5662CCB0F11DCA353CAC656D89593 + +namespace +boost + { + namespace + exception_detail + { + class clone_base; + + class + cloning_base + { + public: + + virtual clone_base const * clone() const = 0; + }; + } + } + +#endif diff --git a/include/boost/exception/detail/counted_base.hpp b/include/boost/exception/detail/counted_base.hpp new file mode 100644 index 0000000..c842cbc --- /dev/null +++ b/include/boost/exception/detail/counted_base.hpp @@ -0,0 +1,38 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#ifndef UUID_DBA0D90C930911DCBA7B675A56D89593 +#define UUID_DBA0D90C930911DCBA7B675A56D89593 + +namespace +boost + { + namespace + exception_detail + { + class + counted_base + { + friend + void + intrusive_ptr_add_ref( counted_base const * c ) + { + c->add_ref(); + } + + friend + void + intrusive_ptr_release( counted_base const * c ) + { + c->release(); + } + + virtual void add_ref() const=0; + virtual void release() const=0; + }; + } + } + +#endif diff --git a/include/boost/exception/enable_error_info.hpp b/include/boost/exception/enable_error_info.hpp new file mode 100644 index 0000000..1deee95 --- /dev/null +++ b/include/boost/exception/enable_error_info.hpp @@ -0,0 +1,69 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#ifndef UUID_0C5D492E909711DCB658AD4556D89593 +#define UUID_0C5D492E909711DCB658AD4556D89593 + +#include + +namespace +boost + { + namespace + exception_detail + { + template + struct + error_info_injector: + public T, + public exception + { + explicit + error_info_injector( T const & x ): + T(x) + { + } + }; + + struct large_size { char c[256]; }; + large_size dispatch( exception * ); + + struct small_size { }; + small_size dispatch( void * ); + + template + struct enable_error_info_helper; + + template + struct + enable_error_info_helper + { + typedef T type; + }; + + template + struct + enable_error_info_helper + { + typedef error_info_injector type; + }; + + template + struct + enable_error_info_return_type + { + typedef typename enable_error_info_helper::type type; + }; + } + + template + typename exception_detail::enable_error_info_return_type::type + enable_error_info( T const & x ) + { + return typename exception_detail::enable_error_info_return_type::type(x); + } + } + +#endif diff --git a/include/boost/exception/enable_exception_cloning.hpp b/include/boost/exception/enable_exception_cloning.hpp new file mode 100644 index 0000000..d85a258 --- /dev/null +++ b/include/boost/exception/enable_exception_cloning.hpp @@ -0,0 +1,148 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#ifndef UUID_78CC85B2914F11DC8F47B48E55D89593 +#define UUID_78CC85B2914F11DC8F47B48E55D89593 + +#include +#include +#include +#include +#include + +namespace +boost + { + namespace + exception_detail + { + class + clone_base: + public counted_base + { + public: + + virtual void rethrow() const=0; + }; + + struct + bad_alloc_impl: + public clone_base, + public std::bad_alloc + { + void + add_ref() const + { + } + + void + release() const + { + } + + void + rethrow() const + { + throw *this; + } + }; + + template + clone_base * make_clone( T const & ); + + template + class + clone_impl: + public T, + public cloning_base + { + public: + + explicit + clone_impl( T const & x ): + T(x) + { + } + + private: + + clone_base const * + clone() const + { + return make_clone(*this); + } + }; + + template + class + exception_clone: + public T, + public clone_base + { + public: + + explicit + exception_clone( T const & x ): + T(x), + count_(0) + { + } + + private: + + detail::atomic_count mutable count_; + + void + add_ref() const + { + ++count_; + } + + void + release() const + { + if( !--count_ ) + delete this; + } + + void + rethrow() const + { + throw clone_impl(*this); + } + }; + + template + clone_base * + make_clone( T const & x ) + { + try + { + return new exception_clone(x); + } + catch( + std::bad_alloc & ) + { + static bad_alloc_impl bad_alloc; + return &bad_alloc; + } + catch( + ... ) + { + BOOST_ASSERT(0); + return 0; + } + } + } + + template + exception_detail::clone_impl + enable_exception_cloning( T const & x ) + { + return exception_detail::clone_impl(x); + } + } + +#endif diff --git a/include/boost/exception/error_info.hpp b/include/boost/exception/error_info.hpp new file mode 100644 index 0000000..816942f --- /dev/null +++ b/include/boost/exception/error_info.hpp @@ -0,0 +1,16 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#ifndef UUID_0E57632CCA3011DCB876FD9955D89593 +#define UUID_0E57632CCA3011DCB876FD9955D89593 + +namespace +boost + { + template + class error_info; + } + +#endif diff --git a/include/boost/exception/exception.hpp b/include/boost/exception/exception.hpp new file mode 100644 index 0000000..ec1bf1b --- /dev/null +++ b/include/boost/exception/exception.hpp @@ -0,0 +1,90 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#ifndef UUID_274DA366004E11DCB1DDFE2E56D89593 +#define UUID_274DA366004E11DCB1DDFE2E56D89593 + +#include +#include +#include + +namespace +boost + { + template + class shared_ptr; + + namespace + exception_detail + { + class error_info_base; + + struct + error_info_container: + public exception_detail::counted_base + { + virtual char const * what( std::type_info const & ) const = 0; + virtual shared_ptr get( std::type_info const & ) const = 0; + virtual void set( shared_ptr const & ) = 0; + }; + } + + template + class error_info; + + template + E const & operator<<( E const &, error_info const & ); + + template + shared_ptr get_error_info( E const & ); + + class + exception + { + public: + + virtual ~exception() throw()=0; + virtual char const * what() const throw(); + + private: + + shared_ptr get( std::type_info const & ) const; + void set( shared_ptr const & ) const; + + template + friend E const & operator<<( E const &, error_info const & ); + + template + friend shared_ptr get_error_info( E const & ); + + intrusive_ptr mutable data_; + }; + + inline + exception:: + ~exception() throw() + { + } + + inline + char const * + exception:: + what() const throw() + { + if( data_ ) + try + { + char const * w = data_->what(typeid(*this)); + BOOST_ASSERT(0!=w); + return w; + } + catch(...) + { + } + return typeid(*this).name(); + } + } + +#endif diff --git a/include/boost/exception/info.hpp b/include/boost/exception/info.hpp new file mode 100644 index 0000000..a67bb9b --- /dev/null +++ b/include/boost/exception/info.hpp @@ -0,0 +1,233 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#ifndef UUID_8D22C4CA9CC811DCAA9133D256D89593 +#define UUID_8D22C4CA9CC811DCAA9133D256D89593 + +#include +#include +#include +#include +#include +#include +#include + +#define BOOST_ERROR_INFO\ + ::boost::throw_function(BOOST_CURRENT_FUNCTION) <<\ + ::boost::throw_file(__FILE__) <<\ + ::boost::throw_line((int)__LINE__) + +namespace +boost + { + typedef error_info throw_function; + typedef error_info throw_file; + typedef error_info throw_line; + + namespace + exception_detail + { + class + error_info_base + { + public: + + virtual std::type_info const & tag_typeid() const = 0; + virtual std::string value_as_string() const = 0; + }; + } + + template + class + error_info: + public exception_detail::error_info_base + { + public: + + typedef T value_type; + + error_info( value_type const & value ): + value_(value) + { + } + + value_type const & + value() const + { + return value_; + } + + private: + + std::type_info const & + tag_typeid() const + { + return typeid(type); + } + + std::string + value_as_string() const + { + return to_string_stub(value_); + } + + value_type const value_; + }; + + template + struct + error_info_type + { + typedef typename ErrorInfo::value_type value_type; + }; + + template + E const & + operator<<( E const & x, error_info const & v ) + { + shared_ptr< error_info > p( new error_info(v) ); + x.set(p); + return x; + } + + template + shared_ptr + get_error_info( E const & some_exception ) + { + if( exception const * x = dynamic_cast(&some_exception) ) + if( shared_ptr eib = x->get(typeid(ErrorInfo)) ) + { + BOOST_ASSERT( 0!=dynamic_cast(eib.get()) ); + ErrorInfo const * w = static_cast(eib.get()); + return shared_ptr(eib,&w->value()); + } + return shared_ptr(); + } + + namespace + exception_detail + { + class + error_info_container_impl: + public error_info_container + { + public: + + error_info_container_impl(): + count_(0) + { + } + + ~error_info_container_impl() throw() + { + } + + shared_ptr + get( std::type_info const & ti ) const + { + error_info_map::const_iterator i=info_.find(typeinfo(ti)); + if( info_.end()!=i ) + { + shared_ptr const & p = i->second; + BOOST_ASSERT( typeid(*p)==ti ); + return p; + } + return shared_ptr(); + } + + void + set( shared_ptr const & x ) + { + BOOST_ASSERT(x); + info_[typeinfo(typeid(*x))] = x; + what_.clear(); + } + + char const * + what( std::type_info const & exception_type ) const + { + if( what_.empty() ) + { + std::string tmp(exception_type.name()); + tmp += '\n'; + for( error_info_map::const_iterator i=info_.begin(),end=info_.end(); i!=end; ++i ) + { + shared_ptr const & x = i->second; + tmp += '['; + tmp += x->tag_typeid().name(); + tmp += "] = "; + tmp += x->value_as_string(); + tmp += '\n'; + } + what_.swap(tmp); + } + return what_.c_str(); + } + + private: + + friend class exception; + + struct + typeinfo + { + std::type_info const * type; + + explicit + typeinfo( std::type_info const & t ): + type(&t) + { + } + + bool + operator<( typeinfo const & b ) const + { + return 0!=(type->before(*b.type)); + } + }; + + typedef std::map< typeinfo, shared_ptr > error_info_map; + error_info_map info_; + std::string mutable what_; + int mutable count_; + + void + add_ref() const + { + ++count_; + } + + void + release() const + { + if( !--count_ ) + delete this; + } + }; + } + + inline + void + exception:: + set( shared_ptr const & x ) const + { + if( !data_ ) + data_ = intrusive_ptr(new exception_detail::error_info_container_impl); + data_->set(x); + } + + inline + shared_ptr + exception:: + get( std::type_info const & ti ) const + { + if( data_ ) + return data_->get(ti); + else + return shared_ptr(); + } + } + +#endif diff --git a/include/boost/exception/info_tuple.hpp b/include/boost/exception/info_tuple.hpp new file mode 100644 index 0000000..8b0f5ea --- /dev/null +++ b/include/boost/exception/info_tuple.hpp @@ -0,0 +1,64 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#ifndef UUID_63EE924290FB11DC87BB856555D89593 +#define UUID_63EE924290FB11DC87BB856555D89593 + +#include +#include + +namespace +boost + { + template < + class E, + class Tag1,class T1, + class Tag2,class T2 > + E const & + operator<<( + E const & x, + tuple< + error_info, + error_info > const & v ) + { + return x << v.get<0>() << v.get<1>(); + } + + template < + class E, + class Tag1,class T1, + class Tag2,class T2, + class Tag3,class T3 > + E const & + operator<<( + E const & x, + tuple< + error_info, + error_info, + error_info > const & v ) + { + return x << v.get<0>() << v.get<1>() << v.get<2>(); + } + + template < + class E, + class Tag1,class T1, + class Tag2,class T2, + class Tag3,class T3, + class Tag4,class T4 > + E const & + operator<<( + E const & x, + tuple< + error_info, + error_info, + error_info, + error_info > const & v ) + { + return x << v.get<0>() << v.get<1>() << v.get<2>() << v.get<3>(); + } + } + +#endif diff --git a/include/boost/exception/to_string.hpp b/include/boost/exception/to_string.hpp new file mode 100644 index 0000000..c52e350 --- /dev/null +++ b/include/boost/exception/to_string.hpp @@ -0,0 +1,27 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#ifndef UUID_7E48761AD92811DC9011477D56D89593 +#define UUID_7E48761AD92811DC9011477D56D89593 + +#include + +namespace +boost + { + namespace + { + template + std::string + to_string( T const & x ) + { + std::ostringstream out; + out << x; + return out.str(); + } + } + } + +#endif diff --git a/include/boost/exception/to_string_stub.hpp b/include/boost/exception/to_string_stub.hpp new file mode 100644 index 0000000..45ac98e --- /dev/null +++ b/include/boost/exception/to_string_stub.hpp @@ -0,0 +1,148 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#ifndef UUID_E788439ED9F011DCB181F25B55D89593 +#define UUID_E788439ED9F011DCB181F25B55D89593 + +#include +#include + +namespace +boost + { + namespace + exception_detail + { + template + struct shift_left_dispatcher; + + template <> + struct + shift_left_dispatcher + { + template + static + void + convert( std::basic_ostream & out, T const & x, Stub ) + { + out << x; + } + }; + + template <> + struct + shift_left_dispatcher + { + template + static + void + convert( std::basic_ostream & out, T const & x, Stub s ) + { + out << s(x); + } + }; + + namespace + shift_left_dispatch + { + template + char operator<<( std::basic_ostream &, T ); + + template + void + dispatch( std::basic_ostream & out, T const & x, Stub s ) + { + shift_left_dispatcher<1!=sizeof(out<::convert(out,x,s); + } + } + } + + namespace + exception_detail + { + template + struct to_string_dispatcher; + + template <> + struct + to_string_dispatcher + { + template + static + std::string + convert( T const & x, Stub ) + { + return to_string(x); + } + }; + + template <> + struct + to_string_dispatcher + { + template + static + std::string + convert( T const & x, Stub s ) + { + std::ostringstream out; + shift_left_dispatch::dispatch(out,x,s); + return out.str(); + } + }; + + namespace + to_string_dispatch + { + template + char to_string( T ); + + template + std::string + dispatch( T const & x, Stub s ) + { + return to_string_dispatcher<1!=sizeof(to_string(x))>::convert(x,s); + } + } + + template + std::string + string_stub_dump( T const & x ) + { + std::ostringstream s; + s << "[ type: " << typeid(x).name() << ", size: " << sizeof(T) << ", dump: "; + size_t n=sizeof(T)>16?16:sizeof(T); + s.fill('0'); + s.width(2); + for( unsigned char const * b=reinterpret_cast(&x),* e=b+n; b!=e; ++b ) + s << std::setw(2) << std::hex << (unsigned int)*b << " "; + s << "]"; + return s.str(); + } + } + + template + std::string + to_string_stub( T const & x ) + { + return exception_detail::to_string_dispatch::dispatch(x,&exception_detail::string_stub_dump); + } + + template + std::string + to_string_stub( T const & x, Stub s ) + { + return exception_detail::to_string_dispatch::dispatch(x,s); + } + + template + std::string + to_string( std::pair const & x ) + { + return std::string("(") + to_string(x.first) + ',' + to_string(x.second) + ')'; + } + } + +#endif diff --git a/test/Jamfile b/test/Jamfile new file mode 100644 index 0000000..6e03750 --- /dev/null +++ b/test/Jamfile @@ -0,0 +1,20 @@ +# Boost Exception Library test Jamfile +# +# Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. +# +# Distributed under the Boost Software License, Version 1.0. (See accompanying +# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +import testing ; + +run cloning_test.cpp ; +run unknown_exception_test.cpp ; +run to_string_test.cpp ; +run exception_test.cpp ; +run boost_error_info_test.cpp ; +run enable_error_info_test.cpp helper1.cpp ; +run throw_exception_test.cpp helper2.cpp ; +run errno_test.cpp ; +run error_info_test.cpp ; +run what_test.cpp ; +compile-fail exception_fail.cpp ; diff --git a/test/boost_error_info_test.cpp b/test/boost_error_info_test.cpp new file mode 100644 index 0000000..86be899 --- /dev/null +++ b/test/boost_error_info_test.cpp @@ -0,0 +1,40 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#include +#include +#include + +namespace +test + { + class my_exception: public boost::exception { }; + + typedef boost::error_info my_info; + + void + test_boost_error_info() + { + try + { + throw my_exception() << BOOST_ERROR_INFO << my_info(1); + } + catch( + my_exception & x ) + { + BOOST_TEST(1==*boost::get_error_info(x)); + BOOST_TEST(boost::get_error_info(x)); + BOOST_TEST(boost::get_error_info(x)); + BOOST_TEST(boost::get_error_info(x)); + } + } + } + +int +main() + { + test::test_boost_error_info(); + return boost::report_errors(); + } diff --git a/test/cloning_test.cpp b/test/cloning_test.cpp new file mode 100644 index 0000000..5c480fc --- /dev/null +++ b/test/cloning_test.cpp @@ -0,0 +1,42 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#include +#include + +struct +test_exception: + std::exception + { + }; + +int +main() + { + try + { + throw boost::enable_exception_cloning(test_exception()); + } + catch( + std::exception & x ) + { + boost::exception_ptr p = boost::clone_exception(x); + try + { + rethrow_exception(p); + BOOST_TEST(false); + } + catch( + test_exception & ) + { + } + catch( + ... ) + { + BOOST_TEST(false); + } + } + return boost::report_errors(); + } diff --git a/test/enable_error_info_test.cpp b/test/enable_error_info_test.cpp new file mode 100644 index 0000000..d107597 --- /dev/null +++ b/test/enable_error_info_test.cpp @@ -0,0 +1,49 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#include "helper1.hpp" +#include +#include + +namespace + { + typedef boost::error_info test_int; + + void + throw_wrapper() + { + try + { + boost::exception_test::throw_length_error(); + } + catch( + boost::exception & x ) + { + x << test_int(42); + throw; + } + } + } + +int +main() + { + try + { + throw_wrapper(); + BOOST_TEST(false); + } + catch( + std::exception & x ) + { + BOOST_TEST( 42==*boost::get_error_info(x) ); + } + catch( + ... ) + { + BOOST_TEST(false); + } + return boost::report_errors(); + } diff --git a/test/errno_test.cpp b/test/errno_test.cpp new file mode 100644 index 0000000..78a02f0 --- /dev/null +++ b/test/errno_test.cpp @@ -0,0 +1,33 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#include +#include +#include + +typedef boost::error_info info_errno; + +class +my_exception: + public boost::exception + { + }; + +int +main() + { + try + { + errno=1; + throw my_exception() << info_errno(errno); + BOOST_TEST(false); + } + catch( + my_exception & x ) + { + BOOST_TEST(1==*boost::get_error_info(x)); + } + return boost::report_errors(); + } diff --git a/test/error_info_test.cpp b/test/error_info_test.cpp new file mode 100644 index 0000000..54c8f68 --- /dev/null +++ b/test/error_info_test.cpp @@ -0,0 +1,217 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#include +#include + +struct throws_on_copy; +struct non_printable { }; + +typedef boost::error_info test_1; +typedef boost::error_info test_2; +typedef boost::error_info test_3; +typedef boost::error_info test_4; +typedef boost::error_info test_5; +typedef boost::error_info test_6; + +struct +test_exception: + public boost::exception + { + }; + +struct +throws_on_copy + { + throws_on_copy() + { + } + + throws_on_copy( throws_on_copy const & ) + { + throw test_exception(); + } + }; + +void +basic_test() + { + test_exception x; + x << test_1(1) << test_2(2u) << test_3(3.14159f); + BOOST_TEST(*boost::get_error_info(x)==1); + BOOST_TEST(*boost::get_error_info(x)==2u); + BOOST_TEST(*boost::get_error_info(x)==3.14159f); + BOOST_TEST(!boost::get_error_info(x)); + } + +void +exception_safety_test() + { + test_exception x; + try + { + x << test_4(throws_on_copy()); + BOOST_TEST(false); + } + catch( + test_exception & ) + { + } + BOOST_TEST(!boost::get_error_info(x)); + } + +void +throw_empty() + { + throw test_exception(); + } + +void +throw_test_1( char const * value ) + { + throw test_exception() << test_5(std::string(value)); + } + +void +throw_test_2() + { + throw test_exception() << test_6(non_printable()); + } + +void +throw_catch_add_file_name( char const * name ) + { + try + { + throw_empty(); + BOOST_TEST(false); + } + catch( + boost::exception & x ) + { + x << test_5(std::string(name)); + throw; + } + } + +void +test_empty() + { + try + { + throw_empty(); + BOOST_TEST(false); + } + catch( + boost::exception & x ) + { + BOOST_TEST( dynamic_cast(&x) ); + BOOST_TEST( !boost::get_error_info(x) ); + } + + try + { + throw_empty(); + BOOST_TEST(false); + } + catch( + test_exception & x ) + { + BOOST_TEST( dynamic_cast(&x) ); + } + } + +void +test_basic_throw_catch() + { + try + { + throw_test_1("test"); + BOOST_ASSERT(false); + } + catch( + boost::exception & x ) + { + BOOST_TEST(*boost::get_error_info(x)==std::string("test")); + } + try + { + throw_test_2(); + BOOST_ASSERT(false); + } + catch( + boost::exception & x ) + { + BOOST_TEST(boost::get_error_info(x)); + } + } + +void +test_catch_add_info() + { + try + { + throw_catch_add_file_name("test"); + BOOST_TEST(false); + } + catch( + boost::exception & x ) + { + BOOST_TEST(*boost::get_error_info(x)==std::string("test")); + } + } + +void +test_add_tuple() + { + typedef boost::tuple test_12; + typedef boost::tuple test_123; + typedef boost::tuple test_1235; + try + { + throw test_exception() << test_12(42,42u); + } + catch( + test_exception & x ) + { + BOOST_TEST( *boost::get_error_info(x)==42 ); + BOOST_TEST( *boost::get_error_info(x)==42u ); + } + try + { + throw test_exception() << test_123(42,42u,42.0f); + } + catch( + test_exception & x ) + { + BOOST_TEST( *boost::get_error_info(x)==42 ); + BOOST_TEST( *boost::get_error_info(x)==42u ); + BOOST_TEST( *boost::get_error_info(x)==42.0f ); + } + try + { + throw test_exception() << test_1235(42,42u,42.0f,std::string("42")); + } + catch( + test_exception & x ) + { + BOOST_TEST( *boost::get_error_info(x)==42 ); + BOOST_TEST( *boost::get_error_info(x)==42u ); + BOOST_TEST( *boost::get_error_info(x)==42.0f ); + BOOST_TEST( *boost::get_error_info(x)=="42" ); + } + } + +int +main() + { + basic_test(); + exception_safety_test(); + test_empty(); + test_basic_throw_catch(); + test_catch_add_info(); + test_add_tuple(); + return boost::report_errors(); + } diff --git a/test/exception_fail.cpp b/test/exception_fail.cpp new file mode 100644 index 0000000..d39b27a --- /dev/null +++ b/test/exception_fail.cpp @@ -0,0 +1,12 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#include + +void +tester( boost::exception & x ) + { + throw x; //must not compile. + } diff --git a/test/exception_test.cpp b/test/exception_test.cpp new file mode 100644 index 0000000..39ace16 --- /dev/null +++ b/test/exception_test.cpp @@ -0,0 +1,35 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#include +#include + +class +test_exception: + public boost::exception + { + }; + +void +test_throw() + { + throw test_exception(); + } + +int +main() + { + try + { + test_throw(); + BOOST_TEST(false); + } + catch( + test_exception & ) + { + BOOST_TEST(true); + } + return boost::report_errors(); + } diff --git a/test/helper1.cpp b/test/helper1.cpp new file mode 100644 index 0000000..1446bd2 --- /dev/null +++ b/test/helper1.cpp @@ -0,0 +1,21 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#include +#include + +namespace +boost + { + namespace + exception_test + { + void + throw_length_error() + { + throw enable_error_info( std::length_error("my length error") ); + } + } + } diff --git a/test/helper1.hpp b/test/helper1.hpp new file mode 100644 index 0000000..531983b --- /dev/null +++ b/test/helper1.hpp @@ -0,0 +1,19 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#ifndef UUID_4AEB7924CA2E11DC888A8C9355D89593 +#define UUID_4AEB7924CA2E11DC888A8C9355D89593 + +namespace +boost + { + namespace + exception_test + { + void throw_length_error(); + } + } + +#endif diff --git a/test/helper2.cpp b/test/helper2.cpp new file mode 100644 index 0000000..42b5721 --- /dev/null +++ b/test/helper2.cpp @@ -0,0 +1,53 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#include "helper2.hpp" +#include + +namespace +boost + { + namespace + exception_test + { + inline + some_boost_exception:: + some_boost_exception( int x ): + x_(x) + { + } + + some_boost_exception:: + ~some_boost_exception() throw() + { + } + + inline + some_std_exception:: + some_std_exception( int x ): + x_(x) + { + } + + some_std_exception:: + ~some_std_exception() throw() + { + } + + template <> + void + throw_test_exception( int x ) + { + boost::throw_exception( some_boost_exception(x) ); + } + + template <> + void + throw_test_exception( int x ) + { + boost::throw_exception( some_std_exception(x) ); + } + } + } diff --git a/test/helper2.hpp b/test/helper2.hpp new file mode 100644 index 0000000..3e74c97 --- /dev/null +++ b/test/helper2.hpp @@ -0,0 +1,47 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#ifndef UUID_BC765EB4CA2A11DCBDC5828355D89593 +#define UUID_BC765EB4CA2A11DCBDC5828355D89593 + +#include + +namespace +boost + { + namespace + exception_test + { + struct + some_boost_exception: + public boost::exception, + public std::exception + { + explicit some_boost_exception( int x ); + virtual ~some_boost_exception() throw(); + int x_; + }; + + struct + some_std_exception: + public std::exception + { + explicit some_std_exception( int x ); + virtual ~some_std_exception() throw(); + int x_; + }; + + template + void throw_test_exception( int ); + + template <> + void throw_test_exception( int ); + + template <> + void throw_test_exception( int ); + } + } + +#endif diff --git a/test/throw_exception_test.cpp b/test/throw_exception_test.cpp new file mode 100644 index 0000000..78d64d0 --- /dev/null +++ b/test/throw_exception_test.cpp @@ -0,0 +1,71 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#include "helper2.hpp" +#include +#include +#include + +typedef boost::error_info test_int; + +void +throw_fwd( void (*thrower)(int) ) + { + try + { + thrower(42); + } + catch( + boost::exception & x ) + { + x << test_int(42); + throw; + } + } + +template +void +tester() + { + try + { + throw_fwd( &boost::exception_test::throw_test_exception ); + BOOST_ASSERT(false); + } + catch( + std::exception & x ) + { + boost::exception_ptr p = boost::clone_exception(x); + try + { + rethrow_exception(p); + BOOST_TEST(false); + } + catch( + T & y ) + { + BOOST_TEST(*boost::get_error_info(y)==42); + BOOST_TEST(y.x_==42); + } + catch( + ... ) + { + BOOST_TEST(false); + } + } + catch( + ... ) + { + BOOST_TEST(false); + } + } + +int +main() + { + tester(); + tester(); + return boost::report_errors(); + } diff --git a/test/to_string_test.cpp b/test/to_string_test.cpp new file mode 100644 index 0000000..e56a2fa --- /dev/null +++ b/test/to_string_test.cpp @@ -0,0 +1,97 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#include +#include +#include + +namespace +n1 + { + class + c1 + { + }; + + std::string + to_string( c1 const & ) + { + return "c1"; + } + } + +namespace +n2 + { + class + c2 + { + }; + + std::ostream & + operator<<( std::ostream & s, c2 const & ) + { + s << "c2"; + return s; + } + } + +namespace +n3 + { + class + c3 + { + }; + + std::ostream & + operator<<( std::ostream & s, c3 const & ) + { + s << "bad"; + return s; + } + + std::string + to_string( c3 const & ) + { + return "c3"; + } + } + +namespace +boost + { + class + to_string_tester + { + }; + } + +template +struct +my_stub + { + std::string + operator()( T const & ) + { + return "stub"; + } + }; + +int +main() + { + using namespace boost; + BOOST_TEST( to_string(5)=="5" ); + BOOST_TEST( to_string(n1::c1())=="c1" ); + BOOST_TEST( to_string(n2::c2())=="c2" ); + BOOST_TEST( to_string(n3::c3())=="c3" ); + BOOST_TEST( to_string_stub(5)=="5" ); + BOOST_TEST( to_string_stub(n1::c1())=="c1" ); + BOOST_TEST( to_string_stub(n2::c2())=="c2" ); + BOOST_TEST( to_string_stub(n3::c3())=="c3" ); + BOOST_TEST( to_string_stub(to_string_tester(),my_stub())=="stub" ); + return boost::report_errors(); + } diff --git a/test/unknown_exception_test.cpp b/test/unknown_exception_test.cpp new file mode 100644 index 0000000..030ea8d --- /dev/null +++ b/test/unknown_exception_test.cpp @@ -0,0 +1,84 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#include +#include +#include + +typedef boost::error_info test; + +struct +test_boost_exception: + boost::exception + { + }; + +void +throw_boost_exception() + { + throw test_boost_exception() << test(42); + } + +void +throw_unknown_exception() + { + struct + test_exception: + std::exception + { + }; + throw test_exception(); + } + +int +main() + { + try + { + throw_boost_exception(); + } + catch( + boost::exception & x ) + { + boost::exception_ptr ep=boost::clone_exception(x); + try + { + rethrow_exception(ep); + } + catch( + boost::unknown_exception & x ) + { + BOOST_TEST( 42==*boost::get_error_info(x) ); + } + catch( + ... ) + { + BOOST_TEST(false); + } + } + try + { + throw_unknown_exception(); + } + catch( + std::exception & x ) + { + boost::exception_ptr ep=boost::clone_exception(x); + try + { + rethrow_exception(ep); + } + catch( + boost::unknown_exception & ) + { + } + catch( + ... ) + { + BOOST_TEST(false); + } + } + return boost::report_errors(); + } diff --git a/test/what_test.cpp b/test/what_test.cpp new file mode 100644 index 0000000..71e443a --- /dev/null +++ b/test/what_test.cpp @@ -0,0 +1,27 @@ +//Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. + +//Distributed under the Boost Software License, Version 1.0. (See accompanying +//file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +#include +#include + +typedef boost::error_info test; + +class +my_exception: + public boost::exception + { + }; + +int +main() + { + my_exception x; + x << test(1); + std::string w1 = x.what(); + x << test(2); + std::string w2 = x.what(); + BOOST_TEST( w1!=w2 ); + return boost::report_errors(); + }