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

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

This type has the same in-memory representation as a std::sync::atomic::AtomicPtr, but provides additional functionality and stricter guarantees:

  • 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.
  • All loads and stores on this type use Acquire and Release semantics.

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.

Basic usage

To construct one, use AtomicPtr::from:

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

// Remember to retire the item stored in the AtomicPtr when it's dropped
// (assuming of course that the pointer is not also shared elsewhere):
unsafe { ptr.retire(); }

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.

Warning: When this type is dropped, it does not automatically retire the object it is currently pointing to. In order to retire (and eventually reclaim) that object, use AtomicPtr::retire or AtomicPtr::retire_in.

Implementations

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.

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.

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.

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.

This method is only available for domains with singleton families, because implementations of the unsafe Singleton trait guarantee that there is only ever one instance of a Domain with the family in question, which in turn implies that loads and stores using such a family must be using the same (single) instance of that domain.

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.

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.

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.

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

T must be Send since it may be reclaimed by a different thread.

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.

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

T must be Send since it may be reclaimed by a different thread.

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.

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.

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

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.

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.

Loads the current pointer.

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.

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.

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.

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

Formats the value using the given formatter. Read more

Converts to this type from the input type.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.