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