include/libsex/Exception.hxx

   1 #ifndef EXCEPTION_HXX
   2 #define EXCEPTION_HXX
   3
   4 #include <exception> // std::exception
   5 #include <stdexcept> // std::bad_alloc
   6 #include <ostream>   // std::ostream
   7
   8 namespace libsex {
   9
  10 /**
  11  * Resembles a generic error, stores a message and
  12  * optionally references one previous error (linked list).
  13  *
  14  * The supplied character array must be terminated by a
  15  * nullbyte. It will be copied into an internal array
  16  * (stored on the stack) that is @ref LENGTH chars long,
  17  * until the nullbyte is reached or the internal array is
  18  * full.
  19  *
  20  * For OO error handling you should subclass this class for
  21  * every type of error. Inheriting by hand is tedious, you
  22  * usally don't want to do this. There are some efficient
  23  * macros in @file create.hxx.
  24  *
  25  * @note The previous exceptions, if any, will be copied
  26  *       by calling clone() which may in turn throw
  27  *       std::bad_alloc. In that case, a notice is appended
  28  *       to this message (as long as the array contains
  29  *       free fields) and the exception is swallowed.
  30  */
  31 class Exception : public std::exception
  32 {
  33 public:
  34         /// Max payload in the internal c-string.
  35         static const unsigned short LENGTH = 500;
  36
  37         /// Creates an Exception.
  38         Exception(const char* const message) throw();
  39
  40         /// Creates an Ex. that references a previous one.
  41         Exception(
  42                 const char* const message,
  43                 const Exception& previous) throw();
  44
  45         /// No-op.
  46         virtual ~Exception() throw();
  47
  48         /**
  49          * Writes our message to passed stream.
  50          *
  51          * @exception std::ios_base::failure
  52          *            may be thrown by stream, if it is
  53          *            configured to do so.
  54          */
  55         void write(std::ostream& out) const throw(std::ios_base::failure);
  56
  57         /**
  58          * Writes a backtrace to passed stream.
  59          *
  60          * Messages are delimited by one newline and are
  61          * printed in reverse chronological order.
  62          *
  63          * @exception std::ios_base::failure
  64          *            may be thrown by stream, if it is
  65          *            configured to do so.
  66          */
  67         void backtrace(std::ostream& out) const throw(std::ios_base::failure);
  68
  69         /**
  70          * Clones this exception.
  71          * @throws std::bad_alloc on memory shortage.
  72          */
  73         virtual const Exception* clone() const throw(std::bad_alloc);
  74
  75         /// @return a pointer to the internal cstring.
  76         virtual const char* what() const throw();
  77
  78 private:
  79         /**
  80          * Copy of message passed to constructor.
  81          *
  82          * Length is Exception::LENGTH plus nullbyte.
  83          */
  84         char _message[LENGTH + 1];
  85
  86         /// Pointer to copy of previous exception, or null.
  87         const Exception* _previous;
  88
  89         /// Used by constructors to initialize _message.
  90         void _initMessage(const char* const message);
  91 };
  92
  93 }; // namespace
  94
  95 #endif