Struct AtomicEnum

Source

pub struct AtomicEnum<E, A, U>(/* private fields */);

Expand description

The AtomicEnum is used to store values of an C like enumeration in an atomic type.

Implementations§

Source §

impl<E, A, U> AtomicEnum<E, A, U>
where E: TryFrom + Into, A: AtomicOps, U: Copy,

Source

pub fn new(v: E) -> Self

Create a new atomic enumeration.

§Params

v: The value with which the enumeration is to be initialized

§Returns

A new AtomicEnum

§Example

use atomic_enums::{gen_atomic_enum, AtomicEnumU32};

gen_atomic_enum!(State, u32:
    Running: 2
    Paused: 3
);

impl TryFrom<u32> for State {
    type Error = ();

    fn try_from(v: u32) -> Result<Self, Self::Error> {
        match v {
            2 => Ok(Self::Running),
            3 => Ok(Self::Paused),
            _ => Err(()),
        }
    }
}

let state = AtomicEnumU32::new(State::Running);
 /* Do whatever you want to do... */

Source

pub fn load(&self, order: Ordering) -> Option<E>

Load the currently stored value of the atomic enum

The following is copyed from the offical documentation of atomic::AtomicU32.

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

§Panics

Panics if order is Ordering::Release or Ordering::AcqRel.

§Example

use atomic_enums::{gen_atomic_enum, AtomicEnumU32};

use core::sync::atomic::Ordering::Relaxed;

gen_atomic_enum!(State, u32:
    Running: 2
    Paused: 3
);

impl TryFrom<u32> for State {
    type Error = ();

    fn try_from(v: u32) -> Result<Self, Self::Error> {
        match v {
            2 => Ok(Self::Running),
            3 => Ok(Self::Paused),
            _ => Err(()),
        }
    }
}

let state = AtomicEnumU32::new(State::Paused);

assert_eq!(state.load(Relaxed).unwrap(), State::Paused);

Source

pub fn store(&self, val: E, order: Ordering)

Store the passed value in the atomic enumeration

The following is copyed from the offical documentation of atomic::AtomicU32::store.

store takes an Ordering argument which describes the memory ordering of this operation.

Possible values are Ordering::SeqCst, Ordering::Release and Ordering::Relaxed.

§Panics

Panics if order is Ordering::Acquire or Ordering::AcqRel.

§Example

use atomic_enums::{gen_atomic_enum, AtomicEnumU32};

use core::sync::atomic::Ordering::Relaxed;

gen_atomic_enum!(State, u32:
    Running: 2
    Paused: 3
);

impl TryFrom<u32> for State {
    type Error = ();

    fn try_from(v: u32) -> Result<Self, Self::Error> {
        match v {
            2 => Ok(Self::Running),
            3 => Ok(Self::Paused),
            _ => Err(()),
        }
    }
}

let state = AtomicEnumU32::new(State::Paused);

state.store(State::Running, Relaxed);

assert_eq!(state.load(Relaxed).unwrap(), State::Running);

Source

pub fn swap(&self, val: E, order: Ordering) -> Option<E>

Stores the passed enum value and returns the previous value.

The following is copyed from the offical documentation of atomic::AtomicU32::swap.

swap takes an Ordering argument which describes the memory ordering of this operation. All ordering modes are possible. Note that using Ordering::Acquire makes the store part of this operation Ordering::Relaxed, and using Ordering::Release makes the load part Ordering::Relaxed.

§Example

use atomic_enums::{gen_atomic_enum, AtomicEnumU32};

use core::sync::atomic::Ordering::Relaxed;

gen_atomic_enum!(State, u32:
    Running: 2
    Paused: 3
);

impl TryFrom<u32> for State {
    type Error = ();

    fn try_from(v: u32) -> Result<Self, Self::Error> {
        match v {
            2 => Ok(Self::Running),
            3 => Ok(Self::Paused),
            _ => Err(()),
        }
    }
}

let state = AtomicEnumU32::new(State::Paused);

assert_eq!(state.swap(State::Running, Relaxed).unwrap(), State::Paused);
assert_eq!(state.load(Relaxed).unwrap(), State::Running);

Source

pub fn compare_exchange( &self, current: E, new: E, success: Ordering, failure: Ordering, ) -> Result<Option<E>, Option<E>>

Stores the new value, if the current value ist equal to the currently stored value.

The following is copyed from the offical documentation of atomic::AtomicU32::compare_exchange.

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 Ordering::Acquire as success ordering makes the store part of this operation Ordering::Relaxed, and using Ordering::Release makes the successful load Ordering::Relaxed. The failure ordering can only be Ordering::SeqCst, Ordering::Acquire or Ordering::Relaxed.

§Example

use atomic_enums::{gen_atomic_enum, AtomicEnumU32};

use core::sync::atomic::Ordering::Relaxed;

gen_atomic_enum!(State, u32:
    Running: 2
    Paused: 3
);

impl TryFrom<u32> for State {
    type Error = ();

    fn try_from(v: u32) -> Result<Self, Self::Error> {
        match v {
            2 => Ok(Self::Running),
            3 => Ok(Self::Paused),
            _ => Err(()),
        }
    }
}

let state = AtomicEnumU32::new(State::Paused);

let mut result = state.compare_exchange(
    State::Paused,
    State::Running,
    Relaxed,
    Relaxed,
);
assert_eq!(result.unwrap().unwrap(), State::Paused);

result = state.compare_exchange(
    State::Paused,
    State::Running,
    Relaxed,
    Relaxed,
);

assert_eq!(result.unwrap_err().unwrap(), State::Running);