Struct peril::HazardPointer

pub struct HazardPointer<T: Send + ?Sized> { /* fields omitted */ }

is the an atomic pointer that is safe to read when it is protected

Examples

use peril::{HazardRegistry, HazardValue, HazardRecord, HazardPointer};

let registry = HazardRegistry::default();
let hp = HazardPointer::new(HazardValue::boxed("test"));
let mut record = HazardRecord::default();
loop {
    let scope = hp.protect(&registry, &mut record);
    // ...
    break;
}

Implementations

impl<T: Send + ?Sized> HazardPointer<T>

pub fn new(value: HazardValue<'_, T>) -> HazardPointer<T>

create a HazardPointer

Arguments

• value - the HazardValue the pointer is initzialized with

Examples

use peril::{HazardRegistry, HazardValue, HazardRecord, HazardPointer, Ordering};

let hp = HazardPointer::new(HazardValue::boxed("test"));

#[must_use]pub fn protect<'registry, 'hazard>(
    &'hazard self,
    registry: &'registry HazardRegistry<T>,
    record: &'hazard mut HazardRecord<'registry>
) -> HazardScope<'registry, 'hazard, T>

protect the hazardpointer so that it is safe to read and update using a CAS operation

Arguments

• registry - the HazardRegistry the pointer is registered with, usually HazardPointers in the same system share a common Registry
• record - the HazardRecord, which caches an expensive operation for multiple itterations of the update loop

Examples

use peril::{HazardRegistry, HazardValue, HazardRecord, HazardPointer};

let registry = HazardRegistry::default();
let hp = HazardPointer::new(HazardValue::boxed("test"));
let mut record = HazardRecord::default();
loop {
    let scope = hp.protect(&registry, &mut record);
    // ...
    break;
}

pub fn compare_exchange_weak<'registry>(
    &self,
    registry: &'registry HazardRegistry<T>,
    current: HazardValue<'registry, T>,
    new: HazardValue<'registry, T>,
    success: Ordering,
    failure: Ordering
) -> Result<HazardValue<'registry, T>, HazardValue<'registry, T>>

compare_exchange_weak version of HazardPointer that uses a HazardValue as it's current value (comperator) When the CAS succeeds it will return the previous value held by the HazardPointer and when the CAS fails it will return the new value we just provided. for more detail see compare_exchange

Arguments

• registry - the HazardRegistry the pointer is registered with, usually HazardPointers in the same system share a common Registry
• current - the HazardValue used as a comparator
• new - the new value the HazardPointer should have when the CAS succeeds (and returned when the CAS fails)
• success - the Ordering when the CAS succeeds
• failure - the Ordering when the CAS fails
• return - Result wrapping the old value if the CAS succeeds or the new value if it failed

Examples

use peril::{HazardRegistry, HazardValue, HazardPointer, Ordering};

let registry = HazardRegistry::default();
let hp = HazardPointer::<usize>::new(HazardValue::dummy(1));
loop {
    if hp.compare_exchange_weak(&registry, HazardValue::dummy(1), HazardValue::dummy(0), Ordering::Relaxed, Ordering::Relaxed).is_ok()
    {
        break;
    }
}

pub fn compare_exchange<'registry>(
    &self,
    registry: &'registry HazardRegistry<T>,
    current: HazardValue<'registry, T>,
    new: HazardValue<'registry, T>,
    success: Ordering,
    failure: Ordering
) -> Result<HazardValue<'registry, T>, HazardValue<'registry, T>>

compare_exchange version of HazardPointer that uses a HazardValue as it's current value (comperator) When the CAS succeeds it will return the previous value held by the HazardPointer and when the CAS fails it will return the new value we just provided. for more detail see compare_exchange

Arguments

• registry - the HazardRegistry the pointer is registered with, usually HazardPointers in the same system share a common Registry
• current - the HazardValue used as a comparator
• new - the new value the HazardPointer should have when the CAS succeeds (and returned when the CAS fails)
• success - the Ordering when the CAS succeeds
• failure - the Ordering when the CAS fails
• return - Result wrapping the old value if the CAS succeeds or the new value if it failed

Examples

use peril::{HazardRegistry, HazardValue, HazardPointer, Ordering};

let registry = HazardRegistry::default();
let hp = HazardPointer::<usize>::new(HazardValue::dummy(1));
loop {
    if hp.compare_exchange(&registry, HazardValue::dummy(1), HazardValue::dummy(0), Ordering::Relaxed, Ordering::Relaxed).is_ok()
    {
        break;
    }
}

pub fn swap<'registry>(
    &self,
    registry: &'registry HazardRegistry<T>,
    new: HazardValue<'registry, T>,
    order: Ordering
) -> HazardValue<'registry, T>

swaps the value of a HazardPointer returning the old value

Arguments

• registry - the HazardRegistry the pointer is registered with, usually HazardPointers in the same system share a common Registry
• new - the HazardValue after the swap
• order - the Ordering during the swap operation
• return - the HazardValue before the swap

Examples

use peril::{HazardRegistry, HazardValue, HazardRecord, HazardPointer, Ordering};

let registry = HazardRegistry::default();
let hp = HazardPointer::new(HazardValue::boxed("test"));
let old = hp.swap(&registry, HazardValue::boxed("test2"), Ordering::Relaxed);
assert!(old.as_ref().unwrap() == &"test");

pub fn swap_null<'registry>(
    &self,
    registry: &'registry HazardRegistry<T>,
    order: Ordering
) -> HazardValue<'registry, T>

swaps the value of a HazardPointer with a null dummy HazardValue

Arguments

• registry - the HazardRegistry the pointer is registered with, usually HazardPointers in the same system share a common Registry
• order - the Ordering during the swap operation
• return - the HazardValue before the swap

Examples

use peril::{HazardRegistry, HazardValue, HazardRecord, HazardPointer, Ordering};

let registry = HazardRegistry::default();
let hp = HazardPointer::new(HazardValue::boxed("test"));
let old = hp.swap_null(&registry, Ordering::Relaxed);
assert!(old.as_ref().unwrap() == &"test");
let old = hp.swap_null(&registry, Ordering::Relaxed);
assert!(old.as_dummy().unwrap() == 0);

pub fn store<'registry>(
    &self,
    registry: &'registry HazardRegistry<T>,
    new: HazardValue<'registry, T>,
    order: Ordering
)

stores a new value of a HazardPointer and drops the old value, this internally uses a swap operation

Arguments

• registry - the HazardRegistry the pointer is registered with, usually HazardPointers in the same system share a common Registry
• new - the HazardValue after the store
• order - the Ordering during the store operation

Examples

use peril::{HazardRegistry, HazardValue, HazardRecord, HazardPointer, Ordering};

let registry = HazardRegistry::default();
let hp = HazardPointer::new(HazardValue::boxed("test"));
hp.store(&registry, HazardValue::dummy(1337), Ordering::Relaxed);
let old = hp.swap(&registry, HazardValue::boxed("test2"), Ordering::Relaxed);
assert!(old.as_dummy().unwrap() == 1337);

pub fn get_dummy(&self, order: Ordering) -> Option<usize>

get the value of the HazardPointer but only if it is a dummy

Arguments

• order - the Ordering during the store operation

Examples

use peril::{HazardRegistry, HazardValue, HazardRecord, HazardPointer, Ordering};

let hp = HazardPointer::<usize>::new(HazardValue::dummy(1337));
assert!(hp.get_dummy(Ordering::Relaxed).unwrap() == 1337);

Trait Implementations

impl<T: Send + ?Sized> Drop for HazardPointer<T>

pub fn drop(&mut self)

Executes the destructor for this type.