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//!
33//! ## Example
34//!
35//! ```rust
36//! use qubit_atomic::Atomic;
37//! use std::sync::Arc;
38//! use std::thread;
39//!
40//! // Basic usage
41//! let counter = Atomic::new(0);
42//! counter.fetch_inc();
43//! assert_eq!(counter.load(), 1);
44//!
45//! // Concurrent usage
46//! let counter = Arc::new(Atomic::new(0));
47//! let mut handles = vec![];
48//!
49//! for _ in 0..10 {
50//! let counter = counter.clone();
51//! let handle = thread::spawn(move || {
52//! for _ in 0..100 {
53//! counter.fetch_inc();
54//! }
55//! });
56//! handles.push(handle);
57//! }
58//!
59//! for handle in handles {
60//! handle.join().unwrap();
61//! }
62//!
63//! assert_eq!(counter.load(), 1000);
64//! ```
65//!
66//! ## Author
67//!
68//! Haixing Hu
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 Atomic,
79 AtomicCount,
80 AtomicRef,
81 AtomicSignedCount,
82};