js/public/Exception.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: set ts=8 sts=2 et sw=2 tw=80:
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef js_Exception_h
   8 #define js_Exception_h
   9
  10 #include "mozilla/Attributes.h"
  11
  12 #include "jspubtd.h"
  13 #include "js/RootingAPI.h"  // JS::{Handle,Rooted}
  14 #include "js/Value.h"       // JS::Value, JS::Handle<JS::Value>
  15
  16 namespace JS {
  17
  18 // This class encapsulates a (pending) exception and the corresponding optional
  19 // SavedFrame stack object captured when the pending exception was set
  20 // on the JSContext. This fuzzily correlates with a `throw` statement in JS,
  21 // although arbitrary JSAPI consumers or VM code may also set pending exceptions
  22 // via `JS_SetPendingException`.
  23 //
  24 // This is not the same stack as `e.stack` when `e` is an `Error` object.
  25 // (That would be JS::ExceptionStackOrNull).
  26 class MOZ_STACK_CLASS ExceptionStack {
  27   Rooted<Value> exception_;
  28   Rooted<JSObject*> stack_;
  29
  30   friend JS_PUBLIC_API bool GetPendingExceptionStack(
  31       JSContext* cx, JS::ExceptionStack* exceptionStack);
  32
  33   void init(HandleValue exception, HandleObject stack) {
  34     exception_ = exception;
  35     stack_ = stack;
  36   }
  37
  38  public:
  39   explicit ExceptionStack(JSContext* cx) : exception_(cx), stack_(cx) {}
  40
  41   ExceptionStack(JSContext* cx, HandleValue exception, HandleObject stack)
  42       : exception_(cx, exception), stack_(cx, stack) {}
  43
  44   HandleValue exception() const { return exception_; }
  45
  46   // |stack| can be null.
  47   HandleObject stack() const { return stack_; }
  48 };
  49
  50 // Get the current pending exception value and stack.
  51 // This function asserts that there is a pending exception.
  52 // If this function returns false, then retrieving the current pending exception
  53 // failed and might have been overwritten by a new exception.
  54 extern JS_PUBLIC_API bool GetPendingExceptionStack(
  55     JSContext* cx, JS::ExceptionStack* exceptionStack);
  56
  57 // Similar to GetPendingExceptionStack, but also clears the current
  58 // pending exception.
  59 extern JS_PUBLIC_API bool StealPendingExceptionStack(
  60     JSContext* cx, JS::ExceptionStack* exceptionStack);
  61
  62 // Set both the exception value and its associated stack on the context as
  63 // the current pending exception.
  64 extern JS_PUBLIC_API void SetPendingExceptionStack(
  65     JSContext* cx, const JS::ExceptionStack& exceptionStack);
  66
  67 }  // namespace JS
  68
  69 #endif  // js_Exception_h