Struct Guard 

pub struct Guard<'a> { /* private fields */ }

A guard that keeps the current thread marked as active, enabling protected loads of atomic pointers.

See Collector::enter for details.

Implementations

impl Guard<'_>

pub const unsafe fn unprotected() -> Guard<'static>

Returns a dummy guard.

Calling protect on an unprotected guard will load the pointer directly, and retire will reclaim objects immediately.

Unprotected guards are useful when calling guarded functions on a data structure that has just been created or is about to be destroyed, because you know that no other thread holds a reference to it.

Safety

You must ensure that code used with this guard is sound with the unprotected behavior described above.

pub fn protect<T>(&self, ptr: &Atomic<*mut T>, ordering: Ordering) -> *mut T

where T: AsLink,

Protects the load of an atomic pointer.

See the guide for details.

pub unsafe fn defer_retire<T>(&self, ptr: *mut T, reclaim: unsafe fn(*mut Link))

where T: AsLink,

Retires a value, running reclaim when no threads hold a reference to it.

This method delays reclamation until the guard is dropped as opposed to Collector::retire, which may reclaim objects immediately.

See the guide for details.

pub fn collector(&self) -> Option<&Collector>

Get a reference to the collector this guard we created from.

This method is useful when you need to ensure that all guards used with a data structure come from the same collector.

If this is an unprotected guard this method will return None.

pub fn refresh(&mut self)

Refreshes the guard.

Refreshing a guard is similar to dropping and immediately creating a new guard. The curent thread remains active, but any pointers that were previously protected may be reclaimed.

Safety

This method is not marked as unsafe, but will affect the validity of pointers returned by protect, similar to dropping a guard. It is intended to be used safely by users of concurrent data structures, as references will be tied to the guard and this method takes &mut self.

If this is an unprotected guard this method will be a no-op.

pub fn flush(&self)

Flush any retired values in the local batch.

This method flushes any values from the current thread’s local batch, starting the reclamation process. Note that no memory can be reclaimed while this guard is active, but calling flush may allow memory to be reclaimed more quickly after the guard is dropped.

See Collector::batch_size for details about batching.

pub fn thread_id(&self) -> usize

Returns a numeric identifier for the current thread.

Guards rely on thread-local state, including thread IDs. If you already have a guard you can use this method to get a cheap identifier for the current thread, avoiding TLS overhead. Note that thread IDs may be reused, so the value returned is only unique for the lifetime of this thread.

Trait Implementations

impl Debug for Guard<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

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.