src/base/TextException.h

   1 /*
   2  * Copyright (C) 1996-2025 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_SRC_BASE_TEXTEXCEPTION_H
  10 #define SQUID_SRC_BASE_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 /// If there is an active (i.e., thrown but not yet handled) exception, reports
  56 /// it on a dedicated DebugExtra line. Otherwise, does nothing.
  57 std::ostream &CurrentExceptionExtra(std::ostream &);
  58
  59 /// efficiently prints TextException
  60 std::ostream &operator <<(std::ostream &, const TextException &);
  61
  62 /// legacy convenience macro; it is not difficult to type Here() now
  63 #define TexcHere(msg) TextException((msg), Here())
  64
  65 /// Like Must() but supports custom exception message and location.
  66 /// \param description string literal describing the condition; what MUST happen
  67 /// Deprecated: Use Assure2() for code logic checks and throw explicitly when
  68 /// input validation fails.
  69 #define Must3(condition, description, location) \
  70     Assure_(3, (condition), ("check failed: " description), (location))
  71
  72 /// Like Assure() but only logs the exception if level-3 debugging is enabled
  73 /// and runs even when NDEBUG macro is defined. Deprecated: Use Assure() for
  74 /// code logic checks and throw explicitly when input validation fails.
  75 #define Must(condition) Must3((condition), #condition, Here())
  76
  77 /// Reports and swallows all exceptions to prevent compiler warnings and runtime
  78 /// errors related to throwing class destructors. Should be used for most dtors.
  79 #define SWALLOW_EXCEPTIONS(code) \
  80     try { \
  81         code \
  82     } catch (...) { \
  83         debugs(0, DBG_IMPORTANT, "ERROR: Squid BUG: ignoring exception;" << \
  84                Debug::Extra << "bug location: " << Here() << \
  85                Debug::Extra << "ignored exception: " << CurrentException); \
  86     }
  87
  88 #endif /* SQUID_SRC_BASE_TEXTEXCEPTION_H */
  89