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 underlying types via `inner()` for advanced users
25//!
26//! ## Features
27//!
28//! - Primitive atomic values: `Atomic<bool>`, `Atomic<i32>`,
29//! `Atomic<u64>`, `Atomic<usize>`, `Atomic<f32>`, and other supported
30//! primitive types
31//! - Concrete primitive wrappers under `atomic::primitive` for `const`
32//! initialization use cases
33//! - Counter atomic types: `AtomicCount`, `AtomicSignedCount`
34//! - Reference atomic type: `AtomicRef<T>`
35//! - Shared-owner wrappers: `ArcAtomic<T>`, `ArcAtomicRef<T>`,
36//! `ArcAtomicCount`, and `ArcAtomicSignedCount`
37//!
38//! ## Example
39//!
40//! ```rust
41//! use qubit_atomic::Atomic;
42//! use std::sync::Arc;
43//! use std::thread;
44//!
45//! // Basic usage
46//! let counter = Atomic::new(0);
47//! counter.fetch_inc();
48//! assert_eq!(counter.load(), 1);
49//!
50//! // Concurrent usage
51//! let counter = Arc::new(Atomic::new(0));
52//! let mut handles = vec![];
53//!
54//! for _ in 0..10 {
55//! let counter = counter.clone();
56//! let handle = thread::spawn(move || {
57//! for _ in 0..100 {
58//! counter.fetch_inc();
59//! }
60//! });
61//! handles.push(handle);
62//! }
63//!
64//! for handle in handles {
65//! handle.join().unwrap();
66//! }
67//!
68//! assert_eq!(counter.load(), 1000);
69//! ```
70//!
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};