Struct Atom

pub struct Atom<P>
where
    P: IntoRawPtr + FromRawPtr,
{ /* private fields */ }

An Atom wraps an AtomicPtr, it allows for safe mutation of an atomic into common Rust Types.

Implementations

impl<P> Atom<P>

where P: IntoRawPtr + FromRawPtr,

pub fn empty() -> Atom<P>

Create a empty Atom

Examples found in repository

examples/simple.rs (line 9)

fn main() {
    // Create an empty atom
    let shared_atom = Arc::new(Atom::empty());

    // set the value 75
    shared_atom.swap(Box::new(75), Ordering::AcqRel);

    // Spawn a bunch of thread that will try and take the value
    let threads: Vec<thread::JoinHandle<()>> = (0..8)
        .map(|_| {
            let shared_atom = shared_atom.clone();
            thread::spawn(move || {
                // Take the contents of the atom, only one will win the race
                if let Some(v) = shared_atom.take(Ordering::Acquire) {
                    println!("I got it: {:?} :D", v);
                } else {
                    println!("I did not get it :(");
                }
            })
        })
        .collect();

    // join the threads
    for t in threads {
        t.join().unwrap();
    }
}

pub fn new(value: P) -> Atom<P>

Create a new Atomic from Pointer P

pub fn swap(&self, v: P, order: Ordering) -> Option<P>

Swap a new value into the Atom, This will try multiple times until it succeeds. The old value will be returned.

Examples found in repository

examples/simple.rs (line 12)

fn main() {
    // Create an empty atom
    let shared_atom = Arc::new(Atom::empty());

    // set the value 75
    shared_atom.swap(Box::new(75), Ordering::AcqRel);

    // Spawn a bunch of thread that will try and take the value
    let threads: Vec<thread::JoinHandle<()>> = (0..8)
        .map(|_| {
            let shared_atom = shared_atom.clone();
            thread::spawn(move || {
                // Take the contents of the atom, only one will win the race
                if let Some(v) = shared_atom.take(Ordering::Acquire) {
                    println!("I got it: {:?} :D", v);
                } else {
                    println!("I did not get it :(");
                }
            })
        })
        .collect();

    // join the threads
    for t in threads {
        t.join().unwrap();
    }
}

pub fn take(&self, order: Ordering) -> Option<P>

Take the value of the Atom replacing it with null pointer Returning the contents. If the contents was a null pointer the result will be None.

Examples found in repository

examples/fifo.rs (line 32)

    fn drop(&mut self) {
        // This is done to avoid a recusive drop of the List
        while let Some(mut h) = self.next.atom().take(Ordering::Acquire) {
            self.next = mem::replace(&mut h.next, AtomSetOnce::empty());
        }
    }

examples/simple.rs (line 20)

fn main() {
    // Create an empty atom
    let shared_atom = Arc::new(Atom::empty());

    // set the value 75
    shared_atom.swap(Box::new(75), Ordering::AcqRel);

    // Spawn a bunch of thread that will try and take the value
    let threads: Vec<thread::JoinHandle<()>> = (0..8)
        .map(|_| {
            let shared_atom = shared_atom.clone();
            thread::spawn(move || {
                // Take the contents of the atom, only one will win the race
                if let Some(v) = shared_atom.take(Ordering::Acquire) {
                    println!("I got it: {:?} :D", v);
                } else {
                    println!("I did not get it :(");
                }
            })
        })
        .collect();

    // join the threads
    for t in threads {
        t.join().unwrap();
    }
}

pub fn set_if_none(&self, v: P, order: Ordering) -> Option<P>

This will do a CAS setting the value only if it is NULL this will return None if the value was written, otherwise a Some(v) will be returned, where the value was the same value that you passed into this function

pub fn replace_and_set_next( &self, value: P, load_order: Ordering, cas_order: Ordering, ) -> bool

where P: GetNextMut<NextPtr = Option<P>>,

Take the current content, write it into P then do a CAS to extent this Atom with the previous contents. This can be used to create a LIFO

Returns true if this set this migrated the Atom from null.

pub fn is_none(&self, order: Ordering) -> bool

Check to see if an atom is None

This only means that the contents was None when it was measured

impl<P, T> Atom<P>

where P: IntoRawPtr + FromRawPtr + Deref<Target = T>,

pub fn compare_and_swap( &self, current: Option<&P>, new: Option<P>, order: Ordering, ) -> Result<Option<P>, (Option<P>, *mut P)>

Stores new in the Atom if current has the same raw pointer representation as the currently stored value.

On success, the Atom’s previous value is returned. On failure, new is returned together with a raw pointer to the Atom’s current unchanged value, which is not safe to dereference, especially if the Atom is accessed from multiple threads.

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

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

Stores a value into the pointer 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. The first describes the required ordering if the operation succeeds while the second describes the required ordering when the operation fails. The failure ordering can’t be Release or AcqRel and must be equivalent or weaker than the success ordering.

pub fn compare_exchange_weak( &self, current: Option<&P>, new: Option<P>, success: Ordering, failure: Ordering, ) -> Result<Option<P>, (Option<P>, *mut P)>

Stores a value into the pointer 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. The first describes the required ordering if the operation succeeds while the second describes the required ordering when the operation fails. The failure ordering can’t be Release or AcqRel and must be equivalent or weaker than the success ordering.

Trait Implementations

impl<P> Debug for Atom<P>

where P: IntoRawPtr + FromRawPtr,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<P> Drop for Atom<P>

where P: IntoRawPtr + FromRawPtr,

fn drop(&mut self)

Executes the destructor for this type.

impl<P> Send for Atom<P>

where P: IntoRawPtr + FromRawPtr + Send,

impl<P> Sync for Atom<P>

where P: IntoRawPtr + FromRawPtr + Send,