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 the finalization callback will be invoked. However, unlike the C++ API, this API guarantees that when an isolate is destroyed, any finalizers that haven’t been called yet will be run, unless a Global reference is keeping the object alive. Other than that, there is still no guarantee as to when the finalizers will be called.

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

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

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,