js/src/jsexn.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  * vim: set ts=8 sts=4 et sw=4 tw=99:
   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 /*
   8  * JS runtime exception classes.
   9  */
  10
  11 #ifndef jsexn_h
  12 #define jsexn_h
  13
  14 #include "jsapi.h"
  15 #include "NamespaceImports.h"
  16
  17 namespace js {
  18 class ErrorObject;
  19
  20 JSErrorReport*
  21 CopyErrorReport(JSContext* cx, JSErrorReport* report);
  22
  23 JSString*
  24 ComputeStackString(JSContext* cx);
  25 }
  26
  27 /*
  28  * Given a JSErrorReport, check to see if there is an exception associated with
  29  * the error number.  If there is, then create an appropriate exception object,
  30  * set it as the pending exception, and set the JSREPORT_EXCEPTION flag on the
  31  * error report.  Exception-aware host error reporters should probably ignore
  32  * error reports so flagged.
  33  *
  34  * Return true if cx->throwing and cx->exception were set.
  35  *
  36  * This means that:
  37  *
  38  *   - If the error is successfully converted to an exception and stored in
  39  *     cx->exception, the return value is true. This is the "normal", happiest
  40  *     case for the caller.
  41  *
  42  *   - If we try to convert, but fail with OOM or some other error that ends up
  43  *     setting cx->throwing to true and setting cx->exception, then we also
  44  *     return true (because callers want to treat that case the same way).
  45  *     The original error described by *reportp typically won't be reported
  46  *     anywhere; instead OOM is reported.
  47  *
  48  *   - If *reportp is just a warning, or the error code is unrecognized, or if
  49  *     we decided to do nothing in order to avoid recursion, then return
  50  *     false. In those cases, this error is just being swept under the rug
  51  *     unless the caller decides to call CallErrorReporter explicitly.
  52  */
  53 extern bool
  54 js_ErrorToException(JSContext* cx, const char* message, JSErrorReport* reportp,
  55                     JSErrorCallback callback, void* userRef);
  56
  57 /*
  58  * Called if a JS API call to js_Execute or js_InternalCall fails; calls the
  59  * error reporter with the error report associated with any uncaught exception
  60  * that has been raised.  Returns true if there was an exception pending, and
  61  * the error reporter was actually called.
  62  *
  63  * The JSErrorReport * that the error reporter is called with is currently
  64  * associated with a JavaScript object, and is not guaranteed to persist after
  65  * the object is collected.  Any persistent uses of the JSErrorReport contents
  66  * should make their own copy.
  67  *
  68  * The flags field of the JSErrorReport will have the JSREPORT_EXCEPTION flag
  69  * set; embeddings that want to silently propagate JavaScript exceptions to
  70  * other contexts may want to use an error reporter that ignores errors with
  71  * this flag.
  72  */
  73 extern bool
  74 js_ReportUncaughtException(JSContext* cx);
  75
  76 extern JSErrorReport*
  77 js_ErrorFromException(JSContext* cx, js::HandleObject obj);
  78
  79 /*
  80  * Make a copy of errobj parented to cx's compartment's global.
  81  *
  82  * errobj may be in a different compartment than cx, but it must be an Error
  83  * object (not a wrapper of one) and it must not be one of the standard error
  84  * prototype objects (errobj->getPrivate() must not be nullptr).
  85  */
  86 extern JSObject*
  87 js_CopyErrorObject(JSContext* cx, JS::Handle<js::ErrorObject*> errobj);
  88
  89 static_assert(JSEXN_ERR == 0 &&
  90               JSProto_Error + JSEXN_INTERNALERR == JSProto_InternalError &&
  91               JSProto_Error + JSEXN_EVALERR == JSProto_EvalError &&
  92               JSProto_Error + JSEXN_RANGEERR == JSProto_RangeError &&
  93               JSProto_Error + JSEXN_REFERENCEERR == JSProto_ReferenceError &&
  94               JSProto_Error + JSEXN_SYNTAXERR == JSProto_SyntaxError &&
  95               JSProto_Error + JSEXN_TYPEERR == JSProto_TypeError &&
  96               JSProto_Error + JSEXN_URIERR == JSProto_URIError &&
  97               JSEXN_URIERR + 1 == JSEXN_LIMIT,
  98               "GetExceptionProtoKey and ExnTypeFromProtoKey require that "
  99               "each corresponding JSExnType and JSProtoKey value be separated "
 100               "by the same constant value");
 101
 102 static inline JSProtoKey
 103 GetExceptionProtoKey(JSExnType exn)
 104 {
 105     MOZ_ASSERT(JSEXN_ERR <= exn);
 106     MOZ_ASSERT(exn < JSEXN_LIMIT);
 107     return JSProtoKey(JSProto_Error + int(exn));
 108 }
 109
 110 static inline JSExnType
 111 ExnTypeFromProtoKey(JSProtoKey key)
 112 {
 113     JSExnType type = static_cast<JSExnType>(key - JSProto_Error);
 114     MOZ_ASSERT(type >= JSEXN_ERR);
 115     MOZ_ASSERT(type < JSEXN_LIMIT);
 116     return type;
 117 }
 118
 119 #endif /* jsexn_h */