source/Exception.hxx

   1 /**
   2  * @file
   3  *
   4  * Declaration of @ref libsex::Exception.
   5  */
   6
   7 /**
   8  * @mainpage Example
   9  *
  10  * The unit tests serve as compilable and runnable
  11  * documentation (not included in this API documentation).
  12  *
  13  * @n@n
  14  *
  15  * At first, let's declare a very primitive exception in
  16  * @c tests/framework/ExampleException1.hxx
  17  * @include framework/ExampleException1.hxx
  18  *
  19  * We then define it and assign an error message in
  20  * @c tests/framework/ExampleException1.cxx
  21  * @include framework/ExampleException1.cxx
  22  *
  23  * We repeat that procedure to create a more sophisticated
  24  * class:
  25  *
  26  * @c tests/framework/ExampleException2.hxx
  27  * @include framework/ExampleException2.hxx
  28  *
  29  * @c tests/framework/ExampleException2.cxx
  30  * @include framework/ExampleException2.cxx
  31  *
  32  * Finally, here's how to use those classes and the
  33  * framework:
  34  *
  35  * @c tests/UsageExamples.cxx
  36  * @include UsageExamples.cxx
  37  */
  38
  39 #ifndef LIBSEX_EXCEPTION_HXX
  40 #define LIBSEX_EXCEPTION_HXX
  41
  42 #include <exception> // std::exception
  43 #include <stdexcept> // std::bad_alloc
  44 #include <ostream>   // std::ostream
  45
  46 namespace libsex
  47 {
  48         class Exception;
  49 }
  50
  51 /**
  52  * @class libsex::Exception
  53  *
  54  * Generic error made up of a message and
  55  * (optional) references to previous one.
  56  *
  57  * Double-fault save (not throwing std::bad_alloc
  58  * or other exceptions in critical situations) and
  59  * allows exception chaining.
  60  *
  61  * For object-oriented error handling you should
  62  * subclass this class for every type of error.
  63  * There are elegant macros in @file declare.hxx
  64  * and @file define.hxx.
  65  */
  66 class libsex::Exception : public std::exception
  67 {
  68 public:
  69         /// Max payload of the internal character string.
  70         static const unsigned short LENGTH = 500;
  71
  72         /**
  73          * Creates an exception.
  74          *
  75          * Supplied character array should be null-
  76          * terminated and should not exceed LENGTH
  77          * characters (excl. null byte). Its contents will
  78          * be copied into an internal buffer and can be
  79          * overwritten/freed afterwards.
  80          *
  81          * The constructors do not accept std::string
  82          * since that class uses the heap and may throw
  83          * std::bad_alloc -- which might obviously happen
  84          * even before this constructor is entered and
  85          * thus might result in loss of the actual (chain
  86          * of) exception(s) describing the error.
  87          */
  88         Exception(const char* const message) throw();
  89
  90         /**
  91          * Creates a chained exception.
  92          *
  93          * Both the error message and the previous
  94          * exception are cloned.
  95          *
  96          * Since exceptions should be created on the stack
  97          * (see std::bad_alloc), the previous one will be
  98          * internally copied to the heap by calling
  99          * clone().
 100          *
 101          * If clone() throws std::bad_alloc, a notice is
 102          * appended to the internal message buffer of this
 103          * exception (as long as space left) and
 104          * std::bad_alloc is swallowed.
 105          *
 106          * @see Exception(message)
 107          */
 108         Exception(
 109                 const char* const message,
 110                 const Exception& previous) throw();
 111
 112         /// No-op.
 113         virtual ~Exception() throw();
 114
 115         /**
 116          * Writes our message to passed stream.
 117          *
 118          * @exception std::ios_base::failure
 119          *            may be thrown by stream, if it is
 120          *            configured to do so.
 121          */
 122         void write(std::ostream& out) const throw(std::ios_base::failure);
 123
 124         /**
 125          * Writes a backtrace to passed stream.
 126          *
 127          * Messages are delimited by one newline and are
 128          * printed in reverse chronological order.
 129          *
 130          * @exception std::ios_base::failure
 131          *            may be thrown by stream, if it is
 132          *            configured to do so.
 133          */
 134         void backtrace(std::ostream& out) const throw(std::ios_base::failure);
 135
 136         /**
 137          * Creates a shallow copy of this exception.
 138          *
 139          * Copy is allocated on the heap.
 140          *
 141          * @throws std::bad_alloc on memory shortage.
 142          */
 143         virtual const Exception* clone() const throw(std::bad_alloc);
 144
 145         /// Returns a pointer to the internal character string.
 146         virtual const char* what() const throw();
 147
 148 private:
 149         /**
 150          * Copy of message passed to constructor.
 151          *
 152          * Length is @ref Exception::LENGTH plus nullbyte.
 153          */
 154         char _message[LENGTH + 1];
 155
 156         /// Pointer to copy of previous exception, or null.
 157         const Exception* _previous;
 158
 159         /// Used by constructors to initialize _message.
 160         void _initMessage(const char* const message);
 161 };
 162
 163 #endif