Struct Deferred

pub struct Deferred { /* private fields */ }

A batch of pointers to be reclaimed in the future.

Sometimes it is necessary to defer the retirement of a batch of pointers. For example, a set of pointers may be reachable from multiple locations in a data structure and can only be retired after a specific object is reclaimed. In such cases, the Deferred type can serve as a cheap place to defer the retirement of pointers, without allocating extra memory.

Deferred is a concurrent list, meaning that pointers can be added from multiple threads concurrently. It is not meant to be used to amortize the cost of retirement, which is done through thread-local batches controlled with Collector::batch_size, as access from a single-thread can be more expensive than is required. Deferred batches are useful when you need to control when a batch of objects is retired directly, a relatively rare use case.

Examples

let collector = Collector::new().batch_size(10);

// allocate a set of pointers
let items = (0..10)
    .map(|i| AtomicPtr::new(collector.link_boxed(i)))
    .collect::<Arc<[_]>>();

// create a batch of objects to retire
let mut batch = Deferred::new();

for item in items.iter() {
    // make the item unreachable with an atomic swap
    let old = item.swap(std::ptr::null_mut(), Ordering::AcqRel);
    // don't retire just yet, add the object to the batch
    unsafe { batch.defer(old) };
}

// sometime later... retire all the items in the batch
unsafe { batch.retire_all(&collector, reclaim::boxed::<Linked<usize>>) }

Implementations

impl Deferred

pub const fn new() -> Deferred

Create a new batch of deferred objects.

pub unsafe fn defer<T: AsLink>(&self, ptr: *mut T)

Add an object to the batch.

Safety

After this method is called, it is undefined behavior to add this pointer to the batch again, or any other batch. The pointer must also be valid for access as a Link, per the AsLink trait.

pub unsafe fn retire_all( &mut self, collector: &Collector, reclaim: unsafe fn(*mut Link), )

Retires a batch of values, running reclaim when no threads hold a reference to any objects in the batch.

Note that this method is disconnected from any guards on the current thread, so the pointers may be reclaimed immediately.

Safety

The safety requirements of Collector::retire apply to each object in the batch.

pub fn for_each(&mut self, f: impl FnMut(*mut Node))

Run a function for each object in the batch.

This function does not consume the batch and can be called multiple times, before retirement.

Trait Implementations

impl Default for Deferred

fn default() -> Deferred

Returns the “default value” for a type.