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