Struct WriteOnce 

pub struct WriteOnce<T> {
    value: UnsafeCell<MaybeUninit<T>>,
    state: AtomicU8,
}

A thread-safe, wait-free, write-once cell that allows a value to be set exactly once.

WriteOnce provides a way to initialize a value exactly once in a thread-safe manner. Once a value is set, it cannot be changed. This is useful in scenarios where you need to ensure that a value is initialized exactly once, even in the presence of concurrent access.

WriteOnce is similar to std::sync::OnceLock, but with a key difference: it takes a value directly rather than a closure that initializes the value. In other words, we assume an optimistic concurrency model, contrary to OnceLock’s pessimistic model.

This concurrency model allows WriteOnce to be fully wait-free. This also implies that, whereas OnceLock guarantees that the closure is called at most once, WriteOnce guarantees that the value is set at most once.

Thread Safety

WriteOnce is designed to be thread-safe and wait-free, allowing concurrent attempts to set the value from multiple threads. Only the first successful call to set or try_set will initialize the value; subsequent attempts will either panic (with set) or return an error (with try_set).

Memory Safety

WriteOnce uses atomic operations to ensure memory safety and proper synchronization between threads. It guarantees that:

• A value can be set exactly once
• Once set, the value can be safely read from any thread
• The value is properly dropped when the WriteOnce is dropped

Examples

use once::write_once::WriteOnce;

// Create a new WriteOnce with no value
let cell = WriteOnce::<String>::none();

// Set the value
cell.set("Hello, world!".to_string());

// Get the value
assert_eq!(cell.get(), Some(&"Hello, world!".to_string()));

// Attempting to set the value again will panic
// cell.set("Another value".to_string()); // This would panic

// Using try_set instead returns an error
let result = cell.try_set("Another value".to_string());
assert!(result.is_err());
if let Err(value) = result {
    assert_eq!(value, "Another value".to_string());
}

Fields

value: UnsafeCell<MaybeUninit<T>>

state: AtomicU8

Implementations

impl<T> WriteOnce<T>

pub fn none() -> Self

Creates a new WriteOnce with no value.

This initializes the cell in an empty state. The value can be set later using set or try_set.

Examples

use once::write_once::WriteOnce;

let cell = WriteOnce::<i32>::none();
assert_eq!(cell.get(), None);
assert!(!cell.is_set());

pub fn new(value: T) -> Self

Creates a new WriteOnce with a value.

Examples

use once::write_once::WriteOnce;

let cell = WriteOnce::new(2);
assert_eq!(cell.get(), Some(&2));
assert!(cell.is_set());

pub fn set(&self, value: T)

Sets the value of the WriteOnce.

This method sets the value of the cell if it hasn’t been set yet. If the cell already has a value, this method will panic.

Panics

Panics if the cell already has a value.

Examples

use once::write_once::WriteOnce;

let cell = WriteOnce::<i32>::none();
cell.set(42);
assert_eq!(cell.get(), Some(&42));

// Uncommenting the following line would cause a panic:
// cell.set(100);

pub fn try_set(&self, value: T) -> Result<(), T>

Attempts to set the value of the WriteOnce.

This method tries to set the value of the cell if it hasn’t been set yet. If the cell already has a value, this method will return an error containing the value that was attempted to be set.

Returns

• Ok(()) if the value was successfully set
• Err(value) if the cell already had a value, returning the value that was attempted to be set

Examples

use once::write_once::WriteOnce;

let cell = WriteOnce::<String>::none();

// First attempt succeeds
let result = cell.try_set("Hello".to_string());
assert!(result.is_ok());
assert_eq!(cell.get(), Some(&"Hello".to_string()));

// Second attempt fails
let result = cell.try_set("World".to_string());
assert!(result.is_err());
if let Err(value) = result {
    assert_eq!(value, "World".to_string());
}

// The value remains unchanged
assert_eq!(cell.get(), Some(&"Hello".to_string()));

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

Gets the value of the WriteOnce.

Returns Some(&T) if the cell has a value, or None if it doesn’t.

Examples

use once::write_once::WriteOnce;

let cell = WriteOnce::<i32>::none();
assert_eq!(cell.get(), None);

cell.set(42);
assert_eq!(cell.get(), Some(&42));

pub unsafe fn get_unchecked(&self) -> &T

Safety

This method is unsafe because it returns a reference to the value without checking if the value is initialized. The caller must ensure that the value is initialized before calling this method.

pub fn is_set(&self) -> bool

Checks if the WriteOnce has a value.

Returns true if the cell has a value, or false if it doesn’t.

This method only returns true if the value has been set and is ready to be read. In particular, it will return false if the value is currently being set by another thread. This may be relevant if the value is a large object and moving it in memory is expensive.

Examples

use once::write_once::WriteOnce;

let cell = WriteOnce::<i32>::none();
assert!(!cell.is_set());

cell.set(42);
assert!(cell.is_set());

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

Gets a mutable reference to the value of the WriteOnce.

Returns Some(&mut T) if the cell has a value, or None if it doesn’t. This method requires a mutable reference to the WriteOnce, which ensures that no other thread is accessing the value.

Examples

use once::write_once::WriteOnce;

let mut cell = WriteOnce::<String>::none();
assert_eq!(cell.get_mut(), None);

cell.set("Hello".to_string());

// Modify the value through a mutable reference
if let Some(value) = cell.get_mut() {
    value.push_str(", world!");
}

assert_eq!(cell.get(), Some(&"Hello, world!".to_string()));

Trait Implementations

impl<T: Clone> Clone for WriteOnce<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for WriteOnce<T>

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

Formats the value using the given formatter.

impl<T> Drop for WriteOnce<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Hash> Hash for WriteOnce<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: Ord> Ord for WriteOnce<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: PartialEq> PartialEq for WriteOnce<T>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialOrd> PartialOrd for WriteOnce<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: Eq> Eq for WriteOnce<T>

impl<T: Send> Send for WriteOnce<T>

impl<T: Sync> Sync for WriteOnce<T>