source/Exception.hxx

   1 #ifndef LIBSEX_EXCEPTION_HXX
   2 #define LIBSEX_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          * Generic error made up of a message and
  12          * (optional) references to previous one.
  13          *
  14          * Double-fault save (not throwing std::bad_alloc
  15          * or other exceptions in critical situations) and
  16          * allows exception chaining.
  17          *
  18          * For object-oriented error handling you should
  19          * subclass this class for every type of error.
  20          * There are elegant macros in @file declare.hxx
  21          * and @file define.hxx.
  22          */
  23         class Exception;
  24 }
  25
  26 class libsex::Exception : public std::exception
  27 {
  28 public:
  29         /// Max payload of the internal character string.
  30         static const unsigned short LENGTH = 500;
  31
  32         /**
  33          * Creates an exception.
  34          *
  35          * Supplied character array should be null-
  36          * terminated and should not exceed LENGTH
  37          * characters (excl. null byte). Its contents will
  38          * be copied into an internal buffer and can be
  39          * overwritten/freed afterwards.
  40          *
  41          * The constructors do not accept std::string
  42          * since that class uses the heap and may throw
  43          * std::bad_alloc -- which might obviously happen
  44          * even before this constructor is entered and
  45          * thus might result in loss of the actual (chain
  46          * of) exception(s) describing the error.
  47          */
  48         Exception(const char* const message) throw();
  49
  50         /**
  51          * Creates a chained exception.
  52          *
  53          * Both the error message and the previous
  54          * exception are cloned.
  55          *
  56          * Since exceptions should be created on the stack
  57          * (see std::bad_alloc), the previous one will be
  58          * internally copied to the heap by calling
  59          * clone().
  60          *
  61          * If clone() throws std::bad_alloc, a notice is
  62          * appended to the internal message buffer of this
  63          * exception (as long as space left) and
  64          * std::bad_alloc is swallowed.
  65          *
  66          * @see Exception(message)
  67          */
  68         Exception(
  69                 const char* const message,
  70                 const Exception& previous) throw();
  71
  72         /// No-op.
  73         virtual ~Exception() throw();
  74
  75         /**
  76          * Writes our message to passed stream.
  77          *
  78          * @exception std::ios_base::failure
  79          *            may be thrown by stream, if it is
  80          *            configured to do so.
  81          */
  82         void write(std::ostream& out) const throw(std::ios_base::failure);
  83
  84         /**
  85          * Writes a backtrace to passed stream.
  86          *
  87          * Messages are delimited by one newline and are
  88          * printed in reverse chronological order.
  89          *
  90          * @exception std::ios_base::failure
  91          *            may be thrown by stream, if it is
  92          *            configured to do so.
  93          */
  94         void backtrace(std::ostream& out) const throw(std::ios_base::failure);
  95
  96         /**
  97          * Creates a shallow copy of this exception.
  98          *
  99          * Copy is allocated on the heap.
 100          *
 101          * @throws std::bad_alloc on memory shortage.
 102          */
 103         virtual const Exception* clone() const throw(std::bad_alloc);
 104
 105         /// Returns a pointer to the internal character string.
 106         virtual const char* what() const throw();
 107
 108 private:
 109         /**
 110          * Copy of message passed to constructor.
 111          *
 112          * Length is @ref Exception::LENGTH plus nullbyte.
 113          */
 114         char _message[LENGTH + 1];
 115
 116         /// Pointer to copy of previous exception, or null.
 117         const Exception* _previous;
 118
 119         /// Used by constructors to initialize _message.
 120         void _initMessage(const char* const message);
 121 };
 122
 123 #endif