Trait Guard 

pub trait Guard {
    // Required methods
    fn refresh(&mut self);
    fn flush(&self);
    fn collector(&self) -> &Collector;
    fn thread_id(&self) -> usize;
    unsafe fn defer_retire<T>(
        &self,
        ptr: *mut T,
        reclaim: unsafe fn(*mut T, &Collector),
    );

    // Provided methods
    fn protect<T>(&self, ptr: &AtomicPtr<T>, order: Ordering) -> *mut T { ... }
    fn swap<T>(
        &self,
        ptr: &AtomicPtr<T>,
        value: *mut T,
        order: Ordering,
    ) -> *mut T { ... }
    fn compare_exchange<T>(
        &self,
        ptr: &AtomicPtr<T>,
        current: *mut T,
        new: *mut T,
        success: Ordering,
        failure: Ordering,
    ) -> Result<*mut T, *mut T> { ... }
    fn compare_exchange_weak<T>(
        &self,
        ptr: &AtomicPtr<T>,
        current: *mut T,
        new: *mut T,
        success: Ordering,
        failure: Ordering,
    ) -> Result<*mut T, *mut T> { ... }
}

A guard that enables protected loads of concurrent objects.

This trait provides common functionality implemented by LocalGuard and OwnedGuard. See the guide for an introduction to using guards.

Required Methods

fn refresh(&mut self)

Refreshes the guard.

Calling this method is similar to dropping and immediately creating a new guard. The current 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 loaded using Guard::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.

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.

Note that the batch must contain at least as many objects as the number of currently active threads for a flush to be performed. See Collector::batch_size for details about batch sizes.

fn collector(&self) -> &Collector

Returns the collector this guard was created from.

fn thread_id(&self) -> usize

Returns a numeric identifier for the current thread.

Guards rely on thread-local state, including thread IDs. This method is a cheap way to get an identifier for the current thread without TLS overhead. Note that thread IDs may be reused, so the value returned is only unique for the lifetime of this thread.

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

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.

Safety

The retired pointer must no longer be accessible to any thread that enters after it is removed. Additionally, the pointer must be valid to pass to the provided reclaimer, once it is safe to reclaim.

Provided Methods

fn protect<T>(&self, ptr: &AtomicPtr<T>, order: Ordering) -> *mut T

Protects the load of an atomic pointer.

Any valid pointer loaded through a guard using the protect method is guaranteed to stay valid until the guard is dropped, or the object is retired by the current thread. Importantly, if another thread retires this object, it will not be reclaimed for the lifetime of this guard.

Note that the lifetime of a guarded pointer is logically tied to that of the guard — when the guard is dropped the pointer is invalidated. Data structures that return shared references to values should ensure that the lifetime of the reference is tied to the lifetime of a guard.

fn swap<T>(&self, ptr: &AtomicPtr<T>, value: *mut T, order: Ordering) -> *mut T

Stores a value into the pointer, returning the protected previous value.

This method is equivalent to AtomicPtr::swap, except the returned value is guaranteed to be protected with the same guarantees as Guard::protect.

fn compare_exchange<T>( &self, ptr: &AtomicPtr<T>, current: *mut T, new: *mut T, success: Ordering, failure: Ordering, ) -> Result<*mut T, *mut T>

Stores a value into the pointer if the current value is the same as the current value, returning the protected previous value.

This method is equivalent to AtomicPtr::compare_exchange, except the returned value is guaranteed to be protected with the same guarantees as Guard::protect.

fn compare_exchange_weak<T>( &self, ptr: &AtomicPtr<T>, current: *mut T, new: *mut T, success: Ordering, failure: Ordering, ) -> Result<*mut T, *mut T>

Stores a value into the pointer if the current value is the same as the current value, returning the protected previous value.

This method is equivalent to AtomicPtr::compare_exchange_weak, except the returned value is guaranteed to be protected with the same guarantees as Guard::protect.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Guard for LocalGuard<'_>

impl Guard for OwnedGuard<'_>