CrashRecoveryContext.h revision 212793
1113813Sphk//===--- CrashRecoveryContext.h - Crash Recovery ----------------*- C++ -*-===// 2113813Sphk// 3113813Sphk// The LLVM Compiler Infrastructure 4129963Sjoerg// 5113813Sphk// This file is distributed under the University of Illinois Open Source 6113813Sphk// License. See LICENSE.TXT for details. 7113813Sphk// 8113813Sphk//===----------------------------------------------------------------------===// 9113813Sphk 10113813Sphk#ifndef LLVM_SUPPORT_CRASHRECOVERYCONTEXT_H 11113813Sphk#define LLVM_SUPPORT_CRASHRECOVERYCONTEXT_H 12113813Sphk 13113813Sphk#include <string> 14113813Sphk 15113813Sphknamespace llvm { 16113813Sphkclass StringRef; 17113813Sphk 18113813Sphk/// \brief Crash recovery helper object. 19113813Sphk/// 20113813Sphk/// This class implements support for running operations in a safe context so 21113813Sphk/// that crashes (memory errors, stack overflow, assertion violations) can be 22113813Sphk/// detected and control restored to the crashing thread. Crash detection is 23113813Sphk/// purely "best effort", the exact set of failures which can be recovered from 24113813Sphk/// is platform dependent. 25113813Sphk/// 26113813Sphk/// Clients make use of this code by first calling 27139778Simp/// CrashRecoveryContext::Enable(), and then executing unsafe operations via a 28139778Simp/// CrashRecoveryContext object. For example: 29113813Sphk/// 30113813Sphk/// void actual_work(void *); 31113813Sphk/// 32113813Sphk/// void foo() { 33113813Sphk/// CrashRecoveryContext CRC; 34116196Sobrien/// 35116196Sobrien/// if (!CRC.RunSafely(actual_work, 0)) { 36116196Sobrien/// ... a crash was detected, report error to user ... 37113813Sphk/// } 38113813Sphk/// 39113813Sphk/// ... no crash was detected ... 40113813Sphk/// } 41113813Sphk/// 42113813Sphk/// Crash recovery contexts may not be nested. 43113813Sphkclass CrashRecoveryContext { 44129963Sjoerg void *Impl; 45129963Sjoerg 46129963Sjoergpublic: 47129963Sjoerg CrashRecoveryContext() : Impl(0) {} 48113813Sphk ~CrashRecoveryContext(); 49113813Sphk 50113813Sphk /// \brief Enable crash recovery. 51113813Sphk static void Enable(); 52113813Sphk 53113813Sphk /// \brief Disable crash recovery. 54113813Sphk static void Disable(); 55113813Sphk 56113813Sphk /// \brief Return the active context, if the code is currently executing in a 57113813Sphk /// thread which is in a protected context. 58113813Sphk static CrashRecoveryContext *GetCurrent(); 59113813Sphk 60113813Sphk /// \brief Execute the provide callback function (with the given arguments) in 61113813Sphk /// a protected context. 62129963Sjoerg /// 63113813Sphk /// \return True if the function completed successfully, and false if the 64129963Sjoerg /// function crashed (or HandleCrash was called explicitly). Clients should 65129963Sjoerg /// make as little assumptions as possible about the program state when 66129963Sjoerg /// RunSafely has returned false. Clients can use getBacktrace() to retrieve 67129963Sjoerg /// the backtrace of the crash on failures. 68113813Sphk bool RunSafely(void (*Fn)(void*), void *UserData); 69113813Sphk 70113813Sphk /// \brief Explicitly trigger a crash recovery in the current process, and 71113813Sphk /// return failure from RunSafely(). This function does not return. 72113813Sphk void HandleCrash(); 73113813Sphk 74113813Sphk /// \brief Return a string containing the backtrace where the crash was 75113813Sphk /// detected; or empty if the backtrace wasn't recovered. 76113813Sphk /// 77113813Sphk /// This function is only valid when a crash has been detected (i.e., 78129963Sjoerg /// RunSafely() has returned false. 79129963Sjoerg const std::string &getBacktrace() const; 80113813Sphk}; 81113813Sphk 82113813Sphk} 83113813Sphk 84113813Sphk#endif 85113813Sphk