Struct haphazard::raw::HazardPointer
source · [−]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 [haphazard::AtomicPtr
].
If you need to protect multiple referenced objects at the same time, use
HazardPointerArray
.
Implementations
sourceimpl HazardPointer<'static, Global>
impl HazardPointer<'static, Global>
sourcepub fn new() -> Self
pub fn new() -> Self
Create a new hazard pointer in the global domain.
sourcepub fn many<const N: usize>() -> HazardPointerArray<'static, Global, N>
pub fn many<const N: usize>() -> HazardPointerArray<'static, Global, N>
Create a new hazard pointer array in the global domain.
sourceimpl<'domain, F> HazardPointer<'domain, F>
impl<'domain, F> HazardPointer<'domain, F>
sourcepub fn new_in_domain(domain: &'domain Domain<F>) -> Self
pub fn new_in_domain(domain: &'domain Domain<F>) -> Self
Create a new hazard pointer in the given domain.
sourcepub fn many_in_domain<const N: usize>(
domain: &'domain Domain<F>
) -> HazardPointerArray<'domain, F, N>
pub fn many_in_domain<const N: usize>(
domain: &'domain Domain<F>
) -> HazardPointerArray<'domain, F, N>
Create a new hazard pointer array in the given domain.
sourcepub unsafe fn protect<'l, T>(&'l mut self, src: &AtomicPtr<T>) -> Option<&'l T> where
F: 'static,
pub unsafe fn protect<'l, T>(&'l mut self, src: &AtomicPtr<T>) -> Option<&'l T> where
F: 'static,
Protect the value loaded from the given AtomicPtr
, and dereference it to &T
.
This operation will load the AtomicPtr
multiple times:
- load to get the currently stored pointer,
ptr
- store
ptr
into the hazard pointer to protect it from reclamation - 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.
Safety
- The value loaded from
AtomicPtr
is a valid&T
, or null. - The loaded
&T
will only be deallocated through calls to [HazPtrObject::retire
] on the sameDomain
as this holder is associated with.
sourcepub fn protect_ptr<'l, T>(
&'l mut self,
src: &AtomicPtr<T>
) -> Option<(NonNull<T>, PhantomData<&'l T>)> where
F: 'static,
pub fn protect_ptr<'l, T>(
&'l mut self,
src: &AtomicPtr<T>
) -> Option<(NonNull<T>, PhantomData<&'l T>)> where
F: 'static,
Protect the value loaded from the given AtomicPtr
, and return it as NonNull<T>
.
This operation will load the AtomicPtr
multiple times:
- load to get the currently stored pointer,
ptr
- store
ptr
into the hazard pointer to protect it from reclamation - 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.
sourcepub unsafe fn try_protect<'l, T>(
&'l mut self,
ptr: *mut T,
src: &AtomicPtr<T>
) -> Result<Option<&'l T>, *mut T> where
F: 'static,
pub unsafe fn try_protect<'l, T>(
&'l mut self,
ptr: *mut T,
src: &AtomicPtr<T>
) -> Result<Option<&'l T>, *mut T> where
F: 'static,
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
.
Returns Ok(None)
if ptr.is_null()
.
Safety
- The value loaded from
AtomicPtr
is a valid&T
, or null. - The loaded
&T
will only be deallocated through calls to [HazPtrObject::retire
] on the sameDomain
as this holder is associated with.
sourcepub fn try_protect_ptr<'l, T>(
&'l mut self,
ptr: *mut T,
src: &AtomicPtr<T>
) -> Result<Option<(NonNull<T>, PhantomData<&'l T>)>, *mut T> where
F: 'static,
pub fn try_protect_ptr<'l, T>(
&'l mut self,
ptr: *mut T,
src: &AtomicPtr<T>
) -> Result<Option<(NonNull<T>, PhantomData<&'l T>)>, *mut T> where
F: 'static,
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()
.
sourcepub fn reset_protection(&mut self)
pub fn reset_protection(&mut self)
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).
sourcepub fn protect_raw<T>(&mut self, ptr: *mut T) where
F: 'static,
pub fn protect_raw<T>(&mut self, ptr: *mut T) where
F: 'static,
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
sourceimpl Default for HazardPointer<'static, Global>
impl Default for HazardPointer<'static, Global>
Auto Trait Implementations
impl<'domain, F> RefUnwindSafe for HazardPointer<'domain, F> where
F: RefUnwindSafe,
impl<'domain, F> Send for HazardPointer<'domain, F> where
F: Sync,
impl<'domain, F> Sync for HazardPointer<'domain, F> where
F: Sync,
impl<'domain, F> Unpin for HazardPointer<'domain, F>
impl<'domain, F> UnwindSafe for HazardPointer<'domain, F> where
F: RefUnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more