[−][src]Struct reclaim::Atomic
An atomic markable pointer type to an owned heap allocated value similar to
AtomicPtr
.
The Atomic
type has similarities to Option<Box>
, as it is a
pointer that is either null
or otherwise must point to a valid, heap
allocated value.
Note, that the type does not implement the Drop
trait,
meaning it does not automatically take care of memory de-allocation when it
goes out of scope.
Use the take
method to extract an (optional) Owned
value, which does correctly deallocate memory when it goes out of scope.
Methods
impl<T, R, N> Atomic<T, R, N>
[src]
pub const fn null() -> Self
[src]
Creates a new null
pointer.
pub const fn as_raw(&self) -> &AtomicMarkedPtr<T, N>
[src]
Gets a reference to the underlying (raw) atomic markable pointer.
impl<T, R: Reclaim, N: Unsigned> Atomic<T, R, N>
[src]
pub fn new(val: T) -> Self
[src]
Allocates a new Owned
containing the given val
and immediately
storing it an Atomic
.
pub unsafe fn from_raw(ptr: MarkedPtr<T, N>) -> Self
[src]
Creates a new Atomic
from the given ptr
.
Safety
The given ptr
argument must be a pointer to a valid heap allocated
instance of T
that was allocated as part of a Record
,
e.g. through an Owned
.
The same pointer should also not be used to create more than one
Atomic
s.
pub fn load_raw(&self, order: Ordering) -> MarkedPtr<T, N>
[src]
Loads a raw marked value from the pointer.
load_raw
takes an Ordering
argument, which describes the
memory ordering of this operation.
Panics
Panics if order
is Release
or AcqRel
.
Example
Commonly, this is likely going to be used in conjunction with
load_if_equal
or
[acquire_if_equal
][Protect::acquire_if_equal].
use std::sync::atomic::Ordering::Relaxed; use reclaim::typenum::U0; use reclaim::leak::Guard; type Atomic<T> = reclaim::leak::Atomic<T, U0>; let atomic = Atomic::new("string"); let guard = &Guard::new(); let ptr = atomic.load_raw(Relaxed); let res = atomic.load_if_equal(ptr, Relaxed, guard); assert!(res.is_ok());
pub fn load_unprotected(&self, order: Ordering) -> Option<Unprotected<T, R, N>>
[src]
Loads an optional Unprotected
reference from the Atomic
.
The returned reference is explicitly not protected from reclamation, meaning another thread could free the value's memory at any time.
This method is similar to load_raw
, but the
resulting Unprotected
type has stronger guarantees than a raw
MarkedPtr
.
It can be useful to load an unprotected pointer if that pointer does not
need to be de-referenced, but is only used to reinsert it in a different
spot, which is e.g. done when removing a value from a linked list.
Panics
pub fn load_marked_unprotected(
&self,
order: Ordering
) -> Marked<Unprotected<T, R, N>>
[src]
&self,
order: Ordering
) -> Marked<Unprotected<T, R, N>>
Loads an Unprotected
reference wrapped in a Marked
from the
Atomic
.
The returned reference is explicitly not protected from reclamation, meaning another thread could free the value's memory at any time.
This method is similar to load_raw
, but the
resulting Unprotected
type has stronger guarantees than a raw
MarkedPtr
.
It can be useful to load an unprotected pointer if that pointer does not
need to be de-referenced, but is only used to reinsert it in a different
spot, which is e.g. done when removing a value from a linked list.
Panics
pub fn load<'g>(
&self,
order: Ordering,
guard: impl GuardRef<'g, Reclaimer = R>
) -> Option<Shared<'g, T, R, N>>
[src]
&self,
order: Ordering,
guard: impl GuardRef<'g, Reclaimer = R>
) -> Option<Shared<'g, T, R, N>>
Loads a value from the pointer and uses guard
to protect it.
If the loaded value is non-null, the value is guaranteed to be protected
from reclamation during the lifetime of guard
.
load
takes an Ordering
argument, which describes the
memory ordering of this operation.
Panics
pub fn load_if_equal<'g>(
&self,
expected: MarkedPtr<T, N>,
order: Ordering,
guard: impl GuardRef<'g, Reclaimer = R>
) -> Result<Option<Shared<'g, T, R, N>>, NotEqualError>
[src]
&self,
expected: MarkedPtr<T, N>,
order: Ordering,
guard: impl GuardRef<'g, Reclaimer = R>
) -> Result<Option<Shared<'g, T, R, N>>, NotEqualError>
Loads a value from the pointer and uses guard
to protect it, but only
if the loaded value equals expected
.
If the loaded value is non-null, the value is guaranteed to be protected
from reclamation during the lifetime of guard
.
load_if_equal
takes an Ordering
argument, which
describes the memory ordering of this operation.
Panics
pub fn load_marked<'g>(
&self,
order: Ordering,
guard: impl GuardRef<'g, Reclaimer = R>
) -> Marked<Shared<'g, T, R, N>>
[src]
&self,
order: Ordering,
guard: impl GuardRef<'g, Reclaimer = R>
) -> Marked<Shared<'g, T, R, N>>
Loads a value from the pointer and uses guard
to protect it.
The (optional) protected Shared
value is wrapped in a `Marked.
If the loaded value is non-null, the value is guaranteed to be protected
from reclamation during the lifetime of guard
.
The primary difference to load
is, that the returned
Marked
type is additionally able to represent marked null
pointers.
load_marked
takes an Ordering
argument, which describes
the memory ordering of this operation.
Panics
pub fn load_marked_if_equal<'g>(
&self,
expected: MarkedPtr<T, N>,
order: Ordering,
guard: impl GuardRef<'g, Reclaimer = R>
) -> AcquireResult<'g, T, R, N>
[src]
&self,
expected: MarkedPtr<T, N>,
order: Ordering,
guard: impl GuardRef<'g, Reclaimer = R>
) -> AcquireResult<'g, T, R, N>
Loads a value from the pointer and uses guard
to protect it, but only
if the loaded value equals expected
.
The (optional) protected Shared
value is wrapped in a `Marked.
If the loaded value is non-null, the value is guaranteed to be protected
from reclamation during the lifetime of guard
.
The primary difference to load_if_equal
is,
that the returned Marked
type is additionally able to represent
marked null
pointers.
load_marked_if_equal
takes an Ordering
argument, which
describes the memory ordering of this operation.
Panics
pub fn store(
&self,
ptr: impl Store<Item = T, MarkBits = N, Reclaimer = R>,
order: Ordering
)
[src]
&self,
ptr: impl Store<Item = T, MarkBits = N, Reclaimer = R>,
order: Ordering
)
Stores either null
or a valid pointer to an owned heap allocated value
into the pointer.
Note, that overwriting a non-null value through store
will very likely
lead to memory leaks, since instances of Atomic
will most commonly
be associated wit some kind of uniqueness invariants in order to be sound.
store
takes an Ordering
argument, which
describes the memory ordering of this operation.
Panics
pub fn swap(
&self,
ptr: impl Store<Item = T, Reclaimer = R, MarkBits = N>,
order: Ordering
) -> Option<Unlinked<T, R, N>>
[src]
&self,
ptr: impl Store<Item = T, Reclaimer = R, MarkBits = N>,
order: Ordering
) -> Option<Unlinked<T, R, N>>
Stores either null
or a valid pointer to an owned heap allocated value
into the pointer, returning the previous value.
The returned value can be safely reclaimed as long as the uniqueness invariant is maintained.
swap
takes an Ordering
argument which describes the memory
ordering of this operation. All ordering modes are possible. Note that using
Acquire
makes the store part of this operation Relaxed
,
and using Release
makes the load part Relaxed
.
pub fn compare_exchange<C, S>(
&self,
current: C,
new: S,
success: Ordering,
failure: Ordering
) -> Result<C::Unlinked, CompareExchangeFailure<T, R, S, N>> where
C: Compare<Item = T, MarkBits = N, Reclaimer = R>,
S: Store<Item = T, MarkBits = N, Reclaimer = R>,
[src]
&self,
current: C,
new: S,
success: Ordering,
failure: Ordering
) -> Result<C::Unlinked, CompareExchangeFailure<T, R, S, N>> where
C: Compare<Item = T, MarkBits = N, Reclaimer = R>,
S: Store<Item = T, MarkBits = N, Reclaimer = R>,
Stores a value (either null or valid) into the pointer if the current
value is the same as current
.
The return value is a result indicating whether the new
value was
written and containing the previous and now unlinked value.
On success this value is guaranteed to be equal to current
and can be
safely reclaimed as long as the uniqueness invariant is maintained.
On failure, a struct is returned that contains
both the actual value and the value that was previously attempted to be
inserted (new
).
This is necessary, because it is possible to attempt insertion of
move-only types such as Owned
or Unlinked
, which would otherwise
be irretrievably lost when the compare_exchange
fails.
The actually loaded value is Unprotected
.
compare_exchange
takes two Ordering
arguments to
describe the memory ordering of this operation.
The first describes the required ordering if the operation succeeds
while the second describes the required ordering when the operation
fails.
Using Acquire
as success ordering makes the store part of
this operation Relaxed
, and using Release
makes the successful load Relaxed
.
The failure ordering can only be SeqCst
,
Acquire
or Relaxed
and must be equivalent to
or weaker than the success ordering.
pub fn compare_exchange_weak<C, S>(
&self,
current: C,
new: S,
success: Ordering,
failure: Ordering
) -> Result<C::Unlinked, CompareExchangeFailure<T, R, S, N>> where
C: Compare<Item = T, MarkBits = N, Reclaimer = R>,
S: Store<Item = T, MarkBits = N, Reclaimer = R>,
[src]
&self,
current: C,
new: S,
success: Ordering,
failure: Ordering
) -> Result<C::Unlinked, CompareExchangeFailure<T, R, S, N>> where
C: Compare<Item = T, MarkBits = N, Reclaimer = R>,
S: Store<Item = T, MarkBits = N, Reclaimer = R>,
Stores a value (either null or valid) into the pointer if the current
value is the same as current
.
Unlike compare_exchange
, this function is
allowed to spuriously fail even when the comparision 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 and now unlinked value.
On success this value is guaranteed to be equal to current
and can be
safely reclaimed as long as the uniqueness invariant is maintained.
On failure, a struct is returned that contains
both the actual value and the value that was previously attempted to be
inserted (new
).
This is necessary, because it is possible to attempt insertion of
move-only types such as Owned
or Unlinked
, which would otherwise
be irretrievably lost when the compare_exchange
fails.
The actually loaded value is Unprotected
.
compare_exchange
takes two Ordering
arguments to
describe the memory ordering of this operation.
The first describes the required ordering if the operation succeeds
while the second describes the required ordering when the operation
fails.
Using Acquire
as success ordering makes the store part of
this operation Relaxed
, and using Release
makes the successful load Relaxed
.
The failure ordering can only be SeqCst
,
Acquire
or Relaxed
and must be equivalent to
or weaker than the success ordering.
pub fn take(&mut self) -> Option<Owned<T, R, N>>
[src]
Takes the value out of the pointer as an optional Owned
, leaving a
null
pointer in its place.
This is similar to Option::take
and is useful for
manually dropping the value pointed-to by the Atomic
, since
Owned
values behave like Box
when they are dropped.
impl<T, N: Unsigned> Atomic<T, Leaking, N>
[src]
pub fn load_shared(&self, order: Ordering) -> Option<Shared<T, Leaking, N>>
[src]
Loads an optional Shared
reference from the Atomic
.
Since Leaking
never frees memory of retired records, this is always
safe even without any guards.
Panics
pub fn load_marked_shared(
&self,
order: Ordering
) -> Marked<Shared<T, Leaking, N>>
[src]
&self,
order: Ordering
) -> Marked<Shared<T, Leaking, N>>
Trait Implementations
impl<T, R: Reclaim, N: Unsigned> Sync for Atomic<T, R, N> where
T: Send + Sync,
[src]
T: Send + Sync,
impl<T, R: Reclaim, N: Unsigned> Send for Atomic<T, R, N> where
T: Send + Sync,
[src]
T: Send + Sync,
impl<T, R: Reclaim, N: Unsigned> Default for Atomic<T, R, N>
[src]
impl<T, R: Reclaim, N: Unsigned> From<T> for Atomic<T, R, N>
[src]
impl<T, R: Reclaim, N: Unsigned> From<Owned<T, R, N>> for Atomic<T, R, N>
[src]
impl<T, R: Reclaim, N: Unsigned> Debug for Atomic<T, R, N>
[src]
impl<T, R: Reclaim, N: Unsigned> Pointer for Atomic<T, R, N>
[src]
Auto Trait Implementations
impl<T, R, N> Unpin for Atomic<T, R, N> where
N: Unpin,
R: Unpin,
T: Unpin,
N: Unpin,
R: Unpin,
T: Unpin,
impl<T, R, N> RefUnwindSafe for Atomic<T, R, N> where
N: RefUnwindSafe,
R: RefUnwindSafe,
T: RefUnwindSafe,
N: RefUnwindSafe,
R: RefUnwindSafe,
T: RefUnwindSafe,
impl<T, R, N> UnwindSafe for Atomic<T, R, N> where
N: UnwindSafe,
R: UnwindSafe,
T: RefUnwindSafe + UnwindSafe,
N: UnwindSafe,
R: UnwindSafe,
T: RefUnwindSafe + UnwindSafe,
Blanket Implementations
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> From<T> for T
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Same<T> for T
[src]
type Output = T
Should always be Self