Struct concurrent::Option

pub struct Option<T> { /* fields omitted */ }

A concurrently accessible and updatable optional pointer.

This acts as a kind of concurrent Option<T>. It can be compared to std::cell::RefCell in some ways: It allows accessing, referencing, updating, etc., however contrary to RefCell, this is concurrent and has no aliasing restrictions. It is further distinguished from std::sync::AtomicPtr in that it allows references to the inner data without the ABA problem or any variant thereof.

It conveniently wraps this crates API in a seemless manner.

Methods

impl<T> AtomicOption<T>

fn new(init: Option<Box<T>>) -> AtomicOption<T>

fn load(&self, ordering: Ordering) -> Option<Guard<T>>

Get a reference to the current content of the option.

This returns a Guard<T>, which "protects" the inner value such that it is not dropped before the guard is no longer active. This is all handled automatically through RAII.

The ordering defines what constraints the atomic operation has. Refer to the LLVM documentation for more information.

fn store(&self, new: Option<Box<T>>, ordering: Ordering)

Store a new value in the option.

The old value of self will eventually be dropped, at some point after all the guarding references are gone.

The ordering defines what constraints the atomic operation has. Refer to the LLVM documentation for more information.

fn swap(&self, new: Option<Box<T>>, ordering: Ordering) -> Option<Guard<T>>

Swap the old value with a new.

This returns a Guard<T> as readers of the old values might exist. The old value will be queued for destruction.

The ordering defines what constraints the atomic operation has. Refer to the LLVM documentation for more information.

Performance

This is slower than store as it requires initializing a new guard, which requires at least two atomic operations. Thus, when possible, you should use store.

fn compare_and_store(
    &self,
    old: Option<*const T>,
    new: Option<Box<T>>,
    ordering: Ordering
) -> Result<(), Option<Box<T>>>

Store a value if the current matches a particular value.

This compares self to old. If they match, the value is set to new and Ok(()) is returned. Otherwise, Err(new) is returned.

The ordering defines what constraints the atomic operation has. Refer to the LLVM documentation for more information.

fn compare_and_swap(
    &self,
    old: Option<*const T>,
    new: Option<Box<T>>,
    ordering: Ordering
) -> Result<Option<Guard<T>>, (Option<Guard<T>>, Option<Box<T>>)>

Swap a value if it matches.

This compares self to old. If they match, it is swapped with new and a guard to the old value is returned wrapped in Ok. If not, a tuple containing the guard to the actual (non-matching) value and the box of new — wrapped in Err — is returned.

The ordering defines what constraints the atomic operation has. Refer to the LLVM documentation for more information.

Performance

This is slower than compare_and_set as it requires initializing a new guard, which requires at least two atomic operations. Thus, when possible, you should use compare_and_set.

Trait Implementations

impl<T: Default> Default for AtomicOption<T>

fn default() -> AtomicOption<T>

Returns the "default value" for a type.