qubit_atomic/lib.rs
1// =============================================================================
2// Copyright (c) 2025 - 2026 Haixing Hu.
3//
4// SPDX-License-Identifier: Apache-2.0
5//
6// Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! # qubit-atomic
9//!
10//! User-friendly atomic operations wrapper providing JDK-like atomic API.
11//!
12//! This crate provides an easy-to-use generic atomic wrapper with reasonable
13//! default memory orderings, similar to Java's
14//! `java.util.concurrent.atomic` package.
15//!
16//! ## Design Goals
17//!
18//! - **Ease of Use**: Hides memory ordering complexity with reasonable defaults
19//! - **Completeness**: Provides high-level operations similar to JDK atomic
20//! - **Safety**: Guarantees memory safety and thread safety
21//! - **Performance**: Thin primitive forwarding, with inherent costs retained
22//! for CAS loops, checked counters, and reference operations
23//! - **Flexibility**: Exposes ordered integer RMW helpers and `inner()` for
24//! advanced users
25//!
26//! ## Features
27//!
28//! - Primitive atomic values: `Atomic<bool>`, `Atomic<i32>`, `Atomic<u64>`,
29//! `Atomic<usize>`, `Atomic<f32>`, and other supported primitive types
30//! - Concrete primitive wrappers under `atomic::primitive` for `const`
31//! initialization use cases
32//! - Counter atomic types: `AtomicCount`, `AtomicSignedCount`
33//! - Reference atomic type: `AtomicRef<T>`
34//! - Shared-owner wrappers: `ArcAtomic<T>`, `ArcAtomicRef<T>`,
35//! `ArcAtomicCount`, and `ArcAtomicSignedCount`
36//!
37//! ## Example
38//!
39//! ```rust
40//! use qubit_atomic::Atomic;
41//! use std::sync::Arc;
42//! use std::thread;
43//!
44//! // Basic usage
45//! let counter = Atomic::new(0);
46//! counter.fetch_inc();
47//! assert_eq!(counter.load(), 1);
48//!
49//! // Concurrent usage
50//! let counter = Arc::new(Atomic::new(0));
51//! let mut handles = vec![];
52//!
53//! for _ in 0..10 {
54//! let counter = counter.clone();
55//! let handle = thread::spawn(move || {
56//! for _ in 0..100 {
57//! counter.fetch_inc();
58//! }
59//! });
60//! handles.push(handle);
61//! }
62//!
63//! for handle in handles {
64//! handle.join().unwrap();
65//! }
66//!
67//! assert_eq!(counter.load(), 1000);
68//! ```
69
70#![deny(missing_docs)]
71#![deny(unsafe_op_in_unsafe_fn)]
72
73/// Atomic value types and reference/counting helpers.
74pub mod atomic;
75
76// Re-export the public atomic API.
77pub use atomic::{
78 ArcAtomic,
79 ArcAtomicCount,
80 ArcAtomicRef,
81 ArcAtomicSignedCount,
82 Atomic,
83 AtomicCount,
84 AtomicRef,
85 AtomicSignedCount,
86};