Struct v8::Weak

pub struct Weak<T> { /* private fields */ }

An object reference that does not prevent garbage collection for the object, and which allows installing finalization callbacks which will be called after the object has been GC’d.

Note that finalization callbacks are tied to the lifetime of a Weak<T>, and will not be called after the Weak<T> is dropped.

Clone

Since finalization callbacks are specific to a Weak<T> instance, cloning will create a new object reference without a finalizer, as if created by Self::new. You can use Self::clone_with_finalizer to attach a finalization callback to the clone.

Implementations

impl<T> Weak<T>

pub fn new(isolate: &mut Isolate, handle: impl Handle<Data = T>) -> Self

pub fn with_finalizer( isolate: &mut Isolate, handle: impl Handle<Data = T>, finalizer: Box<dyn FnOnce(&mut Isolate)> ) -> Self

Create a weak handle with a finalization callback installed.

There is no guarantee as to when or even if the finalization callback will be invoked. The invocation is performed solely on a best effort basis. GC-based finalization should not be relied upon for any critical form of resource management! Consider using Self::with_guaranteed_finalizer instead.

The callback does not have access to the inner value, because it has already been collected by the time it runs.

pub fn with_guaranteed_finalizer( isolate: &mut Isolate, handle: impl Handle<Data = T>, finalizer: Box<dyn FnOnce()> ) -> Self

Create a weak handle with a finalization callback installed, which is guaranteed to run at some point.

Unlike Self::with_finalizer, whose finalization callbacks are not guaranteed to run, this method is guaranteed to be called before the isolate is destroyed. It can therefore be used for critical resource management. Note that other than that, there is still no guarantee as to when the callback will be called.

Unlike regular finalizers, guaranteed finalizers aren’t passed a mutable Isolate reference, since they might be called when the isolate is being destroyed, at which point it might be no longer valid to use. Accessing the isolate (with unsafe code) from the finalizer callback is therefore unsound, unless you prove the isolate is not being destroyed.

pub fn empty(isolate: &mut Isolate) -> Self

Creates a new empty handle, identical to one for an object that has already been GC’d.

pub fn clone_with_finalizer( &self, finalizer: Box<dyn FnOnce(&mut Isolate)> ) -> Self

Clones this handle and installs a finalizer callback on the clone, as if by calling Self::with_finalizer.

Note that if this handle is empty (its value has already been GC’d), the finalization callback will never run.

pub fn clone_with_guaranteed_finalizer( &self, finalizer: Box<dyn FnOnce()> ) -> Self

Clones this handle and installs a guaranteed finalizer callback on the clone, as if by calling Self::with_guaranteed_finalizer.

Note that if this handle is empty (its value has already been GC’d), the finalization callback will never run.

pub unsafe fn from_raw( isolate: &mut Isolate, data: Option<NonNull<WeakData<T>>> ) -> Self

Converts an optional raw pointer created with Weak::into_raw() back to its original Weak.

This method is called with Some, the pointer is invalidated and it cannot be used with this method again. Additionally, it is unsound to call this method with an isolate other than that in which the original Weak was created.

pub fn into_raw(self) -> Option<NonNull<WeakData<T>>>

Consume this Weak handle and return the underlying raw pointer, or None if the value has been GC’d.

The return value can be converted back into a Weak by using Weak::from_raw. Note that Weak allocates some memory, and if this method returns Some, the pointer must be converted back into a Weak for it to be freed.

Note that this method might return Some even after the V8 value has been GC’d.

pub fn is_empty(&self) -> bool

pub fn to_global(&self, isolate: &mut Isolate) -> Option<Global<T>>

pub fn to_local<'s>( &self, scope: &mut HandleScope<'s, ()> ) -> Option<Local<'s, T>>

Trait Implementations

impl<T> Clone for Weak<T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for Weak<T>

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

Formats the value using the given formatter.

impl<T> Drop for Weak<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T, Rhs: Handle> PartialEq<Rhs> for Weak<T>

where T: PartialEq<Rhs::Data>,

fn eq(&self, other: &Rhs) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, T2> PartialEq<Weak<T2>> for Weak<T>

where T: PartialEq<T2>,

fn eq(&self, other: &Weak<T2>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Eq for Weak<T>

where T: Eq,