qubit-atomic

User-friendly atomic operations wrapper providing JDK-like atomic API for Rust.

Overview

Qubit Atomic is a comprehensive atomic operations library that provides easy-to-use atomic types with reasonable default memory orderings, similar to Java's java.util.concurrent.atomic package. It hides the complexity of memory ordering while maintaining zero-cost abstraction and allowing advanced users to access underlying types for fine-grained control.

Design Goals

• Ease of Use: Hides memory ordering complexity with reasonable defaults
• Completeness: Provides high-level operations similar to JDK atomic classes
• Safety: Guarantees memory safety and thread safety
• Performance: Zero-cost abstraction with no additional overhead
• Flexibility: Exposes narrowly scoped ordered integer RMW helpers and

inner() for advanced users

• Simplicity: Default APIs keep common cases free of explicit ordering

parameters

Features

🔢 Generic Atomic Primitive Types

• Integer Specializations: Atomic<i8>, Atomic<u8>, Atomic<i16>, Atomic<u16>, Atomic<i32>, Atomic<u32>, Atomic<i64>, Atomic<u64>, Atomic<i128>, Atomic<u128>, Atomic<isize>, Atomic<usize>
• Boolean Specialization: Atomic<bool> with set, clear, negate, logical AND/OR/XOR, and conditional CAS helpers
• Floating-Point Specializations: Atomic<f32> and Atomic<f64> with arithmetic operations implemented through CAS loops
• Rich Operations: increment, decrement, add, subtract, multiply, divide, bitwise operations, max/min
• Functional Updates: fetch_update, update_and_get, try_update, try_update_and_get, fetch_accumulate, accumulate_and_get
• Const Initialization Escape Hatch: concrete wrappers such as atomic::primitive::AtomicBool, AtomicU8, and AtomicF32 expose const fn new for static initialization when the generic Atomic<T> constructor cannot be used in const contexts

🔢 AtomicCount and AtomicSignedCount

• AtomicCount: non-negative count for active tasks, in-flight requests, and resource usage
• AtomicSignedCount: signed count for deltas, balances, backlog, and offsets
• No-Wrap Semantics: checked updates that panic or return None instead of wrapping
• Zero-Transition Logic: inc, dec, add, and sub return the new value

🔗 Atomic Reference Type

• AtomicRef<T>: Thread-safe atomic reference using Arc<T>
• Reference Updates: Atomic swap and CAS operations
• Guarded Loads: load_guard() for short-lived reads without cloning on the fast path
• Functional Updates: Transform references atomically with fetch_update / update_and_get or conditionally with try_update / try_update_and_get

🤝 Shared-Owner Convenience Wrappers

• ArcAtomic<T>: convenience newtype around Arc<Atomic<T>>
• ArcAtomicRef<T>: convenience newtype around Arc<AtomicRef<T>>
• ArcAtomicCount / ArcAtomicSignedCount: shared-owner wrappers for the count types
• Shared Container Clone: cloning an ArcAtomic* value shares the same atomic container

🎯 Focused Public API

• Atomic<T>: Generic entry point for primitive atomic values
• *atomic::primitive::**: concrete primitive wrappers for const fn new use cases
• AtomicRef<T>: Atomic Arc<T> reference wrapper
• AtomicCount / AtomicSignedCount: checked state-oriented semantics (no silent wrap)
• *ArcAtomic wrappers**: ergonomic shared ownership without spelling Arc<...> at every use site

Installation

Add this to your Cargo.toml:

[dependencies]
qubit-atomic = "0.13"

Quick Start

Specifying the value type T

Atomic<T> is generic over the primitive value type. Rust usually infers T from the argument to Atomic::new, but literals such as 0 can be ambiguous across integer widths.

In those cases, pick T explicitly using a turbofish on the constructor, or by annotating the variable:

use qubit_atomic::Atomic;

let wide: Atomic<u64> = Atomic::new(0);
assert_eq!(wide.load(), 0u64);

let narrow = Atomic::<i16>::new(0);
assert_eq!(narrow.load(), 0i16);

Const initialization

Use Atomic<T> for normal code. The generic constructor is the intended entry point because it keeps the public API compact and lets one type cover all primitive specializations.

Rust stable does not currently allow Atomic<T>::new to call the hidden trait constructor in a const fn. When you need a static or another const-initialized atomic value, use the concrete wrappers under atomic::primitive:

use qubit_atomic::atomic::primitive::{
    AtomicBool,
    AtomicU32,
};

static READY: AtomicBool = AtomicBool::new(false);
static NEXT_ID: AtomicU32 = AtomicU32::new(1);

Example: concurrent Atomic<i32>

use qubit_atomic::Atomic;
use std::sync::Arc;
use std::thread;

fn main() {
    let counter = Arc::new(Atomic::<i32>::new(0));
    let mut handles = vec![];

    // Spawn 10 threads, each increments counter 1000 times
    for _ in 0..10 {
        let counter = counter.clone();
        let handle = thread::spawn(move || {
            for _ in 0..1000 {
                counter.fetch_inc();
            }
        });
        handles.push(handle);
    }

    // Wait for all threads to complete
    for handle in handles {
        handle.join().unwrap();
    }

    // Verify result
    assert_eq!(counter.load(), 10000);
    println!("Final count: {}", counter.load());
}

AtomicCount and AtomicSignedCount

Use Atomic<T> for pure metrics. Use AtomicCount when the count is part of concurrent state, such as active work or termination checks.

use qubit_atomic::{
    AtomicCount,
    AtomicSignedCount,
};

fn main() {
    let active_tasks = AtomicCount::zero();

    active_tasks.inc();
    assert!(!active_tasks.is_zero());

    if active_tasks.dec() == 0 {
        println!("all active tasks are finished");
    }

    let backlog_delta = AtomicSignedCount::zero();
    assert_eq!(backlog_delta.add(5), 5);
    assert_eq!(backlog_delta.sub(8), -3);
    assert!(backlog_delta.is_negative());
}

Shared-owner wrappers

Use the ArcAtomic* wrappers when the atomic container itself is shared across threads or components. Their clone() operation clones the outer Arc, so all clones observe and update the same container.

use qubit_atomic::{
    ArcAtomic,
    ArcAtomicCount,
    ArcAtomicRef,
    ArcAtomicSignedCount,
};
use std::sync::Arc;
use std::thread;

fn main() {
    let requests = ArcAtomic::new(0usize);
    let worker_requests = requests.clone();

    let handle = thread::spawn(move || {
        worker_requests.fetch_inc();
    });
    handle.join().expect("worker should finish");

    assert_eq!(requests.load(), 1);
    assert_eq!(requests.strong_count(), 1);

    let active_tasks = ArcAtomicCount::zero();
    let shared_tasks = active_tasks.clone();
    assert_eq!(shared_tasks.inc(), 1);
    assert_eq!(active_tasks.get(), 1);

    let backlog = ArcAtomicSignedCount::zero();
    let shared_backlog = backlog.clone();
    assert_eq!(shared_backlog.sub(3), -3);
    assert_eq!(backlog.get(), -3);

    let config = ArcAtomicRef::from_value(String::from("v1"));
    let same_config = config.clone();
    same_config.store(Arc::new(String::from("v2")));
    assert_eq!(config.load().as_str(), "v2");
}

CAS Loop

use qubit_atomic::Atomic;

fn increment_even_only(atomic: &Atomic<i32>) -> Result<i32, &'static str> {
    let mut current = atomic.load();
    loop {
        // Only increment even values
        if current % 2 != 0 {
            return Err("Value is odd");
        }

        let new = current + 2;
        match atomic.compare_set(current, new) {
            Ok(_) => return Ok(new),
            Err(actual) => current = actual, // Retry
        }
    }
}

fn main() {
    let atomic = Atomic::<i32>::new(10);
    match increment_even_only(&atomic) {
        Ok(new_value) => println!("Successfully incremented to: {}", new_value),
        Err(e) => println!("Failed: {}", e),
    }
    assert_eq!(atomic.load(), 12);
}

Functional Updates

use qubit_atomic::Atomic;

fn main() {
    let atomic = Atomic::<i32>::new(10);

    // Update using a function (returns old value)
    let old_value = atomic.fetch_update(|x| {
        if x < 100 {
            x * 2
        } else {
            x
        }
    });

    assert_eq!(old_value, 10);
    assert_eq!(atomic.load(), 20);
    println!("Updated value: {}", atomic.load());

    // Update and return the committed new value
    let new_value = atomic.update_and_get(|x| x + 5);
    assert_eq!(new_value, 25);
    assert_eq!(atomic.load(), 25);

    // Conditional update and return the committed new value
    let accepted_new = atomic.try_update_and_get(|x| (x < 100).then_some(x + 5));
    assert_eq!(accepted_new, Some(30));
    assert_eq!(atomic.load(), 30);

    // Accumulate operation (returns old value)
    let old_result = atomic.fetch_accumulate(5, |a, b| a + b);
    assert_eq!(old_result, 30);
    assert_eq!(atomic.load(), 35);

    // Accumulate and return the committed new value
    let accumulated = atomic.accumulate_and_get(5, |a, b| a + b);
    assert_eq!(accumulated, 40);
    assert_eq!(atomic.load(), 40);
    println!("Accumulated value: {}", atomic.load());
}

Atomic Reference

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

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

fn main() {
    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);
    println!("Old config: {:?}", old_config);
    println!("New config: {:?}", atomic_config.load());

    // Update using a function (returns old value)
    let old = atomic_config.fetch_update(|current| {
        Arc::new(Config {
            timeout: current.timeout * 2,
            max_retries: current.max_retries + 1,
        })
    });

    println!("Previous config: {:?}", old);
    println!("Updated config: {:?}", atomic_config.load());

    // Update and return the committed new reference
    let updated = atomic_config.update_and_get(|current| {
        Arc::new(Config {
            timeout: current.timeout + 500,
            max_retries: current.max_retries + 1,
        })
    });
    println!("Committed config: {:?}", updated);

    // Short-lived read without cloning the Arc on the fast path
    let snapshot = atomic_config.load_guard();
    println!("Snapshot config: {:?}", snapshot);

    // Conditional update; returns the committed new reference or None if rejected
    let accepted = atomic_config.try_update_and_get(|current| {
        (current.timeout < 10_000).then_some(Arc::new(Config {
            timeout: current.timeout + 1000,
            max_retries: current.max_retries,
        }))
    });
    assert!(accepted.is_some());
}

Boolean Flag

use qubit_atomic::Atomic;
use std::sync::Arc;

struct Service {
    running: Arc<Atomic<bool>>,
}

impl Service {
    fn new() -> Self {
        Self {
            running: Arc::new(Atomic::<bool>::new(false)),
        }
    }

    fn start(&self) {
        // Only start if not already running
        if self.running.set_if_false(true).is_ok() {
            println!("Service started successfully");
        } else {
            println!("Service is already running");
        }
    }

    fn stop(&self) {
        // Only stop if currently running
        if self.running.set_if_true(false).is_ok() {
            println!("Service stopped successfully");
        } else {
            println!("Service is already stopped");
        }
    }

    fn is_running(&self) -> bool {
        self.running.load()
    }
}

fn main() {
    let service = Service::new();

    service.start();
    assert!(service.is_running());

    service.start(); // Duplicate start will fail

    service.stop();
    assert!(!service.is_running());

    service.stop(); // Duplicate stop will fail
}

Floating-Point Atomics

use qubit_atomic::Atomic;
use std::sync::Arc;
use std::thread;

fn main() {
    let sum = Arc::new(Atomic::<f32>::new(0.0));
    let mut handles = vec![];

    // Spawn 10 threads, each adds 100 times
    for _ in 0..10 {
        let sum = sum.clone();
        let handle = thread::spawn(move || {
            for _ in 0..100 {
                sum.fetch_add(0.01);
            }
        });
        handles.push(handle);
    }

    for handle in handles {
        handle.join().unwrap();
    }

    // Note: Due to floating-point precision, result may not be exactly 10.0
    let result = sum.load();
    println!("Sum: {:.6}", result);
    println!("Error: {:.6}", (result - 10.0).abs());
}

API Reference

Common Operations

Primitive Weak CAS Operations

These methods are available on primitive Atomic<T> specializations. They are not available on AtomicRef<T>, which exposes strong pointer CAS only.

Integer Operations

Primitive integer operations intentionally use wrapping arithmetic on overflow and underflow, matching Rust atomic integer semantics. Use AtomicCount or AtomicSignedCount when overflow or underflow should be rejected. The _with_ordering variants are available only for integer read-modify-write counter arithmetic, for cases where the counter value is also used as a synchronization signal.

AtomicCount / AtomicSignedCount operations

Shared-owner wrapper operations

The ArcAtomic* wrappers dereference to their underlying atomic container, so you can call operations such as load, fetch_inc, store, inc, and sub directly on the wrapper.

Boolean Operations

Floating-Point Operations

Floating-point CAS operations (compare_set, compare_and_exchange, and weak variants) compare raw to_bits() representations, not PartialEq. Values such as 0.0 and -0.0 compare equal but do not CAS-match, and NaN payload bits must match exactly. Use compare_set when you need an explicit success result, or compare to_bits() values yourself.

Memory Ordering Strategy

Advanced Usage: Explicit Ordering and Direct Access

For integer counter arithmetic that needs synchronization semantics, use the ordered variants before reaching for inner():

use std::sync::atomic::Ordering;
use qubit_atomic::Atomic;

let atomic = Atomic::<i32>::new(0);

// 99% of scenarios: use simple API
let value = atomic.load();

// State-signal counter: keep the wrapper while choosing ordering explicitly
atomic.fetch_add_with_ordering(1, Ordering::AcqRel);

// Lowest-level escape hatch: direct backend access
let value = atomic.inner().load(Ordering::Relaxed);
atomic.inner().store(42, Ordering::Release);

Comparison with JDK

Performance Considerations

Zero-Cost Abstraction

Primitive wrappers use #[repr(transparent)] and #[inline] so the generic API compiles down to the backend atomic operations:

use qubit_atomic::Atomic;
use std::sync::atomic::Ordering;

// Our wrapper
let atomic = Atomic::<i32>::new(0);
let value = atomic.load();

// Compiles to the same code as
let atomic = std::sync::atomic::AtomicI32::new(0);
let value = atomic.load(Ordering::Acquire);

When to Use inner()

99% of scenarios: Use default API, which already provides optimal performance.

1% of scenarios: Use inner() only when:

• Extreme performance optimization (need Relaxed ordering)
• Complex lock-free algorithms (need precise memory ordering control)
• Interoperating with code that directly uses standard library or portable-atomic backend types

Golden Rule: Default API first, inner() as last resort.

Testing & Code Coverage

This project maintains comprehensive test coverage with detailed validation of all functionality.

Running Tests

# Run all tests
cargo test

# Run benchmarks
cargo bench --bench atomic_bench

# List benchmark scenarios
cargo bench --bench atomic_bench -- --list

# Run with coverage report
./coverage.sh

# Generate text format report
./coverage.sh text

# Run CI checks (format, clippy, test, coverage)
./ci-check.sh

Coverage Metrics

See COVERAGE.md for detailed coverage statistics.

Dependencies

Runtime dependencies are intentionally small:

• arc-swap powers AtomicRef<T>.
• portable-atomic provides the stable backend for Atomic<i128> and Atomic<u128>.

License

Copyright (c) 2025 - 2026. Haixing Hu, Qubit Co. Ltd. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See LICENSE for the full license text.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Guidelines

• Follow the Rust API guidelines
• Maintain comprehensive test coverage
• Document all public APIs with examples
• Ensure all tests pass before submitting PR

Author

Haixing Hu - Qubit Co. Ltd.

Related Projects

More Rust libraries from Qubit are published under the qubit-ltd organization on GitHub.

---

Repository: https://github.com/qubit-ltd/rs-atomic