Struct voluntary_servitude::atomics::FillOnceAtomicOption

pub struct FillOnceAtomicOption<T>(_);

Atomic abstraction of a Option<Box<T>> that can provide access to a Option<&T>

This is ideal for a iterator or some consumer that doesn't actually consume the data

To make that possible the API is heavily limited (can only write to it through try_store)

Methods

impl<T> FillOnceAtomicOption<T>

pub fn new<V>(data: V) -> Self where
    V: Into<Option<Box<T>>>, 

Creates new FillOnceAtomicOption

use std::sync::atomic::Ordering;
let empty: FillOnceAtomicOption<()> = FillOnceAtomicOption::new(None);
assert_eq!(empty.get_ref(Ordering::Relaxed), None);

let filled = FillOnceAtomicOption::new(Box::new(10));
assert_eq!(filled.get_ref(Ordering::Relaxed), Some(&10));

pub fn try_store<V>(&self, data: V, order: Ordering) -> Result<(), NotEmpty> where
    V: Into<Box<T>>, 

Stores new value if FillOnceAtomicOption was not initialized (contains a None)

This operation is implemented as a single atomic compare_and_swap.

use std::sync::atomic::Ordering;
let option = FillOnceAtomicOption::default();
let old = option.try_store(5, Ordering::Relaxed);
assert!(old.is_ok());
assert_eq!(option.get_ref(Ordering::Relaxed), Some(&5));

let failed_to_store = option.try_store(10, Ordering::Relaxed);
assert!(failed_to_store.is_err());
assert_eq!(option.get_ref(Ordering::Relaxed), Some(&5));

pub fn take(&mut self, order: Ordering) -> Option<Box<T>>

Replaces FillOnceAtomicOption value with None returning old value

As opposed to take from AtomicOption

use std::sync::atomic::Ordering;
let mut option = FillOnceAtomicOption::from(5);
assert_eq!(option.take(Ordering::Relaxed), Some(Box::new(5)));
assert_eq!(option.take(Ordering::Relaxed), None);

impl<T: Copy> FillOnceAtomicOption<T>

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

Returns a copy of the wrapped T

use std::sync::atomic::Ordering;
let empty: FillOnceAtomicOption<()> = FillOnceAtomicOption::new(None);
assert_eq!(empty.load(Ordering::Relaxed), None);

let filled = FillOnceAtomicOption::from(10);
assert_eq!(filled.load(Ordering::Relaxed), Some(10));

impl<T> FillOnceAtomicOption<T>

pub fn get_ref<'a>(&'a self, order: Ordering) -> Option<&'a T>

Atomically extracts a reference to the element stored

use std::sync::atomic::Ordering;
let empty: FillOnceAtomicOption<()> = FillOnceAtomicOption::new(None);
assert_eq!(empty.get_ref(Ordering::Relaxed), None);

let filled = FillOnceAtomicOption::from(10);
assert_eq!(filled.get_ref(Ordering::Relaxed), Some(&10));

pub fn into_inner(self) -> Option<Box<T>>

Converts itself into a Option<Box<T>>

let ten = FillOnceAtomicOption::from(10);
assert_eq!(ten.into_inner().map(|a| *a), Some(10));

pub unsafe fn from_raw(ptr: *mut T) -> Self

Creates new FillOnceAtomicOption based on a raw pointer

Safety

Unsafe because it uses a raw pointer, so it can't be sure of its origin (and ownership)

You must own the pointer to call this

use std::{sync::atomic::Ordering, ptr::null_mut};
let empty = unsafe { FillOnceAtomicOption::<()>::from_raw(null_mut()) };
assert_eq!(empty.get_ref(Ordering::Relaxed), None);

let filled = unsafe { FillOnceAtomicOption::from_raw(Box::into_raw(10.into())) };
assert_eq!(filled.get_ref(Ordering::Relaxed), Some(&10));

pub fn get_raw(&self, order: Ordering) -> *mut T

Atomically extracts the stored pointer

If pointer returned is not null it's safe to deref as long as you don't drop the FillOnceAtomicOption

Safety

To deref it you must ensure that it's not null, the FillOnceAtomicOption wasn't dropped

Returns null if FillOnceAtomicOption is empty (was not initialized)

use std::{sync::atomic::Ordering, ptr::null_mut, ops::Deref};
let empty: FillOnceAtomicOption<()> = FillOnceAtomicOption::new(None);
assert_eq!(empty.get_raw(Ordering::Relaxed), null_mut());

let filled = FillOnceAtomicOption::from(10);
assert_eq!(unsafe { (&*filled.get_raw(Ordering::Relaxed)).deref() }, &10);

Trait Implementations

impl<T> Default for FillOnceAtomicOption<T>

fn default() -> Self

Returns the "default value" for a type.

impl<T> From<FillOnceAtomicOption<T>> for AtomicOption<T>

fn from(atomic: FillOnceAtomicOption<T>) -> Self

Performs the conversion.

impl<T> From<T> for FillOnceAtomicOption<T>

fn from(value: T) -> Self

Performs the conversion.

impl<T> From<Box<T>> for FillOnceAtomicOption<T>

fn from(into_ptr: Box<T>) -> Self

Performs the conversion.

impl<T> From<Option<T>> for FillOnceAtomicOption<T>

fn from(into_ptr: Option<T>) -> Self

Performs the conversion.

impl<T> From<Option<Box<T>>> for FillOnceAtomicOption<T>

fn from(into_ptr: Option<Box<T>>) -> Self

Performs the conversion.

impl<T> From<AtomicOption<T>> for FillOnceAtomicOption<T>

fn from(atomic: AtomicOption<T>) -> Self

Performs the conversion.

impl<T> From<Atomic<T>> for FillOnceAtomicOption<T>

fn from(atomic: Atomic<T>) -> Self

Performs the conversion.

impl<T: Debug> Debug for FillOnceAtomicOption<T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T> Pointer for FillOnceAtomicOption<T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.