Struct OnceArc 

pub struct OnceArc<T> { /* private fields */ }

A thread-safe container that can be atomically initialized once with an Arc<T>.

This is conceptually similar to Atomic<Option<Arc<T>>>, but with a critical restriction: the value can only be set once. This restriction is what makes the implementation both sound and extremely fast — load is a single atomic read with no reference count manipulation.

Examples

use std::sync::Arc;
use std::sync::atomic::Ordering;
use once_arc::OnceArc;

let slot: OnceArc<i32> = OnceArc::new();
assert!(slot.get(Ordering::Acquire).is_none());

slot.store(Arc::new(42), Ordering::Release).unwrap();

// get() returns &T — just a single atomic load
assert_eq!(slot.get(Ordering::Acquire), Some(&42));

// load() returns a cloned Arc
let arc = slot.load(Ordering::Acquire).unwrap();
assert_eq!(*arc, 42);

// Second store fails and returns the value back.
let err = slot.store(Arc::new(99), Ordering::Release).unwrap_err();
assert_eq!(*err, 99);

Implementations

impl<T> OnceArc<T>

pub const fn new() -> Self

Creates a new empty OnceArc.

Examples

use once_arc::OnceArc;

let slot: OnceArc<i32> = OnceArc::new();

pub fn store(&self, value: Arc<T>, ordering: Ordering) -> Result<(), Arc<T>>

Attempts to store the value. Returns Ok(()) if this is the first call, or Err(value) if a value was already stored.

ordering describes the required ordering for the read-modify-write operation that takes place if the None-check succeeds. Using Acquire as ordering makes the store part of this operation Relaxed, and using Release makes the load Relaxed.

Examples

use std::sync::Arc;
use std::sync::atomic::Ordering;
use once_arc::OnceArc;

let slot: OnceArc<i32> = OnceArc::new();
assert!(slot.store(Arc::new(42), Ordering::Release).is_ok());

// Second store fails
let err = slot.store(Arc::new(99), Ordering::Release).unwrap_err();
assert_eq!(*err, 99);

pub fn get(&self, ordering: Ordering) -> Option<&T>

Returns a reference to the stored value, or None if not yet set.

This is extremely fast: a single atomic load with no reference count manipulation. The returned reference is valid for as long as &self is valid, because the stored Arc is never removed until self is dropped.

Examples

use std::sync::Arc;
use std::sync::atomic::Ordering;
use once_arc::OnceArc;

let slot: OnceArc<i32> = OnceArc::new();
assert_eq!(slot.get(Ordering::Acquire), None);

slot.store(Arc::new(42), Ordering::Release).unwrap();
assert_eq!(slot.get(Ordering::Acquire), Some(&42));

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

Loads the stored value as a cloned Arc<T>. This increments the reference count, so the caller gets an independent handle to the underlying data.

Returns None if the value has not been set yet.

Examples

use std::sync::Arc;
use std::sync::atomic::Ordering;
use once_arc::OnceArc;

let slot = OnceArc::from(Arc::new(42));
let arc = slot.load(Ordering::Acquire).unwrap();
assert_eq!(*arc, 42);

pub fn is_set(&self, ordering: Ordering) -> bool

Returns true if a value has been stored.

Examples

use std::sync::Arc;
use std::sync::atomic::Ordering;
use once_arc::OnceArc;

let slot: OnceArc<i32> = OnceArc::new();
assert!(!slot.is_set(Ordering::Relaxed));

slot.store(Arc::new(1), Ordering::Release).unwrap();
assert!(slot.is_set(Ordering::Relaxed));

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

Consumes self and returns the stored Arc<T>, if any.

Examples

use std::sync::Arc;
use std::sync::atomic::Ordering;
use once_arc::OnceArc;

let slot = OnceArc::from(Arc::new(42));
let arc = slot.into_inner().unwrap();
assert_eq!(*arc, 42);

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

Returns a mutable reference to the stored value, or None if not yet set.

Since this requires &mut self, no atomic operations are needed and this is guaranteed to be the only accessor.

Examples

use std::sync::Arc;
use std::sync::atomic::Ordering;
use once_arc::OnceArc;

let mut slot = OnceArc::from(Arc::new(10));
*slot.get_mut().unwrap() = 20;
assert_eq!(slot.get(Ordering::Acquire), Some(&20));

Trait Implementations

impl<T: Debug> Debug for OnceArc<T>

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

Formats the value using the given formatter.

impl<T> Default for OnceArc<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> Drop for OnceArc<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> From<Arc<T>> for OnceArc<T>

fn from(value: Arc<T>) -> Self

Converts to this type from the input type.

impl<T> From<Option<Arc<T>>> for OnceArc<T>

fn from(value: Option<Arc<T>>) -> Self

Converts to this type from the input type.

impl<T: Send + Sync> Send for OnceArc<T>

impl<T: Send + Sync> Sync for OnceArc<T>