v8-callbacks.h

Go to the documentation of this file.

// 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 <string_view>
 
#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 {
 
class ArrayBuffer;
template <typename T>
class FunctionCallbackInfo;
class Isolate;
class Message;
class Module;
class Object;
class Promise;
class ScriptOrModule;
class String;
class UnboundScript;
class Value;
 
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;
};
 
enum JitCodeEventOptions {
  kJitCodeEventDefault = 0,
  // Generate callbacks for already existent code.
  kJitCodeEventEnumExisting = 1,
 
  kLastJitCodeEventOption = kJitCodeEventEnumExisting
};
 
using JitCodeEventHandler = void (*)(const JitCodeEvent* event);
 
// --- Garbage Collection Callbacks ---
 
enum GCType {
  kGCTypeScavenge = 1 << 0,
  kGCTypeMinorMarkSweep = 1 << 1,
  kGCTypeMarkSweepCompact = 1 << 2,
  kGCTypeIncrementalMarking = 1 << 3,
  kGCTypeProcessWeakCallbacks = 1 << 4,
  kGCTypeAll = kGCTypeScavenge | kGCTypeMinorMarkSweep |
               kGCTypeMarkSweepCompact | kGCTypeIncrementalMarking |
               kGCTypeProcessWeakCallbacks
};
 
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);
 
using NearHeapLimitCallback = size_t (*)(void* data, size_t current_heap_limit,
                                         size_t initial_heap_limit);
 
#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);
 
// --- CrashKey Callbacks ---
using CrashKey = void*;
enum class CrashKeySize { Size32, Size64, Size256, Size1024 };
 
// Allocates a new crash key with the given `key` name and maximum value `size`.
// Embedders do not need to deduplicate by `key` name: V8 caches the returned
// `CrashKey` handle in static storage whenever a key may be updated multiple
// times. Returns nullptr if crash keys are not supported or initialized.
using AllocateCrashKeyCallback = CrashKey (*)(const char key[],
                                              CrashKeySize size);
using SetCrashKeyCallback = void (*)(CrashKey key, std::string_view value);
 
// Deprecated: use AllocateCrashKeyCallback / SetCrashKeyCallback with
// V8::SetCrashKeyCallbacks instead.
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;
};
 
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 ---
 
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 WasmModuleCallback = bool (*)(Isolate* isolate, Local<Value> source);
using WasmInstanceCallback = bool (*)(Isolate* isolate, Local<Value> source);
 
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);
 
// --- Callback for getting high resolution timestamps in Temporal ---
using TemporalHostSystemUTCEpochNanosecondsCallback =
    int64_t (*)(Local<Context> context);
 
enum class ModuleImportPhase {
  kSource,
  kDefer,
  kEvaluation,
};
 
using HostImportModuleDynamicallyCallback = MaybeLocal<Promise> (*)(
    Local<Context> context, Local<Data> host_defined_options,
    Local<Value> resource_name, Local<String> specifier,
    Local<FixedArray> import_attributes);
 
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);
 
using CompileHintCallback = bool (*)(int, void*);
 
using HostInitializeImportMetaObjectCallback = void (*)(Local<Context> context,
                                                        Local<Module> module,
                                                        Local<Object> meta);
 
using HostCreateShadowRealmContextCallback =
    MaybeLocal<Context> (*)(Local<Context> initiator_context);
 
using IsJSApiWrapperNativeErrorCallback = bool (*)(Isolate* isolate,
                                                   Local<Object> obj);
 
using ArrayBufferDetachCallback = void (*)(Isolate* isolate,
                                           Local<ArrayBuffer> buffer);
 
using PrepareStackTraceCallback = MaybeLocal<Value> (*)(Local<Context> context,
                                                        Local<Value> error,
                                                        Local<Array> sites);
 
using DynamicScriptCompiledFromEmbedderCallback =
    void (*)(Local<Context> context, int script_id);
 
#if defined(V8_OS_WIN)
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_