Trait Atomic

pub unsafe trait Atomic: Send + Sync {
    type Primitive: HasAtomic<Atomic = Self>;

    // Required methods
    fn new(v: Self::Primitive) -> Self;
    fn get_mut(&mut self) -> &mut Self::Primitive;
    fn into_inner(self) -> Self::Primitive;
    fn load(&self, order: Ordering) -> Self::Primitive;
    fn store(&self, val: Self::Primitive, order: Ordering);
    fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive;
    fn compare_exchange(
        &self,
        current: Self::Primitive,
        new: Self::Primitive,
        success: Ordering,
        failure: Ordering,
    ) -> Result<Self::Primitive, Self::Primitive>;
    fn compare_exchange_weak(
        &self,
        current: Self::Primitive,
        new: Self::Primitive,
        success: Ordering,
        failure: Ordering,
    ) -> Result<Self::Primitive, Self::Primitive>;
    fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>(
        &self,
        set_order: Ordering,
        fetch_ordering: Ordering,
        f: F,
    ) -> Result<Self::Primitive, Self::Primitive>;
}

A trait representing atomic types.

Safety

• Self must have the same size and alignment as Primitive

Required Associated Types

type Primitive: HasAtomic<Atomic = Self>

Required Methods

fn new(v: Self::Primitive) -> Self

Creates a new atomic integer.

fn get_mut(&mut self) -> &mut Self::Primitive

Returns a mutable reference to the underlying integer.

This is safe because the mutable reference guarantees that no other threads are concurrently accessing the atomic data.

fn into_inner(self) -> Self::Primitive

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.

fn load(&self, order: Ordering) -> Self::Primitive

Loads a value from the atomic integer.

load takes an Ordering argument which describes the memory ordering of this operation. Possible values are SeqCst, Acquire and Relaxed.

Panics

Panics if order is Release or AcqRel.

fn store(&self, val: Self::Primitive, order: Ordering)

Stores a value into the atomic integer.

store takes an Ordering argument which describes the memory ordering of this operation. Possible values are SeqCst, Release and Relaxed.

Panics

Panics if order is Acquire or AcqRel.

fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive

Stores a value into the atomic integer, returning the previous value.

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.

fn compare_exchange( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

Stores a value into the atomic integer if the current value is the same as the current value.

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.

compare_exchange takes two Ordering arguments to describe the memory ordering of this operation. success describes the required ordering for the read-modify-write operation that takes place if the comparison with current succeeds. failure describes the required ordering for the load operation that takes place when the comparison 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.

fn compare_exchange_weak( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

Stores a value into the atomic integer if the current value is the same as the current value.

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

compare_exchange_weak takes two Ordering arguments to describe the memory ordering of this operation. success describes the required ordering for the read-modify-write operation that takes place if the comparison with current succeeds. failure describes the required ordering for the load operation that takes place when the comparison 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.

fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>( &self, set_order: Ordering, fetch_ordering: Ordering, f: F, ) -> Result<Self::Primitive, Self::Primitive>

Fetches the value, and applies a function to it that returns an optional new value. Returns a Result of Ok(previous_value) if the function returned Some(_), else Err(previous_value).

Note: This may call the function multiple times if the value has been changed from other threads in the meantime, as long as the function returns Some(_), but the function will have been applied only once to the stored value.

fetch_update takes two Ordering arguments to describe the memory ordering of this operation. The first describes the required ordering for when the operation finally succeeds while the second describes the required ordering for loads. These correspond to the success and failure orderings of compare_exchange respectively.

Using Acquire as success ordering makes the store part of this operation Relaxed, and using Release makes the final successful load Relaxed. The (failed) load ordering can only be SeqCst, Acquire or Relaxed.

Considerations

This method is not magic; it is not provided by the hardware. It is implemented in terms of compare_exchange_weak, and suffers from the same drawbacks. In particular, this method will not circumvent the ABA Problem.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl Atomic for AtomicBool

Available on target_has_atomic="8" only.

type Primitive = bool

fn new(v: Self::Primitive) -> Self

fn get_mut(&mut self) -> &mut Self::Primitive

fn into_inner(self) -> Self::Primitive

fn load(&self, order: Ordering) -> Self::Primitive

fn store(&self, val: Self::Primitive, order: Ordering)

fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive

fn compare_exchange( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn compare_exchange_weak( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>( &self, set_order: Ordering, fetch_ordering: Ordering, f: F, ) -> Result<Self::Primitive, Self::Primitive>

impl Atomic for AtomicI8

Available on target_has_atomic="8" only.

type Primitive = i8

fn new(v: Self::Primitive) -> Self

fn get_mut(&mut self) -> &mut Self::Primitive

fn into_inner(self) -> Self::Primitive

fn load(&self, order: Ordering) -> Self::Primitive

fn store(&self, val: Self::Primitive, order: Ordering)

fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive

fn compare_exchange( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn compare_exchange_weak( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>( &self, set_order: Ordering, fetch_ordering: Ordering, f: F, ) -> Result<Self::Primitive, Self::Primitive>

impl Atomic for AtomicI16

Available on target_has_atomic="16" only.

type Primitive = i16

fn new(v: Self::Primitive) -> Self

fn get_mut(&mut self) -> &mut Self::Primitive

fn into_inner(self) -> Self::Primitive

fn load(&self, order: Ordering) -> Self::Primitive

fn store(&self, val: Self::Primitive, order: Ordering)

fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive

fn compare_exchange( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn compare_exchange_weak( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>( &self, set_order: Ordering, fetch_ordering: Ordering, f: F, ) -> Result<Self::Primitive, Self::Primitive>

impl Atomic for AtomicI32

Available on target_has_atomic="32" only.

type Primitive = i32

fn new(v: Self::Primitive) -> Self

fn get_mut(&mut self) -> &mut Self::Primitive

fn into_inner(self) -> Self::Primitive

fn load(&self, order: Ordering) -> Self::Primitive

fn store(&self, val: Self::Primitive, order: Ordering)

fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive

fn compare_exchange( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn compare_exchange_weak( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>( &self, set_order: Ordering, fetch_ordering: Ordering, f: F, ) -> Result<Self::Primitive, Self::Primitive>

impl Atomic for AtomicI64

Available on target_has_atomic="64" only.

type Primitive = i64

fn new(v: Self::Primitive) -> Self

fn get_mut(&mut self) -> &mut Self::Primitive

fn into_inner(self) -> Self::Primitive

fn load(&self, order: Ordering) -> Self::Primitive

fn store(&self, val: Self::Primitive, order: Ordering)

fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive

fn compare_exchange( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn compare_exchange_weak( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>( &self, set_order: Ordering, fetch_ordering: Ordering, f: F, ) -> Result<Self::Primitive, Self::Primitive>

impl Atomic for AtomicIsize

Available on target_has_atomic="ptr" only.

type Primitive = isize

fn new(v: Self::Primitive) -> Self

fn get_mut(&mut self) -> &mut Self::Primitive

fn into_inner(self) -> Self::Primitive

fn load(&self, order: Ordering) -> Self::Primitive

fn store(&self, val: Self::Primitive, order: Ordering)

fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive

fn compare_exchange( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn compare_exchange_weak( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>( &self, set_order: Ordering, fetch_ordering: Ordering, f: F, ) -> Result<Self::Primitive, Self::Primitive>

impl Atomic for AtomicU8

Available on target_has_atomic="8" only.

type Primitive = u8

fn new(v: Self::Primitive) -> Self

fn get_mut(&mut self) -> &mut Self::Primitive

fn into_inner(self) -> Self::Primitive

fn load(&self, order: Ordering) -> Self::Primitive

fn store(&self, val: Self::Primitive, order: Ordering)

fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive

fn compare_exchange( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn compare_exchange_weak( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>( &self, set_order: Ordering, fetch_ordering: Ordering, f: F, ) -> Result<Self::Primitive, Self::Primitive>

impl Atomic for AtomicU16

Available on target_has_atomic="16" only.

type Primitive = u16

fn new(v: Self::Primitive) -> Self

fn get_mut(&mut self) -> &mut Self::Primitive

fn into_inner(self) -> Self::Primitive

fn load(&self, order: Ordering) -> Self::Primitive

fn store(&self, val: Self::Primitive, order: Ordering)

fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive

fn compare_exchange( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn compare_exchange_weak( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>( &self, set_order: Ordering, fetch_ordering: Ordering, f: F, ) -> Result<Self::Primitive, Self::Primitive>

impl Atomic for AtomicU32

Available on target_has_atomic="32" only.

type Primitive = u32

fn new(v: Self::Primitive) -> Self

fn get_mut(&mut self) -> &mut Self::Primitive

fn into_inner(self) -> Self::Primitive

fn load(&self, order: Ordering) -> Self::Primitive

fn store(&self, val: Self::Primitive, order: Ordering)

fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive

fn compare_exchange( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn compare_exchange_weak( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>( &self, set_order: Ordering, fetch_ordering: Ordering, f: F, ) -> Result<Self::Primitive, Self::Primitive>

impl Atomic for AtomicU64

Available on target_has_atomic="64" only.

type Primitive = u64

fn new(v: Self::Primitive) -> Self

fn get_mut(&mut self) -> &mut Self::Primitive

fn into_inner(self) -> Self::Primitive

fn load(&self, order: Ordering) -> Self::Primitive

fn store(&self, val: Self::Primitive, order: Ordering)

fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive

fn compare_exchange( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn compare_exchange_weak( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>( &self, set_order: Ordering, fetch_ordering: Ordering, f: F, ) -> Result<Self::Primitive, Self::Primitive>

impl Atomic for AtomicUsize

Available on target_has_atomic="ptr" only.

type Primitive = usize

fn new(v: Self::Primitive) -> Self

fn get_mut(&mut self) -> &mut Self::Primitive

fn into_inner(self) -> Self::Primitive

fn load(&self, order: Ordering) -> Self::Primitive

fn store(&self, val: Self::Primitive, order: Ordering)

fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive

fn compare_exchange( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn compare_exchange_weak( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>( &self, set_order: Ordering, fetch_ordering: Ordering, f: F, ) -> Result<Self::Primitive, Self::Primitive>

impl<T> Atomic for AtomicPtr<T>

Available on target_has_atomic="ptr" only.

type Primitive = *mut T

fn new(v: Self::Primitive) -> Self

fn get_mut(&mut self) -> &mut Self::Primitive

fn into_inner(self) -> Self::Primitive

fn load(&self, order: Ordering) -> Self::Primitive

fn store(&self, val: Self::Primitive, order: Ordering)

fn swap(&self, val: Self::Primitive, order: Ordering) -> Self::Primitive

fn compare_exchange( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn compare_exchange_weak( &self, current: Self::Primitive, new: Self::Primitive, success: Ordering, failure: Ordering, ) -> Result<Self::Primitive, Self::Primitive>

fn fetch_update<F: FnMut(Self::Primitive) -> Option<Self::Primitive>>( &self, set_order: Ordering, fetch_ordering: Ordering, f: F, ) -> Result<Self::Primitive, Self::Primitive>

Implementors