v8  10.1.124 (node 18.2.0)
V8 is Google's open source JavaScript engine
v8-callbacks.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_ISOLATE_CALLBACKS_H_
6 #define INCLUDE_V8_ISOLATE_CALLBACKS_H_
7 
8 #include <stddef.h>
9 
10 #include <string>
11 
12 #include "cppgc/common.h"
13 #include "v8-data.h" // NOLINT(build/include_directory)
14 #include "v8-local-handle.h" // NOLINT(build/include_directory)
15 #include "v8config.h" // NOLINT(build/include_directory)
16 
17 #if defined(V8_OS_WIN)
18 struct _EXCEPTION_POINTERS;
19 #endif
20 
21 namespace v8 {
22 
23 template <typename T>
25 class Isolate;
26 class Message;
27 class Module;
28 class Object;
29 class Promise;
30 class ScriptOrModule;
31 class String;
32 class UnboundScript;
33 class Value;
34 
35 /**
36  * A JIT code event is issued each time code is added, moved or removed.
37  *
38  * \note removal events are not currently issued.
39  */
40 struct JitCodeEvent {
41  enum EventType {
48  };
49  // Definition of the code position type. The "POSITION" type means the place
50  // in the source code which are of interest when making stack traces to
51  // pin-point the source location of a stack frame as close as possible.
52  // The "STATEMENT_POSITION" means the place at the beginning of each
53  // statement, and is used to indicate possible break locations.
55 
56  // There are three different kinds of CodeType, one for JIT code generated
57  // by the optimizing compiler, one for byte code generated for the
58  // interpreter, and one for code generated from Wasm. For JIT_CODE and
59  // WASM_CODE, |code_start| points to the beginning of jitted assembly code,
60  // while for BYTE_CODE events, |code_start| points to the first bytecode of
61  // the interpreted function.
63 
64  // Type of event.
67  // Start of the instructions.
68  void* code_start;
69  // Size of the instructions.
70  size_t code_len;
71  // Script info for CODE_ADDED event.
73  // User-defined data for *_LINE_INFO_* event. It's used to hold the source
74  // code line information which is returned from the
75  // CODE_START_LINE_INFO_RECORDING event. And it's passed to subsequent
76  // CODE_ADD_LINE_POS_INFO and CODE_END_LINE_INFO_RECORDING events.
77  void* user_data;
78 
79  struct name_t {
80  // Name of the object associated with the code, note that the string is not
81  // zero-terminated.
82  const char* str;
83  // Number of chars in str.
84  size_t len;
85  };
86 
87  struct line_info_t {
88  // PC offset
89  size_t offset;
90  // Code position
91  size_t pos;
92  // The position type.
94  };
95 
97  // Source file name.
98  const char* filename;
99  // Length of filename.
101  // Line number table, which maps offsets of JITted code to line numbers of
102  // source file.
104  // Number of entries in the line number table.
106  };
107 
109 
110  union {
111  // Only valid for CODE_ADDED.
112  struct name_t name;
113 
114  // Only valid for CODE_ADD_LINE_POS_INFO
115  struct line_info_t line_info;
116 
117  // New location of instructions. Only valid for CODE_MOVED.
119  };
120 
122 };
123 
124 /**
125  * Option flags passed to the SetJitCodeEventHandler function.
126  */
129  // Generate callbacks for already existent code.
131 };
132 
133 /**
134  * Callback function passed to SetJitCodeEventHandler.
135  *
136  * \param event code add, move or removal event.
137  */
138 using JitCodeEventHandler = void (*)(const JitCodeEvent* event);
139 
140 // --- Garbage Collection Callbacks ---
141 
142 /**
143  * Applications can register callback functions which will be called before and
144  * after certain garbage collection operations. Allocations are not allowed in
145  * the callback functions, you therefore cannot manipulate objects (set or
146  * delete properties for example) since it is possible such operations will
147  * result in the allocation of objects.
148  */
149 enum GCType {
150  kGCTypeScavenge = 1 << 0,
158 };
159 
160 /**
161  * GCCallbackFlags is used to notify additional information about the GC
162  * callback.
163  * - kGCCallbackFlagConstructRetainedObjectInfos: The GC callback is for
164  * constructing retained object infos.
165  * - kGCCallbackFlagForced: The GC callback is for a forced GC for testing.
166  * - kGCCallbackFlagSynchronousPhantomCallbackProcessing: The GC callback
167  * is called synchronously without getting posted to an idle task.
168  * - kGCCallbackFlagCollectAllAvailableGarbage: The GC callback is called
169  * in a phase where V8 is trying to collect all available garbage
170  * (e.g., handling a low memory notification).
171  * - kGCCallbackScheduleIdleGarbageCollection: The GC callback is called to
172  * trigger an idle garbage collection.
173  */
182 };
183 
184 using GCCallback = void (*)(GCType type, GCCallbackFlags flags);
185 
186 using InterruptCallback = void (*)(Isolate* isolate, void* data);
187 
188 /**
189  * This callback is invoked when the heap size is close to the heap limit and
190  * V8 is likely to abort with out-of-memory error.
191  * The callback can extend the heap limit by returning a value that is greater
192  * than the current_heap_limit. The initial heap limit is the limit that was
193  * set after heap setup.
194  */
195 using NearHeapLimitCallback = size_t (*)(void* data, size_t current_heap_limit,
196  size_t initial_heap_limit);
197 
198 /**
199  * Callback function passed to SetUnhandledExceptionCallback.
200  */
201 #if defined(V8_OS_WIN)
204 #endif
205 
206 // --- Counters Callbacks ---
207 
208 using CounterLookupCallback = int* (*)(const char* name);
209 
210 using CreateHistogramCallback = void* (*)(const char* name, int min, int max,
211  size_t buckets);
212 
213 using AddHistogramSampleCallback = void (*)(void* histogram, int sample);
214 
215 // --- Exceptions ---
216 
217 using FatalErrorCallback = void (*)(const char* location, const char* message);
218 
219 using OOMErrorCallback = void (*)(const char* location, bool is_heap_oom);
220 
221 using MessageCallback = void (*)(Local<Message> message, Local<Value> data);
222 
223 // --- Tracing ---
224 
225 enum LogEventStatus : int { kStart = 0, kEnd = 1, kStamp = 2 };
226 using LogEventCallback = void (*)(const char* name,
227  int /* LogEventStatus */ status);
228 
229 // --- Crashkeys Callback ---
230 enum class CrashKeyId {
235  kDumpType,
236 };
237 
238 using AddCrashKeyCallback = void (*)(CrashKeyId id, const std::string& value);
239 
240 // --- Enter/Leave Script Callback ---
241 using BeforeCallEnteredCallback = void (*)(Isolate*);
242 using CallCompletedCallback = void (*)(Isolate*);
243 
244 // --- AllowCodeGenerationFromStrings callbacks ---
245 
246 /**
247  * Callback to check if code generation from strings is allowed. See
248  * Context::AllowCodeGenerationFromStrings.
249  */
250 using AllowCodeGenerationFromStringsCallback = bool (*)(Local<Context> context,
251  Local<String> source);
252 
254  // If true, proceed with the codegen algorithm. Otherwise, block it.
255  bool codegen_allowed = false;
256  // Overwrite the original source with this string, if present.
257  // Use the original source if empty.
258  // This field is considered only if codegen_allowed is true.
260 };
261 
262 /**
263  * Access type specification.
264  */
271 };
272 
273 // --- Failed Access Check Callback ---
274 
275 using FailedAccessCheckCallback = void (*)(Local<Object> target,
276  AccessType type, Local<Value> data);
277 
278 /**
279  * Callback to check if codegen is allowed from a source object, and convert
280  * the source to string if necessary. See: ModifyCodeGenerationFromStrings.
281  */
282 using ModifyCodeGenerationFromStringsCallback =
284  Local<Value> source);
285 using ModifyCodeGenerationFromStringsCallback2 =
287  Local<Value> source,
288  bool is_code_like);
289 
290 // --- WebAssembly compilation callbacks ---
291 using ExtensionCallback = bool (*)(const FunctionCallbackInfo<Value>&);
292 
293 using AllowWasmCodeGenerationCallback = bool (*)(Local<Context> context,
294  Local<String> source);
295 
296 // --- Callback for APIs defined on v8-supported objects, but implemented
297 // by the embedder. Example: WebAssembly.{compile|instantiate}Streaming ---
298 using ApiImplementationCallback = void (*)(const FunctionCallbackInfo<Value>&);
299 
300 // --- Callback for WebAssembly.compileStreaming ---
301 using WasmStreamingCallback = void (*)(const FunctionCallbackInfo<Value>&);
302 
303 // --- Callback for loading source map file for Wasm profiling support
304 using WasmLoadSourceMapCallback = Local<String> (*)(Isolate* isolate,
305  const char* name);
306 
307 // --- Callback for checking if WebAssembly Simd is enabled ---
308 using WasmSimdEnabledCallback = bool (*)(Local<Context> context);
309 
310 // --- Callback for checking if WebAssembly exceptions are enabled ---
311 using WasmExceptionsEnabledCallback = bool (*)(Local<Context> context);
312 
313 // --- Callback for checking if WebAssembly dynamic tiering is enabled ---
314 using WasmDynamicTieringEnabledCallback = bool (*)(Local<Context> context);
315 
316 // --- Callback for checking if the SharedArrayBuffer constructor is enabled ---
317 using SharedArrayBufferConstructorEnabledCallback =
318  bool (*)(Local<Context> context);
319 
320 /**
321  * HostImportModuleDynamicallyCallback is called when we
322  * require the embedder to load a module. This is used as part of the dynamic
323  * import syntax.
324  *
325  * The referrer contains metadata about the script/module that calls
326  * import.
327  *
328  * The specifier is the name of the module that should be imported.
329  *
330  * The import_assertions are import assertions for this request in the form:
331  * [key1, value1, key2, value2, ...] where the keys and values are of type
332  * v8::String. Note, unlike the FixedArray passed to ResolveModuleCallback and
333  * returned from ModuleRequest::GetImportAssertions(), this array does not
334  * contain the source Locations of the assertions.
335  *
336  * The embedder must compile, instantiate, evaluate the Module, and
337  * obtain its namespace object.
338  *
339  * The Promise returned from this function is forwarded to userland
340  * JavaScript. The embedder must resolve this promise with the module
341  * namespace object. In case of an exception, the embedder must reject
342  * this promise with the exception. If the promise creation itself
343  * fails (e.g. due to stack overflow), the embedder must propagate
344  * that exception by returning an empty MaybeLocal.
345  */
346 using HostImportModuleDynamicallyWithImportAssertionsCallback =
347  MaybeLocal<Promise> (*)(Local<Context> context,
348  Local<ScriptOrModule> referrer,
349  Local<String> specifier,
350  Local<FixedArray> import_assertions);
351 using HostImportModuleDynamicallyCallback = MaybeLocal<Promise> (*)(
352  Local<Context> context, Local<Data> host_defined_options,
353  Local<Value> resource_name, Local<String> specifier,
354  Local<FixedArray> import_assertions);
355 
356 /**
357  * HostInitializeImportMetaObjectCallback is called the first time import.meta
358  * is accessed for a module. Subsequent access will reuse the same value.
359  *
360  * The method combines two implementation-defined abstract operations into one:
361  * HostGetImportMetaProperties and HostFinalizeImportMeta.
362  *
363  * The embedder should use v8::Object::CreateDataProperty to add properties on
364  * the meta object.
365  */
366 using HostInitializeImportMetaObjectCallback = void (*)(Local<Context> context,
367  Local<Module> module,
368  Local<Object> meta);
369 
370 /**
371  * HostCreateShadowRealmContextCallback is called each time a ShadowRealm is
372  * being constructed in the initiator_context.
373  *
374  * The method combines Context creation and implementation defined abstract
375  * operation HostInitializeShadowRealm into one.
376  *
377  * The embedder should use v8::Context::New or v8::Context:NewFromSnapshot to
378  * create a new context. If the creation fails, the embedder must propagate
379  * that exception by returning an empty MaybeLocal.
380  */
381 using HostCreateShadowRealmContextCallback =
382  MaybeLocal<Context> (*)(Local<Context> initiator_context);
383 
384 /**
385  * PrepareStackTraceCallback is called when the stack property of an error is
386  * first accessed. The return value will be used as the stack value. If this
387  * callback is registed, the |Error.prepareStackTrace| API will be disabled.
388  * |sites| is an array of call sites, specified in
389  * https://v8.dev/docs/stack-trace-api
390  */
391 using PrepareStackTraceCallback = MaybeLocal<Value> (*)(Local<Context> context,
392  Local<Value> error,
393  Local<Array> sites);
394 
395 } // namespace v8
396 
397 #endif // INCLUDE_V8_ISOLATE_CALLBACKS_H_