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 "jscntxt.h"
16 #include "NamespaceImports.h"
17
18 namespace js {
19 class ErrorObject;
20
21 JSErrorReport*
22 CopyErrorReport(JSContext* cx, JSErrorReport* report);
23
24 JSString*
25 ComputeStackString(JSContext* cx);
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 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 ReportUncaughtException(JSContext* cx);
75
76 extern JSErrorReport*
77 ErrorFromException(JSContext* cx, 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 CopyErrorObject(JSContext* cx, JS::Handle<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
GetExceptionProtoKey(JSExnType exn)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
ExnTypeFromProtoKey(JSProtoKey key)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 class AutoClearPendingException
120 {
121 JSContext* cx;
122
123 public:
AutoClearPendingException(JSContext * cxArg)124 explicit AutoClearPendingException(JSContext* cxArg)
125 : cx(cxArg)
126 { }
127
~AutoClearPendingException()128 ~AutoClearPendingException() {
129 JS_ClearPendingException(cx);
130 }
131 };
132
133 extern const char*
134 ValueToSourceForError(JSContext* cx, HandleValue val, JSAutoByteString& bytes);
135
136 } // namespace js
137
138 #endif /* jsexn_h */
139