[][src]Struct reclaim::Atomic

pub struct Atomic<T, R, N> { /* fields omitted */ }

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 Atomics.

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

Panics if order is Release or AcqRel.

pub fn load_marked_unprotected(
    &self,
    order: Ordering
) -> Marked<Unprotected<T, R, N>>
[src]

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

Panics if order is Release or AcqRel.

pub fn load<'g>(
    &self,
    order: Ordering,
    guard: impl GuardRef<'g, Reclaimer = R>
) -> Option<Shared<'g, T, R, N>>
[src]

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

May panic if order is Release or AcqRel.

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]

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

May panic if order is Release or AcqRel.

pub fn load_marked<'g>(
    &self,
    order: Ordering,
    guard: impl GuardRef<'g, Reclaimer = R>
) -> Marked<Shared<'g, T, R, N>>
[src]

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

May panic if order is Release or AcqRel.

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]

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

May panic if order is Release or AcqRel.

pub fn store(
    &self,
    ptr: impl Store<Item = T, MarkBits = N, Reclaimer = R>,
    order: Ordering
)
[src]

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

Panics if order is Acquire or AcqRel

pub fn swap(
    &self,
    ptr: impl Store<Item = T, Reclaimer = R, MarkBits = N>,
    order: Ordering
) -> Option<Unlinked<T, R, N>>
[src]

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]

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]

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

Panics if order is Release or AcqRel.

pub fn load_marked_shared(
    &self,
    order: Ordering
) -> Marked<Shared<T, Leaking, N>>
[src]

Loads a Shared reference wrapped in a Marked from the Atomic.

Since Leaking never frees memory of retired records, this is always safe even without any guards.

Panics

Panics if order is Release or AcqRel.

Trait Implementations

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> Default for Atomic<T, R, N>[src]

impl<T, R: Reclaim, N: Unsigned> Send for Atomic<T, R, N> where
    T: Send + Sync
[src]

impl<T, R: Reclaim, N: Unsigned> Sync for Atomic<T, R, N> where
    T: Send + Sync
[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

impl<T, R, N> UnwindSafe for Atomic<T, R, N> where
    N: UnwindSafe,
    R: UnwindSafe,
    T: RefUnwindSafe + UnwindSafe

impl<T, R, N> RefUnwindSafe for Atomic<T, R, N> where
    N: RefUnwindSafe,
    R: RefUnwindSafe,
    T: RefUnwindSafe

Blanket Implementations

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Same<T> for T[src]

type Output = T

Should always be Self