src/base/TextException.h

   1 /*
   2  * Copyright (C) 1996-2023 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef SQUID__TEXTEXCEPTION_H
  10 #define SQUID__TEXTEXCEPTION_H
  11
  12 #include "base/Assure.h"
  13 #include "base/Here.h"
  14
  15 #include <stdexcept>
  16
  17 class SBuf;
  18
  19 /// an std::runtime_error with thrower location info
  20 class TextException: public std::runtime_error
  21 {
  22
  23 public:
  24     TextException(const char *message, const SourceLocation &location):
  25         std::runtime_error(message),
  26         where(location)
  27     {}
  28
  29     TextException(SBuf message, const SourceLocation &location);
  30
  31     TextException(const TextException &) = default;
  32     TextException(TextException &&) = default;
  33     TextException& operator=(const TextException &) = default;
  34
  35     /* std::runtime_error API */
  36     ~TextException() throw() override;
  37     const char *what() const throw() override;
  38
  39     /// same-location exceptions have the same ID
  40     SourceLocationId id() const { return where.id(); }
  41
  42     /// dumps the exception text into the stream
  43     std::ostream &print(std::ostream &) const;
  44
  45     /// code location related to the exception; usually the thrower location
  46     SourceLocation where;
  47
  48     // TODO: Add support for arbitrary (re)thrower-supplied details:
  49     // std::tuple<Details...> details;
  50 };
  51
  52 /// prints active (i.e., thrown but not yet handled) exception
  53 std::ostream &CurrentException(std::ostream &);
  54
  55 /// efficiently prints TextException
  56 std::ostream &operator <<(std::ostream &, const TextException &);
  57
  58 /// legacy convenience macro; it is not difficult to type Here() now
  59 #define TexcHere(msg) TextException((msg), Here())
  60
  61 /// Like Must() but supports custom exception message and location.
  62 /// \param description string literal describing the condition; what MUST happen
  63 /// Deprecated: Use Assure2() for code logic checks and throw explicitly when
  64 /// input validation fails.
  65 #define Must3(condition, description, location) \
  66     Assure_(3, (condition), ("check failed: " description), (location))
  67
  68 /// Like Assure() but only logs the exception if level-3 debugging is enabled
  69 /// and runs even when NDEBUG macro is defined. Deprecated: Use Assure() for
  70 /// code logic checks and throw explicitly when input validation fails.
  71 #define Must(condition) Must3((condition), #condition, Here())
  72
  73 /// Reports and swallows all exceptions to prevent compiler warnings and runtime
  74 /// errors related to throwing class destructors. Should be used for most dtors.
  75 #define SWALLOW_EXCEPTIONS(code) \
  76     try { \
  77         code \
  78     } catch (...) { \
  79         debugs(0, DBG_IMPORTANT, "ERROR: Squid BUG: ignoring exception;" << \
  80                Debug::Extra << "bug location: " << Here() << \
  81                Debug::Extra << "ignored exception: " << CurrentException); \
  82     }
  83
  84 #endif /* SQUID__TEXTEXCEPTION_H */
  85