EIC code displayed by LXR master/​include/​node/​v8-callbacks.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2026-09-25 09:17:57

 // 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_ISOLATE_CALLBACKS_H_
 #define INCLUDE_V8_ISOLATE_CALLBACKS_H_
 
 #include <stddef.h>
 
 #include <functional>
 #include <string>
 
 #include "cppgc/common.h"
 #include "v8-data.h"          // NOLINT(build/include_directory)
 #include "v8-local-handle.h"  // NOLINT(build/include_directory)
 #include "v8-promise.h"       // NOLINT(build/include_directory)
 #include "v8config.h"         // NOLINT(build/include_directory)
 
 #if defined(V8_OS_WIN)
 struct _EXCEPTION_POINTERS;
 #endif
 
 namespace v8 {
 
 template <typename T>
 class FunctionCallbackInfo;
 class Isolate;
 class Message;
 class Module;
 class Object;
 class Promise;
 class ScriptOrModule;
 class String;
 class UnboundScript;
 class Value;
 
 /**
  * A JIT code event is issued each time code is added, moved or removed.
  *
  * \note removal events are not currently issued.
  */
 struct JitCodeEvent {
   enum EventType {
     CODE_ADDED,
     CODE_MOVED,
     CODE_REMOVED,
     CODE_ADD_LINE_POS_INFO,
     CODE_START_LINE_INFO_RECORDING,
     CODE_END_LINE_INFO_RECORDING
   };
   // Definition of the code position type. The "POSITION" type means the place
   // in the source code which are of interest when making stack traces to
   // pin-point the source location of a stack frame as close as possible.
   // The "STATEMENT_POSITION" means the place at the beginning of each
   // statement, and is used to indicate possible break locations.
   enum PositionType { POSITION, STATEMENT_POSITION };
 
   // There are three different kinds of CodeType, one for JIT code generated
   // by the optimizing compiler, one for byte code generated for the
   // interpreter, and one for code generated from Wasm. For JIT_CODE and
   // WASM_CODE, |code_start| points to the beginning of jitted assembly code,
   // while for BYTE_CODE events, |code_start| points to the first bytecode of
   // the interpreted function.
   enum CodeType { BYTE_CODE, JIT_CODE, WASM_CODE };
 
   // Type of event.
   EventType type;
   CodeType code_type;
   // Start of the instructions.
   void* code_start;
   // Size of the instructions.
   size_t code_len;
   // Script info for CODE_ADDED event.
   Local<UnboundScript> script;
   // User-defined data for *_LINE_INFO_* event. It's used to hold the source
   // code line information which is returned from the
   // CODE_START_LINE_INFO_RECORDING event. And it's passed to subsequent
   // CODE_ADD_LINE_POS_INFO and CODE_END_LINE_INFO_RECORDING events.
   void* user_data;
 
   struct name_t {
     // Name of the object associated with the code, note that the string is not
     // zero-terminated.
     const char* str;
     // Number of chars in str.
     size_t len;
   };
 
   struct line_info_t {
     // PC offset
     size_t offset;
     // Code position
     size_t pos;
     // The position type.
     PositionType position_type;
   };
 
   struct wasm_source_info_t {
     // Source file name.
     const char* filename;
     // Length of filename.
     size_t filename_size;
     // Line number table, which maps offsets of JITted code to line numbers of
     // source file.
     const line_info_t* line_number_table;
     // Number of entries in the line number table.
     size_t line_number_table_size;
   };
 
   wasm_source_info_t* wasm_source_info = nullptr;
 
   union {
     // Only valid for CODE_ADDED.
     struct name_t name;
 
     // Only valid for CODE_ADD_LINE_POS_INFO
     struct line_info_t line_info;
 
     // New location of instructions. Only valid for CODE_MOVED.
     void* new_code_start;
   };
 
   Isolate* isolate;
 };
 
 /**
  * Option flags passed to the SetJitCodeEventHandler function.
  */
 enum JitCodeEventOptions {
   kJitCodeEventDefault = 0,
   // Generate callbacks for already existent code.
   kJitCodeEventEnumExisting = 1,
 
   kLastJitCodeEventOption = kJitCodeEventEnumExisting
 };
 
 /**
  * Callback function passed to SetJitCodeEventHandler.
  *
  * \param event code add, move or removal event.
  */
 using JitCodeEventHandler = void (*)(const JitCodeEvent* event);
 
 // --- Garbage Collection Callbacks ---
 
 /**
  * Applications can register callback functions which will be called before and
  * after certain garbage collection operations.  Allocations are not allowed in
  * the callback functions, you therefore cannot manipulate objects (set or
  * delete properties for example) since it is possible such operations will
  * result in the allocation of objects.
  * TODO(v8:12612): Deprecate kGCTypeMinorMarkSweep after updating blink.
  */
 enum GCType {
   kGCTypeScavenge = 1 << 0,
   kGCTypeMinorMarkSweep = 1 << 1,
   kGCTypeMarkSweepCompact = 1 << 2,
   kGCTypeIncrementalMarking = 1 << 3,
   kGCTypeProcessWeakCallbacks = 1 << 4,
   kGCTypeAll = kGCTypeScavenge | kGCTypeMinorMarkSweep |
                kGCTypeMarkSweepCompact | kGCTypeIncrementalMarking |
                kGCTypeProcessWeakCallbacks
 };
 
 /**
  * GCCallbackFlags is used to notify additional information about the GC
  * callback.
  *   - kGCCallbackFlagConstructRetainedObjectInfos: The GC callback is for
  *     constructing retained object infos.
  *   - kGCCallbackFlagForced: The GC callback is for a forced GC for testing.
  *   - kGCCallbackFlagSynchronousPhantomCallbackProcessing: The GC callback
  *     is called synchronously without getting posted to an idle task.
  *   - kGCCallbackFlagCollectAllAvailableGarbage: The GC callback is called
  *     in a phase where V8 is trying to collect all available garbage
  *     (e.g., handling a low memory notification).
  *   - kGCCallbackScheduleIdleGarbageCollection: The GC callback is called to
  *     trigger an idle garbage collection.
  */
 enum GCCallbackFlags {
   kNoGCCallbackFlags = 0,
   kGCCallbackFlagConstructRetainedObjectInfos = 1 << 1,
   kGCCallbackFlagForced = 1 << 2,
   kGCCallbackFlagSynchronousPhantomCallbackProcessing = 1 << 3,
   kGCCallbackFlagCollectAllAvailableGarbage = 1 << 4,
   kGCCallbackFlagCollectAllExternalMemory = 1 << 5,
   kGCCallbackScheduleIdleGarbageCollection = 1 << 6,
   kGCCallbackFlagLastResort = 1 << 7,
 };
 
 using GCCallback = void (*)(GCType type, GCCallbackFlags flags);
 
 using InterruptCallback = void (*)(Isolate* isolate, void* data);
 
 using PrintCurrentStackTraceFilterCallback =
     bool (*)(Isolate* isolate, Local<String> script_name);
 
 /**
  * This callback is invoked when the heap size is close to the heap limit and
  * V8 is likely to abort with out-of-memory error.
  * The callback can extend the heap limit by returning a value that is greater
  * than the current_heap_limit. The initial heap limit is the limit that was
  * set after heap setup.
  */
 using NearHeapLimitCallback = size_t (*)(void* data, size_t current_heap_limit,
                                          size_t initial_heap_limit);
 
 /**
  * Callback function passed to SetUnhandledExceptionCallback.
  */
 #if defined(V8_OS_WIN)
 using UnhandledExceptionCallback =
     int (*)(_EXCEPTION_POINTERS* exception_pointers);
 #endif
 
 // --- Counters Callbacks ---
 
 using CounterLookupCallback = int* (*)(const char* name);
 
 using CreateHistogramCallback = void* (*)(const char* name, int min, int max,
                                           size_t buckets);
 
 using AddHistogramSampleCallback = void (*)(void* histogram, int sample);
 
 // --- Exceptions ---
 
 using FatalErrorCallback = void (*)(const char* location, const char* message);
 
 struct OOMDetails {
   bool is_heap_oom = false;
   const char* detail = nullptr;
 };
 
 using OOMErrorCallback = void (*)(const char* location,
                                   const OOMDetails& details);
 
 using OOMErrorCallbackWithData = void (*)(const char* location,
                                           const OOMDetails& details,
                                           void* data);
 
 using MessageCallback = void (*)(Local<Message> message, Local<Value> data);
 
 // --- Tracing ---
 
 enum LogEventStatus : int { kStart = 0, kEnd = 1, kLog = 2 };
 using LogEventCallback = void (*)(const char* name,
                                   int /* LogEventStatus */ status);
 
 // --- Crashkeys Callback ---
 enum class CrashKeyId {
   kIsolateAddress,
   kReadonlySpaceFirstPageAddress,
   kMapSpaceFirstPageAddress V8_ENUM_DEPRECATE_SOON("Map space got removed"),
   kOldSpaceFirstPageAddress,
   kCodeRangeBaseAddress,
   kCodeSpaceFirstPageAddress,
   kDumpType,
   kSnapshotChecksumCalculated,
   kSnapshotChecksumExpected,
 };
 
 using AddCrashKeyCallback = void (*)(CrashKeyId id, const std::string& value);
 
 // --- CrashKeyString Callbacks ---
 using CrashKey = void*;
 enum class CrashKeySize { Size32, Size64, Size256, Size1024 };
 
 using AllocateCrashKeyStringCallback =
     std::function<CrashKey(const char key[], CrashKeySize size)>;
 using SetCrashKeyStringCallback =
     std::function<void(CrashKey key, const std::string_view value)>;
 
 // --- Enter/Leave Script Callback ---
 using BeforeCallEnteredCallback = void (*)(Isolate*);
 using CallCompletedCallback = void (*)(Isolate*);
 
 // --- Modify Code Generation From Strings Callback ---
 struct ModifyCodeGenerationFromStringsResult {
   // If true, proceed with the codegen algorithm. Otherwise, block it.
   bool codegen_allowed = false;
   // Overwrite the original source with this string, if present.
   // Use the original source if empty.
   // This field is considered only if codegen_allowed is true.
   MaybeLocal<String> modified_source;
 };
 
 /**
  * Callback to check if codegen is allowed from a source object, and convert
  * the source to string if necessary. See: ModifyCodeGenerationFromStrings.
  */
 using ModifyCodeGenerationFromStringsCallback =
     ModifyCodeGenerationFromStringsResult (*)(Local<Context> context,
                                               Local<Value> source);
 using ModifyCodeGenerationFromStringsCallback2 =
     ModifyCodeGenerationFromStringsResult (*)(Local<Context> context,
                                               Local<Value> source,
                                               bool is_code_like);
 
 // --- Failed Access Check Callback ---
 
 /**
  * Access type specification.
  */
 enum AccessType {
   ACCESS_GET,
   ACCESS_SET,
   ACCESS_HAS,
   ACCESS_DELETE,
   ACCESS_KEYS
 };
 
 using FailedAccessCheckCallback = void (*)(Local<Object> target,
                                            AccessType type, Local<Value> data);
 
 // --- WebAssembly compilation callbacks ---
 using ExtensionCallback = bool (*)(const FunctionCallbackInfo<Value>&);
 
 using AllowWasmCodeGenerationCallback = bool (*)(Local<Context> context,
                                                  Local<String> source);
 
 // --- Callback for APIs defined on v8-supported objects, but implemented
 // by the embedder. Example: WebAssembly.{compile|instantiate}Streaming ---
 using ApiImplementationCallback = void (*)(const FunctionCallbackInfo<Value>&);
 
 // --- Callback for WebAssembly.compileStreaming ---
 using WasmStreamingCallback = void (*)(const FunctionCallbackInfo<Value>&);
 
 enum class WasmAsyncSuccess { kSuccess, kFail };
 
 // --- Callback called when async WebAssembly operations finish ---
 using WasmAsyncResolvePromiseCallback = void (*)(
     Isolate* isolate, Local<Context> context, Local<Promise::Resolver> resolver,
     Local<Value> result, WasmAsyncSuccess success);
 
 // --- Callback for loading source map file for Wasm profiling support
 using WasmLoadSourceMapCallback = Local<String> (*)(Isolate* isolate,
                                                     const char* name);
 
 // --- Callback for checking if WebAssembly Custom Descriptors are enabled ---
 using WasmCustomDescriptorsEnabledCallback = bool (*)(Local<Context> context);
 
 // --- Callback for checking if the SharedArrayBuffer constructor is enabled ---
 using SharedArrayBufferConstructorEnabledCallback =
     bool (*)(Local<Context> context);
 
 /**
  * Import phases in import requests.
  */
 enum class ModuleImportPhase {
   kSource,
   kDefer,
   kEvaluation,
 };
 
 /**
  * HostImportModuleDynamicallyCallback is called when we
  * require the embedder to load a module. This is used as part of the dynamic
  * import syntax.
  *
  * The referrer contains metadata about the script/module that calls
  * import.
  *
  * The specifier is the name of the module that should be imported.
  *
  * The import_attributes are import attributes for this request in the form:
  * [key1, value1, key2, value2, ...] where the keys and values are of type
  * v8::String. Note, unlike the FixedArray passed to ResolveModuleCallback and
  * returned from ModuleRequest::GetImportAttributes(), this array does not
  * contain the source Locations of the attributes.
  *
  * The embedder must compile, instantiate, evaluate the Module, and
  * obtain its namespace object.
  *
  * The Promise returned from this function is forwarded to userland
  * JavaScript. The embedder must resolve this promise with the module
  * namespace object. In case of an exception, the embedder must reject
  * this promise with the exception. If the promise creation itself
  * fails (e.g. due to stack overflow), the embedder must propagate
  * that exception by returning an empty MaybeLocal.
  */
 using HostImportModuleDynamicallyCallback = MaybeLocal<Promise> (*)(
     Local<Context> context, Local<Data> host_defined_options,
     Local<Value> resource_name, Local<String> specifier,
     Local<FixedArray> import_attributes);
 
 /**
  * HostImportModuleWithPhaseDynamicallyCallback is called when we
  * require the embedder to load a module with a specific phase. This is used
  * as part of the dynamic import syntax.
  *
  * The referrer contains metadata about the script/module that calls
  * import.
  *
  * The specifier is the name of the module that should be imported.
  *
  * The phase is the phase of the import requested.
  *
  * The import_attributes are import attributes for this request in the form:
  * [key1, value1, key2, value2, ...] where the keys and values are of type
  * v8::String. Note, unlike the FixedArray passed to ResolveModuleCallback and
  * returned from ModuleRequest::GetImportAttributes(), this array does not
  * contain the source Locations of the attributes.
  *
  * The Promise returned from this function is forwarded to userland
  * JavaScript. The embedder must resolve this promise according to the phase
  * requested:
  * - For ModuleImportPhase::kSource, the promise must be resolved with a
  *   compiled ModuleSource object, or rejected with a SyntaxError if the
  *   module does not support source representation.
  * - For ModuleImportPhase::kEvaluation, the promise must be resolved with a
  *   ModuleNamespace object of a module that has been compiled, instantiated,
  *   and evaluated.
  *
  * In case of an exception, the embedder must reject this promise with the
  * exception. If the promise creation itself fails (e.g. due to stack
  * overflow), the embedder must propagate that exception by returning an empty
  * MaybeLocal.
  *
  * This callback is still experimental and is only invoked for source phase
  * imports.
  */
 using HostImportModuleWithPhaseDynamicallyCallback = MaybeLocal<Promise> (*)(
     Local<Context> context, Local<Data> host_defined_options,
     Local<Value> resource_name, Local<String> specifier,
     ModuleImportPhase phase, Local<FixedArray> import_attributes);
 
 /**
  * Callback for requesting a compile hint for a function from the embedder. The
  * first parameter is the position of the function in source code and the second
  * parameter is embedder data to be passed back.
  */
 using CompileHintCallback = bool (*)(int, void*);
 
 /**
  * HostInitializeImportMetaObjectCallback is called the first time import.meta
  * is accessed for a module. Subsequent access will reuse the same value.
  *
  * The method combines two implementation-defined abstract operations into one:
  * HostGetImportMetaProperties and HostFinalizeImportMeta.
  *
  * The embedder should use v8::Object::CreateDataProperty to add properties on
  * the meta object.
  */
 using HostInitializeImportMetaObjectCallback = void (*)(Local<Context> context,
                                                         Local<Module> module,
                                                         Local<Object> meta);
 
 /**
  * HostCreateShadowRealmContextCallback is called each time a ShadowRealm is
  * being constructed in the initiator_context.
  *
  * The method combines Context creation and implementation defined abstract
  * operation HostInitializeShadowRealm into one.
  *
  * The embedder should use v8::Context::New or v8::Context:NewFromSnapshot to
  * create a new context. If the creation fails, the embedder must propagate
  * that exception by returning an empty MaybeLocal.
  */
 using HostCreateShadowRealmContextCallback =
     MaybeLocal<Context> (*)(Local<Context> initiator_context);
 
 /**
  * IsJSApiWrapperNativeErrorCallback is called on an JSApiWrapper object to
  * determine if Error.isError should return true or false. For instance, in an
  * HTML embedder, DOMExceptions return true when passed to Error.isError.
  */
 using IsJSApiWrapperNativeErrorCallback = bool (*)(Isolate* isolate,
                                                    Local<Object> obj);
 
 /**
  * PrepareStackTraceCallback is called when the stack property of an error is
  * first accessed. The return value will be used as the stack value. If this
  * callback is registed, the |Error.prepareStackTrace| API will be disabled.
  * |sites| is an array of call sites, specified in
  * https://v8.dev/docs/stack-trace-api
  */
 using PrepareStackTraceCallback = MaybeLocal<Value> (*)(Local<Context> context,
                                                         Local<Value> error,
                                                         Local<Array> sites);
 
 #if defined(V8_OS_WIN)
 /**
  * Callback to selectively enable ETW tracing based on the document URL.
  * Implemented by the embedder, it should never call back into V8.
  *
  * Windows allows passing additional data to the ETW EnableCallback:
  * https://learn.microsoft.com/en-us/windows/win32/api/evntprov/nc-evntprov-penablecallback
  *
  * This data can be configured in a WPR (Windows Performance Recorder)
  * profile, adding a CustomFilter to an EventProvider like the following:
  *
  * <EventProvider Id=".." Name="57277741-3638-4A4B-BDBA-0AC6E45DA56C" Level="5">
  *   <CustomFilter Type="0x80000000" Value="AQABAAAAAAA..." />
  * </EventProvider>
  *
  * Where:
  * - Name="57277741-3638-4A4B-BDBA-0AC6E45DA56C" is the GUID of the V8
  *     ETW provider, (see src/libplatform/etw/etw-provider-win.h),
  * - Type="0x80000000" is EVENT_FILTER_TYPE_SCHEMATIZED,
  * - Value="AQABAAAAAA..." is a base64-encoded byte array that is
  *     base64-decoded by Windows and passed to the ETW enable callback in
  *     the 'PEVENT_FILTER_DESCRIPTOR FilterData' argument; see:
  * https://learn.microsoft.com/en-us/windows/win32/api/evntprov/ns-evntprov-event_filter_descriptor.
  *
  * This array contains a struct EVENT_FILTER_HEADER followed by a
  * variable length payload, and as payload we pass a string in JSON format,
  * with a list of regular expressions that should match the document URL
  * in order to enable ETW tracing:
  *   {
  *     "version": "2.0",
  *     "filtered_urls": [
  *         "https:\/\/.*\.chromium\.org\/.*", "https://v8.dev/";, "..."
  *     ],
  *     "trace_interpreter_frames": true
  *  }
  */
 
 using FilterETWSessionByURLCallback =
     bool (*)(Local<Context> context, const std::string& etw_filter_payload);
 
 struct FilterETWSessionByURLResult {
   // If true, enable ETW tracing for the current isolate.
   bool enable_etw_tracing;
 
   // If true, also enables ETW tracing for interpreter stack frames.
   bool trace_interpreter_frames;
 };
 using FilterETWSessionByURL2Callback = FilterETWSessionByURLResult (*)(
     Local<Context> context, const std::string& etw_filter_payload);
 #endif  // V8_OS_WIN
 
 }  // namespace v8
 
 #endif  // INCLUDE_V8_ISOLATE_CALLBACKS_H_

This page was automatically generated by the 2.3.7 LXR engine. The LXR team