Struct Guard 

pub struct Guard { /* private fields */ }

Grants the current thread access to the managed heap.

Obtain one with pin() or Handle::pin. While the guard is alive you can allocate managed objects, load atomic pointers, and dereference the resulting Local references. A Guard is not a lock: any number of threads may hold their own guards at once. It only marks the thread as actively using the heap so the collector does not reclaim anything the thread might still reach, much like the read side of an RCU critical section.

Keep guards short-lived

A long-lived guard prevents the collector from reclaiming garbage, so drop it as soon as you stop loading new pointers. To keep a reference past the guard, promote it to a Local<Handle, T> with Local::protect (hazard-pointer protected) or to a Shared<T> with Local::as_shared (root-count protected). The Local<Handle, T> form is generally cheaper to create.

Examples

let guard = pin();                                // enter a critical section
let cell = AtomicShared::new(Node { value: 1 }, &guard);
let node = cell.load(Ordering::Acquire, &guard);  // load a pointer
assert_eq!(node.value, 1);                         // dereference it
drop(guard);                                       // let the collector proceed

Implementations

impl Guard

pub fn repin(&mut self)

Lets the collector make progress during a long-running loop.

Briefly unpins and re-pins the thread, refreshing the local epoch so the collector is not blocked indefinitely. Takes &mut self to statically ensure no Local<Guard, T> references are held across the call. To keep those references alive across this call, consider promoting them (see the struct-level docs).

Only effective when this is the sole active guard for the current thread.

Examples

let mut guard = pin();
for _ in 0..3 {
    // ... a chunk of work using `&guard` ...
    guard.repin(); // let the collector make progress between chunks
}

pub fn help_collect(&self)

Voluntarily assists the collector with pending work.

Called automatically during intensive allocation, but you can invoke it explicitly in long-running operations to help the collector make progress, for example sweeping dead objects or tracing live ones.

Examples

let guard = pin();
// In a long loop that rarely allocates, lend the collector a hand.
guard.help_collect();

Trait Implementations

impl Drop for Guard

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Protector for Guard

type Shield = ()

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