Struct voluntary_servitude::atomics::Atomic

source ·

pub struct Atomic<T>(_, _);

Expand description

Atomic Box<T>

It can’t provide a reference to the current value since it may be dropped at any time

You must swap the element to access it

FillOnceAtomicOption provides a API that enables access to the reference, but only enables try_store to write to it

Implementations

source

impl<T> Atomic<T>

source

pub fn new<V>(data: V) -> Selfwhere
V: Into<Box<T>>,

Creates new Atomic

let filled = Atomic::new(10);
assert_eq!(*filled.into_inner(), 10);

source

pub fn store<V>(&self, new: V, order: Ordering)where
V: Into<Box<T>>,

Stores value into Atomic and drops old one

use std::sync::atomic::Ordering;
let filled = Atomic::from(10);
filled.store(5, Ordering::SeqCst);
assert_eq!(*filled.into_inner(), 5);

source

pub fn swap<V>(&self, new: V, order: Ordering) -> Box<T>where
V: Into<Box<T>>,

Stores value into Atomic returning old value

use std::sync::atomic::Ordering;
let option = Atomic::from(10);
assert_eq!(*option.swap(4, Ordering::SeqCst), 10);
assert_eq!(*option.into_inner(), 4);

source

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

Converts itself into a Box<T>

let ten = Atomic::from(10);
assert_eq!(*ten.into_inner(), 10);

source

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

Creates new Atomic if pointer is not null (like NonNull)

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::ptr::null_mut;
let empty: Option<Atomic<()>> = unsafe { Atomic::from_raw(null_mut()) };
assert!(empty.is_none());

let filled = unsafe { Atomic::from_raw(Box::into_raw(Box::new(10))) };
assert_eq!(filled.map(|a| *a.into_inner()), Some(10));

source

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

Creates new Atomic based on raw pointer without checking for null pointer

Safety

Unsafe because it trusts that the pointer is not null and because it can’t be sure of the origin of T (and ownership)

You must own the pointer to call this

let filled = unsafe { Atomic::from_raw_unchecked(Box::into_raw(Box::new(10))) };
assert_eq!(*filled.into_inner(), 10);

// It's UB for `ptr` to be `null_mut()`
// let empty = unsafe { Atomic::<()>::from_raw_unchecked(null_mut()) };

source

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

Atomically extracts the current stored pointer, this function should probably not be called

Safety

It’s almost never safe to deref this value, it could have been dropped from the moment you extracted it to the moment you deref/access it in any way, it will cause UB

It exists to provide a way of implementing safe wrappers (like FillOnceAtomicOption)

use std::{sync::atomic::Ordering, ptr::null_mut};

let ptr = Box::into_raw(Box::new(10u8));
let filled = unsafe { Atomic::from_raw(ptr) };
assert_eq!(filled.map(|a| a.get_raw(Ordering::SeqCst)), Some(ptr));

// You should probably never deref `ptr`
// You should probably never use this method
// UB will be everywhere, FillOnceAtomicOption is a safe an alternative