gdbsupport/common-exceptions.h

   1 /* Exception (throw catch) mechanism, for GDB, the GNU debugger.
   2
   3    Copyright (C) 1986-2023 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20 #ifndef COMMON_COMMON_EXCEPTIONS_H
  21 #define COMMON_COMMON_EXCEPTIONS_H
  22
  23 #include <setjmp.h>
  24 #include <new>
  25 #include <memory>
  26 #include <string>
  27 #include <functional>
  28
  29 /* Reasons for calling throw_exceptions().  NOTE: all reason values
  30    must be different from zero.  enum value 0 is reserved for internal
  31    use as the return value from an initial setjmp().  */
  32
  33 enum return_reason
  34   {
  35     /* User interrupt.  */
  36     RETURN_QUIT = -2,
  37     /* Any other error.  */
  38     RETURN_ERROR
  39   };
  40
  41 #define RETURN_MASK(reason)     (1 << (int)(-reason))
  42
  43 typedef enum
  44 {
  45   RETURN_MASK_QUIT = RETURN_MASK (RETURN_QUIT),
  46   RETURN_MASK_ERROR = RETURN_MASK (RETURN_ERROR),
  47   RETURN_MASK_ALL = (RETURN_MASK_QUIT | RETURN_MASK_ERROR)
  48 } return_mask;
  49
  50 /* Describe all exceptions.  */
  51
  52 enum errors {
  53   GDB_NO_ERROR,
  54
  55   /* Any generic error, the corresponding text is in
  56      exception.message.  */
  57   GENERIC_ERROR,
  58
  59   /* Something requested was not found.  */
  60   NOT_FOUND_ERROR,
  61
  62   /* Thread library lacks support necessary for finding thread local
  63      storage.  */
  64   TLS_NO_LIBRARY_SUPPORT_ERROR,
  65
  66   /* Load module not found while attempting to find thread local storage.  */
  67   TLS_LOAD_MODULE_NOT_FOUND_ERROR,
  68
  69   /* Thread local storage has not been allocated yet.  */
  70   TLS_NOT_ALLOCATED_YET_ERROR,
  71
  72   /* Something else went wrong while attempting to find thread local
  73      storage.  The ``struct gdb_exception'' message field provides
  74      more detail.  */
  75   TLS_GENERIC_ERROR,
  76
  77   /* Problem parsing an XML document.  */
  78   XML_PARSE_ERROR,
  79
  80   /* Error accessing memory.  */
  81   MEMORY_ERROR,
  82
  83   /* Value not available.  E.g., a register was not collected in a
  84      traceframe.  */
  85   NOT_AVAILABLE_ERROR,
  86
  87   /* Value was optimized out.  Note: if the value was a register, this
  88      means the register was not saved in the frame.  */
  89   OPTIMIZED_OUT_ERROR,
  90
  91   /* DW_OP_entry_value resolving failed.  */
  92   NO_ENTRY_VALUE_ERROR,
  93
  94   /* Target throwing an error has been closed.  Current command should be
  95      aborted as the inferior state is no longer valid.  */
  96   TARGET_CLOSE_ERROR,
  97
  98   /* An undefined command was executed.  */
  99   UNDEFINED_COMMAND_ERROR,
 100
 101   /* Requested feature, method, mechanism, etc. is not supported.  */
 102   NOT_SUPPORTED_ERROR,
 103
 104   /* The number of candidates generated during line completion has
 105      reached the user's specified limit.  This isn't an error, this exception
 106      is used to halt searching for more completions, but for consistency
 107      "_ERROR" is appended to the name.  */
 108   MAX_COMPLETIONS_REACHED_ERROR,
 109
 110   /* Add more errors here.  */
 111   NR_ERRORS
 112 };
 113
 114 struct gdb_exception
 115 {
 116   gdb_exception ()
 117     : reason ((enum return_reason) 0),
 118       error (GDB_NO_ERROR)
 119   {
 120   }
 121
 122   gdb_exception (enum return_reason r, enum errors e)
 123     : reason (r),
 124       error (e)
 125   {
 126   }
 127
 128   gdb_exception (enum return_reason r, enum errors e,
 129                  const char *fmt, va_list ap)
 130     ATTRIBUTE_PRINTF (4, 0)
 131     : reason (r),
 132       error (e),
 133       message (std::make_shared<std::string> (string_vprintf (fmt, ap)))
 134   {
 135   }
 136
 137   /* The move constructor exists so that we can mark it "noexcept",
 138      which is a good practice for any sort of exception object.  */
 139   explicit gdb_exception (gdb_exception &&other) noexcept = default;
 140
 141   /* The copy constructor exists so that we can mark it "noexcept",
 142      which is a good practice for any sort of exception object.  */
 143   gdb_exception (const gdb_exception &other) noexcept
 144     : reason (other.reason),
 145       error (other.error),
 146       message (other.message)
 147   {
 148   }
 149
 150   /* The assignment operator exists so that we can mark it "noexcept",
 151      which is a good practice for any sort of exception object.  */
 152   gdb_exception &operator= (const gdb_exception &other) noexcept
 153   {
 154     reason = other.reason;
 155     error = other.error;
 156     message = other.message;
 157     return *this;
 158   }
 159
 160   gdb_exception &operator= (gdb_exception &&other) noexcept = default;
 161
 162   /* Return the contents of the exception message, as a C string.  The
 163      string remains owned by the exception object.  */
 164   const char *what () const noexcept
 165   {
 166     return message->c_str ();
 167   }
 168
 169   /* Compare two exceptions.  */
 170   bool operator== (const gdb_exception &other) const
 171   {
 172     const char *msg1 = message == nullptr ? "" : what ();
 173     const char *msg2 = other.message == nullptr ? "" : other.what ();
 174
 175     return (reason == other.reason
 176             && error == other.error
 177             && strcmp (msg1, msg2) == 0);
 178   }
 179
 180   /* Compare two exceptions.  */
 181   bool operator!= (const gdb_exception &other) const
 182   {
 183     return !(*this == other);
 184   }
 185
 186   enum return_reason reason;
 187   enum errors error;
 188   std::shared_ptr<std::string> message;
 189 };
 190
 191 namespace std
 192 {
 193
 194 /* Specialization of std::hash for gdb_exception.  */
 195 template<>
 196 struct hash<gdb_exception>
 197 {
 198   size_t operator() (const gdb_exception &exc) const
 199   {
 200     size_t result = exc.reason + exc.error;
 201     if (exc.message != nullptr)
 202       result += std::hash<std::string> {} (*exc.message);
 203     return result;
 204   }
 205 };
 206
 207 }
 208
 209 /* Functions to drive the sjlj-based exceptions state machine.  Though
 210    declared here by necessity, these functions should be considered
 211    internal to the exceptions subsystem and not used other than via
 212    the TRY/CATCH (or TRY_SJLJ/CATCH_SJLJ) macros defined below.  */
 213
 214 extern jmp_buf *exceptions_state_mc_init (void);
 215 extern int exceptions_state_mc_action_iter (void);
 216 extern int exceptions_state_mc_action_iter_1 (void);
 217 extern int exceptions_state_mc_catch (struct gdb_exception *, int);
 218
 219 /* Macro to wrap up standard try/catch behavior.
 220
 221    The double loop lets us correctly handle code "break"ing out of the
 222    try catch block.  (It works as the "break" only exits the inner
 223    "while" loop, the outer for loop detects this handling it
 224    correctly.)  Of course "return" and "goto" are not so lucky.
 225
 226    For instance:
 227
 228    *INDENT-OFF*
 229
 230    TRY_SJLJ
 231      {
 232      }
 233    CATCH_SJLJ (e, RETURN_MASK_ERROR)
 234      {
 235        switch (e.reason)
 236          {
 237            case RETURN_ERROR: ...
 238          }
 239      }
 240    END_CATCH_SJLJ
 241
 242    The SJLJ variants are needed in some cases where gdb exceptions
 243    need to cross third-party library code compiled without exceptions
 244    support (e.g., readline).  */
 245
 246 #define TRY_SJLJ \
 247      { \
 248        jmp_buf *buf = \
 249          exceptions_state_mc_init (); \
 250        setjmp (*buf); \
 251      } \
 252      while (exceptions_state_mc_action_iter ()) \
 253        while (exceptions_state_mc_action_iter_1 ())
 254
 255 #define CATCH_SJLJ(EXCEPTION, MASK)                             \
 256   {                                                     \
 257     struct gdb_exception EXCEPTION;                             \
 258     if (exceptions_state_mc_catch (&(EXCEPTION), MASK))
 259
 260 #define END_CATCH_SJLJ                          \
 261   }
 262
 263 /* The exception types client code may catch.  They're just shims
 264    around gdb_exception that add nothing but type info.  Which is used
 265    is selected depending on the MASK argument passed to CATCH.  */
 266
 267 struct gdb_exception_error : public gdb_exception
 268 {
 269   gdb_exception_error (enum errors e, const char *fmt, va_list ap)
 270     ATTRIBUTE_PRINTF (3, 0)
 271     : gdb_exception (RETURN_ERROR, e, fmt, ap)
 272   {
 273   }
 274
 275   explicit gdb_exception_error (gdb_exception &&ex) noexcept
 276     : gdb_exception (std::move (ex))
 277   {
 278     gdb_assert (ex.reason == RETURN_ERROR);
 279   }
 280 };
 281
 282 struct gdb_exception_quit : public gdb_exception
 283 {
 284   gdb_exception_quit (const char *fmt, va_list ap)
 285     ATTRIBUTE_PRINTF (2, 0)
 286     : gdb_exception (RETURN_QUIT, GDB_NO_ERROR, fmt, ap)
 287   {
 288   }
 289
 290   explicit gdb_exception_quit (gdb_exception &&ex) noexcept
 291     : gdb_exception (std::move (ex))
 292   {
 293     gdb_assert (ex.reason == RETURN_QUIT);
 294   }
 295 };
 296
 297 /* An exception type that inherits from both std::bad_alloc and a gdb
 298    exception.  This is necessary because operator new can only throw
 299    std::bad_alloc, and OTOH, we want exceptions thrown due to memory
 300    allocation error to be caught by all the CATCH/RETURN_MASK_ALL
 301    spread around the codebase.  */
 302
 303 struct gdb_quit_bad_alloc
 304   : public gdb_exception_quit,
 305     public std::bad_alloc
 306 {
 307   explicit gdb_quit_bad_alloc (gdb_exception &&ex) noexcept
 308     : gdb_exception_quit (std::move (ex)),
 309       std::bad_alloc ()
 310   {
 311   }
 312 };
 313
 314 /* *INDENT-ON* */
 315
 316 /* Throw an exception (as described by "struct gdb_exception"),
 317    landing in the inner most containing exception handler established
 318    using TRY/CATCH.  */
 319 extern void throw_exception (gdb_exception &&exception)
 320      ATTRIBUTE_NORETURN;
 321
 322 /* Throw an exception by executing a LONG JUMP to the inner most
 323    containing exception handler established using TRY_SJLJ.  Necessary
 324    in some cases where we need to throw GDB exceptions across
 325    third-party library code (e.g., readline).  */
 326 extern void throw_exception_sjlj (const struct gdb_exception &exception)
 327      ATTRIBUTE_NORETURN;
 328
 329 /* Convenience wrappers around throw_exception that throw GDB
 330    errors.  */
 331 extern void throw_verror (enum errors, const char *fmt, va_list ap)
 332      ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 0);
 333 extern void throw_vquit (const char *fmt, va_list ap)
 334      ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 0);
 335 extern void throw_error (enum errors error, const char *fmt, ...)
 336      ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 3);
 337 extern void throw_quit (const char *fmt, ...)
 338      ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 2);
 339
 340 #endif /* COMMON_COMMON_EXCEPTIONS_H */