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. 46 class CrashRecoveryContext { 47 void *Impl; 48 CrashRecoveryContextCleanup *head; 49 50 public: CrashRecoveryContext()51 CrashRecoveryContext() : Impl(nullptr), head(nullptr) {} 52 ~CrashRecoveryContext(); 53 54 /// Register cleanup handler, which is used when the recovery context is 55 /// finished. 56 /// The recovery context owns the handler. 57 void registerCleanup(CrashRecoveryContextCleanup *cleanup); 58 59 void unregisterCleanup(CrashRecoveryContextCleanup *cleanup); 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. 69 static CrashRecoveryContext *GetCurrent(); 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); RunSafely(void (* Fn)(void *),void * UserData)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. 102 void HandleCrash(); 103 }; 104 105 /// Abstract base class of cleanup handlers. 106 /// 107 /// Derived classes override method recoverResources, which makes actual work on 108 /// resource recovery. 109 /// 110 /// Cleanup handlers are stored in a double list, which is owned and managed by 111 /// a crash recovery context. 112 class CrashRecoveryContextCleanup { 113 protected: 114 CrashRecoveryContext *context; CrashRecoveryContextCleanup(CrashRecoveryContext * context)115 CrashRecoveryContextCleanup(CrashRecoveryContext *context) 116 : context(context), cleanupFired(false) {} 117 118 public: 119 bool cleanupFired; 120 121 virtual ~CrashRecoveryContextCleanup(); 122 virtual void recoverResources() = 0; 123 getContext()124 CrashRecoveryContext *getContext() const { 125 return context; 126 } 127 128 private: 129 friend class CrashRecoveryContext; 130 CrashRecoveryContextCleanup *prev, *next; 131 }; 132 133 /// Base class of cleanup handler that controls recovery of resources of the 134 /// given type. 135 /// 136 /// \tparam Derived Class that uses this class as a base. 137 /// \tparam T Type of controlled resource. 138 /// 139 /// This class serves as a base for its template parameter as implied by 140 /// Curiously Recurring Template Pattern. 141 /// 142 /// This class factors out creation of a cleanup handler. The latter requires 143 /// knowledge of the current recovery context, which is provided by this class. 144 template<typename Derived, typename T> 145 class CrashRecoveryContextCleanupBase : public CrashRecoveryContextCleanup { 146 protected: 147 T *resource; CrashRecoveryContextCleanupBase(CrashRecoveryContext * context,T * resource)148 CrashRecoveryContextCleanupBase(CrashRecoveryContext *context, T *resource) 149 : CrashRecoveryContextCleanup(context), resource(resource) {} 150 151 public: 152 /// Creates cleanup handler. 153 /// \param x Pointer to the resource recovered by this handler. 154 /// \return New handler or null if the method was called outside a recovery 155 /// context. create(T * x)156 static Derived *create(T *x) { 157 if (x) { 158 if (CrashRecoveryContext *context = CrashRecoveryContext::GetCurrent()) 159 return new Derived(context, x); 160 } 161 return nullptr; 162 } 163 }; 164 165 /// Cleanup handler that reclaims resource by calling destructor on it. 166 template <typename T> 167 class CrashRecoveryContextDestructorCleanup : public 168 CrashRecoveryContextCleanupBase<CrashRecoveryContextDestructorCleanup<T>, T> { 169 public: CrashRecoveryContextDestructorCleanup(CrashRecoveryContext * context,T * resource)170 CrashRecoveryContextDestructorCleanup(CrashRecoveryContext *context, 171 T *resource) 172 : CrashRecoveryContextCleanupBase< 173 CrashRecoveryContextDestructorCleanup<T>, T>(context, resource) {} 174 recoverResources()175 virtual void recoverResources() { 176 this->resource->~T(); 177 } 178 }; 179 180 /// Cleanup handler that reclaims resource by calling 'delete' on it. 181 template <typename T> 182 class CrashRecoveryContextDeleteCleanup : public 183 CrashRecoveryContextCleanupBase<CrashRecoveryContextDeleteCleanup<T>, T> { 184 public: CrashRecoveryContextDeleteCleanup(CrashRecoveryContext * context,T * resource)185 CrashRecoveryContextDeleteCleanup(CrashRecoveryContext *context, T *resource) 186 : CrashRecoveryContextCleanupBase< 187 CrashRecoveryContextDeleteCleanup<T>, T>(context, resource) {} 188 recoverResources()189 void recoverResources() override { delete this->resource; } 190 }; 191 192 /// Cleanup handler that reclaims resource by calling its method 'Release'. 193 template <typename T> 194 class CrashRecoveryContextReleaseRefCleanup : public 195 CrashRecoveryContextCleanupBase<CrashRecoveryContextReleaseRefCleanup<T>, T> { 196 public: CrashRecoveryContextReleaseRefCleanup(CrashRecoveryContext * context,T * resource)197 CrashRecoveryContextReleaseRefCleanup(CrashRecoveryContext *context, 198 T *resource) 199 : CrashRecoveryContextCleanupBase<CrashRecoveryContextReleaseRefCleanup<T>, 200 T>(context, resource) {} 201 recoverResources()202 void recoverResources() override { this->resource->Release(); } 203 }; 204 205 /// Helper class for managing resource cleanups. 206 /// 207 /// \tparam T Type of resource been reclaimed. 208 /// \tparam Cleanup Class that defines how the resource is reclaimed. 209 /// 210 /// Clients create objects of this type in the code executed in a crash recovery 211 /// context to ensure that the resource will be reclaimed even in the case of 212 /// crash. For example: 213 /// 214 /// \code 215 /// void actual_work(void *) { 216 /// ... 217 /// std::unique_ptr<Resource> R(new Resource()); 218 /// CrashRecoveryContextCleanupRegistrar D(R.get()); 219 /// ... 220 /// } 221 /// 222 /// void foo() { 223 /// CrashRecoveryContext CRC; 224 /// 225 /// if (!CRC.RunSafely(actual_work, 0)) { 226 /// ... a crash was detected, report error to user ... 227 /// } 228 /// \endcode 229 /// 230 /// If the code of `actual_work` in the example above does not crash, the 231 /// destructor of CrashRecoveryContextCleanupRegistrar removes cleanup code from 232 /// the current CrashRecoveryContext and the resource is reclaimed by the 233 /// destructor of std::unique_ptr. If crash happens, destructors are not called 234 /// and the resource is reclaimed by cleanup object registered in the recovery 235 /// context by the constructor of CrashRecoveryContextCleanupRegistrar. 236 template <typename T, typename Cleanup = CrashRecoveryContextDeleteCleanup<T> > 237 class CrashRecoveryContextCleanupRegistrar { 238 CrashRecoveryContextCleanup *cleanup; 239 240 public: CrashRecoveryContextCleanupRegistrar(T * x)241 CrashRecoveryContextCleanupRegistrar(T *x) 242 : cleanup(Cleanup::create(x)) { 243 if (cleanup) 244 cleanup->getContext()->registerCleanup(cleanup); 245 } 246 ~CrashRecoveryContextCleanupRegistrar()247 ~CrashRecoveryContextCleanupRegistrar() { unregister(); } 248 unregister()249 void unregister() { 250 if (cleanup && !cleanup->cleanupFired) 251 cleanup->getContext()->unregisterCleanup(cleanup); 252 cleanup = nullptr; 253 } 254 }; 255 } // end namespace llvm 256 257 #endif // LLVM_SUPPORT_CRASHRECOVERYCONTEXT_H 258