LLVM  11.0.0git
CrashRecoveryContext.h
Go to the documentation of this file.
1 //===--- CrashRecoveryContext.h - Crash Recovery ----------------*- 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 #ifndef LLVM_SUPPORT_CRASHRECOVERYCONTEXT_H
10 #define LLVM_SUPPORT_CRASHRECOVERYCONTEXT_H
11 
12 #include "llvm/ADT/STLExtras.h"
13 
14 namespace llvm {
15 class CrashRecoveryContextCleanup;
16 
17 /// Crash recovery helper object.
18 ///
19 /// This class implements support for running operations in a safe context so
20 /// that crashes (memory errors, stack overflow, assertion violations) can be
21 /// detected and control restored to the crashing thread. Crash detection is
22 /// purely "best effort", the exact set of failures which can be recovered from
23 /// is platform dependent.
24 ///
25 /// Clients make use of this code by first calling
26 /// CrashRecoveryContext::Enable(), and then executing unsafe operations via a
27 /// CrashRecoveryContext object. For example:
28 ///
29 /// \code
30 /// void actual_work(void *);
31 ///
32 /// void foo() {
33 /// CrashRecoveryContext CRC;
34 ///
35 /// if (!CRC.RunSafely(actual_work, 0)) {
36 /// ... a crash was detected, report error to user ...
37 /// }
38 ///
39 /// ... no crash was detected ...
40 /// }
41 /// \endcode
42 ///
43 /// To assist recovery the class allows specifying set of actions that will be
44 /// executed in any case, whether crash occurs or not. These actions may be used
45 /// to reclaim resources in the case of crash.
47  void *Impl;
49 
50 public:
51  CrashRecoveryContext() : Impl(nullptr), head(nullptr) {}
53 
54  /// Register cleanup handler, which is used when the recovery context is
55  /// finished.
56  /// The recovery context owns the handler.
58 
60 
61  /// Enable crash recovery.
62  static void Enable();
63 
64  /// Disable crash recovery.
65  static void Disable();
66 
67  /// Return the active context, if the code is currently executing in a
68  /// thread which is in a protected context.
70 
71  /// Return true if the current thread is recovering from a crash.
72  static bool isRecoveringFromCrash();
73 
74  /// Execute the provided callback function (with the given arguments) in
75  /// a protected context.
76  ///
77  /// \return True if the function completed successfully, and false if the
78  /// function crashed (or HandleCrash was called explicitly). Clients should
79  /// make as little assumptions as possible about the program state when
80  /// RunSafely has returned false.
81  bool RunSafely(function_ref<void()> Fn);
82  bool RunSafely(void (*Fn)(void*), void *UserData) {
83  return RunSafely([&]() { Fn(UserData); });
84  }
85 
86  /// Execute the provide callback function (with the given arguments) in
87  /// a protected context which is run in another thread (optionally with a
88  /// requested stack size).
89  ///
90  /// See RunSafely() and llvm_execute_on_thread().
91  ///
92  /// On Darwin, if PRIO_DARWIN_BG is set on the calling thread, it will be
93  /// propagated to the new thread as well.
94  bool RunSafelyOnThread(function_ref<void()>, unsigned RequestedStackSize = 0);
95  bool RunSafelyOnThread(void (*Fn)(void*), void *UserData,
96  unsigned RequestedStackSize = 0) {
97  return RunSafelyOnThread([&]() { Fn(UserData); }, RequestedStackSize);
98  }
99 
100  /// Explicitly trigger a crash recovery in the current process, and
101  /// return failure from RunSafely(). This function does not return.
103  void HandleExit(int RetCode);
104 
105  /// In case of a crash, this is the crash identifier.
106  int RetCode = 0;
107 
108  /// Selects whether handling of failures should be done in the same way as
109  /// for regular crashes. When this is active, a crash would print the
110  /// callstack, clean-up any temporary files and create a coredump/minidump.
112 };
113 
114 /// Abstract base class of cleanup handlers.
115 ///
116 /// Derived classes override method recoverResources, which makes actual work on
117 /// resource recovery.
118 ///
119 /// Cleanup handlers are stored in a double list, which is owned and managed by
120 /// a crash recovery context.
122 protected:
123  CrashRecoveryContext *context = nullptr;
125  : context(context) {}
126 
127 public:
128  bool cleanupFired = false;
129 
130  virtual ~CrashRecoveryContextCleanup();
131  virtual void recoverResources() = 0;
132 
134  return context;
135  }
136 
137 private:
138  friend class CrashRecoveryContext;
139  CrashRecoveryContextCleanup *prev = nullptr, *next = nullptr;
140 };
141 
142 /// Base class of cleanup handler that controls recovery of resources of the
143 /// given type.
144 ///
145 /// \tparam Derived Class that uses this class as a base.
146 /// \tparam T Type of controlled resource.
147 ///
148 /// This class serves as a base for its template parameter as implied by
149 /// Curiously Recurring Template Pattern.
150 ///
151 /// This class factors out creation of a cleanup handler. The latter requires
152 /// knowledge of the current recovery context, which is provided by this class.
153 template<typename Derived, typename T>
155 protected:
158  : CrashRecoveryContextCleanup(context), resource(resource) {}
159 
160 public:
161  /// Creates cleanup handler.
162  /// \param x Pointer to the resource recovered by this handler.
163  /// \return New handler or null if the method was called outside a recovery
164  /// context.
165  static Derived *create(T *x) {
166  if (x) {
168  return new Derived(context, x);
169  }
170  return nullptr;
171  }
172 };
173 
174 /// Cleanup handler that reclaims resource by calling destructor on it.
175 template <typename T>
177  CrashRecoveryContextCleanupBase<CrashRecoveryContextDestructorCleanup<T>, T> {
178 public:
180  T *resource)
182  CrashRecoveryContextDestructorCleanup<T>, T>(context, resource) {}
183 
184  virtual void recoverResources() {
185  this->resource->~T();
186  }
187 };
188 
189 /// Cleanup handler that reclaims resource by calling 'delete' on it.
190 template <typename T>
192  CrashRecoveryContextCleanupBase<CrashRecoveryContextDeleteCleanup<T>, T> {
193 public:
196  CrashRecoveryContextDeleteCleanup<T>, T>(context, resource) {}
197 
198  void recoverResources() override { delete this->resource; }
199 };
200 
201 /// Cleanup handler that reclaims resource by calling its method 'Release'.
202 template <typename T>
204  CrashRecoveryContextCleanupBase<CrashRecoveryContextReleaseRefCleanup<T>, T> {
205 public:
207  T *resource)
209  T>(context, resource) {}
210 
211  void recoverResources() override { this->resource->Release(); }
212 };
213 
214 /// Helper class for managing resource cleanups.
215 ///
216 /// \tparam T Type of resource been reclaimed.
217 /// \tparam Cleanup Class that defines how the resource is reclaimed.
218 ///
219 /// Clients create objects of this type in the code executed in a crash recovery
220 /// context to ensure that the resource will be reclaimed even in the case of
221 /// crash. For example:
222 ///
223 /// \code
224 /// void actual_work(void *) {
225 /// ...
226 /// std::unique_ptr<Resource> R(new Resource());
227 /// CrashRecoveryContextCleanupRegistrar D(R.get());
228 /// ...
229 /// }
230 ///
231 /// void foo() {
232 /// CrashRecoveryContext CRC;
233 ///
234 /// if (!CRC.RunSafely(actual_work, 0)) {
235 /// ... a crash was detected, report error to user ...
236 /// }
237 /// \endcode
238 ///
239 /// If the code of `actual_work` in the example above does not crash, the
240 /// destructor of CrashRecoveryContextCleanupRegistrar removes cleanup code from
241 /// the current CrashRecoveryContext and the resource is reclaimed by the
242 /// destructor of std::unique_ptr. If crash happens, destructors are not called
243 /// and the resource is reclaimed by cleanup object registered in the recovery
244 /// context by the constructor of CrashRecoveryContextCleanupRegistrar.
245 template <typename T, typename Cleanup = CrashRecoveryContextDeleteCleanup<T> >
248 
249 public:
251  : cleanup(Cleanup::create(x)) {
252  if (cleanup)
253  cleanup->getContext()->registerCleanup(cleanup);
254  }
255 
257 
258  void unregister() {
259  if (cleanup && !cleanup->cleanupFired)
260  cleanup->getContext()->unregisterCleanup(cleanup);
261  cleanup = nullptr;
262  }
263 };
264 } // end namespace llvm
265 
266 #endif // LLVM_SUPPORT_CRASHRECOVERYCONTEXT_H
static Derived * create(T *x)
Creates cleanup handler.
This class represents lattice values for constants.
Definition: AllocatorList.h:23
Cleanup handler that reclaims resource by calling destructor on it.
Helper class for managing resource cleanups.
bool DumpStackAndCleanupOnFailure
Selects whether handling of failures should be done in the same way as for regular crashes...
Cleanup handler that reclaims resource by calling its method &#39;Release&#39;.
An efficient, type-erasing, non-owning reference to a callable.
Definition: STLExtras.h:176
static CrashRecoveryContext * GetCurrent()
Return the active context, if the code is currently executing in a thread which is in a protected con...
static void cleanup(BlockFrequencyInfoImplBase &BFI)
Clear all memory not needed downstream.
static void Cleanup(SetVector< Instruction *> &MaybeDead, Loop *L)
CrashRecoveryContextDeleteCleanup(CrashRecoveryContext *context, T *resource)
void unregisterCleanup(CrashRecoveryContextCleanup *cleanup)
Base class of cleanup handler that controls recovery of resources of the given type.
static void Enable()
Enable crash recovery.
Abstract base class of cleanup handlers.
CrashRecoveryContextCleanup(CrashRecoveryContext *context)
bool RunSafelyOnThread(function_ref< void()>, unsigned RequestedStackSize=0)
Execute the provide callback function (with the given arguments) in a protected context which is run ...
bool RunSafelyOnThread(void(*Fn)(void *), void *UserData, unsigned RequestedStackSize=0)
void registerCleanup(CrashRecoveryContextCleanup *cleanup)
Register cleanup handler, which is used when the recovery context is finished.
bool RunSafely(void(*Fn)(void *), void *UserData)
CrashRecoveryContextReleaseRefCleanup(CrashRecoveryContext *context, T *resource)
#define LLVM_ATTRIBUTE_NORETURN
Definition: Compiler.h:249
bool RunSafely(function_ref< void()> Fn)
Execute the provided callback function (with the given arguments) in a protected context.
Crash recovery helper object.
LLVM_ATTRIBUTE_NORETURN void HandleExit(int RetCode)
Explicitly trigger a crash recovery in the current process, and return failure from RunSafely()...
Cleanup handler that reclaims resource by calling &#39;delete&#39; on it.
CrashRecoveryContext * getContext() const
int RetCode
In case of a crash, this is the crash identifier.
CrashRecoveryContextCleanupBase(CrashRecoveryContext *context, T *resource)
static bool isRecoveringFromCrash()
Return true if the current thread is recovering from a crash.
static void Disable()
Disable crash recovery.
CrashRecoveryContextDestructorCleanup(CrashRecoveryContext *context, T *resource)