papaya

Trait Guard

Source 
pub trait Guard {
    // Required methods
    fn refresh(&mut self);
    fn flush(&self);
    fn protect<T>(&self, ptr: &AtomicPtr<T>, ordering: Ordering) -> *mut T
       where T: AsLink;
    unsafe fn defer_retire<T>(
        &self,
        ptr: *mut T,
        reclaim: unsafe fn(_: *mut Link),
    )
       where T: AsLink;
    fn thread_id(&self) -> usize;
    fn belongs_to(&self, collector: &Collector) -> bool;
    fn link(&self, collector: &Collector) -> Link;
}
Expand description

A guard that enables protected loads of concurrent objects.

This trait provides common functionality implemented by LocalGuard, OwnedGuard, and UnprotectedGuard.

See the guide for an introduction to using guards.

Required Methods§

Source

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 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.

Source

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 batching.

Source

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

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 – but a raw pointer is returned for convenience. Data structures that return shared references to values should ensure that the lifetime of the reference is tied to the lifetime of a guard.

Source

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.

§Safety

The retired object must no longer be accessible to any thread that enters after it is removed.

Retiring the same pointer twice can cause undefined behavior, even if the reclaimer doesn’t free memory.

Additionally, the pointer must be valid to access as a Link, per the AsLink trait, and the reclaimer passed to retire must correctly free values of type T.

Source

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.

Source

fn belongs_to(&self, collector: &Collector) -> bool

Returns true if this guard belongs to the given collector.

This can be used to verify that user-provided guards are valid for the expected collector.

Create a Link that can be used to link an object to the collector.

This is identical to Collector::link, but may have slightly less overhead due to the existence of a guard.

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§