Trait zerogc::GcHandle

pub unsafe trait GcHandle<T: GcSafe<'static, Self::Id> + ?Sized>: Sized + Clone + NullTrace + for<'gc> GcSafe<'gc, Self::Id> {
    type System: GcSystem<Id = Self::Id>;
    type Id: CollectorId;
    fn use_critical<R>(&self, func: impl FnOnce(&T) -> R) -> R;
    fn bind_to<'new_gc>(
        &self, 
        context: &'new_gc <Self::System as GcSystem>::Context
    ) -> Gc<'new_gc, <T as GcRebrand<'new_gc, Self::Id>>::Branded, Self::Id>
    where
        T: GcRebrand<'new_gc, Self::Id>;
}

A owned handle which points to a garbage collected object.

This is considered a root by the garbage collector that is independent of any specific GcContext. Safepoints don’t need to be informed of this object for collection to start. The root is manually managed by user-code, much like a Box or a reference counted pointer.

This can be cloned and stored independently from a context, bridging the gap between native memory and managed memory. These are useful to pass to C APIs or any other code that doesn’t cooperate with zerogc.

Tracing

The object behind this handle is already considered a root of the collection. It should always be considered reachable by the garbage collector.

Validity is tracked by this smart-pointer and not by tracing. Therefore it is safe to implement NullTrace for handles.

Associated Types

type System: GcSystem<Id = Self::Id>

The type of the system used with this handle

type Id: CollectorId

The type of CollectorId used with this sytem

Required methods

fn use_critical<R>(&self, func: impl FnOnce(&T) -> R) -> R

Access this handle inside the closure, possibly associating it with the specified

This is accesses the object within “critical section” that will block collections for as long as the closure is in use.

These calls cannot be invoked recursively or they may cause a deadlock.

This is similar in purpose to JNI’s GetPrimitiveArrayCritical. However it never performs a copy, it is just guarenteed to block any collections.

fn bind_to<'new_gc>(
    &self,
    context: &'new_gc <Self::System as GcSystem>::Context
) -> Gc<'new_gc, <T as GcRebrand<'new_gc, Self::Id>>::Branded, Self::Id> where
    T: GcRebrand<'new_gc, Self::Id>, 

Associate this handle with the specified context, allowing its underlying object to be accessed as long as the context is valid.

The underlying object can be accessed just like any other object that would be allocated from the context. It’ll be properly collected and can even be used as a root at the next safepoint.

Implementors