Struct HzrdCell 

pub struct HzrdCell<T, D = GlobalDomain> { /* private fields */ }

Holds a value protected by hazard pointers.

Each HzrdCell belongs to a given domain, which contains the set of hazard pointers protecting the value. See the Domain trait for more details on this.

See the crate-level documentation for a “getting started” guide.

Implementations

impl<T: 'static> HzrdCell<T>

pub fn new(value: T) -> Self

Construct a new HzrdCell with the given value in the default domain.

The default domain is a globally shared domain, see GlobalDomain for more information on this domain. This is the recommended way for constructing HzrdCells, unless you really know what you’re doing, in which case you can use HzrdCell::new_in to construct a new cell in a custom domain.

Note

The value held in the cell will be allocated on the heap via Box, and is stored seperate from the metadata associated with the HzrdCell.

Example

let cell = HzrdCell::new(0);

impl<T: 'static, D: Domain> HzrdCell<T, D>

pub fn set(&self, value: T)

Set the value of the cell

This will perform the following operations (in this order):

• Allocate the new value on the heap using Box
• Swap out the old value for the new value
• Retire the old value
• Reclaim retired values, if possible

Example

let cell = HzrdCell::new(0);
cell.set(1);

pub fn just_set(&self, value: T)

Set the value of the cell without attempting to reclaim memory

pub fn read(&self) -> ReadHandle<'_, T>

Get a handle holding a reference to the current value held by the HzrdCell

The functionality of this is somewhat similar to a MutexGuard, except the ReadHandle only accepts reading the value. There is no locking mechanism needed to grab this handle, although there might be a short wait if the read overlaps with a write.

The ReadHandle acquired holds a shared reference to the value of the HzrdCell as it was when the read function was called. If the value of the HzrdCell is changed after the ReadHandle is acquired its new value is not reflected in the value of the ReadHandle. The hazard pointer held by the handle will keep the old value alive. See the documentation of ReadHandle for more information.

Example

let cell = HzrdCell::new(String::from("Hey"));

let handle = cell.read();

// We can create multiple references from a single handle
let string: &str = &*handle;
let bytes: &[u8] = handle.as_bytes();

assert_eq!(string, "Hey");
assert_eq!(bytes, [72, 101, 121]);

pub fn get(&self) -> T

where T: Copy,

Read the associated value and copy it (requires the type to be Copy)

Example

let cell = HzrdCell::new(100);
assert_eq!(cell.get(), 100);

pub fn reclaim(&self)

Reclaim available memory, if possible

Example

let cell = HzrdCell::new(0);

cell.just_set(1); // Current garbage: [0]
cell.just_set(2); // Current garbage: [0, 1]
cell.reclaim(); // Current garbage: []

pub fn reader(&self) -> HzrdReader<'_, T>

Construct a reader to the current cell

Constructing a reader can be helpful (and more performant) when doing consecutive reads, as the reader will hold a HzrdPtr which will be reused for each read. The reader exposes a similar API to HzrdCell, with the exception of “write-actions” such as HzrdCell::set & HzrdCell::reclaim. See HzrdReader for more details.

Example

let cell = HzrdCell::new(false);
let reader = cell.reader();

impl<T: 'static, D> HzrdCell<T, D>

pub fn new_in(value: T, domain: D) -> Self

Construct a new HzrdCell in the given domain.

This method is aimed at more advanced usage of this library, as it requires more knowledge about hazard pointer domains and how they work The recommended way for most users to construct a HzrdCell is using the new function, which uses a globally shared domain.

A good starting point for using this function is to understand the basics of the Domain trait. You can then browse the various implementations of this trait provided by this crate in the domains-module.

Note

The value held in the cell will be allocated on the heap via Box, and is stored seperate from the metadata associated with the HzrdCell.

let cell = HzrdCell::new_in(0, SharedDomain::new());

Trait Implementations

impl<T, D> Drop for HzrdCell<T, D>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Send, D: Send> Send for HzrdCell<T, D>

impl<T: Send + Sync, D: Send + Sync> Sync for HzrdCell<T, D>