/src/node/deps/v8/include/v8-initialization.h

Source
// Copyright 2021 the V8 project authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef INCLUDE_V8_INITIALIZATION_H_
#define INCLUDE_V8_INITIALIZATION_H_

#include <stddef.h>
#include <stdint.h>

#include "v8-callbacks.h"  // NOLINT(build/include_directory)
#include "v8-internal.h"   // NOLINT(build/include_directory)
#include "v8-isolate.h"    // NOLINT(build/include_directory)
#include "v8-platform.h"   // NOLINT(build/include_directory)
#include "v8config.h"      // NOLINT(build/include_directory)

// We reserve the V8_* prefix for macros defined in V8 public API and
// assume there are no name conflicts with the embedder's code.

/**
 * The v8 JavaScript engine.
 */
namespace v8 {

class PageAllocator;
class Platform;
template <class K, class V, class T>
class PersistentValueMapBase;

/**
 * EntropySource is used as a callback function when v8 needs a source
 * of entropy.
 */
using EntropySource = bool (*)(unsigned char* buffer, size_t length);

/**
 * ReturnAddressLocationResolver is used as a callback function when v8 is
 * resolving the location of a return address on the stack. Profilers that
 * change the return address on the stack can use this to resolve the stack
 * location to wherever the profiler stashed the original return address.
 *
 * \param return_addr_location A location on stack where a machine
 *    return address resides.
 * \returns Either return_addr_location, or else a pointer to the profiler's
 *    copy of the original return address.
 *
 * \note The resolver function must not cause garbage collection.
 */
using ReturnAddressLocationResolver =
    uintptr_t (*)(uintptr_t return_addr_location);

using DcheckErrorCallback = void (*)(const char* file, int line,
                                     const char* message);

using V8FatalErrorCallback = void (*)(const char* file, int line,
                                      const char* message);

/**
 * Container class for static utility functions.
 */
class V8_EXPORT V8 {
 public:
  /**
   * Hand startup data to V8, in case the embedder has chosen to build
   * V8 with external startup data.
   *
   * Note:
   * - By default the startup data is linked into the V8 library, in which
   *   case this function is not meaningful.
   * - If this needs to be called, it needs to be called before V8
   *   tries to make use of its built-ins.
   * - To avoid unnecessary copies of data, V8 will point directly into the
   *   given data blob, so pretty please keep it around until V8 exit.
   * - Compression of the startup blob might be useful, but needs to
   *   handled entirely on the embedders' side.
   * - The call will abort if the data is invalid.
   */
  static void SetSnapshotDataBlob(StartupData* startup_blob);

  /** Set the callback to invoke in case of Dcheck failures. */
  static void SetDcheckErrorHandler(DcheckErrorCallback that);

  /** Set the callback to invoke in the case of CHECK failures or fatal
   * errors. This is distinct from Isolate::SetFatalErrorHandler, which
   * is invoked in response to API usage failures.
   * */
  static void SetFatalErrorHandler(V8FatalErrorCallback that);

  /**
   * Sets V8 flags from a string.
   */
  static void SetFlagsFromString(const char* str);
  static void SetFlagsFromString(const char* str, size_t length);

  /**
   * Sets V8 flags from the command line.
   */
  static void SetFlagsFromCommandLine(int* argc, char** argv,
                                      bool remove_flags);

  /** Get the version string. */
  static const char* GetVersion();

  /**
   * Initializes V8. This function needs to be called before the first Isolate
   * is created. It always returns true.
   */
  V8_INLINE static bool Initialize() {
#ifdef V8_TARGET_OS_ANDROID
    const bool kV8TargetOsIsAndroid = true;
#else
    const bool kV8TargetOsIsAndroid = false;
#endif

#ifdef V8_ENABLE_CHECKS
    const bool kV8EnableChecks = true;
#else
    const bool kV8EnableChecks = false;
#endif

    const int kBuildConfiguration =
        (internal::PointerCompressionIsEnabled() ? kPointerCompression : 0) |
        (internal::SmiValuesAre31Bits() ? k31BitSmis : 0) |
        (internal::SandboxIsEnabled() ? kSandbox : 0) |
        (kV8TargetOsIsAndroid ? kTargetOsIsAndroid : 0) |
        (kV8EnableChecks ? kEnableChecks : 0);
    return Initialize(kBuildConfiguration);
  }

  /**
   * Allows the host application to provide a callback which can be used
   * as a source of entropy for random number generators.
   */
  static void SetEntropySource(EntropySource source);

  /**
   * Allows the host application to provide a callback that allows v8 to
   * cooperate with a profiler that rewrites return addresses on stack.
   */
  static void SetReturnAddressLocationResolver(
      ReturnAddressLocationResolver return_address_resolver);

  /**
   * Releases any resources used by v8 and stops any utility threads
   * that may be running.  Note that disposing v8 is permanent, it
   * cannot be reinitialized.
   *
   * It should generally not be necessary to dispose v8 before exiting
   * a process, this should happen automatically.  It is only necessary
   * to use if the process needs the resources taken up by v8.
   */
  static bool Dispose();

  /**
   * Initialize the ICU library bundled with V8. The embedder should only
   * invoke this method when using the bundled ICU. Returns true on success.
   *
   * If V8 was compiled with the ICU data in an external file, the location
   * of the data file has to be provided.
   */
  static bool InitializeICU(const char* icu_data_file = nullptr);

  /**
   * Initialize the ICU library bundled with V8. The embedder should only
   * invoke this method when using the bundled ICU. If V8 was compiled with
   * the ICU data in an external file and when the default location of that
   * file should be used, a path to the executable must be provided.
   * Returns true on success.
   *
   * The default is a file called icudtl.dat side-by-side with the executable.
   *
   * Optionally, the location of the data file can be provided to override the
   * default.
   */
  static bool InitializeICUDefaultLocation(const char* exec_path,
                                           const char* icu_data_file = nullptr);

  /**
   * Initialize the external startup data. The embedder only needs to
   * invoke this method when external startup data was enabled in a build.
   *
   * If V8 was compiled with the startup data in an external file, then
   * V8 needs to be given those external files during startup. There are
   * three ways to do this:
   * - InitializeExternalStartupData(const char*)
   *   This will look in the given directory for the file "snapshot_blob.bin".
   * - InitializeExternalStartupDataFromFile(const char*)
   *   As above, but will directly use the given file name.
   * - Call SetSnapshotDataBlob.
   *   This will read the blobs from the given data structure and will
   *   not perform any file IO.
   */
  static void InitializeExternalStartupData(const char* directory_path);
  static void InitializeExternalStartupDataFromFile(const char* snapshot_blob);

  /**
   * Sets the v8::Platform to use. This should be invoked before V8 is
   * initialized.
   */
  static void InitializePlatform(Platform* platform);

  /**
   * Clears all references to the v8::Platform. This should be invoked after
   * V8 was disposed.
   */
  static void DisposePlatform();

#if defined(V8_ENABLE_SANDBOX)
  /**
   * Returns true if the sandbox is configured securely.
   *
   * If V8 cannot create a regular sandbox during initialization, for example
   * because not enough virtual address space can be reserved, it will instead
   * create a fallback sandbox that still allows it to function normally but
   * does not have the same security properties as a regular sandbox. This API
   * can be used to determine if such a fallback sandbox is being used, in
   * which case it will return false.
   */
  static bool IsSandboxConfiguredSecurely();

  /**
   * Provides access to the virtual address subspace backing the sandbox.
   *
   * This can be used to allocate pages inside the sandbox, for example to
   * obtain virtual memory for ArrayBuffer backing stores, which must be
   * located inside the sandbox.
   *
   * It should be assumed that an attacker can corrupt data inside the sandbox,
   * and so in particular the contents of pages allocagted in this virtual
   * address space, arbitrarily and concurrently. Due to this, it is
   * recommended to to only place pure data buffers in them.
   */
  static VirtualAddressSpace* GetSandboxAddressSpace();

  /**
   * Returns the size of the sandbox in bytes.
   *
   * This represents the size of the address space that V8 can directly address
   * and in which it allocates its objects.
   */
  static size_t GetSandboxSizeInBytes();

  /**
   * Returns the size of the address space reservation backing the sandbox.
   *
   * This may be larger than the sandbox (i.e. |GetSandboxSizeInBytes()|) due
   * to surrounding guard regions, or may be smaller than the sandbox in case a
   * fallback sandbox is being used, which will use a smaller virtual address
   * space reservation. In the latter case this will also be different from
   * |GetSandboxAddressSpace()->size()| as that will cover a larger part of the
   * address space than what has actually been reserved.
   */
  static size_t GetSandboxReservationSizeInBytes();
#endif  // V8_ENABLE_SANDBOX

  /**
   * Activate trap-based bounds checking for WebAssembly.
   *
   * \param use_v8_signal_handler Whether V8 should install its own signal
   * handler or rely on the embedder's.
   */
  static bool EnableWebAssemblyTrapHandler(bool use_v8_signal_handler);

#if defined(V8_OS_WIN)
  /**
   * On Win64, by default V8 does not emit unwinding data for jitted code,
   * which means the OS cannot walk the stack frames and the system Structured
   * Exception Handling (SEH) cannot unwind through V8-generated code:
   * https://code.google.com/p/v8/issues/detail?id=3598.
   *
   * This function allows embedders to register a custom exception handler for
   * exceptions in V8-generated code.
   */
  static void SetUnhandledExceptionCallback(
      UnhandledExceptionCallback callback);
#endif

  /**
   * Allows the host application to provide a callback that will be called when
   * v8 has encountered a fatal failure to allocate memory and is about to
   * terminate.
   */
  static void SetFatalMemoryErrorCallback(OOMErrorCallback callback);

  /**
   * Get statistics about the shared memory usage.
   */
  static void GetSharedMemoryStatistics(SharedMemoryStatistics* statistics);

 private:
  V8();

  enum BuildConfigurationFeatures {
    kPointerCompression = 1 << 0,
    k31BitSmis = 1 << 1,
    kSandbox = 1 << 2,
    kTargetOsIsAndroid = 1 << 3,
    kEnableChecks = 1 << 4,
  };

  /**
   * Checks that the embedder build configuration is compatible with
   * the V8 binary and if so initializes V8.
   */
  static bool Initialize(int build_config);

  friend class Context;
  template <class K, class V, class T>
  friend class PersistentValueMapBase;
};

}  // namespace v8

#endif  // INCLUDE_V8_INITIALIZATION_H_

Coverage Report

Created: 2025-10-31 09:06

Line	Count	Source
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-callbacks.h" // NOLINT(build/include_directory)
12		#include "v8-internal.h" // NOLINT(build/include_directory)
13		#include "v8-isolate.h" // NOLINT(build/include_directory)
14		#include "v8-platform.h" // NOLINT(build/include_directory)
15		#include "v8config.h" // NOLINT(build/include_directory)
16
17		// We reserve the V8_* prefix for macros defined in V8 public API and
18		// assume there are no name conflicts with the embedder's code.
19
20		/**
21		* The v8 JavaScript engine.
22		*/
23		namespace v8 {
24
25		class PageAllocator;
26		class Platform;
27		template <class K, class V, class T>
28		class PersistentValueMapBase;
29
30		/**
31		* EntropySource is used as a callback function when v8 needs a source
32		* of entropy.
33		*/
34		using EntropySource = bool ()(unsigned char buffer, size_t length);
35
36		/**
37		* ReturnAddressLocationResolver is used as a callback function when v8 is
38		* resolving the location of a return address on the stack. Profilers that
39		* change the return address on the stack can use this to resolve the stack
40		* location to wherever the profiler stashed the original return address.
41		*
42		* \param return_addr_location A location on stack where a machine
43		* return address resides.
44		* \returns Either return_addr_location, or else a pointer to the profiler's
45		* copy of the original return address.
46		*
47		* \note The resolver function must not cause garbage collection.
48		*/
49		using ReturnAddressLocationResolver =
50		uintptr_t (*)(uintptr_t return_addr_location);
51
52		using DcheckErrorCallback = void ()(const char file, int line,
53		const char* message);
54
55		using V8FatalErrorCallback = void ()(const char file, int line,
56		const char* message);
57
58		/**
59		* Container class for static utility functions.
60		*/
61		class V8_EXPORT V8 {
62		public:
63		/**
64		* Hand startup data to V8, in case the embedder has chosen to build
65		* V8 with external startup data.
66		*
67		* Note:
68		* - By default the startup data is linked into the V8 library, in which
69		* case this function is not meaningful.
70		* - If this needs to be called, it needs to be called before V8
71		* tries to make use of its built-ins.
72		* - To avoid unnecessary copies of data, V8 will point directly into the
73		* given data blob, so pretty please keep it around until V8 exit.
74		* - Compression of the startup blob might be useful, but needs to
75		* handled entirely on the embedders' side.
76		* - The call will abort if the data is invalid.
77		*/
78		static void SetSnapshotDataBlob(StartupData* startup_blob);
79
80		/** Set the callback to invoke in case of Dcheck failures. */
81		static void SetDcheckErrorHandler(DcheckErrorCallback that);
82
83		/** Set the callback to invoke in the case of CHECK failures or fatal
84		* errors. This is distinct from Isolate::SetFatalErrorHandler, which
85		* is invoked in response to API usage failures.
86		* */
87		static void SetFatalErrorHandler(V8FatalErrorCallback that);
88
89		/**
90		* Sets V8 flags from a string.
91		*/
92		static void SetFlagsFromString(const char* str);
93		static void SetFlagsFromString(const char* str, size_t length);
94
95		/**
96		* Sets V8 flags from the command line.
97		*/
98		static void SetFlagsFromCommandLine(int* argc, char** argv,
99		bool remove_flags);
100
101		/** Get the version string. */
102		static const char* GetVersion();
103
104		/**
105		* Initializes V8. This function needs to be called before the first Isolate
106		* is created. It always returns true.
107		*/
108	35	V8_INLINE static bool Initialize() {
109		#ifdef V8_TARGET_OS_ANDROID
110		const bool kV8TargetOsIsAndroid = true;
111		#else
112	35	const bool kV8TargetOsIsAndroid = false;
113	35	#endif
114
115		#ifdef V8_ENABLE_CHECKS
116		const bool kV8EnableChecks = true;
117		#else
118	35	const bool kV8EnableChecks = false;
119	35	#endif
120
121	35	const int kBuildConfiguration =
122	35	(internal::PointerCompressionIsEnabled() ? kPointerCompression : 0) \|
123	35	(internal::SmiValuesAre31Bits() ? k31BitSmis : 0) \|
124	35	(internal::SandboxIsEnabled() ? kSandbox : 0) \|
125	35	(kV8TargetOsIsAndroid ? kTargetOsIsAndroid : 0) \|
126	35	(kV8EnableChecks ? kEnableChecks : 0);
127	35	return Initialize(kBuildConfiguration);
128	35	}
129
130		/**
131		* Allows the host application to provide a callback which can be used
132		* as a source of entropy for random number generators.
133		*/
134		static void SetEntropySource(EntropySource source);
135
136		/**
137		* Allows the host application to provide a callback that allows v8 to
138		* cooperate with a profiler that rewrites return addresses on stack.
139		*/
140		static void SetReturnAddressLocationResolver(
141		ReturnAddressLocationResolver return_address_resolver);
142
143		/**
144		* Releases any resources used by v8 and stops any utility threads
145		* that may be running. Note that disposing v8 is permanent, it
146		* cannot be reinitialized.
147		*
148		* It should generally not be necessary to dispose v8 before exiting
149		* a process, this should happen automatically. It is only necessary
150		* to use if the process needs the resources taken up by v8.
151		*/
152		static bool Dispose();
153
154		/**
155		* Initialize the ICU library bundled with V8. The embedder should only
156		* invoke this method when using the bundled ICU. Returns true on success.
157		*
158		* If V8 was compiled with the ICU data in an external file, the location
159		* of the data file has to be provided.
160		*/
161		static bool InitializeICU(const char* icu_data_file = nullptr);
162
163		/**
164		* Initialize the ICU library bundled with V8. The embedder should only
165		* invoke this method when using the bundled ICU. If V8 was compiled with
166		* the ICU data in an external file and when the default location of that
167		* file should be used, a path to the executable must be provided.
168		* Returns true on success.
169		*
170		* The default is a file called icudtl.dat side-by-side with the executable.
171		*
172		* Optionally, the location of the data file can be provided to override the
173		* default.
174		*/
175		static bool InitializeICUDefaultLocation(const char* exec_path,
176		const char* icu_data_file = nullptr);
177
178		/**
179		* Initialize the external startup data. The embedder only needs to
180		* invoke this method when external startup data was enabled in a build.
181		*
182		* If V8 was compiled with the startup data in an external file, then
183		* V8 needs to be given those external files during startup. There are
184		* three ways to do this:
185		* - InitializeExternalStartupData(const char*)
186		* This will look in the given directory for the file "snapshot_blob.bin".
187		* - InitializeExternalStartupDataFromFile(const char*)
188		* As above, but will directly use the given file name.
189		* - Call SetSnapshotDataBlob.
190		* This will read the blobs from the given data structure and will
191		* not perform any file IO.
192		*/
193		static void InitializeExternalStartupData(const char* directory_path);
194		static void InitializeExternalStartupDataFromFile(const char* snapshot_blob);
195
196		/**
197		* Sets the v8::Platform to use. This should be invoked before V8 is
198		* initialized.
199		*/
200		static void InitializePlatform(Platform* platform);
201
202		/**
203		* Clears all references to the v8::Platform. This should be invoked after
204		* V8 was disposed.
205		*/
206		static void DisposePlatform();
207
208		#if defined(V8_ENABLE_SANDBOX)
209		/**
210		* Returns true if the sandbox is configured securely.
211		*
212		* If V8 cannot create a regular sandbox during initialization, for example
213		* because not enough virtual address space can be reserved, it will instead
214		* create a fallback sandbox that still allows it to function normally but
215		* does not have the same security properties as a regular sandbox. This API
216		* can be used to determine if such a fallback sandbox is being used, in
217		* which case it will return false.
218		*/
219		static bool IsSandboxConfiguredSecurely();
220
221		/**
222		* Provides access to the virtual address subspace backing the sandbox.
223		*
224		* This can be used to allocate pages inside the sandbox, for example to
225		* obtain virtual memory for ArrayBuffer backing stores, which must be
226		* located inside the sandbox.
227		*
228		* It should be assumed that an attacker can corrupt data inside the sandbox,
229		* and so in particular the contents of pages allocagted in this virtual
230		* address space, arbitrarily and concurrently. Due to this, it is
231		* recommended to to only place pure data buffers in them.
232		*/
233		static VirtualAddressSpace* GetSandboxAddressSpace();
234
235		/**
236		* Returns the size of the sandbox in bytes.
237		*
238		* This represents the size of the address space that V8 can directly address
239		* and in which it allocates its objects.
240		*/
241		static size_t GetSandboxSizeInBytes();
242
243		/**
244		* Returns the size of the address space reservation backing the sandbox.
245		*
246		* This may be larger than the sandbox (i.e. \|GetSandboxSizeInBytes()\|) due
247		* to surrounding guard regions, or may be smaller than the sandbox in case a
248		* fallback sandbox is being used, which will use a smaller virtual address
249		* space reservation. In the latter case this will also be different from
250		* \|GetSandboxAddressSpace()->size()\| as that will cover a larger part of the
251		* address space than what has actually been reserved.
252		*/
253		static size_t GetSandboxReservationSizeInBytes();
254		#endif // V8_ENABLE_SANDBOX
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(
275		UnhandledExceptionCallback callback);
276		#endif
277
278		/**
279		* Allows the host application to provide a callback that will be called when
280		* v8 has encountered a fatal failure to allocate memory and is about to
281		* terminate.
282		*/
283		static void SetFatalMemoryErrorCallback(OOMErrorCallback callback);
284
285		/**
286		* Get statistics about the shared memory usage.
287		*/
288		static void GetSharedMemoryStatistics(SharedMemoryStatistics* statistics);
289
290		private:
291		V8();
292
293		enum BuildConfigurationFeatures {
294		kPointerCompression = 1 << 0,
295		k31BitSmis = 1 << 1,
296		kSandbox = 1 << 2,
297		kTargetOsIsAndroid = 1 << 3,
298		kEnableChecks = 1 << 4,
299		};
300
301		/**
302		* Checks that the embedder build configuration is compatible with
303		* the V8 binary and if so initializes V8.
304		*/
305		static bool Initialize(int build_config);
306
307		friend class Context;
308		template <class K, class V, class T>
309		friend class PersistentValueMapBase;
310		};
311
312		} // namespace v8
313
314		#endif // INCLUDE_V8_INITIALIZATION_H_