include/llvm/Support/PrettyStackTrace.h

   1 //===- llvm/Support/PrettyStackTrace.h - Pretty Crash Handling --*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 // This file defines the PrettyStackTraceEntry class, which is used to make
  10 // crashes give more contextual information about what the program was doing
  11 // when it crashed.
  12 //
  13 //===----------------------------------------------------------------------===//
  14
  15 #ifndef LLVM_SUPPORT_PRETTYSTACKTRACE_H
  16 #define LLVM_SUPPORT_PRETTYSTACKTRACE_H
  17
  18 #include "llvm/ADT/SmallVector.h"
  19 #include "llvm/Support/Compiler.h"
  20
  21 namespace llvm {
  22   class raw_ostream;
  23
  24   /// Enables dumping a "pretty" stack trace when the program crashes.
  25   ///
  26   /// \see PrettyStackTraceEntry
  27   void EnablePrettyStackTrace();
  28
  29   /// Enables (or disables) dumping a "pretty" stack trace when the user sends
  30   /// SIGINFO or SIGUSR1 to the current process.
  31   ///
  32   /// This is a per-thread decision so that a program can choose to print stack
  33   /// traces only on a primary thread, or on all threads that use
  34   /// PrettyStackTraceEntry.
  35   ///
  36   /// \see EnablePrettyStackTrace
  37   /// \see PrettyStackTraceEntry
  38   void EnablePrettyStackTraceOnSigInfoForThisThread(bool ShouldEnable = true);
  39
  40   /// PrettyStackTraceEntry - This class is used to represent a frame of the
  41   /// "pretty" stack trace that is dumped when a program crashes. You can define
  42   /// subclasses of this and declare them on the program stack: when they are
  43   /// constructed and destructed, they will add their symbolic frames to a
  44   /// virtual stack trace.  This gets dumped out if the program crashes.
  45   class PrettyStackTraceEntry {
  46     friend PrettyStackTraceEntry *ReverseStackTrace(PrettyStackTraceEntry *);
  47
  48     PrettyStackTraceEntry *NextEntry;
  49     PrettyStackTraceEntry(const PrettyStackTraceEntry &) = delete;
  50     void operator=(const PrettyStackTraceEntry &) = delete;
  51   public:
  52     PrettyStackTraceEntry();
  53     virtual ~PrettyStackTraceEntry();
  54
  55     /// print - Emit information about this stack frame to OS.
  56     virtual void print(raw_ostream &OS) const = 0;
  57
  58     /// getNextEntry - Return the next entry in the list of frames.
  59     const PrettyStackTraceEntry *getNextEntry() const { return NextEntry; }
  60   };
  61
  62   /// PrettyStackTraceString - This object prints a specified string (which
  63   /// should not contain newlines) to the stream as the stack trace when a crash
  64   /// occurs.
  65   class PrettyStackTraceString : public PrettyStackTraceEntry {
  66     const char *Str;
  67   public:
  68     PrettyStackTraceString(const char *str) : Str(str) {}
  69     void print(raw_ostream &OS) const override;
  70   };
  71
  72   /// PrettyStackTraceFormat - This object prints a string (which may use
  73   /// printf-style formatting but should not contain newlines) to the stream
  74   /// as the stack trace when a crash occurs.
  75   class PrettyStackTraceFormat : public PrettyStackTraceEntry {
  76     llvm::SmallVector<char, 32> Str;
  77   public:
  78     PrettyStackTraceFormat(const char *Format, ...);
  79     void print(raw_ostream &OS) const override;
  80   };
  81
  82   /// PrettyStackTraceProgram - This object prints a specified program arguments
  83   /// to the stream as the stack trace when a crash occurs.
  84   class PrettyStackTraceProgram : public PrettyStackTraceEntry {
  85     int ArgC;
  86     const char *const *ArgV;
  87   public:
  88     PrettyStackTraceProgram(int argc, const char * const*argv)
  89       : ArgC(argc), ArgV(argv) {
  90       EnablePrettyStackTrace();
  91     }
  92     void print(raw_ostream &OS) const override;
  93   };
  94
  95   /// Returns the topmost element of the "pretty" stack state.
  96   const void *SavePrettyStackState();
  97
  98   /// Restores the topmost element of the "pretty" stack state to State, which
  99   /// should come from a previous call to SavePrettyStackState().  This is
 100   /// useful when using a CrashRecoveryContext in code that also uses
 101   /// PrettyStackTraceEntries, to make sure the stack that's printed if a crash
 102   /// happens after a crash that's been recovered by CrashRecoveryContext
 103   /// doesn't have frames on it that were added in code unwound by the
 104   /// CrashRecoveryContext.
 105   void RestorePrettyStackState(const void *State);
 106
 107 } // end namespace llvm
 108
 109 #endif