Struct rusty_v8::TryCatch

pub struct TryCatch<'s, P> { /* fields omitted */ }

An external exception handler.

Implementations

impl<'s, P: NewTryCatch<'s>> TryCatch<'s, P>

pub fn new(param: &'s mut P) -> P::NewScope

impl<'s, P> TryCatch<'s, P>

pub fn has_caught(&self) -> bool

Returns true if an exception has been caught by this try/catch block.

pub fn can_continue(&self) -> bool

For certain types of exceptions, it makes no sense to continue execution.

If CanContinue returns false, the correct action is to perform any C++ cleanup needed and then return. If CanContinue returns false and HasTerminated returns true, it is possible to call CancelTerminateExecution in order to continue calling into the engine.

pub fn has_terminated(&self) -> bool

Returns true if an exception has been caught due to script execution being terminated.

There is no JavaScript representation of an execution termination exception. Such exceptions are thrown when the TerminateExecution methods are called to terminate a long-running script.

If such an exception has been thrown, HasTerminated will return true, indicating that it is possible to call CancelTerminateExecution in order to continue calling into the engine.

pub fn is_verbose(&self) -> bool

Returns true if verbosity is enabled.

pub fn set_verbose(&mut self, value: bool)

Set verbosity of the external exception handler.

By default, exceptions that are caught by an external exception handler are not reported. Call SetVerbose with true on an external exception handler to have exceptions caught by the handler reported as if they were not caught.

pub fn set_capture_message(&mut self, value: bool)

Set whether or not this TryCatch should capture a Message object which holds source information about where the exception occurred. True by default.

pub fn reset(&mut self)

Clears any exceptions that may have been caught by this try/catch block. After this method has been called, HasCaught() will return false. Cancels the scheduled exception if it is caught and ReThrow() is not called before.

It is not necessary to clear a try/catch block before using it again; if another exception is thrown the previously caught exception will just be overwritten. However, it is often a good idea since it makes it easier to determine which operation threw a given exception.

impl<'s, 'p: 's, P> TryCatch<'s, P> where
    Self: AsMut<HandleScope<'p, ()>>, 

pub fn exception(&mut self) -> Option<Local<'p, Value>>

Returns the exception caught by this try/catch block. If no exception has been caught an empty handle is returned.

Note: v8.h states that “the returned handle is valid until this TryCatch block has been destroyed”. This is incorrect; the return value lives no longer and no shorter than the active HandleScope at the time this method is called. An issue has been opened about this in the V8 bug tracker: https://bugs.chromium.org/p/v8/issues/detail?id=10537.

pub fn message(&mut self) -> Option<Local<'p, Message>>

Returns the message associated with this exception. If there is no message associated an empty handle is returned.

Note: the remark about the lifetime for the exception() return value applies here too.

pub fn rethrow(&mut self) -> Option<Local<'_, Value>>

Throws the exception caught by this TryCatch in a way that avoids it being caught again by this same TryCatch. As with ThrowException it is illegal to execute any JavaScript operations after calling ReThrow; the caller must return immediately to where the exception is caught.

This function returns the undefined value when successful, or None if no exception was caught and therefore there was nothing to rethrow.

impl<'s, 'p: 's, P> TryCatch<'s, P> where
    Self: AsMut<HandleScope<'p>>, 

pub fn stack_trace(&mut self) -> Option<Local<'p, Value>>

Returns the .stack property of the thrown object. If no .stack property is present an empty handle is returned.

Methods from Deref<Target = HandleScope<'p, ()>>

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.

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.

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.

pub fn get_isolate_data_from_snapshot_once<T>(
    &mut self,
    index: usize
) -> Result<Local<'s, T>, DataError> where
    T: 'static,
    Local<'l, Data>: TryInto<Local<'l, T>, Error = 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.

pub fn get_context_data_from_snapshot_once<T>(
    &mut self,
    index: usize
) -> Result<Local<'s, T>, DataError> where
    T: 'static,
    Local<'l, Data>: TryInto<Local<'l, T>, Error = 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.

Methods from Deref<Target = Isolate>

pub fn thread_safe_handle(&self) -> IsolateHandle

pub fn terminate_execution(&self) -> bool

See IsolateHandle::terminate_execution

pub fn cancel_terminate_execution(&self) -> bool

See IsolateHandle::cancel_terminate_execution

pub fn is_execution_terminating(&self) -> bool

See IsolateHandle::is_execution_terminating

pub fn get_slot<T: 'static>(&self) -> Option<&T>

Get a reference to embedder data added with set_slot().

pub fn get_slot_mut<T: 'static>(&mut self) -> Option<&mut T>

Get a mutable reference to embedder data added with set_slot().

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.

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.

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.

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.

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.

pub fn get_heap_statistics(&mut self, s: &mut HeapStatistics)

Get statistics about the heap memory usage.

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.

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.

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>) -> *const Value>
)

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

pub fn set_promise_hook(&mut self, hook: PromiseHook)

Set the PromiseHook callback for various promise lifecycle events.

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_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.

pub fn set_host_import_module_dynamically_callback(
    &mut self,
    callback: HostImportModuleDynamicallyWithImportAssertionsCallback
)

This specifies the callback called by the upcoming dynamic import() language feature to load modules.

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.

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.

pub fn set_oom_error_handler(
    &mut self,
    callback: extern "C" fn(location: *const c_char, is_heap_oom: bool)
)

pub fn get_microtasks_policy(&self) -> MicrotasksPolicy

Returns the policy controlling how Microtasks are invoked.

pub fn set_microtasks_policy(&mut self, policy: MicrotasksPolicy)

Returns the policy controlling how Microtasks are invoked.

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.

pub fn run_microtasks(&mut self)

👎 Deprecated:

Use Isolate::perform_microtask_checkpoint() instead

An alias for PerformMicrotaskCheckpoint.

pub fn enqueue_microtask(&mut self, microtask: Local<'_, Function>)

Enqueues the callback to the default MicrotaskQueue

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.

pub fn set_wasm_streaming_callback<F>(&mut self, _: F) where
    F: UnitType + Fn(&mut HandleScope<'_>, Local<'_, Value>, WasmStreaming), 

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.

pub fn take_heap_snapshot<F>(&mut self, callback: F) where
    F: FnMut(&[u8]) -> bool, 

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.

Trait Implementations

impl<'s, 'p, 'e, C> AsMut<EscapableHandleScope<'p, 'e, ()>> for TryCatch<'s, EscapableHandleScope<'p, 'e, C>>

fn as_mut(&mut self) -> &mut EscapableHandleScope<'p, 'e, ()>

Performs the conversion.

impl<'s, 'p, 'e> AsMut<EscapableHandleScope<'p, 'e, Context>> for TryCatch<'s, EscapableHandleScope<'p, 'e>>

fn as_mut(&mut self) -> &mut EscapableHandleScope<'p, 'e>

Performs the conversion.

impl<'s, 'p, C> AsMut<HandleScope<'p, ()>> for TryCatch<'s, HandleScope<'p, C>>

fn as_mut(&mut self) -> &mut HandleScope<'p, ()>

Performs the conversion.

impl<'s, 'p, 'e, C> AsMut<HandleScope<'p, ()>> for TryCatch<'s, EscapableHandleScope<'p, 'e, C>>

fn as_mut(&mut self) -> &mut HandleScope<'p, ()>

Performs the conversion.

impl<'s, 'p> AsMut<HandleScope<'p, Context>> for TryCatch<'s, HandleScope<'p>>

fn as_mut(&mut self) -> &mut HandleScope<'p>

Performs the conversion.

impl<'s, 'p, 'e> AsMut<HandleScope<'p, Context>> for TryCatch<'s, EscapableHandleScope<'p, 'e>>

fn as_mut(&mut self) -> &mut HandleScope<'p>

Performs the conversion.

impl<'s, P> AsMut<Isolate> for TryCatch<'s, P>

fn as_mut(&mut self) -> &mut Isolate

Performs the conversion.

impl<'s, 'p, 'e, C> AsMut<TryCatch<'s, EscapableHandleScope<'p, 'e, ()>>> for TryCatch<'s, EscapableHandleScope<'p, 'e, C>>

fn as_mut(&mut self) -> &mut TryCatch<'s, EscapableHandleScope<'p, 'e, ()>>

Performs the conversion.

impl<'s, 'p, 'e> AsMut<TryCatch<'s, EscapableHandleScope<'p, 'e, Context>>> for TryCatch<'s, EscapableHandleScope<'p, 'e>>

fn as_mut(&mut self) -> &mut TryCatch<'s, EscapableHandleScope<'p, 'e>>

Performs the conversion.

impl<'s, 'p, C> AsMut<TryCatch<'s, HandleScope<'p, ()>>> for TryCatch<'s, HandleScope<'p, C>>

fn as_mut(&mut self) -> &mut TryCatch<'s, HandleScope<'p, ()>>

Performs the conversion.

impl<'s, 'p, 'e, C> AsMut<TryCatch<'s, HandleScope<'p, ()>>> for TryCatch<'s, EscapableHandleScope<'p, 'e, C>>

fn as_mut(&mut self) -> &mut TryCatch<'s, HandleScope<'p, ()>>

Performs the conversion.

impl<'s, 'p> AsMut<TryCatch<'s, HandleScope<'p, Context>>> for TryCatch<'s, HandleScope<'p>>

fn as_mut(&mut self) -> &mut TryCatch<'s, HandleScope<'p>>

Performs the conversion.

impl<'s, 'p, 'e> AsMut<TryCatch<'s, HandleScope<'p, Context>>> for TryCatch<'s, EscapableHandleScope<'p, 'e>>

fn as_mut(&mut self) -> &mut TryCatch<'s, HandleScope<'p>>

Performs the conversion.

impl<'s, 'p, 'e, C> AsRef<EscapableHandleScope<'p, 'e, ()>> for TryCatch<'s, EscapableHandleScope<'p, 'e, C>>

fn as_ref(&self) -> &EscapableHandleScope<'p, 'e, ()>

Performs the conversion.

impl<'s, 'p, 'e> AsRef<EscapableHandleScope<'p, 'e, Context>> for TryCatch<'s, EscapableHandleScope<'p, 'e>>

fn as_ref(&self) -> &EscapableHandleScope<'p, 'e>

Performs the conversion.

impl<'s, 'p, C> AsRef<HandleScope<'p, ()>> for TryCatch<'s, HandleScope<'p, C>>

fn as_ref(&self) -> &HandleScope<'p, ()>

Performs the conversion.

impl<'s, 'p, 'e, C> AsRef<HandleScope<'p, ()>> for TryCatch<'s, EscapableHandleScope<'p, 'e, C>>

fn as_ref(&self) -> &HandleScope<'p, ()>

Performs the conversion.

impl<'s, 'p> AsRef<HandleScope<'p, Context>> for TryCatch<'s, HandleScope<'p>>

fn as_ref(&self) -> &HandleScope<'p>

Performs the conversion.

impl<'s, 'p, 'e> AsRef<HandleScope<'p, Context>> for TryCatch<'s, EscapableHandleScope<'p, 'e>>

fn as_ref(&self) -> &HandleScope<'p>

Performs the conversion.

impl<'s, P> AsRef<Isolate> for TryCatch<'s, P>

fn as_ref(&self) -> &Isolate

Performs the conversion.

impl<'s, 'p, 'e, C> AsRef<TryCatch<'s, EscapableHandleScope<'p, 'e, ()>>> for TryCatch<'s, EscapableHandleScope<'p, 'e, C>>

fn as_ref(&self) -> &TryCatch<'s, EscapableHandleScope<'p, 'e, ()>>

Performs the conversion.

impl<'s, 'p, 'e> AsRef<TryCatch<'s, EscapableHandleScope<'p, 'e, Context>>> for TryCatch<'s, EscapableHandleScope<'p, 'e>>

fn as_ref(&self) -> &TryCatch<'s, EscapableHandleScope<'p, 'e>>

Performs the conversion.

impl<'s, 'p, C> AsRef<TryCatch<'s, HandleScope<'p, ()>>> for TryCatch<'s, HandleScope<'p, C>>

fn as_ref(&self) -> &TryCatch<'s, HandleScope<'p, ()>>

Performs the conversion.

impl<'s, 'p, 'e, C> AsRef<TryCatch<'s, HandleScope<'p, ()>>> for TryCatch<'s, EscapableHandleScope<'p, 'e, C>>

fn as_ref(&self) -> &TryCatch<'s, HandleScope<'p, ()>>

Performs the conversion.

impl<'s, 'p> AsRef<TryCatch<'s, HandleScope<'p, Context>>> for TryCatch<'s, HandleScope<'p>>

fn as_ref(&self) -> &TryCatch<'s, HandleScope<'p>>

Performs the conversion.

impl<'s, 'p, 'e> AsRef<TryCatch<'s, HandleScope<'p, Context>>> for TryCatch<'s, EscapableHandleScope<'p, 'e>>

fn as_ref(&self) -> &TryCatch<'s, HandleScope<'p>>

Performs the conversion.

impl<'s, P: Debug> Debug for TryCatch<'s, P>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'s, 'p> Deref for TryCatch<'s, HandleScope<'p, ()>>

type Target = HandleScope<'p, ()>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'s, 'p> Deref for TryCatch<'s, HandleScope<'p>>

type Target = HandleScope<'p>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'s, 'p, 'e> Deref for TryCatch<'s, EscapableHandleScope<'p, 'e, ()>>

type Target = EscapableHandleScope<'p, 'e, ()>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'s, 'p, 'e> Deref for TryCatch<'s, EscapableHandleScope<'p, 'e>>

type Target = EscapableHandleScope<'p, 'e>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'s, 'p> DerefMut for TryCatch<'s, HandleScope<'p, ()>>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'s, 'p> DerefMut for TryCatch<'s, HandleScope<'p>>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'s, 'p, 'e> DerefMut for TryCatch<'s, EscapableHandleScope<'p, 'e, ()>>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'s, 'p, 'e> DerefMut for TryCatch<'s, EscapableHandleScope<'p, 'e>>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'s, P> Drop for TryCatch<'s, P>

fn drop(&mut self)

Executes the destructor for this type.