Struct AtomicCell

pub struct AtomicCell<T, A: Allocator = Global> { /* private fields */ }

Available on crate feature alloc only.

An atomic cell that can be safely shared between threads and can contain an optional value.

AtomicCell provides methods to store, replace, and take values atomically, ensuring safe access and modification across multiple threads.

Example

use utils_atomics::AtomicCell;

let mut atomic_cell = AtomicCell::new(Some(42));

std::thread::scope(|s| {
    // Spawn a thread that replaces the value inside the AtomicCell
    s.spawn(|| {
        let prev_value = atomic_cell.replace(Some(24));
        assert_eq!(prev_value, Some(42));
    });
});

// Check that the value was replaced
assert_eq!(atomic_cell.get_mut().copied(), Some(24));

Implementations

impl<T, A: Allocator> AtomicCell<T, A>

pub fn new_in(t: impl Into<Option<T>>, alloc: A) -> Self

Available on crate feature alloc_api only.

Constructs a new AtomicCell containing an optional value t and an allocator alloc.

If the value is Some(x), it is boxed using the allocator. If the value is None, an empty AtomicCell is created with the allocator.

Example

#![feature(allocator_api)]

use utils_atomics::AtomicCell;
use std::alloc::System;

let atomic_cell = AtomicCell::<i32, _>::new_in(Some(42), System);

pub fn new_boxed_in(t: Result<Box<T, A>, A>) -> Self

Available on crate feature alloc_api only.

Constructs a new AtomicCell from a boxed value or an allocator.

If the input is Ok(t), the AtomicCell contains the boxed value, and the allocator is extracted from the box. If the input is Err(alloc), an empty AtomicCell is created with the allocator.

Example

#![feature(allocator_api)]
extern crate alloc;

use utils_atomics::AtomicCell;
use std::alloc::System;
use alloc::boxed::Box;
    
let atomic_cell = AtomicCell::new_boxed_in(Ok(Box::new_in(42, System)));

pub fn allocator(&self) -> &A

Available on crate feature alloc_api only.

Returns a reference to the allocator associated with the AtomicCell.

Example

#![feature(allocator_api)]

use utils_atomics::AtomicCell;
use std::alloc::System;

let atomic_cell = AtomicCell::<i32, System>::new_in(Some(42), System);
let allocator = atomic_cell.allocator();

pub fn take_in(&self) -> Option<Box<T, &A>>

Available on crate feature alloc_api only.

Takes the value out of the AtomicCell, leaving it empty.

Returns an optional boxed value with a reference to the allocator. If the AtomicCell is empty, returns None.

Example

#![feature(allocator_api)]

use utils_atomics::AtomicCell;
use std::alloc::System;

let atomic_cell = AtomicCell::new_in(Some(42), System);
let taken_value = atomic_cell.take_in();
assert_eq!(taken_value, Some(Box::new_in(42, &System)))

pub fn replace_in(&self, new: impl Into<Option<T>>) -> Option<Box<T, &A>>

Available on crate feature alloc_api only.

Replaces the value inside the AtomicCell with a new optional value.

If the new value is Some(new), it is boxed using the allocator. If the new value is None, the AtomicCell is emptied.

Returns the old value as an optional boxed value with a reference to the allocator. If the AtomicCell was empty, returns None.

Example

#![feature(allocator_api)]

use utils_atomics::AtomicCell;
use std::alloc::System;

let atomic_cell = AtomicCell::new_in(Some(42), System);
let old_value = atomic_cell.replace_in(Some(24));
assert_eq!(old_value, Some(Box::new_in(42, atomic_cell.allocator())));
assert_eq!(atomic_cell.take(), Some(24));

impl<T> AtomicCell<T>

pub fn new(t: impl Into<Option<T>>) -> Self

Constructs a new AtomicCell containing an optional value t.

Example

use utils_atomics::AtomicCell;

let atomic_cell = AtomicCell::<i32>::new(Some(42));

pub fn new_boxed(t: impl Into<Option<Box<T>>>) -> Self

Constructs a new AtomicCell from an optional boxed value t.

Example

extern crate alloc;

use utils_atomics::AtomicCell;
use alloc::boxed::Box;

let atomic_cell = AtomicCell::new_boxed(Some(Box::new(42)));

pub fn replace(&self, new: impl Into<Option<T>>) -> Option<T>

Replaces the value inside the AtomicCell with a new optional value new. Returns the old value as an optional value. If the AtomicCell was empty, returns None.

Example

use utils_atomics::AtomicCell;

let atomic_cell = AtomicCell::<i32>::new(Some(42));
let old_value = atomic_cell.replace(Some(24));

pub fn replace_boxed(&self, new: impl Into<Option<Box<T>>>) -> Option<Box<T>>

Replaces the value inside the AtomicCell with a new optional boxed value new. Returns the old value as an optional boxed value. If the AtomicCell was empty, returns None.

Example

extern crate alloc;

use utils_atomics::AtomicCell;
use alloc::boxed::Box;

let atomic_cell = AtomicCell::new_boxed(Some(Box::new(42)));
let old_value = atomic_cell.replace_boxed(Some(Box::new(24)));

pub fn take_boxed(&self) -> Option<Box<T>>

Takes the value out of the AtomicCell, leaving it empty. Returns an optional boxed value. If the AtomicCell is empty, returns None.

Example

use utils_atomics::AtomicCell;

let atomic_cell = AtomicCell::new_boxed(Some(Box::new(42)));
let taken_value = atomic_cell.take_boxed();

impl<T, A: Allocator> AtomicCell<T, A>

pub fn take(&self) -> Option<T>

Takes the value out of the AtomicCell, leaving it empty. Returns an optional value. If the AtomicCell is empty, returns None.

Examples

use utils_atomics::AtomicCell;

let atomic_cell = AtomicCell::new(Some(42));
assert_eq!(atomic_cell.take(), Some(42));
assert_eq!(atomic_cell.take(), None);

pub fn get_mut(&mut self) -> Option<&mut T>

Returns a mutable reference to the value inside the AtomicCell, if any. If the AtomicCell is empty, returns None.

Examples

use utils_atomics::AtomicCell;

let mut atomic_cell = AtomicCell::new(Some(42));
let value_ref = atomic_cell.get_mut().unwrap();
*value_ref = 24;
assert_eq!(*value_ref, 24);

pub fn is_some(&self) -> bool

Returns true if the AtomicCell contains a value.

Examples

use utils_atomics::AtomicCell;

let atomic_cell = AtomicCell::<i32>::new(Some(42));
assert!(atomic_cell.is_some());

pub fn is_none(&self) -> bool

Returns true if the AtomicCell is empty.

Examples

use utils_atomics::AtomicCell;

let atomic_cell = AtomicCell::<i32>::new(None);
assert!(atomic_cell.is_none());

Trait Implementations

impl<T: Debug, A: Debug + Allocator> Debug for AtomicCell<T, A>

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

Formats the value using the given formatter.

impl<T, A: Allocator> Drop for AtomicCell<T, A>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Send, A: Allocator + Send> Send for AtomicCell<T, A>

impl<T: Sync, A: Allocator + Sync> Sync for AtomicCell<T, A>