Struct v8::HandleScope
source · pub struct HandleScope<'s, C = Context> { /* private fields */ }Expand description
A stack-allocated class that governs a number of local handles. After a handle scope has been created, all local handles will be allocated within that handle scope until either the handle scope is deleted or another handle scope is created. If there is already a handle scope and a new one is created, all allocations will take place in the new handle scope until it is deleted. After that, new handles will again be allocated in the original handle scope.
After the handle scope of a local handle has been deleted the garbage collector will no longer track the object stored in the handle and may deallocate it. The behavior of accessing a handle for which the handle scope has been deleted is undefined.
Implementations§
source§impl<'s> HandleScope<'s>
impl<'s> HandleScope<'s>
pub fn new<P: NewHandleScope<'s>>(param: &'s mut P) -> P::NewScope
sourcepub fn with_context<P: NewHandleScopeWithContext<'s>, H: Handle<Data = Context>>(
param: &'s mut P,
context: H
) -> Self
pub fn with_context<P: NewHandleScopeWithContext<'s>, H: Handle<Data = Context>>( param: &'s mut P, context: H ) -> Self
Opens a new HandleScope and enters a Context in one step.
The first argument should be an Isolate or OwnedIsolate.
The second argument can be any handle that refers to a Context object;
usually this will be a Global<Context>.
sourcepub fn get_current_context(&self) -> Local<'s, Context>
pub fn get_current_context(&self) -> Local<'s, Context>
Returns the context of the currently running JavaScript, or the context on the top of the stack if no JavaScript is running.
sourcepub fn get_entered_or_microtask_context(&self) -> Local<'s, Context>
pub fn get_entered_or_microtask_context(&self) -> Local<'s, Context>
Returns either the last context entered through V8’s C++ API, or the context of the currently running microtask while processing microtasks. If a context is entered while executing a microtask, that context is returned.
source§impl<'s> HandleScope<'s, ()>
impl<'s> HandleScope<'s, ()>
sourcepub fn throw_exception(
&mut self,
exception: Local<'_, Value>
) -> Local<'s, Value>
pub fn throw_exception( &mut self, exception: Local<'_, Value> ) -> Local<'s, Value>
Schedules an exception to be thrown when returning to JavaScript. When an exception has been scheduled it is illegal to invoke any JavaScript operation; the caller must return immediately and only after the exception has been handled does it become legal to invoke JavaScript operations.
This function always returns the undefined value.
source§impl<'s> HandleScope<'s>
impl<'s> HandleScope<'s>
sourcepub fn get_isolate_data_from_snapshot_once<T>(
&mut self,
index: usize
) -> Result<Local<'s, T>, DataError>
pub fn get_isolate_data_from_snapshot_once<T>( &mut self, index: usize ) -> Result<Local<'s, T>, DataError>
Return data that was previously attached to the isolate snapshot via
SnapshotCreator, and removes the reference to it. If called again with
same index argument, this function returns DataError::NoData.
The value that was stored in the snapshot must either match or be
convertible to type parameter T, otherwise DataError::BadType is
returned.
sourcepub fn get_context_data_from_snapshot_once<T>(
&mut self,
index: usize
) -> Result<Local<'s, T>, DataError>
pub fn get_context_data_from_snapshot_once<T>( &mut self, index: usize ) -> Result<Local<'s, T>, DataError>
Return data that was previously attached to the context snapshot via
SnapshotCreator, and removes the reference to it. If called again with
same index argument, this function returns DataError::NoData.
The value that was stored in the snapshot must either match or be
convertible to type parameter T, otherwise DataError::BadType is
returned.
pub fn set_promise_hooks( &mut self, init_hook: Option<Local<'_, Function>>, before_hook: Option<Local<'_, Function>>, after_hook: Option<Local<'_, Function>>, resolve_hook: Option<Local<'_, Function>> )
pub fn set_continuation_preserved_embedder_data( &mut self, data: Local<'_, Value> )
pub fn get_continuation_preserved_embedder_data(&mut self) -> Local<'s, Value>
Methods from Deref<Target = Isolate>§
pub fn thread_safe_handle(&self) -> IsolateHandle
sourcepub fn terminate_execution(&self) -> bool
pub fn terminate_execution(&self) -> bool
sourcepub fn cancel_terminate_execution(&self) -> bool
pub fn cancel_terminate_execution(&self) -> bool
sourcepub fn is_execution_terminating(&self) -> bool
pub fn is_execution_terminating(&self) -> bool
sourcepub fn get_data(&self, slot: u32) -> *mut c_void
pub fn get_data(&self, slot: u32) -> *mut c_void
Retrieve embedder-specific data from the isolate.
Returns NULL if SetData has never been called for the given slot.
sourcepub fn set_data(&mut self, slot: u32, data: *mut c_void)
pub fn set_data(&mut self, slot: u32, data: *mut c_void)
Associate embedder-specific data with the isolate. slot has to be
between 0 and Isolate::get_number_of_data_slots().
sourcepub fn get_number_of_data_slots(&self) -> u32
pub fn get_number_of_data_slots(&self) -> u32
Returns the maximum number of available embedder data slots. Valid slots
are in the range of 0 <= n < Isolate::get_number_of_data_slots().
sourcepub fn get_slot<T: 'static>(&self) -> Option<&T>
pub fn get_slot<T: 'static>(&self) -> Option<&T>
Get a reference to embedder data added with set_slot().
sourcepub fn get_slot_mut<T: 'static>(&mut self) -> Option<&mut T>
pub fn get_slot_mut<T: 'static>(&mut self) -> Option<&mut T>
Get a mutable reference to embedder data added with set_slot().
sourcepub fn set_slot<T: 'static>(&mut self, value: T) -> bool
pub fn set_slot<T: 'static>(&mut self, value: T) -> bool
Use with Isolate::get_slot and Isolate::get_slot_mut to associate state with an Isolate.
This method gives ownership of value to the Isolate. Exactly one object of each type can be associated with an Isolate. If called more than once with an object of the same type, the earlier version will be dropped and replaced.
Returns true if value was set without replacing an existing value.
The value will be dropped when the isolate is dropped.
sourcepub fn remove_slot<T: 'static>(&mut self) -> Option<T>
pub fn remove_slot<T: 'static>(&mut self) -> Option<T>
Removes the embedder data added with set_slot() and returns it if it exists.
sourcepub unsafe fn enter(&mut self)
pub unsafe fn enter(&mut self)
Sets this isolate as the entered one for the current thread. Saves the previously entered one (if any), so that it can be restored when exiting. Re-entering an isolate is allowed.
rusty_v8 note: Unlike in the C++ API, the isolate is entered when it is constructed and exited when dropped.
sourcepub unsafe fn exit(&mut self)
pub unsafe fn exit(&mut self)
Exits this isolate by restoring the previously entered one in the current thread. The isolate may still stay the same, if it was entered more than once.
Requires: self == Isolate::GetCurrent().
rusty_v8 note: Unlike in the C++ API, the isolate is entered when it is constructed and exited when dropped.
sourcepub fn memory_pressure_notification(&mut self, level: MemoryPressureLevel)
pub fn memory_pressure_notification(&mut self, level: MemoryPressureLevel)
Optional notification that the system is running low on memory. V8 uses these notifications to guide heuristics. It is allowed to call this function from another thread while the isolate is executing long running JavaScript code.
sourcepub fn clear_kept_objects(&mut self)
pub fn clear_kept_objects(&mut self)
Clears the set of objects held strongly by the heap. This set of objects are originally built when a WeakRef is created or successfully dereferenced.
This is invoked automatically after microtasks are run. See MicrotasksPolicy for when microtasks are run.
This needs to be manually invoked only if the embedder is manually running microtasks via a custom MicrotaskQueue class’s PerformCheckpoint. In that case, it is the embedder’s responsibility to make this call at a time which does not interrupt synchronous ECMAScript code execution.
sourcepub fn low_memory_notification(&mut self)
pub fn low_memory_notification(&mut self)
Optional notification that the system is running low on memory. V8 uses these notifications to attempt to free memory.
sourcepub fn get_heap_statistics(&mut self, s: &mut HeapStatistics)
pub fn get_heap_statistics(&mut self, s: &mut HeapStatistics)
Get statistics about the heap memory usage.
sourcepub fn set_capture_stack_trace_for_uncaught_exceptions(
&mut self,
capture: bool,
frame_limit: i32
)
pub fn set_capture_stack_trace_for_uncaught_exceptions( &mut self, capture: bool, frame_limit: i32 )
Tells V8 to capture current stack trace when uncaught exception occurs and report it to the message listeners. The option is off by default.
sourcepub fn add_message_listener(&mut self, callback: MessageCallback) -> bool
pub fn add_message_listener(&mut self, callback: MessageCallback) -> bool
Adds a message listener (errors only).
The same message listener can be added more than once and in that case it will be called more than once for each message.
The exception object will be passed to the callback.
sourcepub fn add_message_listener_with_error_level(
&mut self,
callback: MessageCallback,
message_levels: MessageErrorLevel
) -> bool
pub fn add_message_listener_with_error_level( &mut self, callback: MessageCallback, message_levels: MessageErrorLevel ) -> bool
Adds a message listener for the specified message levels.
sourcepub fn set_prepare_stack_trace_callback<'s>(
&mut self,
callback: impl MapFnTo<extern "C" fn(_: Local<'s, Context>, _: Local<'s, Value>, _: Local<'s, Array>) -> PrepareStackTraceCallbackRet>
)
pub fn set_prepare_stack_trace_callback<'s>( &mut self, callback: impl MapFnTo<extern "C" fn(_: Local<'s, Context>, _: Local<'s, Value>, _: Local<'s, Array>) -> PrepareStackTraceCallbackRet> )
This specifies the callback called when the stack property of Error is accessed.
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
sourcepub fn set_promise_hook(&mut self, hook: PromiseHook)
pub fn set_promise_hook(&mut self, hook: PromiseHook)
Set the PromiseHook callback for various promise lifecycle events.
sourcepub fn set_promise_reject_callback(&mut self, callback: PromiseRejectCallback)
pub fn set_promise_reject_callback(&mut self, callback: PromiseRejectCallback)
Set callback to notify about promise reject with no handler, or revocation of such a previous notification once the handler is added.
pub fn set_wasm_async_resolve_promise_callback( &mut self, callback: extern "C" fn(_: *mut Isolate, _: Local<'_, Context>, _: Local<'_, PromiseResolver>, _: Local<'_, Value>, _: WasmAsyncSuccess) )
sourcepub fn set_host_initialize_import_meta_object_callback(
&mut self,
callback: HostInitializeImportMetaObjectCallback
)
pub fn set_host_initialize_import_meta_object_callback( &mut self, callback: HostInitializeImportMetaObjectCallback )
This specifies the callback called by the upcoming importa.meta language feature to retrieve host-defined meta data for a module.
sourcepub fn set_host_import_module_dynamically_callback(
&mut self,
callback: impl HostImportModuleDynamicallyCallback
)
pub fn set_host_import_module_dynamically_callback( &mut self, callback: impl HostImportModuleDynamicallyCallback )
This specifies the callback called by the upcoming dynamic import() language feature to load modules.
sourcepub fn set_host_create_shadow_realm_context_callback(
&mut self,
callback: HostCreateShadowRealmContextCallback
)
pub fn set_host_create_shadow_realm_context_callback( &mut self, callback: HostCreateShadowRealmContextCallback )
This specifies the callback called by the upcoming ShadowRealm
construction language feature to retrieve host created globals.
sourcepub fn add_gc_prologue_callback(
&mut self,
callback: extern "C" fn(isolate: *mut Isolate, type: GCType, flags: GCCallbackFlags, data: *mut c_void),
data: *mut c_void,
gc_type_filter: GCType
)
pub fn add_gc_prologue_callback( &mut self, callback: extern "C" fn(isolate: *mut Isolate, type: GCType, flags: GCCallbackFlags, data: *mut c_void), data: *mut c_void, gc_type_filter: GCType )
Enables the host application to receive a notification before a garbage collection. Allocations are allowed in the callback function, but the callback is not re-entrant: if the allocation inside it will trigger the garbage collection, the callback won’t be called again. It is possible to specify the GCType filter for your callback. But it is not possible to register the same callback function two times with different GCType filters.
sourcepub fn remove_gc_prologue_callback(
&mut self,
callback: extern "C" fn(isolate: *mut Isolate, type: GCType, flags: GCCallbackFlags, data: *mut c_void),
data: *mut c_void
)
pub fn remove_gc_prologue_callback( &mut self, callback: extern "C" fn(isolate: *mut Isolate, type: GCType, flags: GCCallbackFlags, data: *mut c_void), data: *mut c_void )
This function removes callback which was installed by AddGCPrologueCallback function.
sourcepub fn add_near_heap_limit_callback(
&mut self,
callback: NearHeapLimitCallback,
data: *mut c_void
)
pub fn add_near_heap_limit_callback( &mut self, callback: NearHeapLimitCallback, data: *mut c_void )
Add a callback to invoke in case the heap size is close to the heap limit. If multiple callbacks are added, only the most recently added callback is invoked.
sourcepub fn remove_near_heap_limit_callback(
&mut self,
callback: NearHeapLimitCallback,
heap_limit: usize
)
pub fn remove_near_heap_limit_callback( &mut self, callback: NearHeapLimitCallback, heap_limit: usize )
Remove the given callback and restore the heap limit to the given limit. If the given limit is zero, then it is ignored. If the current heap size is greater than the given limit, then the heap limit is restored to the minimal limit that is possible for the current heap size.
sourcepub fn adjust_amount_of_external_allocated_memory(
&mut self,
change_in_bytes: i64
) -> i64
pub fn adjust_amount_of_external_allocated_memory( &mut self, change_in_bytes: i64 ) -> i64
Adjusts the amount of registered external memory. Used to give V8 an indication of the amount of externally allocated memory that is kept alive by JavaScript objects. V8 uses this to decide when to perform global garbage collections. Registering externally allocated memory will trigger global garbage collections more often than it would otherwise in an attempt to garbage collect the JavaScript objects that keep the externally allocated memory alive.
sourcepub fn attach_cpp_heap(&mut self, heap: &Heap)
pub fn attach_cpp_heap(&mut self, heap: &Heap)
Attaches a managed C++ heap as an extension to the JavaScript heap.
The embedder maintains ownership of the CppHeap. At most one C++ heap can be attached to V8.
pub fn get_cpp_heap(&mut self) -> Option<&Heap>
pub fn set_oom_error_handler(&mut self, callback: OomErrorCallback)
sourcepub fn get_microtasks_policy(&self) -> MicrotasksPolicy
pub fn get_microtasks_policy(&self) -> MicrotasksPolicy
Returns the policy controlling how Microtasks are invoked.
sourcepub fn set_microtasks_policy(&mut self, policy: MicrotasksPolicy)
pub fn set_microtasks_policy(&mut self, policy: MicrotasksPolicy)
Returns the policy controlling how Microtasks are invoked.
sourcepub fn perform_microtask_checkpoint(&mut self)
pub fn perform_microtask_checkpoint(&mut self)
Runs the default MicrotaskQueue until it gets empty and perform other microtask checkpoint steps, such as calling ClearKeptObjects. Asserts that the MicrotasksPolicy is not kScoped. Any exceptions thrown by microtask callbacks are swallowed.
sourcepub fn run_microtasks(&mut self)
👎Deprecated: Use Isolate::perform_microtask_checkpoint() instead
pub fn run_microtasks(&mut self)
An alias for PerformMicrotaskCheckpoint.
sourcepub fn enqueue_microtask(&mut self, microtask: Local<'_, Function>)
pub fn enqueue_microtask(&mut self, microtask: Local<'_, Function>)
Enqueues the callback to the default MicrotaskQueue
sourcepub fn set_allow_atomics_wait(&mut self, allow: bool)
pub fn set_allow_atomics_wait(&mut self, allow: bool)
Set whether calling Atomics.wait (a function that may block) is allowed in this isolate. This can also be configured via CreateParams::allow_atomics_wait.
sourcepub fn set_wasm_streaming_callback<F>(&mut self, _: F)
pub fn set_wasm_streaming_callback<F>(&mut self, _: F)
Embedder injection point for WebAssembly.compileStreaming(source).
The expectation is that the embedder sets it at most once.
The callback receives the source argument (string, Promise, etc.) and an instance of WasmStreaming. The WasmStreaming instance can outlive the callback and is used to feed data chunks to V8 asynchronously.
sourcepub fn date_time_configuration_change_notification(
&mut self,
time_zone_detection: TimeZoneDetection
)
pub fn date_time_configuration_change_notification( &mut self, time_zone_detection: TimeZoneDetection )
Notification that the embedder has changed the time zone, daylight savings time or other date / time configuration parameters. V8 keeps a cache of various values used for date / time computation. This notification will reset those cached values for the current context so that date / time configuration changes would be reflected.
This API should not be called more than needed as it will negatively impact the performance of date operations.
sourcepub fn has_pending_background_tasks(&self) -> bool
pub fn has_pending_background_tasks(&self) -> bool
Returns true if there is ongoing background work within V8 that will eventually post a foreground task, like asynchronous WebAssembly compilation.
sourcepub fn request_garbage_collection_for_testing(
&mut self,
type: GarbageCollectionType
)
pub fn request_garbage_collection_for_testing( &mut self, type: GarbageCollectionType )
Request garbage collection with a specific embedderstack state in this Isolate. It is only valid to call this function if –expose_gc was specified.
This should only be used for testing purposes and not to enforce a garbage collection schedule. It has strong negative impact on the garbage collection performance. Use IdleNotificationDeadline() or LowMemoryNotification() instead to influence the garbage collection schedule.
sourcepub fn take_heap_snapshot<F>(&mut self, callback: F)
pub fn take_heap_snapshot<F>(&mut self, callback: F)
Take a heap snapshot. The callback is invoked one or more times with byte slices containing the snapshot serialized as JSON. It’s the callback’s responsibility to reassemble them into a single document, e.g., by writing them to a file. Note that Chrome DevTools refuses to load snapshots without a .heapsnapshot suffix.
sourcepub fn set_default_context(&mut self, context: Local<'_, Context>)
pub fn set_default_context(&mut self, context: Local<'_, Context>)
Set the default context to be included in the snapshot blob. The snapshot will not contain the global proxy, and we expect one or a global object template to create one, to be provided upon deserialization.
§Panics
Panics if the isolate was not created using Isolate::snapshot_creator
sourcepub fn add_context(&mut self, context: Local<'_, Context>) -> usize
pub fn add_context(&mut self, context: Local<'_, Context>) -> usize
Add additional context to be included in the snapshot blob. The snapshot will include the global proxy.
Returns the index of the context in the snapshot blob.
§Panics
Panics if the isolate was not created using Isolate::snapshot_creator
sourcepub fn add_isolate_data<T>(&mut self, data: Local<'_, T>) -> usize
pub fn add_isolate_data<T>(&mut self, data: Local<'_, T>) -> usize
Attach arbitrary v8::Data to the isolate snapshot, which can be
retrieved via HandleScope::get_context_data_from_snapshot_once() after
deserialization. This data does not survive when a new snapshot is created
from an existing snapshot.
§Panics
Panics if the isolate was not created using Isolate::snapshot_creator
sourcepub fn add_context_data<T>(
&mut self,
context: Local<'_, Context>,
data: Local<'_, T>
) -> usize
pub fn add_context_data<T>( &mut self, context: Local<'_, Context>, data: Local<'_, T> ) -> usize
Attach arbitrary v8::Data to the context snapshot, which can be
retrieved via HandleScope::get_context_data_from_snapshot_once() after
deserialization. This data does not survive when a new snapshot is
created from an existing snapshot.
§Panics
Panics if the isolate was not created using Isolate::snapshot_creator