C++ Library containing a lot of needful things: Stack Trace, Command Line Parser, Resource Handling, Configuration Files, Unix Command Execution, Directories, Regular Expressions, Tokenizer, Function Trace, Standard Extensions.
455 lines
17 KiB
455 lines
17 KiB
/** @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
|
|
|