cannam@62: // Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
cannam@62: // Licensed under the MIT License:
cannam@62: //
cannam@62: // Permission is hereby granted, free of charge, to any person obtaining a copy
cannam@62: // of this software and associated documentation files (the "Software"), to deal
cannam@62: // in the Software without restriction, including without limitation the rights
cannam@62: // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
cannam@62: // copies of the Software, and to permit persons to whom the Software is
cannam@62: // furnished to do so, subject to the following conditions:
cannam@62: //
cannam@62: // The above copyright notice and this permission notice shall be included in
cannam@62: // all copies or substantial portions of the Software.
cannam@62: //
cannam@62: // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
cannam@62: // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
cannam@62: // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
cannam@62: // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
cannam@62: // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
cannam@62: // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
cannam@62: // THE SOFTWARE.
cannam@62: 
cannam@62: #ifndef KJ_EXCEPTION_H_
cannam@62: #define KJ_EXCEPTION_H_
cannam@62: 
cannam@62: #if defined(__GNUC__) && !KJ_HEADER_WARNINGS
cannam@62: #pragma GCC system_header
cannam@62: #endif
cannam@62: 
cannam@62: #include "memory.h"
cannam@62: #include "array.h"
cannam@62: #include "string.h"
cannam@62: 
cannam@62: namespace kj {
cannam@62: 
cannam@62: class ExceptionImpl;
cannam@62: 
cannam@62: class Exception {
cannam@62:   // Exception thrown in case of fatal errors.
cannam@62:   //
cannam@62:   // Actually, a subclass of this which also implements std::exception will be thrown, but we hide
cannam@62:   // that fact from the interface to avoid #including <exception>.
cannam@62: 
cannam@62: public:
cannam@62:   enum class Type {
cannam@62:     // What kind of failure?
cannam@62: 
cannam@62:     FAILED = 0,
cannam@62:     // Something went wrong. This is the usual error type. KJ_ASSERT and KJ_REQUIRE throw this
cannam@62:     // error type.
cannam@62: 
cannam@62:     OVERLOADED = 1,
cannam@62:     // The call failed because of a temporary lack of resources. This could be space resources
cannam@62:     // (out of memory, out of disk space) or time resources (request queue overflow, operation
cannam@62:     // timed out).
cannam@62:     //
cannam@62:     // The operation might work if tried again, but it should NOT be repeated immediately as this
cannam@62:     // may simply exacerbate the problem.
cannam@62: 
cannam@62:     DISCONNECTED = 2,
cannam@62:     // The call required communication over a connection that has been lost. The callee will need
cannam@62:     // to re-establish connections and try again.
cannam@62: 
cannam@62:     UNIMPLEMENTED = 3
cannam@62:     // The requested method is not implemented. The caller may wish to revert to a fallback
cannam@62:     // approach based on other methods.
cannam@62: 
cannam@62:     // IF YOU ADD A NEW VALUE:
cannam@62:     // - Update the stringifier.
cannam@62:     // - Update Cap'n Proto's RPC protocol's Exception.Type enum.
cannam@62:   };
cannam@62: 
cannam@62:   Exception(Type type, const char* file, int line, String description = nullptr) noexcept;
cannam@62:   Exception(Type type, String file, int line, String description = nullptr) noexcept;
cannam@62:   Exception(const Exception& other) noexcept;
cannam@62:   Exception(Exception&& other) = default;
cannam@62:   ~Exception() noexcept;
cannam@62: 
cannam@62:   const char* getFile() const { return file; }
cannam@62:   int getLine() const { return line; }
cannam@62:   Type getType() const { return type; }
cannam@62:   StringPtr getDescription() const { return description; }
cannam@62:   ArrayPtr<void* const> getStackTrace() const { return arrayPtr(trace, traceCount); }
cannam@62: 
cannam@62:   struct Context {
cannam@62:     // Describes a bit about what was going on when the exception was thrown.
cannam@62: 
cannam@62:     const char* file;
cannam@62:     int line;
cannam@62:     String description;
cannam@62:     Maybe<Own<Context>> next;
cannam@62: 
cannam@62:     Context(const char* file, int line, String&& description, Maybe<Own<Context>>&& next)
cannam@62:         : file(file), line(line), description(mv(description)), next(mv(next)) {}
cannam@62:     Context(const Context& other) noexcept;
cannam@62:   };
cannam@62: 
cannam@62:   inline Maybe<const Context&> getContext() const {
cannam@62:     KJ_IF_MAYBE(c, context) {
cannam@62:       return **c;
cannam@62:     } else {
cannam@62:       return nullptr;
cannam@62:     }
cannam@62:   }
cannam@62: 
cannam@62:   void wrapContext(const char* file, int line, String&& description);
cannam@62:   // Wraps the context in a new node.  This becomes the head node returned by getContext() -- it
cannam@62:   // is expected that contexts will be added in reverse order as the exception passes up the
cannam@62:   // callback stack.
cannam@62: 
cannam@62:   KJ_NOINLINE void extendTrace(uint ignoreCount);
cannam@62:   // Append the current stack trace to the exception's trace, ignoring the first `ignoreCount`
cannam@62:   // frames (see `getStackTrace()` for discussion of `ignoreCount`).
cannam@62: 
cannam@62:   KJ_NOINLINE void truncateCommonTrace();
cannam@62:   // Remove the part of the stack trace which the exception shares with the caller of this method.
cannam@62:   // This is used by the async library to remove the async infrastructure from the stack trace
cannam@62:   // before replacing it with the async trace.
cannam@62: 
cannam@62:   void addTrace(void* ptr);
cannam@62:   // Append the given pointer to the backtrace, if it is not already full. This is used by the
cannam@62:   // async library to trace through the promise chain that led to the exception.
cannam@62: 
cannam@62: private:
cannam@62:   String ownFile;
cannam@62:   const char* file;
cannam@62:   int line;
cannam@62:   Type type;
cannam@62:   String description;
cannam@62:   Maybe<Own<Context>> context;
cannam@62:   void* trace[32];
cannam@62:   uint traceCount;
cannam@62: 
cannam@62:   friend class ExceptionImpl;
cannam@62: };
cannam@62: 
cannam@62: StringPtr KJ_STRINGIFY(Exception::Type type);
cannam@62: String KJ_STRINGIFY(const Exception& e);
cannam@62: 
cannam@62: // =======================================================================================
cannam@62: 
cannam@62: enum class LogSeverity {
cannam@62:   INFO,      // Information describing what the code is up to, which users may request to see
cannam@62:              // with a flag like `--verbose`.  Does not indicate a problem.  Not printed by
cannam@62:              // default; you must call setLogLevel(INFO) to enable.
cannam@62:   WARNING,   // A problem was detected but execution can continue with correct output.
cannam@62:   ERROR,     // Something is wrong, but execution can continue with garbage output.
cannam@62:   FATAL,     // Something went wrong, and execution cannot continue.
cannam@62:   DBG        // Temporary debug logging.  See KJ_DBG.
cannam@62: 
cannam@62:   // Make sure to update the stringifier if you add a new severity level.
cannam@62: };
cannam@62: 
cannam@62: StringPtr KJ_STRINGIFY(LogSeverity severity);
cannam@62: 
cannam@62: class ExceptionCallback {
cannam@62:   // If you don't like C++ exceptions, you may implement and register an ExceptionCallback in order
cannam@62:   // to perform your own exception handling.  For example, a reasonable thing to do is to have
cannam@62:   // onRecoverableException() set a flag indicating that an error occurred, and then check for that
cannam@62:   // flag just before writing to storage and/or returning results to the user.  If the flag is set,
cannam@62:   // discard whatever you have and return an error instead.
cannam@62:   //
cannam@62:   // ExceptionCallbacks must always be allocated on the stack.  When an exception is thrown, the
cannam@62:   // newest ExceptionCallback on the calling thread's stack is called.  The default implementation
cannam@62:   // of each method calls the next-oldest ExceptionCallback for that thread.  Thus the callbacks
cannam@62:   // behave a lot like try/catch blocks, except that they are called before any stack unwinding
cannam@62:   // occurs.
cannam@62: 
cannam@62: public:
cannam@62:   ExceptionCallback();
cannam@62:   KJ_DISALLOW_COPY(ExceptionCallback);
cannam@62:   virtual ~ExceptionCallback() noexcept(false);
cannam@62: 
cannam@62:   virtual void onRecoverableException(Exception&& exception);
cannam@62:   // Called when an exception has been raised, but the calling code has the ability to continue by
cannam@62:   // producing garbage output.  This method _should_ throw the exception, but is allowed to simply
cannam@62:   // return if garbage output is acceptable.
cannam@62:   //
cannam@62:   // The global default implementation throws an exception unless the library was compiled with
cannam@62:   // -fno-exceptions, in which case it logs an error and returns.
cannam@62: 
cannam@62:   virtual void onFatalException(Exception&& exception);
cannam@62:   // Called when an exception has been raised and the calling code cannot continue.  If this method
cannam@62:   // returns normally, abort() will be called.  The method must throw the exception to avoid
cannam@62:   // aborting.
cannam@62:   //
cannam@62:   // The global default implementation throws an exception unless the library was compiled with
cannam@62:   // -fno-exceptions, in which case it logs an error and returns.
cannam@62: 
cannam@62:   virtual void logMessage(LogSeverity severity, const char* file, int line, int contextDepth,
cannam@62:                           String&& text);
cannam@62:   // Called when something wants to log some debug text.  `contextDepth` indicates how many levels
cannam@62:   // of context the message passed through; it may make sense to indent the message accordingly.
cannam@62:   //
cannam@62:   // The global default implementation writes the text to stderr.
cannam@62: 
cannam@62:   enum class StackTraceMode {
cannam@62:     FULL,
cannam@62:     // Stringifying a stack trace will attempt to determine source file and line numbers. This may
cannam@62:     // be expensive. For example, on Linux, this shells out to `addr2line`.
cannam@62:     //
cannam@62:     // This is the default in debug builds.
cannam@62: 
cannam@62:     ADDRESS_ONLY,
cannam@62:     // Stringifying a stack trace will only generate a list of code addresses.
cannam@62:     //
cannam@62:     // This is the default in release builds.
cannam@62: 
cannam@62:     NONE
cannam@62:     // Generating a stack trace will always return an empty array.
cannam@62:     //
cannam@62:     // This avoids ever unwinding the stack. On Windows in particular, the stack unwinding library
cannam@62:     // has been observed to be pretty slow, so exception-heavy code might benefit significantly
cannam@62:     // from this setting. (But exceptions should be rare...)
cannam@62:   };
cannam@62: 
cannam@62:   virtual StackTraceMode stackTraceMode();
cannam@62:   // Returns the current preferred stack trace mode.
cannam@62: 
cannam@62: protected:
cannam@62:   ExceptionCallback& next;
cannam@62: 
cannam@62: private:
cannam@62:   ExceptionCallback(ExceptionCallback& next);
cannam@62: 
cannam@62:   class RootExceptionCallback;
cannam@62:   friend ExceptionCallback& getExceptionCallback();
cannam@62: };
cannam@62: 
cannam@62: ExceptionCallback& getExceptionCallback();
cannam@62: // Returns the current exception callback.
cannam@62: 
cannam@62: KJ_NOINLINE KJ_NORETURN(void throwFatalException(kj::Exception&& exception, uint ignoreCount = 0));
cannam@62: // Invoke the exception callback to throw the given fatal exception.  If the exception callback
cannam@62: // returns, abort.
cannam@62: 
cannam@62: KJ_NOINLINE void throwRecoverableException(kj::Exception&& exception, uint ignoreCount = 0);
cannam@62: // Invoke the exception callback to throw the given recoverable exception.  If the exception
cannam@62: // callback returns, return normally.
cannam@62: 
cannam@62: // =======================================================================================
cannam@62: 
cannam@62: namespace _ { class Runnable; }
cannam@62: 
cannam@62: template <typename Func>
cannam@62: Maybe<Exception> runCatchingExceptions(Func&& func) noexcept;
cannam@62: // Executes the given function (usually, a lambda returning nothing) catching any exceptions that
cannam@62: // are thrown.  Returns the Exception if there was one, or null if the operation completed normally.
cannam@62: // Non-KJ exceptions will be wrapped.
cannam@62: //
cannam@62: // If exception are disabled (e.g. with -fno-exceptions), this will still detect whether any
cannam@62: // recoverable exceptions occurred while running the function and will return those.
cannam@62: 
cannam@62: class UnwindDetector {
cannam@62:   // Utility for detecting when a destructor is called due to unwind.  Useful for:
cannam@62:   // - Avoiding throwing exceptions in this case, which would terminate the program.
cannam@62:   // - Detecting whether to commit or roll back a transaction.
cannam@62:   //
cannam@62:   // To use this class, either inherit privately from it or declare it as a member.  The detector
cannam@62:   // works by comparing the exception state against that when the constructor was called, so for
cannam@62:   // an object that was actually constructed during exception unwind, it will behave as if no
cannam@62:   // unwind is taking place.  This is usually the desired behavior.
cannam@62: 
cannam@62: public:
cannam@62:   UnwindDetector();
cannam@62: 
cannam@62:   bool isUnwinding() const;
cannam@62:   // Returns true if the current thread is in a stack unwind that it wasn't in at the time the
cannam@62:   // object was constructed.
cannam@62: 
cannam@62:   template <typename Func>
cannam@62:   void catchExceptionsIfUnwinding(Func&& func) const;
cannam@62:   // Runs the given function (e.g., a lambda).  If isUnwinding() is true, any exceptions are
cannam@62:   // caught and treated as secondary faults, meaning they are considered to be side-effects of the
cannam@62:   // exception that is unwinding the stack.  Otherwise, exceptions are passed through normally.
cannam@62: 
cannam@62: private:
cannam@62:   uint uncaughtCount;
cannam@62: 
cannam@62:   void catchExceptionsAsSecondaryFaults(_::Runnable& runnable) const;
cannam@62: };
cannam@62: 
cannam@62: namespace _ {  // private
cannam@62: 
cannam@62: class Runnable {
cannam@62: public:
cannam@62:   virtual void run() = 0;
cannam@62: };
cannam@62: 
cannam@62: template <typename Func>
cannam@62: class RunnableImpl: public Runnable {
cannam@62: public:
cannam@62:   RunnableImpl(Func&& func): func(kj::mv(func)) {}
cannam@62:   void run() override {
cannam@62:     func();
cannam@62:   }
cannam@62: private:
cannam@62:   Func func;
cannam@62: };
cannam@62: 
cannam@62: Maybe<Exception> runCatchingExceptions(Runnable& runnable) noexcept;
cannam@62: 
cannam@62: }  // namespace _ (private)
cannam@62: 
cannam@62: template <typename Func>
cannam@62: Maybe<Exception> runCatchingExceptions(Func&& func) noexcept {
cannam@62:   _::RunnableImpl<Decay<Func>> runnable(kj::fwd<Func>(func));
cannam@62:   return _::runCatchingExceptions(runnable);
cannam@62: }
cannam@62: 
cannam@62: template <typename Func>
cannam@62: void UnwindDetector::catchExceptionsIfUnwinding(Func&& func) const {
cannam@62:   if (isUnwinding()) {
cannam@62:     _::RunnableImpl<Decay<Func>> runnable(kj::fwd<Func>(func));
cannam@62:     catchExceptionsAsSecondaryFaults(runnable);
cannam@62:   } else {
cannam@62:     func();
cannam@62:   }
cannam@62: }
cannam@62: 
cannam@62: #define KJ_ON_SCOPE_SUCCESS(code) \
cannam@62:   ::kj::UnwindDetector KJ_UNIQUE_NAME(_kjUnwindDetector); \
cannam@62:   KJ_DEFER(if (!KJ_UNIQUE_NAME(_kjUnwindDetector).isUnwinding()) { code; })
cannam@62: // Runs `code` if the current scope is exited normally (not due to an exception).
cannam@62: 
cannam@62: #define KJ_ON_SCOPE_FAILURE(code) \
cannam@62:   ::kj::UnwindDetector KJ_UNIQUE_NAME(_kjUnwindDetector); \
cannam@62:   KJ_DEFER(if (KJ_UNIQUE_NAME(_kjUnwindDetector).isUnwinding()) { code; })
cannam@62: // Runs `code` if the current scope is exited due to an exception.
cannam@62: 
cannam@62: // =======================================================================================
cannam@62: 
cannam@62: KJ_NOINLINE ArrayPtr<void* const> getStackTrace(ArrayPtr<void*> space, uint ignoreCount);
cannam@62: // Attempt to get the current stack trace, returning a list of pointers to instructions. The
cannam@62: // returned array is a slice of `space`. Provide a larger `space` to get a deeper stack trace.
cannam@62: // If the platform doesn't support stack traces, returns an empty array.
cannam@62: //
cannam@62: // `ignoreCount` items will be truncated from the front of the trace. This is useful for chopping
cannam@62: // off a prefix of the trace that is uninteresting to the developer because it's just locations
cannam@62: // inside the debug infrastructure that is requesting the trace. Be careful to mark functions as
cannam@62: // KJ_NOINLINE if you intend to count them in `ignoreCount`. Note that, unfortunately, the
cannam@62: // ignored entries will still waste space in the `space` array (and the returned array's `begin()`
cannam@62: // is never exactly equal to `space.begin()` due to this effect, even if `ignoreCount` is zero
cannam@62: // since `getStackTrace()` needs to ignore its own internal frames).
cannam@62: 
cannam@62: String stringifyStackTrace(ArrayPtr<void* const>);
cannam@62: // Convert the stack trace to a string with file names and line numbers. This may involve executing
cannam@62: // suprocesses.
cannam@62: 
cannam@62: String getStackTrace();
cannam@62: // Get a stack trace right now and stringify it. Useful for debugging.
cannam@62: 
cannam@62: void printStackTraceOnCrash();
cannam@62: // Registers signal handlers on common "crash" signals like SIGSEGV that will (attempt to) print
cannam@62: // a stack trace. You should call this as early as possible on program startup. Programs using
cannam@62: // KJ_MAIN get this automatically.
cannam@62: 
cannam@62: kj::StringPtr trimSourceFilename(kj::StringPtr filename);
cannam@62: // Given a source code file name, trim off noisy prefixes like "src/" or
cannam@62: // "/ekam-provider/canonical/".
cannam@62: 
cannam@62: }  // namespace kj
cannam@62: 
cannam@62: #endif  // KJ_EXCEPTION_H_