pub struct HazardPointer<'domain, F = Global> { /* private fields */ }
Expand description

A type that can protect a referenced object from reclamation.

Protects up to a single address from concurrent reclamation in the referenced Domain.

A hazard pointer does nothing when initially constructed. You need to load the pointer stored by an std::sync::atomic::AtomicPtr through it with HazardPointer::protect in order for it to protect an object. That protection is tied to the exclusive (&mut) borrow of the HazardPointer that protect takes; the moment the exclusive borrow ends (such as when the HazardPointer is dropped), the protection ends.

Note that a hazard pointer can only protect an object if any call to retire for said object happens in the same domain as the one the hazard pointer was created in. The generic argument F is a domain family, which helps enforce that statically. Families are discussed in the documentation for Domain. F defaults to the global domain.

If you want a (slightly) higher-level interface, use AtomicPtr.

If you need to protect multiple referenced objects at the same time, use HazardPointerArray.

Implementations§

Create a new hazard pointer in the global domain.

Create a new hazard pointer array in the global domain.

Create a new hazard pointer in the given domain.

Create a new hazard pointer array in the given domain.

Protect the value loaded from the given AtomicPtr, and dereference it to &T.

This operation will load the AtomicPtr multiple times:

  1. load to get the currently stored pointer, ptr
  2. store ptr into the hazard pointer to protect it from reclamation
  3. load again to check that the pointer didn’t change between 1 and 2. if it did, set the loaded value to ptr and goto 2.

Returns None if the loaded pointer is null.

T must be Sync since we do not know which thread stored the pointer in the first place.

Safety
  1. The value loaded from AtomicPtr is a valid &T, or null.
  2. The loaded &T will only be deallocated through calls to retire functions on the same Domain as this holder is associated with.

Protect the value loaded from the given AtomicPtr, and return it as NonNull<T>.

This operation will load the AtomicPtr multiple times:

  1. load to get the currently stored pointer, ptr
  2. store ptr into the hazard pointer to protect it from reclamation
  3. load again to check that the pointer didn’t change between 1 and 2. if it did, set the loaded value to ptr and goto 2.

Note that protecting a given pointer only has an effect if any thread that may drop the pointer does so through the same Domain as this hazard pointer is associated with.

Returns None if the loaded pointer is null.

Protect ptr and dereference it to &T if it’s safe to do so.

Unlike HazardPointer::protect, this operation will not load the AtomicPtr multiple times. It will only perform a single load to check that the stored pointer does not change before we have a chance to protect ptr.

If the value has changed, the new pointer is returned wrapped in Err.

T must be Sync since we do not know which thread stored the pointer in the first place.

Returns Ok(None) if ptr.is_null().

Safety
  1. The value loaded from AtomicPtr is a valid &T, or null.
  2. The loaded &T will only be deallocated through calls to retire functions on the same Domain as this holder is associated with.

Protect ptr and dereference it to NonNull<T> if it’s safe to do so.

Unlike HazardPointer::protect_ptr, this operation will not load the AtomicPtr multiple times. It will only perform a single load to check that the stored pointer does not change before we have a chance to protect ptr.

Note that protecting a given pointer only has an effect if any thread that may drop the pointer does so through the same Domain as this hazard pointer is associated with.

If the value has changed, the new pointer is returned wrapped in Err.

Returns Ok(None) if ptr.is_null().

Release the protection awarded by this hazard pointer, if any.

If the hazard pointer was protecting an object, that object may now be reclaimed when retired (assuming it isn’t protected by any other hazard pointers).

Protect the given address.

You will very rarely want to use this method, and should prefer the other protection methods instead, as they guard against races between when the value of a shared pointer was read and any changes to the shared pointer address.

Note that protecting a given pointer only has an effect if any thread that may drop the pointer does so through the same Domain as this hazard pointer is associated with.

Trait Implementations§

Returns the “default value” for a type. Read more
Executes the destructor for this type. Read more

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.