1894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman//===- llvm/Support/ErrorHandling.h - Fatal error handling ------*- C++ -*-===// 2894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman// 3894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman// The LLVM Compiler Infrastructure 4894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman// 5894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman// This file is distributed under the University of Illinois Open Source 6894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman// License. See LICENSE.TXT for details. 7894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman// 8894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman//===----------------------------------------------------------------------===// 9894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman// 10894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman// This file defines an API used to indicate fatal error conditions. Non-fatal 11894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman// errors (most of them) should be handled through LLVMContext. 12894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman// 13894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman//===----------------------------------------------------------------------===// 14894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman 15894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman#ifndef LLVM_SUPPORT_ERRORHANDLING_H 16894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman#define LLVM_SUPPORT_ERRORHANDLING_H 17894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman 18894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman#include "llvm/Support/Compiler.h" 1919bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman#include "llvm/ADT/StringRef.h" 20894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman#include <string> 21894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman 22894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Baumannamespace llvm { 23894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman class Twine; 24894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman 25894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// An error handler callback. 26894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman typedef void (*fatal_error_handler_t)(void *user_data, 27894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman const std::string& reason); 28894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman 29894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// install_fatal_error_handler - Installs a new error handler to be used 30894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// whenever a serious (non-recoverable) error is encountered by LLVM. 31894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// 32894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// If you are using llvm_start_multithreaded, you should register the handler 33894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// before doing that. 34894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// 35894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// If no error handler is installed the default is to print the error message 36894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// to stderr, and call exit(1). If an error handler is installed then it is 37894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// the handler's responsibility to log the message, it will no longer be 38894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// printed to stderr. If the error handler returns, then exit(1) will be 39894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// called. 40894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// 41894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// It is dangerous to naively use an error handler which throws an exception. 42894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// Even though some applications desire to gracefully recover from arbitrary 43894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// faults, blindly throwing exceptions through unfamiliar code isn't a way to 44894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// achieve this. 45894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// 46894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// \param user_data - An argument which will be passed to the install error 47894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// handler. 48894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman void install_fatal_error_handler(fatal_error_handler_t handler, 49894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman void *user_data = 0); 50894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman 51894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// Restores default error handling behaviour. 52894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// This must not be called between llvm_start_multithreaded() and 53894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// llvm_stop_multithreaded(). 54894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman void remove_fatal_error_handler(); 55894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman 5619bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman /// ScopedFatalErrorHandler - This is a simple helper class which just 5719bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman /// calls install_fatal_error_handler in its constructor and 5819bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman /// remove_fatal_error_handler in its destructor. 5919bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman struct ScopedFatalErrorHandler { 6019bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman explicit ScopedFatalErrorHandler(fatal_error_handler_t handler, 6119bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman void *user_data = 0) { 6219bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman install_fatal_error_handler(handler, user_data); 6319bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman } 6419bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman 6519bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman ~ScopedFatalErrorHandler() { remove_fatal_error_handler(); } 6619bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman }; 6719bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman 68894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// Reports a serious error, calling any installed error handler. These 69894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// functions are intended to be used for error conditions which are outside 70894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// the control of the compiler (I/O errors, invalid user input, etc.) 71894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// 72894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// If no error handler is installed the default is to print the message to 73894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// standard error, followed by a newline. 74894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// After the error handler is called this function will call exit(1), it 75894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// does not return. 7619bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman LLVM_ATTRIBUTE_NORETURN void report_fatal_error(const char *reason); 7719bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman LLVM_ATTRIBUTE_NORETURN void report_fatal_error(const std::string &reason); 7819bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman LLVM_ATTRIBUTE_NORETURN void report_fatal_error(StringRef reason); 7919bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman LLVM_ATTRIBUTE_NORETURN void report_fatal_error(const Twine &reason); 80894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman 81894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// This function calls abort(), and prints the optional message to stderr. 82894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// Use the llvm_unreachable macro (that adds location info), instead of 83894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman /// calling this function directly. 8419bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman LLVM_ATTRIBUTE_NORETURN void llvm_unreachable_internal(const char *msg=0, 8519bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman const char *file=0, 8619bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman unsigned line=0); 87894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman} 88894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman 8919bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman/// Marks that the current location is not supposed to be reachable. 9019bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman/// In !NDEBUG builds, prints the message and location info to stderr. 9119bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman/// In NDEBUG builds, becomes an optimizer hint that the current location 9219bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman/// is not supposed to be reachable. On compilers that don't support 9319bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman/// such hints, prints a reduced message instead. 94894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman/// 9519bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman/// Use this instead of assert(0). It conveys intent more clearly and 9619bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman/// allows compilers to omit some unnecessary code. 97894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman#ifndef NDEBUG 98894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman#define llvm_unreachable(msg) \ 99894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman ::llvm::llvm_unreachable_internal(msg, __FILE__, __LINE__) 10019bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman#elif defined(LLVM_BUILTIN_UNREACHABLE) 10119bac1e08be200c31efd26f0f5fd144c9b3eefd3John Bauman#define llvm_unreachable(msg) LLVM_BUILTIN_UNREACHABLE 102894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman#else 103894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman#define llvm_unreachable(msg) ::llvm::llvm_unreachable_internal() 104894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman#endif 105894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman 106894018228b0e0bdbd7aa7e8f47d4a9458789ca82John Bauman#endif 107