Struct Handle 

pub struct Handle { /* private fields */ }

A thread-local handle to the garbage collector.

Obtain one with handle(). A Handle is cheap to clone (it is reference-counted) and serves two purposes:

1. Accessing the managed heap. Call pin() to get a Guard that lets you allocate, load, and dereference managed pointers.
2. Extending pointer lifetimes. Pass it to Local::protect to keep a reference alive past its Guard with hazard-pointer protection.

Examples

let handle = handle();
let guard = handle.pin();
let node = Local::new(Node { value: 1 }, &guard);
let kept = node.protect(&handle); // outlives the guard
drop(guard);
assert_eq!(kept.value, 1);

Implementations

impl Handle

pub fn pin(&self) -> Guard

Returns a Guard that grants access to the managed heap.

While the guard is alive, you may allocate managed objects, load atomic pointers, and freely dereference any Local obtained from those loads. Internally, this pins the current thread to the global epoch (entering a phase-critical section).

Examples

let handle = handle();
let guard = handle.pin();
// ... access the managed heap through `guard` ...
drop(guard);

pub fn is_pinned(&self) -> bool

Returns true if this handle’s thread is currently pinned, that is, if a Guard obtained from this handle is alive.

Examples

let handle = handle();
assert!(!handle.is_pinned());
let guard = handle.pin();
assert!(handle.is_pinned());
drop(guard);
assert!(!handle.is_pinned());

pub fn help_collect(&self)

Voluntarily assists the collector with pending work.

Useful in long-running threads that rarely allocate: calling it periodically helps the collector make progress. It pins the thread briefly for the duration of the call.

Examples

let handle = handle();
handle.help_collect();

Trait Implementations

impl Clone for Handle

fn clone(&self) -> Handle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Protector for Handle

type Shield = HazardPointer

fn protect<T: TraceObj>(&self, ptr: ManPtr<T>) -> Self::Shield