Struct haphazard::AtomicPtr

#[repr(transparent)]
pub struct AtomicPtr<T, F = Global, P = Box<T>>(_, _);

A managed pointer type which can be safely shared between threads.

Unlike std::sync::AtomicPtr, haphazard::AtomicPtr can safely load &T directly, and ensure that the referenced T is not deallocated until the &T is dropped, even in the presence of concurrent writers. Also unlike std::sync::AtomicPtr, all loads and stores on this type use Acquire and Release semantics.

To construct one, use AtomicPtr::from:

let _: AtomicPtr<usize> = AtomicPtr::from(Box::new(42));

Note the explicit use of AtomicPtr<usize>, which is needed to get the default values for the generic arguments F and P, the domain family and pointer types of the stored values. Families are discussed in the documentation for Domain. The pointer type P, which must implement raw::Pointer, is the type originaly used to produce the stored pointer. This is used to ensure that when writers drop a value, it is dropped using the appropriate Drop implementation.

This type has the same in-memory representation as a std::sync::AtomicPtr.

Note: This type is only available on platforms that support atomic loads and stores of pointers. Its size depends on the target pointer’s size.

Implementations

impl<T, F, P> AtomicPtr<T, F, P>

pub unsafe fn new(p: *mut T) -> Self

Directly construct an AtomicPtr from a raw pointer.

Safety

1. p must reference a valid T, or be null.
2. p must have been allocated using the pointer type P.
3. *p must only be dropped through Domain::retire_ptr.

pub unsafe fn as_std(&self) -> &AtomicPtr<T>

Directly access the “real” underlying AtomicPtr.

Safety

If the stored pointer is modified, the new value must conform to the same safety requirements as the argument to AtomicPtr::new.

pub unsafe fn as_std_mut(&mut self) -> &mut AtomicPtr<T>

Directly access the “real” underlying AtomicPtr mutably.

Safety

If the stored pointer is modified, the new value must conform to the same safety requirements as the argument to AtomicPtr::new.

impl<T, P> AtomicPtr<T, Global, P>

pub fn safe_load<'hp>(
    &self,
    hp: &'hp mut HazardPointer<'static, Global>
) -> Option<&'hp T> where
    T: 'hp, 

Loads the value from the stored pointer and guards it using the given hazard pointer.

The guard ensures that the loaded T will remain valid for as long as you hold a reference to it.

Note that this method is only available when using Domain<Global>, since it is a singleton, and thus is guaranteed to fulfill the safety requirement of AtomicPtr::load. For all other domains, use AtomicPtr::load.

impl<T, F, P> AtomicPtr<T, F, P>

pub unsafe fn load<'hp, 'd>(
    &self,
    hp: &'hp mut HazardPointer<'d, F>
) -> Option<&'hp T> where
    T: 'hp,
    F: 'static, 

Loads the value from the stored pointer and guards it using the given hazard pointer.

The guard ensures that the loaded T will remain valid for as long as you hold a reference to it.

Safety

All objects stored in this AtomicPtr are retired through the same Domain as the one that produced hp.

This requirement is partially enforced by the domain family (F), but it’s on you to ensure that you don’t “cross the streams” between multiple Domain<F>, if those can arise in your application.

pub unsafe fn get_mut(&mut self) -> &mut *mut T

Returns a mutable reference to the underlying pointer.

Safety

If the stored pointer is modified, the new value must conform to the same safety requirements as the argument to AtomicPtr::new.

pub fn into_inner(self) -> *mut T

Consumes the atomic and returns the contained value.

This is safe because passing self by value guarantees that no other threads are concurrently accessing the atomic data, and no loads can happen in the future.

impl<T, P> AtomicPtr<T, Global, P> where
    P: Pointer<T>, 

pub unsafe fn retire(self) -> usize

Retire the currently-referenced object, and reclaim it once it is safe to do so.

Safety

1. The currently-referenced object will never again be returned by any AtomicPtr::load.
2. The currently-referenced object has not already been retired.

impl<T, F, P> AtomicPtr<T, F, P> where
    P: Pointer<T>, 

pub unsafe fn retire_in(self, domain: &Domain<F>) -> usize

Retire the currently-referenced object, and reclaim it once it is safe to do so, through the given domain.

Safety

1. The currently-referenced object will never again be returned by any AtomicPtr::load.
2. The currently-referenced object has not already been retired.
3. All calls to load that can have seen the currently-referenced object were using hazard pointers from domain.

Note that requirement #3 is partially enforced by the domain family (F), but it’s on you to ensure that you don’t “cross the streams” between multiple Domain<F>, if those can arise in your application.

pub fn store(&self, p: P)

Store an object into the pointer.

Note, crucially, that this will not automatically retire the pointer that’s currently stored, which is why it is safe.

pub fn swap(&self, p: P) -> Option<Replaced<T, F, P>>

Overwrite the currently stored pointer with the given one, and return the previous pointer.

pub fn compare_exchange(
    &self,
    current: *mut T,
    new: P
) -> Result<Option<Replaced<T, F, P>>, P>

Stores an object into the pointer if the current pointer is current.

The return value is a result indicating whether the new value was written and containing the previous value. On success this value is guaranteed to be equal to current.

pub fn compare_exchange_weak(
    &self,
    current: *mut T,
    new: P
) -> Result<Option<Replaced<T, F, P>>, P>

Stores an object into the pointer if the current pointer is current.

Unlike AtomicPtr::compare_exchange, this function is allowed to spuriously fail even when the comparison succeeds, which can result in more efficient code on some platforms. The return value is a result indicating whether the new value was written and containing the previous value. On success this value is guaranteed to be equal to current.

impl<T, F, P> AtomicPtr<T, F, P>

pub fn load_ptr(&self) -> *mut T

Loads the current pointer.

pub unsafe fn store_ptr(&self, ptr: *mut T)

Overwrite the currently stored pointer with the given one.

Note, crucially, that this will not automatically retire the pointer that’s currently stored.

Safety

ptr must conform to the same safety requirements as the argument to [AtomicPtr::new`].

pub unsafe fn swap_ptr(&self, ptr: *mut T) -> Option<Replaced<T, F, P>>

Overwrite the currently stored pointer with the given one, and return the previous pointer.

Safety

ptr must conform to the same safety requirements as the argument to [AtomicPtr::new`].

pub unsafe fn compare_exchange_ptr(
    &self,
    current: *mut T,
    new: *mut T
) -> Result<Option<Replaced<T, F, P>>, *mut T>

Stores new if the current pointer is current.

The return value is a result indicating whether the new pointer was written and containing the previous pointer. On success this value is guaranteed to be equal to current.

Safety

ptr must conform to the same safety requirements as the argument to [AtomicPtr::new`].

pub unsafe fn compare_exchange_weak_ptr(
    &self,
    current: *mut T,
    new: *mut T
) -> Result<Option<Replaced<T, F, P>>, *mut T>

Stores new if the current pointer is current.

Unlike AtomicPtr::compare_exchange, this function is allowed to spuriously fail even when the comparison succeeds, which can result in more efficient code on some platforms. The return value is a result indicating whether the new pointer was written and containing the previous pointer. On success this value is guaranteed to be equal to current.

Safety

ptr must conform to the same safety requirements as the argument to [AtomicPtr::new`].

Trait Implementations

impl<T, F, P> From<P> for AtomicPtr<T, F, P> where
    P: Pointer<T>, 

fn from(p: P) -> Self

Performs the conversion.