pub struct Weak<T> { /* private fields */ }
Expand description
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§
source§impl<T> Weak<T>
impl<T> Weak<T>
pub fn new(isolate: &mut Isolate, handle: impl Handle<Data = T>) -> Self
sourcepub fn with_finalizer(
isolate: &mut Isolate,
handle: impl Handle<Data = T>,
finalizer: Box<dyn FnOnce(&mut Isolate)>
) -> 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.
sourcepub fn with_guaranteed_finalizer(
isolate: &mut Isolate,
handle: impl Handle<Data = T>,
finalizer: Box<dyn FnOnce()>
) -> Self
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.
sourcepub fn empty(isolate: &mut Isolate) -> 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.
sourcepub fn clone_with_finalizer(
&self,
finalizer: Box<dyn FnOnce(&mut Isolate)>
) -> Self
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.
sourcepub fn clone_with_guaranteed_finalizer(
&self,
finalizer: Box<dyn FnOnce()>
) -> Self
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.
sourcepub unsafe fn from_raw(
isolate: &mut Isolate,
data: Option<NonNull<WeakData<T>>>
) -> 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.
sourcepub fn into_raw(self) -> Option<NonNull<WeakData<T>>>
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.