This macro takes an exception object, records BOOST_CURRENT_FUNCTION, __FILE__ and __LINE__ in it, and forwards it to throw_exception. To recover this information at the catch site, use get_error_info; the information is also included in the message returned by diagnostic_information.
+
This macro takes an exception object, records the current function name, __FILE__ and __LINE__ in it, and forwards it to throw_exception. To recover this information at the catch site, use get_error_info; the information is also included in the message returned by diagnostic_information.
Note that on some non-conformant compilers, for example MSVC 7.0 and older, as well as BCC, BOOST_EXCEPTION_DISABLE is implicitly defined in boost/throw_exception.hpp.
BOOST_NO_EXCEPTIONS
This macro disables exception handling in Boost, forwarding all exceptions to a user-defined non-template version of boost::throw_exception. However, unless BOOST_EXCEPTION_DISABLE is also defined, users can still examine the exception object for any data added at the point of the throw, or use boost::diagnostic_information (of course under BOOST_NO_EXCEPTIONS, the user-defined boost::throw_exception is not allowed to return to the caller.)
+
BOOST_THROW_EXCEPTION_CURRENT_FUNCTION
+
The BOOST_THROW_EXCEPTION macro uses BOOST_THROW_EXCEPTION_CURRENT_FUNCTION to record the name of the current function in the exception object. Unless overridden by the user, BOOST_THROW_EXCEPTION_CURRENT_FUNCTION expands to BOOST_CURRENT_FUNCTION.
diff --git a/doc/diagnostic_information.html b/doc/diagnostic_information.html
index a909eb4..2805813 100644
--- a/doc/diagnostic_information.html
+++ b/doc/diagnostic_information.html
@@ -26,25 +26,21 @@
boost
{
template <class E>
- std::string diagnostic_information( E const & e );
+ std::string diagnostic_information( E const & e, bool verbose=true );
- std::string diagnostic_information( exception_ptr const & p );
+ std::string diagnostic_information( exception_ptr const & p, bool verbose=true );
}
Returns:
-
A string value that contains varying amount of implementation-specific diagnostic information about the passed object:
-
If E can be statically converted to boost::exception, the returned value contains the string representations of all error_info objects stored in the boost::exception through operator<<, along with other diagnostic information relevant to the exception. If e can be dynamically converted to std::exception, the returned value also contains the what() string.
-
Otherwise, if E can be statically converted to std::exception:
if e can be dynamically converted to boost::exception, the returned value is the same as if E could be statically converted to boost::exception;
-
otherwise the returned value contains the what() string.
+
A string value that contains varying amount of diagnostic information about the passed object:
+
If E can be statically converted to either boost::exception or to std::exception, dynamic_cast is used to access both the boost::exception and std::exception subobjects of e; otherwise, the boost::diagnostic_information template is not available.
+
The returned value contains the string representations of all error_info objects stored in the boost::exception subobject through operator<<.
+
In addition, if verbose is true, it contains other diagnostic information relevant to the exception, including the string returned by std::exception::what().
-
-
Otherwise, the boost::diagnostic_information template is not available.
-
-
The string representation of each error_info object is deduced by a function call that is bound at the time the error_info<Tag,T> template is instantiated. The following overload resolutions are attempted in order:
-
Unqualified call to to_string(x), where x is of type error_info<Tag,T> (the return value is expected to be of type std::string.)
-
Unqualified call to to_string(x.value()) (the return value is expected to be of type std::string.)
+
The string representation of each error_info object is deduced by an unqualified call to to_string(x), where x is of type error_info<Tag,T>, for which Boost Exception defines a generic overload. It converts x.value() to string, attempting to bind (at the time the error_info<Tag,T> template is instantiated) the following functions in order:
+
Unqualified call to to_string(x.value()) (the return value is expected to be of type std::string.)
Unqualified call to s << x.value(), where s is a std::ostringstream.
-
The first successfully bound function is used at the time diagnostic_information is called; if all 3 overload resolutions are unsuccessful, the system is unable to convert the error_info object to string, and an unspecified stub string value is used without issuing a compile error.
+
The first successfully bound function is used at the time diagnostic_information is called; if both overload resolutions are unsuccessful, the system is unable to convert the error_info object to string, and an unspecified stub string value is used without issuing a compile error.
The exception_ptr overload of diagnostic_information is equivalent to:
The diagnostic_information_what function is intended to be called from a user-defined std::exception::what() override. This allows diagnostic information to be returned as the what() string.
Instead of using the throw keyword directly, it is preferable to call boost::throw_exception. This is guaranteed to throw an exception that derives from boost::exception and supports the exception_ptr functionality.
An exception_ptr can be added as error_info to any boost::exception. This is a convenient way to nest exceptions. There is no limit on the depth of the nesting, however cyclic references result in undefined behavior.
What is the cost of calling boost::throw_exception?
+
The cost is that boost::exception is added as a base of the exception emitted by boost::throw_exception (unless the passed type already derives from boost::exception.)
+
Calling boost::throw_exception does not cause dynamic memory allocations.
Should I use boost::throw_exception or BOOST_THROW_EXCEPTION or just throw?
+
The benefit of calling boost::throw_exception instead of using throw directly is that it ensures that the emitted exception derives from boost::exception and that it is compatible with boost::current_exception.
+
The BOOST_THROW_EXCEPTION macro also results in a call to boost::throw_exception, but in addition it records in the exception object the __FILE__ and __LINE__ of the throw, as well as the pretty name of the function that throws. This enables boost::diagnostic_information to compose a more useful, if not user-friendly message.
This is a possible message it may display -- the information in the first line is only available if BOOST_THROW_EXCEPTION was used to throw:
+
example_io.cpp(70): Throw in function class boost::shared_ptr<struct _iobuf> __cdecl my_fopen(const char *,const char *)
+Dynamic exception type: class boost::exception_detail::clone_impl<class fopen_error>
+std::exception::what: example_io error
+[struct boost::errinfo_api_function_ *] = fopen
+[struct boost::errinfo_errno_ *] = 2, "No such file or directory"
+[struct boost::errinfo_file_name_ *] = tmp1.txt
+[struct boost::errinfo_file_open_mode_ *] = rb
+
In some development environments, the first line in that message can be clicked to show the location of the throw in the debugger, so it's easy to set a break point and run again to see the unexpected throw in the context of its call stack.
Why doesn't boost::exception derive from std::exception?
Of course, boost::exception should not be used to replace std::exception as a base type in exception type hierarchies. Instead, it should be included as a virtual base, in addition to std::exception (which should also be derived virtually.)
If boost::exception derives from std::exception, using the enable_error_info function with such user-defined types would introduce dangerous ambiguity which would break all catch(std::exception &) statements.
+
Of course, boost::exception should not be used to replace std::exception as a base type in exception type hierarchies. Instead, it should be included as a virtual base, in addition to std::exception (which should probably also be derived virtually.)
Why is boost::exception abstract?
To prevent exception-neutral contexts from erroneously erasing the type of the original exception when adding error_info to an active exception object:
catch( boost::exception & e )
@@ -37,55 +63,16 @@
e << foo_info(foo);
throw; //Okay, re-throwing the original exception object.
}
-
What is the space overhead of the boost::exception base class?
-
The space overhead for the boost::exception data members is negligible in the context of exception handling. Throwing objects that derive from boost::exception does not by itself cause dynamic memory allocations.
-
Deriving from boost::exception enables any data to be added to exceptions, which usually does allocate memory. However, this memory is reclaimed when the exception has been handled, and since typically user code does not allocate memory during the unrolling of the stack, adding error info to exceptions should not cause memory fragmentation.
-
Should I use boost::throw_exception or BOOST_THROW_EXCEPTION or just throw?
-
The benefit of calling boost::throw_exception instead of using throw directly is that it ensures that the emitted exception derives from boost::exception and that it is compatible with boost::current_exception.
-
The BOOST_THROW_EXCEPTION macro also results in a call to boost::throw_exception, but in addition it records in the exception object the __FILE__ and __LINE__ of the throw, as well as the pretty name of the function that throws. This has virtually no overhead, yet enables boost::diagnostic_information to compose a more useful, if not user-friendly message.
This is a possible message it may display, the first line is only possible if BOOST_THROW_EXCEPTION is used:
-
example_io.cpp(70): Throw in function class boost::shared_ptr<struct _iobuf> __cdecl my_fopen(const char *,const char *)
-Dynamic exception type: class boost::exception_detail::clone_impl<class fopen_error>
-std::exception::what: example_io error
-[struct boost::errinfo_api_function_ *] = fopen
-[struct boost::errinfo_errno_ *] = 2, "No such file or directory"
-[struct boost::errinfo_file_name_ *] = tmp1.txt
-[struct boost::errinfo_file_open_mode_ *] = rb
-
Why is boost::exception integrated in boost::throw_exception?
-
The boost::throw_exception function predates the Boost Exception library and there has been some concern about its current behavior of injecting boost::exception as a base of any exception passed to boost::throw_exception. Such concerns are dictated by the typical strict interpretation of a common principle in C and C++, that users only pay for features they actually use.
-
The problem is that users of Boost Exception can't by themselves cause a library to throw types that derive from boost::exception, and without this they can't use any of the Boost Exception facilities.
-
For example, if a user wants to use Boost Serialization in a separate thread, it is desirable to be able to transport exceptions emitted by that library into the main thread where they can be analyzed to generate a user-friendly message. This can be easily achieved using boost::exception_ptr, but this requires that Boost Serialization throws exceptions using boost::enable_current_exception. If Boost Serialization calls boost::throw_exception to throw, this behavior happens automatically and transparently.
-
The cost of this integration is:
-
In terms of space: a pointer and 3 ints are added to the static size of exception objects.
-
In terms of speed: the pointer is initialized to null at the point of the throw.
-
In terms of coupling: about 400 self-contained lines of C++ with no external includes.
-
Why use operator<< overload for adding info to exceptions?
-
Before throwing an object of type that derives from boost::exception, it is often desirable to add one or more error_info objects in it. The syntactic sugar provided by exception/operator<< allows this to be done directly in a throw expression:
+
Before throwing an object of type that derives from boost::exception, it is often desirable to add one or more error_info objects in it. The syntactic sugar provided by operator<< allows this to be done directly in a throw expression:
The intention here is to throw a file_open_error, however if operator<< fails to copy the std::string contained in the file_name error_info wrapper, a std::bad_alloc could propagate instead. This behavior seems undesirable to some programmers.
Bjarne Stroustrup, The C++ Programming Language, 3rd Edition, page 371:
"Throwing an exception requires an object to throw. A C++ implementation is required to have enough spare memory to be able to throw bad_alloc in case of memory exhaustion. However, it is possible that throwing some other exception will cause memory exhaustion."
-
So, an attempt to throw any exception may already result in propagating std::bad_alloc instead.
+
Therefore, the language itself does not guarantee that an attempt to throw an exception is guaranteed to throw an object of the specified type; propagating a std::bad_alloc seems to be a possibility even outside of the scope of Boost Exception.
If BOOST_NO_EXCEPTIONS is not defined, boost::throw_exception(e) is equivalent to throw boost::enable_current_exception(boost::enable_error_info(e)), unless BOOST_EXCEPTION_DISABLE is defined, in which case boost::throw_exception(e) is equivalent to throw e;
+
Effects:
+
If BOOST_NO_EXCEPTIONS is not defined, boost::throw_exception(e) throws an exception of unspecified type that derives publicly from E and from boost::exception.
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.
-
Note:
-
Under BOOST_NO_EXCEPTIONS, unless BOOST_EXCEPTION_DISABLE is also defined, users can examine the passed exception object using boost::get_error_info, or format an automatic diagnostic message using boost::diagnostic_information.
+
Requirements:
+
E must derive publicly from std::exception. E may or may not derive from boost::exception.
+
Notes:
+
The emitted exception can be intercepted as E &, std::exception &, or boost::exception &.
+
The emitted exception supports boost::exception_ptr.
+
If BOOST_EXCEPTION_DISABLE is defined and BOOST_NO_EXCEPTIONS is not defined, boost::throw_exception(e) equivalent to throw e.
-
-
-Copyright (c) 2006-2009 by Emil Dotchevski and Reverge Studios, Inc.