456 lines
17 KiB
C++
456 lines
17 KiB
C++
/** @file
|
|
|
|
$Id$
|
|
|
|
$Date$
|
|
$Author$
|
|
|
|
@copy © Marc Wäckerlin
|
|
@license LGPL, see file <a href="license.html">COPYING</a>
|
|
|
|
$Log$
|
|
Revision 1.5 2004/10/07 09:25:34 marc
|
|
new group for suggestions
|
|
new inheritance
|
|
|
|
Revision 1.4 2004/08/28 16:21:25 marc
|
|
mrw-c++-0.92 (mrw)
|
|
- new file: version.cpp
|
|
- new file header for all sources
|
|
- work around warning in mrw::auto<T>
|
|
- possibility to compile without log4cxx
|
|
- work around bugs in demangle.h and libiberty.h
|
|
- corrections in documentation
|
|
- added simple tracing mechanism
|
|
- more warnings
|
|
- small corrections in Auto<>::Free and a new test for it
|
|
- possibility to compile without stack trace
|
|
|
|
*/
|
|
#ifndef __MRW_EXCEPTION_HPP__
|
|
#define __MRW_EXCEPTION_HPP__
|
|
|
|
#include <exception>
|
|
#include <stdexcept>
|
|
#include <typeinfo>
|
|
#include <string>
|
|
|
|
namespace mrw {
|
|
|
|
class StackTrace;
|
|
|
|
/** @addtogroup StackTrace
|
|
|
|
@section exc Exception Handling with Stack Trace
|
|
|
|
One of the main reasons for the mrw::StackTrace class is, to be
|
|
able to store a trace where an exception is thrown. This trace
|
|
is then stored as exception information, but not yet evaluated,
|
|
symbols are calculated only if necessary, upon request. So the
|
|
exception is still relatively cheap.
|
|
|
|
There is a class named mrw::exception that derieves from and
|
|
behaves as @c std::exception, but it stores a mrw::StackTrace on
|
|
construction and offers a method @c mrw::exception::stacktrace()
|
|
that returns a well formatted stack trace of the point, where
|
|
the exception was created.
|
|
|
|
@subsection excprob Common Problems with Exception Handling
|
|
|
|
Exceptions are very handy: When you have a problem, you throw an
|
|
exception and when you call a method and reach the next line,
|
|
everything was fine. You don't have to care about error handling
|
|
unless you are able to handle it. Otherwise you simply let pass
|
|
any exception up in the stack.
|
|
|
|
The big disadvantage is, when you catch an exception, you don't
|
|
know where it was thrown. That's the stack trace for. Another
|
|
problem is, the exception specification problem: When you don't
|
|
write exception specifications, you don't know what a specific
|
|
method throws. If you do write exception specifications, they
|
|
are not checked at compile time, but enforced at run time. If a
|
|
wrong exception is thrown, the program stops, calls an
|
|
unexpected handler that by default aborts the program. Since the
|
|
unexpected handler must not return, the problem cannot be
|
|
recovered from. But the unexpected handler can rethrow and catch
|
|
the bad exception and it is allowed to throw a new
|
|
exception. This is what my suggested exception handling concept
|
|
makes use of.
|
|
*/
|
|
//@{
|
|
|
|
/** @example exceptionhandling.cpp
|
|
|
|
It is possible to recover from an unexpected exception! A stack
|
|
trace helps you to find the source of a problem, here function
|
|
@c fn2() in file @c /privat/home/marc/pro/mrw-c++/mrw/test.cpp
|
|
on line @c 25. This example produces the following output:
|
|
|
|
@verbatim
|
|
call fn0
|
|
enter fn0
|
|
enter fn1
|
|
enter fn2
|
|
UNEXPECTED:N3mrw9exceptionE
|
|
---------------------------Stack:
|
|
[0x8049e51] ../sysdeps/i386/elf/start.S:105 _start
|
|
[0x401cfd3e] ????:0 ????
|
|
[0x804a3d0] examples/exceptionhandling.cpp:50 main
|
|
[0x804a2a3] examples/exceptionhandling.cpp:38 fn0()
|
|
[0x804a227] examples/exceptionhandling.cpp:32 fn1()
|
|
[0x804a1c1] examples/exceptionhandling.cpp:25 fn2()
|
|
[0x804fdda] ../mrw/exception.cpp:6 mrw::exception::exception()
|
|
[0x804a8f5] ../mrw/stacktrace.cpp:54 mrw::StackTrace::StackTrace()
|
|
---------------------------------
|
|
EXCEPTION caught in fn0:St13bad_exception
|
|
leave fn0
|
|
call of fn0 successful
|
|
@endverbatim
|
|
|
|
The unexpected handler is implemented ready to use in @ref
|
|
AutoTrace "a separate library".
|
|
|
|
Please note, that without the exception concept and without the
|
|
unexpected handler, the program would abort in function fn2 on
|
|
line 25. The output was produced by the following code:
|
|
*/
|
|
|
|
/** @defgroup exceptions Exceptions with Stack Trace
|
|
|
|
The following diagram shows the inheritance of the MRW exception
|
|
classes and how they are related to the C++ standard
|
|
exceptions. @c mrw::exception inherits @c std::exception, then a
|
|
inheritance corresponding to the standard is implemented below
|
|
@c mrw::exception. To prevent diamond-shaped inheritance, the MRW
|
|
exceptions below the @c mrw::exception base class do not inherit
|
|
from their corresponding standard exception.
|
|
|
|
The exception classes are meant as a replacement to the standard
|
|
exceptions that provide stack trace information. I suggest
|
|
exception handling according to @ref excsug.
|
|
|
|
@dot
|
|
digraph ExceptionInheritance {
|
|
graph [rankdir="LR"];
|
|
node [shape=record, fontname=Helvetica, fontsize=8];
|
|
edge [dir=back, headport=w, tailport=e, arrowtail=empty];
|
|
|
|
std_exception [label="std::exception"];
|
|
std_bad_alloc [label="std::bad_alloc"];
|
|
std_bad_cast [label="std::bad_cast"];
|
|
std_logic_error [label="std::logic_error"];
|
|
std_domain_error [label="std::domain_error"];
|
|
std_invalid_argument [label="std::invalid_argument"];
|
|
std_length_error [label="std::length_error"];
|
|
std_out_of_range [label="std::out_of_range"];
|
|
std_runtime_error [label="std::runtime_error"];
|
|
std_overflow_error [label="std::overflow_error"];
|
|
std_range_error [label="std::range_error"];
|
|
std_underflow_error [label="std::underflow_error"];
|
|
std_bad_exception [label="std::bad_exception"];
|
|
std_bad_typeid [label="std::bad_typeid"];
|
|
|
|
mrw_exception [label="mrw::exception" URL="\ref mrw::exception"];
|
|
mrw_bad_alloc [label="mrw::bad_alloc" URL="\ref mrw::bad_alloc"];
|
|
mrw_bad_cast [label="mrw::bad_cast" URL="\ref mrw::bad_cast"];
|
|
mrw_logic_error [label="mrw::logic_error" URL="\ref mrw::logic_error"];
|
|
mrw_domain_error [label="mrw::domain_error" URL="\ref mrw::domain_error"];
|
|
mrw_invalid_argument [label="mrw::invalid_argument" URL="\ref mrw::invalid_argument"];
|
|
mrw_length_error [label="mrw::length_error" URL="\ref mrw::length_error"];
|
|
mrw_out_of_range [label="mrw::out_of_range" URL="\ref mrw::out_of_range"];
|
|
mrw_runtime_error [label="mrw::runtime_error" URL="\ref mrw::runtime_error"];
|
|
mrw_overflow_error [label="mrw::overflow_error" URL="\ref mrw::overflow_error"];
|
|
mrw_range_error [label="mrw::range_error" URL="\ref mrw::range_error"];
|
|
mrw_underflow_error [label="mrw::underflow_error" URL="\ref mrw::underflow_error"];
|
|
mrw_bad_exception [label="mrw::bad_exception" URL="\ref mrw::bad_exception"];
|
|
mrw_bad_typeid [label="mrw::bad_typeid" URL="\ref mrw::bad_typeid"];
|
|
|
|
{rank=same; std_exception; mrw_exception;}
|
|
{rank=same; std_bad_alloc; mrw_bad_alloc;}
|
|
{rank=same; std_bad_cast; mrw_bad_cast;}
|
|
{rank=same; std_logic_error; mrw_logic_error;}
|
|
{rank=same; std_domain_error; mrw_domain_error;}
|
|
{rank=same; std_invalid_argument; mrw_invalid_argument;}
|
|
{rank=same; std_length_error; mrw_length_error;}
|
|
{rank=same; std_out_of_range; mrw_out_of_range;}
|
|
{rank=same; std_runtime_error; mrw_runtime_error;}
|
|
{rank=same; std_overflow_error; mrw_overflow_error;}
|
|
{rank=same; std_range_error; mrw_range_error;}
|
|
{rank=same; std_underflow_error; mrw_underflow_error;}
|
|
{rank=same; std_bad_exception; mrw_bad_exception;}
|
|
{rank=same; std_bad_typeid; mrw_bad_typeid;}
|
|
|
|
mrw_exception -> mrw_bad_alloc;
|
|
mrw_exception -> mrw_bad_cast;
|
|
mrw_exception -> mrw_logic_error;
|
|
mrw_logic_error -> mrw_domain_error;
|
|
mrw_logic_error -> mrw_invalid_argument;
|
|
mrw_logic_error -> mrw_length_error;
|
|
mrw_logic_error -> mrw_out_of_range;
|
|
mrw_exception -> mrw_runtime_error;
|
|
mrw_runtime_error -> mrw_overflow_error;
|
|
mrw_runtime_error -> mrw_range_error;
|
|
mrw_runtime_error -> mrw_underflow_error;
|
|
mrw_exception -> mrw_bad_exception;
|
|
mrw_exception -> mrw_bad_typeid;
|
|
|
|
std_exception -> std_bad_alloc;
|
|
std_exception -> std_bad_cast;
|
|
std_exception -> std_logic_error;
|
|
std_logic_error -> std_domain_error;
|
|
std_logic_error -> std_invalid_argument;
|
|
std_logic_error -> std_length_error;
|
|
std_logic_error -> std_out_of_range;
|
|
std_exception -> std_runtime_error;
|
|
std_runtime_error -> std_overflow_error;
|
|
std_runtime_error -> std_range_error;
|
|
std_runtime_error -> std_underflow_error;
|
|
std_exception -> std_bad_exception;
|
|
std_exception -> std_bad_typeid;
|
|
|
|
std_exception -> mrw_exception;
|
|
|
|
}
|
|
@enddot
|
|
*/
|
|
//@{
|
|
|
|
/** @brief replacement for @c std::exception, that collects a stack trace
|
|
@pre #include <mrw/exception.hpp>
|
|
|
|
This exception class behaves exactely like @c std::exception,
|
|
but it collects a stack trace in the constructor and offers a
|
|
method to return the formatted stack trace for logging.
|
|
|
|
It is recommended, to inherit all the exceptions you ever throw
|
|
from this class. This way you can always access the stack trace
|
|
if you run into troubles. It is fursther recommended, to write a
|
|
unexpected handler, that rethrows, catches this exception, then
|
|
throws a @c std::bad_exception to try to continue. This is the
|
|
reason, why all the exception specifications in the MRW C++
|
|
Library declar @c throw(std::bad_exception) instead of @c
|
|
throw(), when they throw nothing.
|
|
|
|
@code
|
|
namespace myProject {
|
|
void unexpectedHandler() {
|
|
try {
|
|
throw;
|
|
} catch (mrw::exception& x) {
|
|
// trace x.stacktrace() and x.what()
|
|
} catch (std::exception& x) {
|
|
// trace x.what()
|
|
} catch (...) {
|
|
// trace unknown unexpected
|
|
}
|
|
throw std::bad_exception(); // try to recover
|
|
}
|
|
}
|
|
int main() {
|
|
std::set_unexpected(&myProject::unexpectedHandler);
|
|
...
|
|
}
|
|
@endcode
|
|
*/
|
|
class exception: public std::exception {
|
|
public:
|
|
exception() throw(std::bad_exception);
|
|
virtual ~exception() throw();
|
|
virtual const char* what() const throw() {
|
|
return std::exception::what();
|
|
}
|
|
const std::string& stacktrace() const throw(std::bad_exception);
|
|
private:
|
|
StackTrace* _stacktrace;
|
|
};
|
|
|
|
/// Replacement for @c std::bad_alloc, but with stack trace
|
|
class bad_alloc: public mrw::exception {
|
|
public:
|
|
~bad_alloc() throw() {}
|
|
virtual const char* what() const throw() {
|
|
return "mrw::bad_alloc";
|
|
}
|
|
};
|
|
|
|
/// Replacement for @c std::bad_cast, but with stack trace
|
|
class bad_cast: public mrw::exception {
|
|
public:
|
|
~bad_cast() throw() {}
|
|
virtual const char* what() const throw() {
|
|
return "mrw::bad_cast";
|
|
}
|
|
};
|
|
|
|
/// Replacement for @c std::bad_exception, but with stack trace
|
|
class bad_exception: public mrw::exception {
|
|
public:
|
|
~bad_exception() throw() {}
|
|
virtual const char* what() const throw() {
|
|
return "mrw::bad_exception";
|
|
}
|
|
};
|
|
|
|
/// Replacement for @c std::bad_typeid, but with stack trace
|
|
class bad_typeid: public mrw::exception {
|
|
public:
|
|
~bad_typeid() throw() {}
|
|
virtual const char* what() const throw() {
|
|
return "mrw::bad_typeid";
|
|
}
|
|
};
|
|
|
|
/// Replacement for @c std::logic_error, but with stack trace
|
|
class logic_error: public mrw::exception {
|
|
public:
|
|
~logic_error() throw() {}
|
|
logic_error(const std::string& arg) throw(): _what(arg) {}
|
|
virtual const char* what() const throw() {
|
|
return _what.c_str();
|
|
}
|
|
private:
|
|
std::string _what;
|
|
};
|
|
|
|
/// Replacement for @c std::domain_error, but with stack trace
|
|
class domain_error: public mrw::logic_error {
|
|
public:
|
|
~domain_error() throw() {}
|
|
domain_error(const std::string& arg) throw(): mrw::logic_error(arg) {}
|
|
virtual const char* what() const throw() {
|
|
return mrw::logic_error::what();
|
|
}
|
|
};
|
|
|
|
/// Replacement for @c std::invalid_argument, but with stack trace
|
|
class invalid_argument: public mrw::logic_error {
|
|
public:
|
|
~invalid_argument() throw() {}
|
|
invalid_argument(const std::string& arg) throw(): mrw::logic_error(arg) {}
|
|
virtual const char* what() const throw() {
|
|
return mrw::logic_error::what();
|
|
}
|
|
};
|
|
|
|
/// Replacement for @c std::length_error, but with stack trace
|
|
class length_error: public mrw::logic_error {
|
|
public:
|
|
~length_error() throw() {}
|
|
length_error(const std::string& arg) throw(): mrw::logic_error(arg) {}
|
|
virtual const char* what() const throw() {
|
|
return mrw::logic_error::what();
|
|
}
|
|
};
|
|
|
|
/// Replacement for @c std::out_of_range, but with stack trace
|
|
class out_of_range: public mrw::logic_error {
|
|
public:
|
|
~out_of_range() throw() {}
|
|
out_of_range(const std::string& arg) throw(): mrw::logic_error(arg) {}
|
|
virtual const char* what() const throw() {
|
|
return mrw::logic_error::what();
|
|
}
|
|
};
|
|
|
|
/// Replacement for @c std::runtime_error, but with stack trace
|
|
class runtime_error: public mrw::exception {
|
|
public:
|
|
~runtime_error() throw() {}
|
|
runtime_error(const std::string& arg) throw(): _what(arg) {}
|
|
virtual const char* what() const throw() {
|
|
return _what.c_str();
|
|
}
|
|
private:
|
|
std::string _what;
|
|
};
|
|
|
|
/// Replacement for @c std::overflow_error, but with stack trace
|
|
class overflow_error: public mrw::runtime_error {
|
|
public:
|
|
~overflow_error() throw() {}
|
|
overflow_error(const std::string& arg) throw(): mrw::runtime_error(arg) {}
|
|
virtual const char* what() const throw() {
|
|
return mrw::runtime_error::what();
|
|
}
|
|
};
|
|
|
|
/// Replacement for @c std::range_error, but with stack trace
|
|
class range_error: public mrw::runtime_error {
|
|
public:
|
|
~range_error() throw() {}
|
|
range_error(const std::string& arg) throw(): mrw::runtime_error(arg) {}
|
|
virtual const char* what() const throw() {
|
|
return mrw::runtime_error::what();
|
|
}
|
|
};
|
|
|
|
/// Replacement for @c std::underflow_error, but with stack trace
|
|
class underflow_error: public mrw::runtime_error {
|
|
public:
|
|
~underflow_error() throw() {}
|
|
underflow_error(const std::string& arg) throw(): mrw::runtime_error(arg) {}
|
|
virtual const char* what() const throw() {
|
|
return mrw::runtime_error::what();
|
|
}
|
|
};
|
|
|
|
//@}
|
|
|
|
/** @defgroup excsug Suggested Exception Handling Rules
|
|
|
|
-# derieve all your exceptions from mrw::exception
|
|
-# write exception specifications as follows: @n
|
|
(this specification is "binary", it only declares whether an exception
|
|
is thrown or not, but it does not specify which exact exception can
|
|
be thrown)
|
|
- if no exception is thrown, specify @c throw(std::bad_exception)
|
|
instead of @c throw() as you would normally specify
|
|
- if any exception is thrown specify @c throw(std::exception) @n
|
|
(@b Note: If you need a more specific declaration, you must also
|
|
declare @c std::bad_exception in addition to your exceptions!)
|
|
- only declare @c throw() if you are 100% sure, that it is absolutely
|
|
impossible that this method ever throws an exception, that means
|
|
this method calls no other function or method (not even from a
|
|
system library) that does not declare @c throw()
|
|
-# document the exact exception thrown with Doxygen's @c \@throw tag
|
|
-# write an unexpected handler as follows
|
|
(or link to a @ref AutoTrace "library"):
|
|
|
|
@code
|
|
void unexpectedHandler() {
|
|
try {
|
|
throw;
|
|
} catch (mrw::exception& x) {
|
|
// trace x.stacktrace() and x.what()
|
|
} catch (std::exception& x) {
|
|
// trace x.what()
|
|
} catch (...) {
|
|
// trace unknown unexpected
|
|
}
|
|
throw std::bad_exception(); // try to recover
|
|
}
|
|
@endcode
|
|
|
|
What happens:
|
|
- If you throw an exception in a method that declares not to
|
|
throw an exception, the unexpected handler is called.
|
|
- It writes a stack trace for you to be able to find your bug.
|
|
- Then it throws a @c std::bad_exception, which is allowed to pass.
|
|
- Your program does not abort, but continues running.
|
|
- If higher in the stack you catch the exception, you may be
|
|
able to recover.
|
|
- If you throw an exception where you are allowed to, you only need to
|
|
catch mrw::exception and you can access @c what() and @c stacktrace().
|
|
|
|
For a proof of concept refer to
|
|
@ref exceptionhandling.cpp "the example exceptionhandling.cpp".
|
|
|
|
The unexpected handler is implemented ready to use in @ref
|
|
AutoTrace "a separate library".
|
|
*/
|
|
|
|
//@}
|
|
}
|
|
|
|
#endif
|