1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6 /* SpiderMonkey initialization and shutdown APIs. */
7
8 #ifndef js_Initialization_h
9 #define js_Initialization_h
10
11 #include "mozilla/Span.h"
12
13 #include "jstypes.h"
14
15 struct JS_PUBLIC_API JSContext;
16
17 namespace JS {
18 namespace detail {
19
20 enum class InitState { Uninitialized = 0, Initializing, Running, ShutDown };
21
22 /**
23 * SpiderMonkey's initialization status is tracked here, and it controls things
24 * that should happen only once across all runtimes. It's an API requirement
25 * that JS_Init (and JS_ShutDown, if called) be called in a thread-aware
26 * manner, so this (internal -- embedders, don't use!) variable doesn't need to
27 * be atomic.
28 */
29 extern JS_PUBLIC_DATA InitState libraryInitState;
30
31 extern JS_PUBLIC_API const char* InitWithFailureDiagnostic(bool isDebugBuild);
32
33 } // namespace detail
34 } // namespace JS
35
36 // These are equivalent to ICU's |UMemAllocFn|, |UMemReallocFn|, and
37 // |UMemFreeFn| types. The first argument (called |context| in the ICU docs)
38 // will always be nullptr and should be ignored.
39 typedef void* (*JS_ICUAllocFn)(const void*, size_t size);
40 typedef void* (*JS_ICUReallocFn)(const void*, void* p, size_t size);
41 typedef void (*JS_ICUFreeFn)(const void*, void* p);
42
43 /**
44 * This function can be used to track memory used by ICU. If it is called, it
45 * *must* be called before JS_Init. Don't use it unless you know what you're
46 * doing!
47 */
48 extern JS_PUBLIC_API bool JS_SetICUMemoryFunctions(JS_ICUAllocFn allocFn,
49 JS_ICUReallocFn reallocFn,
50 JS_ICUFreeFn freeFn);
51
52 /**
53 * Initialize SpiderMonkey, returning true only if initialization succeeded.
54 * Once this method has succeeded, it is safe to call JS_NewContext and other
55 * JSAPI methods.
56 *
57 * This method must be called before any other JSAPI method is used on any
58 * thread. Once it has been used, it is safe to call any JSAPI method, and it
59 * remains safe to do so until JS_ShutDown is correctly called.
60 *
61 * It is currently not possible to initialize SpiderMonkey multiple times (that
62 * is, calling JS_Init/JSAPI methods/JS_ShutDown in that order, then doing so
63 * again). This restriction may eventually be lifted.
64 */
JS_Init(void)65 inline bool JS_Init(void) {
66 #ifdef DEBUG
67 return !JS::detail::InitWithFailureDiagnostic(true);
68 #else
69 return !JS::detail::InitWithFailureDiagnostic(false);
70 #endif
71 }
72
73 /**
74 * A variant of JS_Init. On success it returns nullptr. On failure it returns a
75 * pointer to a string literal that describes how initialization failed, which
76 * can be useful for debugging purposes.
77 */
JS_InitWithFailureDiagnostic(void)78 inline const char* JS_InitWithFailureDiagnostic(void) {
79 #ifdef DEBUG
80 return JS::detail::InitWithFailureDiagnostic(true);
81 #else
82 return JS::detail::InitWithFailureDiagnostic(false);
83 #endif
84 }
85
86 /*
87 * Returns true if SpiderMonkey has been initialized successfully, even if it
88 * has possibly been shut down.
89 *
90 * Note that it is the responsibility of the embedder to call JS_Init() and
91 * JS_ShutDown() at the correct times, and therefore this API should ideally not
92 * be necessary to use. This is only intended to be used in cases where the
93 * embedder isn't in full control of deciding whether to initialize SpiderMonkey
94 * or hand off the task to another consumer.
95 */
JS_IsInitialized(void)96 inline bool JS_IsInitialized(void) {
97 return JS::detail::libraryInitState >= JS::detail::InitState::Running;
98 }
99
100 namespace JS {
101
102 // Reference to a sequence of bytes.
103 // TODO: This type should be Span<cont uint8_t> (Bug 1709135)
104 using SelfHostedCache = mozilla::Span<const uint8_t>;
105
106 // Callback function used to copy the SelfHosted content to memory or to disk.
107 using SelfHostedWriter = bool (*)(JSContext*, SelfHostedCache);
108
109 /*
110 * Initialize the runtime's self-hosted code. Embeddings should call this
111 * exactly once per runtime/context, before the first JS_NewGlobalObject
112 * call.
113 *
114 * This function parses the self-hosted code, except if the provided cache span
115 * is not empty, in which case the self-hosted content is decoded from the span.
116 *
117 * The cached content provided as argument, when non-empty, should come from the
118 * a previous execution of JS::InitSelfHostedCode where a writer was registered.
119 * The content should come from the same version of the binary, otherwise this
120 * would cause an error.
121 *
122 * The cached content provided with the Span should remain alive until
123 * JS_Shutdown is called.
124 *
125 * The writer callback given as argument would be called by when the result of
126 * the parser is ready to be cached. The writer is in charge of saving the
127 * content in memory or on disk. The span given as argument of the writer only
128 * last for the time of the call, and contains the content to be saved.
129 *
130 * The writer is not called if the cached content given as argument of
131 * InitSelfHostedCode is non-empty.
132 *
133 * Errors returned by the writer callback would bubble up through
134 * JS::InitSelfHostedCode.
135 *
136 * The cached content provided by the writer callback is safe to reuse across
137 * threads, and even across multiple executions as long as the executable is
138 * identical.
139 *
140 * NOTE: This may not set a pending exception in the case of OOM since this
141 * runs very early in startup.
142 */
143 JS_PUBLIC_API bool InitSelfHostedCode(JSContext* cx,
144 SelfHostedCache cache = nullptr,
145 SelfHostedWriter writer = nullptr);
146
147 } // namespace JS
148
149 /**
150 * Destroy free-standing resources allocated by SpiderMonkey, not associated
151 * with any runtime, context, or other structure.
152 *
153 * This method should be called after all other JSAPI data has been properly
154 * cleaned up: every new runtime must have been destroyed, every new context
155 * must have been destroyed, and so on. Calling this method before all other
156 * resources have been destroyed has undefined behavior.
157 *
158 * Failure to call this method, at present, has no adverse effects other than
159 * leaking memory. This may not always be the case; it's recommended that all
160 * embedders call this method when all other JSAPI operations have completed.
161 *
162 * It is currently not possible to initialize SpiderMonkey multiple times (that
163 * is, calling JS_Init/JSAPI methods/JS_ShutDown in that order, then doing so
164 * again). This restriction may eventually be lifted.
165 */
166 extern JS_PUBLIC_API void JS_ShutDown(void);
167
168 #endif /* js_Initialization_h */
169