|
using | BackingStoreDeleterCallback = void(*)(void *data, size_t length, void *deleter_data) |
|
using | JitCodeEventHandler = void(*)(const JitCodeEvent *event) |
|
using | GCCallback = void(*)(GCType type, GCCallbackFlags flags) |
|
using | InterruptCallback = void(*)(Isolate *isolate, void *data) |
|
using | NearHeapLimitCallback = size_t(*)(void *data, size_t current_heap_limit, size_t initial_heap_limit) |
|
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) |
|
using | FatalErrorCallback = void(*)(const char *location, const char *message) |
|
using | OOMErrorCallback = void(*)(const char *location, const OOMDetails &details) |
|
using | MessageCallback = void(*)(Local< Message > message, Local< Value > data) |
|
using | LogEventCallback = void(*)(const char *name, int status) |
|
using | AddCrashKeyCallback = void(*)(CrashKeyId id, const std::string &value) |
|
using | BeforeCallEnteredCallback = void(*)(Isolate *) |
|
using | CallCompletedCallback = void(*)(Isolate *) |
|
using | ModifyCodeGenerationFromStringsCallback = ModifyCodeGenerationFromStringsResult(*)(Local< Context > context, Local< Value > source) |
|
using | ModifyCodeGenerationFromStringsCallback2 = ModifyCodeGenerationFromStringsResult(*)(Local< Context > context, Local< Value > source, bool is_code_like) |
|
using | FailedAccessCheckCallback = void(*)(Local< Object > target, AccessType type, Local< Value > data) |
|
using | ExtensionCallback = bool(*)(const FunctionCallbackInfo< Value > &) |
|
using | AllowWasmCodeGenerationCallback = bool(*)(Local< Context > context, Local< String > source) |
|
using | ApiImplementationCallback = void(*)(const FunctionCallbackInfo< Value > &) |
|
using | WasmStreamingCallback = void(*)(const FunctionCallbackInfo< Value > &) |
|
using | WasmAsyncResolvePromiseCallback = void(*)(Isolate *isolate, Local< Context > context, Local< Promise::Resolver > resolver, Local< Value > result, WasmAsyncSuccess success) |
|
using | WasmLoadSourceMapCallback = Local< String >(*)(Isolate *isolate, const char *name) |
|
using | WasmImportedStringsEnabledCallback = bool(*)(Local< Context > context) |
|
using | SharedArrayBufferConstructorEnabledCallback = bool(*)(Local< Context > context) |
|
using | JavaScriptCompileHintsMagicEnabledCallback = bool(*)(Local< Context > context) |
|
using | WasmJSPIEnabledCallback = bool(*)(Local< Context > context) |
|
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 | PrepareStackTraceCallback = MaybeLocal< Value >(*)(Local< Context > context, Local< Value > error, Local< Array > sites) |
|
using | ExceptionPropagationCallback = void(*)(ExceptionPropagationMessage message) |
|
using | CFunctionBuilder = internal::CFunctionBuilder |
|
using | FunctionCallback = void(*)(const FunctionCallbackInfo< Value > &info) |
|
using | EntropySource = bool(*)(unsigned char *buffer, size_t length) |
|
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) |
|
using | StackState = cppgc::EmbedderStackState |
|
template<class T > |
using | Handle = Local< T > |
|
using | MicrotasksCompletedCallbackWithData = void(*)(Isolate *, void *) |
|
using | MicrotaskCallback = void(*)(void *data) |
|
using | AccessorNameGetterCallback = void(*)(Local< Name > property, const PropertyCallbackInfo< Value > &info) |
|
using | AccessorNameSetterCallback = void(*)(Local< Name > property, Local< Value > value, const PropertyCallbackInfo< void > &info) |
|
template<class T > |
using | UniquePersistent = Global< T > |
|
using | PlatformSharedMemoryHandle = intptr_t |
|
using | NativeObject = void * |
|
using | SnapshotObjectId = uint32_t |
|
using | ProfilerId = uint32_t |
|
using | PromiseHook = void(*)(PromiseHookType type, Local< Promise > promise, Local< Value > parent) |
|
using | PromiseRejectCallback = void(*)(PromiseRejectMessage message) |
|
using | NamedPropertyGetterCallback = Intercepted(*)(Local< Name > property, const PropertyCallbackInfo< Value > &info) |
|
using | GenericNamedPropertyGetterCallback = void(*)(Local< Name > property, const PropertyCallbackInfo< Value > &info) |
|
using | NamedPropertySetterCallback = Intercepted(*)(Local< Name > property, Local< Value > value, const PropertyCallbackInfo< void > &info) |
|
using | GenericNamedPropertySetterCallback = void(*)(Local< Name > property, Local< Value > value, const PropertyCallbackInfo< Value > &info) |
|
using | NamedPropertyQueryCallback = Intercepted(*)(Local< Name > property, const PropertyCallbackInfo< Integer > &info) |
|
using | GenericNamedPropertyQueryCallback = void(*)(Local< Name > property, const PropertyCallbackInfo< Integer > &info) |
|
using | NamedPropertyDeleterCallback = Intercepted(*)(Local< Name > property, const PropertyCallbackInfo< Boolean > &info) |
|
using | GenericNamedPropertyDeleterCallback = void(*)(Local< Name > property, const PropertyCallbackInfo< Boolean > &info) |
|
using | NamedPropertyEnumeratorCallback = void(*)(const PropertyCallbackInfo< Array > &info) |
|
using | GenericNamedPropertyEnumeratorCallback = NamedPropertyEnumeratorCallback |
|
using | NamedPropertyDefinerCallback = Intercepted(*)(Local< Name > property, const PropertyDescriptor &desc, const PropertyCallbackInfo< void > &info) |
|
using | GenericNamedPropertyDefinerCallback = void(*)(Local< Name > property, const PropertyDescriptor &desc, const PropertyCallbackInfo< Value > &info) |
|
using | NamedPropertyDescriptorCallback = Intercepted(*)(Local< Name > property, const PropertyCallbackInfo< Value > &info) |
|
using | GenericNamedPropertyDescriptorCallback = void(*)(Local< Name > property, const PropertyCallbackInfo< Value > &info) |
|
using | IndexedPropertyGetterCallbackV2 = Intercepted(*)(uint32_t index, const PropertyCallbackInfo< Value > &info) |
|
using | IndexedPropertyGetterCallback = void(*)(uint32_t index, const PropertyCallbackInfo< Value > &info) |
|
using | IndexedPropertySetterCallbackV2 = Intercepted(*)(uint32_t index, Local< Value > value, const PropertyCallbackInfo< void > &info) |
|
using | IndexedPropertySetterCallback = void(*)(uint32_t index, Local< Value > value, const PropertyCallbackInfo< Value > &info) |
|
using | IndexedPropertyQueryCallbackV2 = Intercepted(*)(uint32_t index, const PropertyCallbackInfo< Integer > &info) |
|
using | IndexedPropertyQueryCallback = void(*)(uint32_t index, const PropertyCallbackInfo< Integer > &info) |
|
using | IndexedPropertyDeleterCallbackV2 = Intercepted(*)(uint32_t index, const PropertyCallbackInfo< Boolean > &info) |
|
using | IndexedPropertyDeleterCallback = void(*)(uint32_t index, const PropertyCallbackInfo< Boolean > &info) |
|
using | IndexedPropertyEnumeratorCallback = void(*)(const PropertyCallbackInfo< Array > &info) |
|
using | IndexedPropertyDefinerCallbackV2 = Intercepted(*)(uint32_t index, const PropertyDescriptor &desc, const PropertyCallbackInfo< void > &info) |
|
using | IndexedPropertyDefinerCallback = void(*)(uint32_t index, const PropertyDescriptor &desc, const PropertyCallbackInfo< Value > &info) |
|
using | IndexedPropertyDescriptorCallbackV2 = Intercepted(*)(uint32_t index, const PropertyCallbackInfo< Value > &info) |
|
using | IndexedPropertyDescriptorCallback = void(*)(uint32_t index, const PropertyCallbackInfo< Value > &info) |
|
using | AccessCheckCallback = bool(*)(Local< Context > accessing_context, Local< Object > accessed_object, Local< Value > data) |
|
typedef uintptr_t | PersistentContainerValue |
|
|
enum class | ArrayBufferCreationMode { kInternalized
, kExternalized
} |
|
enum class | BackingStoreInitializationMode { kZeroInitialized
, kUninitialized
} |
|
enum | JitCodeEventOptions { kJitCodeEventDefault = 0
, kJitCodeEventEnumExisting = 1
} |
|
enum | GCType {
kGCTypeScavenge = 1 << 0
, kGCTypeMinorMarkSweep = 1 << 1
, kGCTypeMarkSweepCompact = 1 << 2
, kGCTypeIncrementalMarking = 1 << 3
,
kGCTypeProcessWeakCallbacks = 1 << 4
, kGCTypeAll
} |
|
enum | GCCallbackFlags {
kNoGCCallbackFlags = 0
, kGCCallbackFlagConstructRetainedObjectInfos = 1 << 1
, kGCCallbackFlagForced = 1 << 2
, kGCCallbackFlagSynchronousPhantomCallbackProcessing = 1 << 3
,
kGCCallbackFlagCollectAllAvailableGarbage = 1 << 4
, kGCCallbackFlagCollectAllExternalMemory = 1 << 5
, kGCCallbackScheduleIdleGarbageCollection = 1 << 6
} |
|
enum | LogEventStatus : int { kStart = 0
, kEnd = 1
, kLog = 2
} |
|
enum class | CrashKeyId {
kIsolateAddress
, kReadonlySpaceFirstPageAddress
, kMapSpaceFirstPageAddress
, kOldSpaceFirstPageAddress
,
kCodeRangeBaseAddress
, kCodeSpaceFirstPageAddress
, kDumpType
, kSnapshotChecksumCalculated
,
kSnapshotChecksumExpected
} |
|
enum | AccessType {
ACCESS_GET
, ACCESS_SET
, ACCESS_HAS
, ACCESS_DELETE
,
ACCESS_KEYS
} |
|
enum class | WasmAsyncSuccess { kSuccess
, kFail
} |
|
enum class | ModuleImportPhase { kSource
, kEvaluation
} |
|
enum class | EmbedderStateTag : uint8_t { EMPTY = 0
, OTHER = 1
} |
|
enum class | ExceptionContext : uint32_t {
kUnknown
, kConstructor
, kOperation
, kAttributeGet
,
kAttributeSet
, kIndexedQuery
, kIndexedGetter
, kIndexedDescriptor
,
kIndexedSetter
, kIndexedDefiner
, kIndexedDeleter
, kNamedQuery
,
kNamedGetter
, kNamedDescriptor
, kNamedSetter
, kNamedDefiner
,
kNamedDeleter
, kNamedEnumerator
} |
|
enum | RAILMode : unsigned { PERFORMANCE_RESPONSE
, PERFORMANCE_ANIMATION
, PERFORMANCE_IDLE
, PERFORMANCE_LOAD
} |
|
enum class | MemoryPressureLevel { kNone
, kModerate
, kCritical
} |
|
enum class | MicrotasksPolicy { kExplicit
, kScoped
, kAuto
} |
|
enum | PropertyAttribute { None = 0
, ReadOnly = 1 << 0
, DontEnum = 1 << 1
, DontDelete = 1 << 2
} |
|
enum | AccessControl { DEFAULT = 0
} |
|
enum | PropertyFilter {
ALL_PROPERTIES = 0
, ONLY_WRITABLE = 1
, ONLY_ENUMERABLE = 2
, ONLY_CONFIGURABLE = 4
,
SKIP_STRINGS = 8
, SKIP_SYMBOLS = 16
} |
|
enum class | SideEffectType { kHasSideEffect
, kHasNoSideEffect
, kHasSideEffectToReceiver
} |
|
enum class | KeyCollectionMode { kOwnOnly
, kIncludePrototypes
} |
|
enum class | IndexFilter { kIncludeIndices
, kSkipIndices
} |
|
enum class | KeyConversionMode { kConvertToString
, kKeepNumbers
, kNoNumbers
} |
|
enum class | IntegrityLevel { kFrozen
, kSealed
} |
|
enum class | TaskPriority : uint8_t { kBestEffort
, kUserVisible
, kUserBlocking
, kMaxPriority = kUserBlocking
} |
|
enum class | BlockingType { kMayBlock
, kWillBlock
} |
|
enum class | PagePermissions {
kNoAccess
, kRead
, kReadWrite
, kReadWriteExecute
,
kReadExecute
} |
|
enum class | NewStringType { kNormal
, kInternalized
} |
|
enum | CpuProfilingMode { kLeafNodeLineNumbers
, kCallerLineNumbers
} |
|
enum | CpuProfilingNamingMode { kStandardNaming
, kDebugNaming
} |
|
enum | CpuProfilingLoggingMode { kLazyLogging
, kEagerLogging
} |
|
enum class | CpuProfilingStatus { kStarted
, kAlreadyStarted
, kErrorTooManyProfilers
} |
|
enum | CodeEventType {
kUnknownType
, kBuiltinType
, kCallbackType
, kEvalType
,
kFunctionType
, kInterpretedFunctionType
, kHandlerType
, kBytecodeHandlerType
,
kLazyCompileType
, kRegExpType
, kScriptType
, kStubType
,
kRelocationType
} |
|
enum class | PromiseHookType { kInit
, kResolve
, kBefore
, kAfter
} |
|
enum | PromiseRejectEvent { kPromiseRejectWithNoHandler = 0
, kPromiseHandlerAddedAfterReject = 1
, kPromiseRejectAfterResolved = 2
, kPromiseResolveAfterResolved = 3
} |
|
enum class | CppHeapPointerTag : uint16_t {
kFirstTag = 0
, kNullTag = 0
, kDefaultTag = 0x7000
, kZappedEntryTag = 0x7ffd
,
kEvacuationEntryTag = 0x7ffe
, kFreeEntryTag = 0x7fff
, kLastTag = 0x7fff
} |
|
enum class | ScriptType { kClassic
, kModule
} |
|
enum class | MeasureMemoryMode { kSummary
, kDetailed
} |
|
enum class | MeasureMemoryExecution { kDefault
, kEager
, kLazy
} |
|
enum | Intrinsic {
kArrayProto_entries
, kArrayProto_forEach
, kArrayProto_keys
, kArrayProto_values
,
kArrayPrototype
, kAsyncIteratorPrototype
, kErrorPrototype
, kIteratorPrototype
,
kMapIteratorPrototype
, kObjProto_valueOf
, kSetIteratorPrototype
} |
|
enum class | Intercepted : uint8_t { kNo = 0
, kYes = 1
} |
|
enum class | ConstructorBehavior { kThrow
, kAllow
} |
|
enum class | PropertyHandlerFlags {
kNone = 0
, kNonMasking = 1
, kOnlyInterceptStrings = 1 << 1
, kHasNoSideEffect = 1 << 2
,
kInternalNewCallbacksSignatures = 1 << 10
} |
|
enum | StateTag : uint16_t {
JS
, GC
, PARSER
, BYTECODE_COMPILER
,
COMPILER
, OTHER
, EXTERNAL
, ATOMICS_WAIT
,
IDLE
, LOGGING
} |
|
enum | PersistentContainerCallbackType { kNotWeak
, kWeakWithParameter
, kWeakWithInternalFields
} |
|
enum class | WeakCallbackType { kParameter
, kInternalFields
} |
|
This file provides additional API on top of the default one for making API calls, which come from embedder C++ functions. The functions are being called directly from optimized code, doing all the necessary typechecks in the compiler itself, instead of on the embedder side. Hence the "fast" in the name. Example usage might look like:
void FastMethod(int param, bool another_param);
signature, length, constructor_behavior
side_effect_type,
static CFunction Make(F *func, CFunctionInfo::Int64Representation int64_rep=CFunctionInfo::Int64Representation::kNumber)
Definition: v8-fast-api-calls.h:496
static Local< FunctionTemplate > New(Isolate *isolate, FunctionCallback callback=nullptr, Local< Value > data=Local< Value >(), Local< Signature > signature=Local< Signature >(), int length=0, ConstructorBehavior behavior=ConstructorBehavior::kAllow, SideEffectType side_effect_type=SideEffectType::kHasSideEffect, const CFunction *c_function=nullptr, uint16_t instance_type=0, uint16_t allowed_receiver_instance_type_range_start=0, uint16_t allowed_receiver_instance_type_range_end=0)
By design, fast calls are limited by the following requirements, which the embedder should enforce themselves:
Due to these limitations, it's not directly possible to report errors by throwing a JS exception or to otherwise do an allocation. There is an alternative way of creating fast calls that supports falling back to the slow call and then performing the necessary allocation. When one creates the fast method by using CFunction::MakeWithFallbackSupport instead of CFunction::Make, the fast callback gets as last parameter an output variable, through which it can request falling back to the slow call. So one might declare their method like:
Definition: v8-fast-api-calls.h:546
If the callback wants to signal an error condition or to perform an allocation, it must set options.fallback to true and do an early return from the fast method. Then V8 checks the value of options.fallback and if it's true, falls back to executing the SlowCallback, which is capable of reporting the error (either by throwing a JS exception or logging to the console) or doing the allocation. It's the embedder's responsibility to ensure that the fast callback is idempotent up to the point where error and fallback conditions are checked, because otherwise executing the slow callback might produce visible side-effects twice.
An example for custom embedder type support might employ a way to wrap/ unwrap various C++ types in JSObject instances, e.g:
template <typename T, int offset>
assert(offset < wrapper->InternalFieldCount());
return reinterpret_cast<T*>(
wrapper->GetAlignedPointerFromInternalField(offset));
}
class CustomEmbedderType {
public:
return GetInternalField<CustomEmbedderType,
kV8EmbedderWrapperObjectIndex>(wrapper);
}
CustomEmbedderType* receiver = static_cast<CustomEmbedderType*>(
receiver_obj->GetAlignedPointerFromInternalField(
kV8EmbedderWrapperObjectIndex));
}
static void SlowMethod(
CustomEmbedderType* receiver = Unwrap(instance);
receiver->Method(param);
}
};
static constexpr int kV8EmbedderWrapperTypeIndex = 0;
static constexpr int kV8EmbedderWrapperObjectIndex = 1;
CustomEmbedderType* embedder_object) {
isolate->set_embedder_wrapper_type_index(
kV8EmbedderWrapperTypeIndex);
isolate->set_embedder_wrapper_object_index(
kV8EmbedderWrapperObjectIndex);
MakeV8CFunction(CustomEmbedderType::FastMethod);
Local<v8::FunctionTemplate> method_template =
object_template->SetInternalFieldCount(
kV8EmbedderWrapperObjectIndex + 1);
object_template->Set(isolate, "method", method_template);
object_template->NewInstance(context).ToLocalChecked();
object->SetAlignedPointerInInternalField(
kV8EmbedderWrapperObjectIndex,
reinterpret_cast<void*>(embedder_object));
}
Definition: v8-fast-api-calls.h:437
Definition: v8-function-callback.h:118
Local< Object > Holder() const
Definition: v8-function-callback.h:658
Definition: v8-isolate.h:212
Definition: v8-local-handle.h:266
static Local< T > Cast(Local< S > that)
Definition: v8-local-handle.h:321
static Local< ObjectTemplate > New(Isolate *isolate, Local< FunctionTemplate > constructor=Local< FunctionTemplate >())
For instance if {object} is exposed via a global "obj" variable, one could write in JS: function hot_func() { obj.method(42); } and once {hot_func} gets optimized, CustomEmbedderType::FastMethod will be called instead of the slow version, with the following arguments: receiver := the {embedder_object} from above param := 42
Currently supported return types:
- void
- bool
- int32_t
- uint32_t
- float32_t
- float64_t Currently supported argument types:
pointer to an embedder type
- JavaScript array of primitive types
- bool
- int32_t
- uint32_t
- int64_t
- uint64_t
- float32_t
- float64_t
The 64-bit integer types currently have the IDL (unsigned) long long semantics: https://heycam.github.io/webidl/#abstract-opdef-converttoint In the future we'll extend the API to also provide conversions from/to BigInt to preserve full precision. The floating point types currently have the IDL (unrestricted) semantics, which is the only one used by WebGL. We plan to add support also for restricted floats/doubles, similarly to the BigInt conversion policies. We also differ from the specific NaN bit pattern that WebIDL prescribes (https://heycam.github.io/webidl/#es-unrestricted-float) in that Blink passes NaN values as-is, i.e. doesn't normalize them.
To be supported types:
- TypedArrays and ArrayBuffers
- arrays of embedder types
The API offers a limited support for function overloads:
void FastMethod_2Args(int param, bool another_param);
void FastMethod_3Args(int param, bool another_param, int third_param);
MakeV8CFunction(FastMethod_2Args);
MakeV8CFunction(FastMethod_3Args);
const v8::CFunction fast_method_overloads[] = {fast_method_2args_c_func,
fast_method_3args_c_func};
Local<v8::FunctionTemplate> method_template =
isolate, SlowCallback, data, signature, length,
constructor_behavior, side_effect_type,
{fast_method_overloads, 2});
static Local< FunctionTemplate > NewWithCFunctionOverloads(Isolate *isolate, FunctionCallback callback=nullptr, Local< Value > data=Local< Value >(), Local< Signature > signature=Local< Signature >(), int length=0, ConstructorBehavior behavior=ConstructorBehavior::kAllow, SideEffectType side_effect_type=SideEffectType::kHasSideEffect, const MemorySpan< const CFunction > &c_function_overloads={})
In this example a single FunctionTemplate is associated to multiple C++ functions. The overload resolution is currently only based on the number of arguments passed in a call. For example, if this method_template is registered with a wrapper JS object as described above, a call with two arguments: obj.method(42, true); will result in a fast call to FastMethod_2Args, while a call with three or more arguments: obj.method(42, true, 11); will result in a fast call to FastMethod_3Args. Instead a call with less than two arguments, like: obj.method(42); would not result in a fast call but would fall back to executing the associated SlowCallback.
The v8 JavaScript engine.
Profiler support for the V8 JavaScript engine.
Support for Persistent containers.
C++11 embedders can use STL containers with Global values, but pre-C++11 does not support the required move semantic and hence may want these container classes.
Compile-time constants.
This header provides access to information about the value serializer at compile time, without declaring or defining any symbols that require linking to V8.