Struct ArcAtomicRef

Source

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

Expand description

Shared-owner wrapper around AtomicRef<T>.

This type is a convenience newtype for Arc<AtomicRef<T>>. Cloning an ArcAtomicRef clones the shared owner handle, so all clones operate on the same atomic reference container.

This is different from AtomicRef::clone, which creates a new independent atomic container that initially points to the same value.

§Example

use qubit_atomic::ArcAtomicRef;
use std::sync::Arc;

let config = ArcAtomicRef::from_value(10);
let shared = config.clone();

shared.store(Arc::new(20));
assert_eq!(*config.load(), 20);
assert_eq!(config.strong_count(), 2);

Implementations§

Source §

impl<T> ArcAtomicRef<T>

Source

pub fn new(value: Arc<T>) -> Self

Creates a new shared atomic reference from an Arc<T>.

§Parameters

value - The initial shared value stored in the atomic reference.

§Returns

A shared atomic reference wrapper initialized to value.

Source

pub fn from_value(value: T) -> Self

Creates a new shared atomic reference from an owned value.

§Parameters

value - The owned value to store as the initial reference.

§Returns

A shared atomic reference wrapper initialized to Arc::new(value).

Source

pub fn from_atomic_ref(atomic_ref: AtomicRef<T>) -> Self

Wraps an existing AtomicRef<T> in an Arc.

§Parameters

atomic_ref - The atomic reference container to share.

§Returns

A shared atomic reference wrapper owning atomic_ref.

Source

pub fn from_arc(inner: Arc<AtomicRef<T>>) -> Self

Wraps an existing shared atomic reference container.

§Parameters

inner - The shared atomic reference container to wrap.

§Returns

A wrapper around inner.

Source

pub fn as_arc(&self) -> &Arc<AtomicRef<T>>

Returns the underlying Arc without cloning it.

§Returns

A shared reference to the underlying Arc<AtomicRef<T>>.

Source

pub fn into_arc(self) -> Arc<AtomicRef<T>>

Consumes this wrapper and returns the underlying Arc.

§Returns

The underlying Arc<AtomicRef<T>>.

Source

pub fn strong_count(&self) -> usize

Returns the number of strong Arc owners.

§Returns

The current strong reference count of the shared atomic reference container.

Methods from Deref<Target = AtomicRef<T>>§

Source

pub fn load(&self) -> Arc<T>

Gets the current reference.

§Returns

A cloned Arc pointing to the current value.

§Example

use qubit_atomic::AtomicRef;
use std::sync::Arc;

let atomic = AtomicRef::new(Arc::new(42));
let value = atomic.load();
assert_eq!(*value, 42);

Source

pub fn load_guard(&self) -> Guard<Arc<T>>

Gets the current reference as an ArcSwap guard.

This is useful for short-lived reads because it avoids cloning the underlying Arc on the fast path. Use load when the caller needs an owned Arc<T> that can be stored or moved freely.

§Returns

A guard pointing to the current Arc.

§Example

use qubit_atomic::AtomicRef;
use std::sync::Arc;

let atomic = AtomicRef::new(Arc::new(42));
let guard = atomic.load_guard();
assert_eq!(**guard, 42);

Source

pub fn store(&self, value: Arc<T>)

Sets a new reference.

§Parameters

value - The new reference to set.

§Example

use qubit_atomic::AtomicRef;
use std::sync::Arc;

let atomic = AtomicRef::new(Arc::new(42));
atomic.store(Arc::new(100));
assert_eq!(*atomic.load(), 100);

Source

pub fn swap(&self, value: Arc<T>) -> Arc<T>

Swaps the current reference with a new reference, returning the old reference.

§Parameters

value - The new reference to swap in.

§Returns

The old reference.

§Example

use qubit_atomic::AtomicRef;
use std::sync::Arc;

let atomic = AtomicRef::new(Arc::new(10));
let old = atomic.swap(Arc::new(20));
assert_eq!(*old, 10);
assert_eq!(*atomic.load(), 20);

Source

pub fn compare_set(&self, current: &Arc<T>, new: Arc<T>) -> Result<(), Arc<T>>

Compares and sets the reference atomically.

If the current reference equals current (by pointer equality), sets it to new and returns Ok(()). Otherwise, returns Err(actual) where actual is the current reference.

§Parameters

current - The expected current reference.
new - The new reference to set if current matches.

§Returns

Ok(()) if the pointer comparison succeeds and new is stored.

§Errors

Returns Err(actual) with the observed current reference when the pointer comparison fails. On failure, new is not installed.

§Note

Comparison uses pointer equality (Arc::ptr_eq), not value equality.

§Example

use qubit_atomic::AtomicRef;
use std::sync::Arc;

let atomic = AtomicRef::new(Arc::new(10));
let current = atomic.load();

assert!(atomic.compare_set(&current, Arc::new(20)).is_ok());
assert_eq!(*atomic.load(), 20);

Source

pub fn compare_set_weak( &self, current: &Arc<T>, new: Arc<T>, ) -> Result<(), Arc<T>>

Weak version of compare-and-set.

This implementation currently delegates to the same lock-free CAS as compare_set, so it does not introduce extra spurious failures.

§Parameters

current - The expected current reference.
new - The new reference to set if current matches.

§Returns

Ok(()) if the pointer comparison succeeds and new is stored.

§Errors

Returns Err(actual) with the observed current reference when the pointer comparison fails. On failure, new is not installed. This implementation currently delegates to compare_set and does not add extra spurious failures.

§Example

use qubit_atomic::AtomicRef;
use std::sync::Arc;

let atomic = AtomicRef::new(Arc::new(10));
let mut current = atomic.load();
loop {
    match atomic.compare_set_weak(&current, Arc::new(20)) {
        Ok(_) => break,
        Err(actual) => current = actual,
    }
}
assert_eq!(*atomic.load(), 20);

Source

pub fn compare_and_exchange(&self, current: &Arc<T>, new: Arc<T>) -> Arc<T>

Compares and exchanges the reference atomically, returning the previous reference.

If the current reference equals current (by pointer equality), sets it to new and returns the old reference. Otherwise, returns the actual current reference.

§Parameters

current - The expected current reference.
new - The new reference to set if current matches.

§Returns

The reference before the operation.

§Note

Comparison uses pointer equality (Arc::ptr_eq), not value equality.

§Example

use qubit_atomic::AtomicRef;
use std::sync::Arc;

let atomic = AtomicRef::new(Arc::new(10));
let current = atomic.load();

let prev = atomic.compare_and_exchange(&current, Arc::new(20));
assert!(Arc::ptr_eq(&prev, &current));
assert_eq!(*atomic.load(), 20);

Source

pub fn compare_and_exchange_weak(&self, current: &Arc<T>, new: Arc<T>) -> Arc<T>

Weak version of compare-and-exchange.

This implementation currently delegates to the same lock-free CAS as compare_and_exchange, so it does not introduce extra spurious failures.

§Parameters

current - The expected current reference.
new - The new reference to set if current matches.

§Returns

The reference before the operation.

§Example

use qubit_atomic::AtomicRef;
use std::sync::Arc;

let atomic = AtomicRef::new(Arc::new(10));
let mut current = atomic.load();
loop {
    let prev =
        atomic.compare_and_exchange_weak(&current, Arc::new(20));
    if Arc::ptr_eq(&prev, &current) {
        break;
    }
    current = prev;
}
assert_eq!(*atomic.load(), 20);

Source

pub fn fetch_update<F>(&self, f: F) -> Arc<T>
where F: Fn(&Arc<T>) -> Arc<T>,

Updates the reference using a function, returning the old reference.

Internally uses a CAS loop until the update succeeds.

§Parameters

f - A function that takes the current reference and returns the new reference.

§Returns

The old reference before the update.

The closure may be called more than once when concurrent updates cause CAS retries.

§Example

use qubit_atomic::AtomicRef;
use std::sync::Arc;

let atomic = AtomicRef::new(Arc::new(10));
let old = atomic.fetch_update(|x| Arc::new(**x * 2));
assert_eq!(*old, 10);
assert_eq!(*atomic.load(), 20);

Source

pub fn try_update<F>(&self, f: F) -> Option<Arc<T>>
where F: Fn(&Arc<T>) -> Option<Arc<T>>,

Conditionally updates the reference using a function.

Internally uses a pointer-based CAS loop until the update succeeds or the closure rejects the current reference by returning None.

§Parameters

f - A function that takes the current reference and returns the new reference, or None to leave the current reference unchanged.

§Returns

Some(old_reference) when the update succeeds, or None when f rejects the observed current reference.

The closure may be called more than once when concurrent updates cause CAS retries.

§Example

use qubit_atomic::AtomicRef;
use std::sync::Arc;

let atomic = AtomicRef::new(Arc::new(3));
let old = atomic.try_update(|current| {
    (**current % 2 == 1).then_some(Arc::new(**current + 1))
});
assert_eq!(*old.unwrap(), 3);
assert_eq!(*atomic.load(), 4);
assert!(atomic
    .try_update(|current| {
        (**current % 2 == 1).then_some(Arc::new(**current + 1))
    })
    .is_none());
assert_eq!(*atomic.load(), 4);