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