Struct AtomicRef

Source

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

Expand description

Atomic reference type.

Provides easy-to-use atomic operations on references with automatic memory ordering selection. Uses Arc<T> for thread-safe reference counting.

§Implementation Details

This type is backed by arc_swap::ArcSwap<T>, which provides lock-free, memory-safe atomic replacement and loading of Arc<T> values without exposing raw-pointer lifetime hazards.

§Features

Automatic memory ordering selection
Thread-safe reference counting via Arc
Functional update operations
Zero-cost abstraction with inline methods

§Example

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

#[derive(Debug, Clone)]
struct Config {
    timeout: u64,
    max_retries: u32,
}

let config = Arc::new(Config {
    timeout: 1000,
    max_retries: 3,
});

let atomic_config = AtomicRef::new(config);

// Update configuration
let new_config = Arc::new(Config {
    timeout: 2000,
    max_retries: 5,
});

let old_config = atomic_config.swap(new_config);
assert_eq!(old_config.timeout, 1000);
assert_eq!(atomic_config.load().timeout, 2000);

§Author

Haixing Hu

Implementations§

Source §

impl<T> AtomicRef<T>

Source

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

Creates a new atomic reference.

§Parameters

value - The initial reference.

§Example

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

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

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 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(()) on success, or Err(actual) on failure.

§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(()) on success, or Err(actual) on failure.

§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.

§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);