v8  10.1.124 (node 18.2.0)
V8 is Google's open source JavaScript engine
v8-initialization.h
Go to the documentation of this file.
1 // Copyright 2021 the V8 project authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef INCLUDE_V8_INITIALIZATION_H_
6 #define INCLUDE_V8_INITIALIZATION_H_
7 
8 #include <stddef.h>
9 #include <stdint.h>
10 
11 #include "v8-internal.h" // NOLINT(build/include_directory)
12 #include "v8-isolate.h" // NOLINT(build/include_directory)
13 #include "v8-platform.h" // NOLINT(build/include_directory)
14 #include "v8config.h" // NOLINT(build/include_directory)
15 
16 // We reserve the V8_* prefix for macros defined in V8 public API and
17 // assume there are no name conflicts with the embedder's code.
18 
19 /**
20  * The v8 JavaScript engine.
21  */
22 namespace v8 {
23 
24 class PageAllocator;
25 class Platform;
26 template <class K, class V, class T>
28 
29 /**
30  * EntropySource is used as a callback function when v8 needs a source
31  * of entropy.
32  */
33 using EntropySource = bool (*)(unsigned char* buffer, size_t length);
34 
35 /**
36  * ReturnAddressLocationResolver is used as a callback function when v8 is
37  * resolving the location of a return address on the stack. Profilers that
38  * change the return address on the stack can use this to resolve the stack
39  * location to wherever the profiler stashed the original return address.
40  *
41  * \param return_addr_location A location on stack where a machine
42  * return address resides.
43  * \returns Either return_addr_location, or else a pointer to the profiler's
44  * copy of the original return address.
45  *
46  * \note The resolver function must not cause garbage collection.
47  */
48 using ReturnAddressLocationResolver =
49  uintptr_t (*)(uintptr_t return_addr_location);
50 
51 using DcheckErrorCallback = void (*)(const char* file, int line,
52  const char* message);
53 
54 /**
55  * Container class for static utility functions.
56  */
57 class V8_EXPORT V8 {
58  public:
59  /**
60  * Hand startup data to V8, in case the embedder has chosen to build
61  * V8 with external startup data.
62  *
63  * Note:
64  * - By default the startup data is linked into the V8 library, in which
65  * case this function is not meaningful.
66  * - If this needs to be called, it needs to be called before V8
67  * tries to make use of its built-ins.
68  * - To avoid unnecessary copies of data, V8 will point directly into the
69  * given data blob, so pretty please keep it around until V8 exit.
70  * - Compression of the startup blob might be useful, but needs to
71  * handled entirely on the embedders' side.
72  * - The call will abort if the data is invalid.
73  */
74  static void SetSnapshotDataBlob(StartupData* startup_blob);
75 
76  /** Set the callback to invoke in case of Dcheck failures. */
77  static void SetDcheckErrorHandler(DcheckErrorCallback that);
78 
79  /**
80  * Sets V8 flags from a string.
81  */
82  static void SetFlagsFromString(const char* str);
83  static void SetFlagsFromString(const char* str, size_t length);
84 
85  /**
86  * Sets V8 flags from the command line.
87  */
88  static void SetFlagsFromCommandLine(int* argc, char** argv,
89  bool remove_flags);
90 
91  /** Get the version string. */
92  static const char* GetVersion();
93 
94  /**
95  * Initializes V8. This function needs to be called before the first Isolate
96  * is created. It always returns true.
97  */
98  V8_INLINE static bool Initialize() {
99  const int kBuildConfiguration =
100  (internal::PointerCompressionIsEnabled() ? kPointerCompression : 0) |
101  (internal::SmiValuesAre31Bits() ? k31BitSmis : 0) |
103  ? kSandboxedExternalPointers
104  : 0) |
105  (internal::SandboxIsEnabled() ? kSandbox : 0);
106  return Initialize(kBuildConfiguration);
107  }
108 
109  /**
110  * Allows the host application to provide a callback which can be used
111  * as a source of entropy for random number generators.
112  */
113  static void SetEntropySource(EntropySource source);
114 
115  /**
116  * Allows the host application to provide a callback that allows v8 to
117  * cooperate with a profiler that rewrites return addresses on stack.
118  */
120  ReturnAddressLocationResolver return_address_resolver);
121 
122  /**
123  * Releases any resources used by v8 and stops any utility threads
124  * that may be running. Note that disposing v8 is permanent, it
125  * cannot be reinitialized.
126  *
127  * It should generally not be necessary to dispose v8 before exiting
128  * a process, this should happen automatically. It is only necessary
129  * to use if the process needs the resources taken up by v8.
130  */
131  static bool Dispose();
132 
133  /**
134  * Initialize the ICU library bundled with V8. The embedder should only
135  * invoke this method when using the bundled ICU. Returns true on success.
136  *
137  * If V8 was compiled with the ICU data in an external file, the location
138  * of the data file has to be provided.
139  */
140  static bool InitializeICU(const char* icu_data_file = nullptr);
141 
142  /**
143  * Initialize the ICU library bundled with V8. The embedder should only
144  * invoke this method when using the bundled ICU. If V8 was compiled with
145  * the ICU data in an external file and when the default location of that
146  * file should be used, a path to the executable must be provided.
147  * Returns true on success.
148  *
149  * The default is a file called icudtl.dat side-by-side with the executable.
150  *
151  * Optionally, the location of the data file can be provided to override the
152  * default.
153  */
154  static bool InitializeICUDefaultLocation(const char* exec_path,
155  const char* icu_data_file = nullptr);
156 
157  /**
158  * Initialize the external startup data. The embedder only needs to
159  * invoke this method when external startup data was enabled in a build.
160  *
161  * If V8 was compiled with the startup data in an external file, then
162  * V8 needs to be given those external files during startup. There are
163  * three ways to do this:
164  * - InitializeExternalStartupData(const char*)
165  * This will look in the given directory for the file "snapshot_blob.bin".
166  * - InitializeExternalStartupDataFromFile(const char*)
167  * As above, but will directly use the given file name.
168  * - Call SetSnapshotDataBlob.
169  * This will read the blobs from the given data structure and will
170  * not perform any file IO.
171  */
172  static void InitializeExternalStartupData(const char* directory_path);
173  static void InitializeExternalStartupDataFromFile(const char* snapshot_blob);
174 
175  /**
176  * Sets the v8::Platform to use. This should be invoked before V8 is
177  * initialized.
178  */
179  static void InitializePlatform(Platform* platform);
180 
181  /**
182  * Clears all references to the v8::Platform. This should be invoked after
183  * V8 was disposed.
184  */
185  static void DisposePlatform();
186  V8_DEPRECATED("Use DisposePlatform()")
188 
189 #ifdef V8_SANDBOX
190  //
191  // Sandbox related API.
192  //
193  // This API is not yet stable and subject to changes in the future.
194  //
195 
196  /**
197  * Initializes the V8 sandbox.
198  *
199  * This must be invoked after the platform was initialized but before V8 is
200  * initialized. The sandbox is torn down during platform shutdown.
201  * Returns true on success, false otherwise.
202  *
203  * TODO(saelo) Once it is no longer optional to initialize the sandbox when
204  * compiling with V8_SANDBOX, the sandbox initialization will likely happen
205  * as part of V8::Initialize, at which point this function should be removed.
206  */
207  static bool InitializeSandbox();
208  V8_DEPRECATE_SOON("Use InitializeSandbox()")
209  static bool InitializeVirtualMemoryCage() { return InitializeSandbox(); }
210 
211  /**
212  * Provides access to the virtual address subspace backing the sandbox.
213  *
214  * This can be used to allocate pages inside the sandbox, for example to
215  * obtain virtual memory for ArrayBuffer backing stores, which must be
216  * located inside the sandbox.
217  *
218  * It should be assumed that an attacker can corrupt data inside the sandbox,
219  * and so in particular the contents of pages allocagted in this virtual
220  * address space, arbitrarily and concurrently. Due to this, it is
221  * recommended to to only place pure data buffers in them.
222  *
223  * This function must only be called after initializing the sandbox.
224  */
226  V8_DEPRECATE_SOON("Use GetSandboxAddressSpace()")
228 
229  /**
230  * Returns the size of the sandbox in bytes.
231  *
232  * If the sandbox has not been initialized, or if the initialization failed,
233  * this returns zero.
234  */
235  static size_t GetSandboxSizeInBytes();
236  V8_DEPRECATE_SOON("Use GetSandboxSizeInBytes()")
238  return GetSandboxSizeInBytes();
239  }
240 
241  /**
242  * Returns whether the sandbox is configured securely.
243  *
244  * If V8 cannot create a proper sandbox, it will fall back to creating a
245  * sandbox that doesn't have the desired security properties but at least
246  * still allows V8 to function. This API can be used to determine if such an
247  * insecure sandbox is being used, in which case it will return false.
248  */
249  static bool IsSandboxConfiguredSecurely();
250  V8_DEPRECATE_SOON("Use IsSandboxConfiguredSecurely()")
251  static bool IsUsingSecureVirtualMemoryCage() {
253  }
254 #endif
255 
256  /**
257  * Activate trap-based bounds checking for WebAssembly.
258  *
259  * \param use_v8_signal_handler Whether V8 should install its own signal
260  * handler or rely on the embedder's.
261  */
262  static bool EnableWebAssemblyTrapHandler(bool use_v8_signal_handler);
263 
264 #if defined(V8_OS_WIN)
265  /**
266  * On Win64, by default V8 does not emit unwinding data for jitted code,
267  * which means the OS cannot walk the stack frames and the system Structured
268  * Exception Handling (SEH) cannot unwind through V8-generated code:
269  * https://code.google.com/p/v8/issues/detail?id=3598.
270  *
271  * This function allows embedders to register a custom exception handler for
272  * exceptions in V8-generated code.
273  */
274  static void SetUnhandledExceptionCallback(
276 #endif
277 
278  /**
279  * Get statistics about the shared memory usage.
280  */
282 
283  private:
284  V8();
285 
286  enum BuildConfigurationFeatures {
287  kPointerCompression = 1 << 0,
288  k31BitSmis = 1 << 1,
289  kSandboxedExternalPointers = 1 << 2,
290  kSandbox = 1 << 3,
291  };
292 
293  /**
294  * Checks that the embedder build configuration is compatible with
295  * the V8 binary and if so initializes V8.
296  */
297  static bool Initialize(int build_config);
298 
299  friend class Context;
300  template <class K, class V, class T>
302 };
303 
304 } // namespace v8
305 
306 #endif // INCLUDE_V8_INITIALIZATION_H_