1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
/*******************************************************************************
*
* Copyright (c) 2025 - 2026.
* Haixing Hu, Qubit Co. Ltd.
*
* All rights reserved.
*
******************************************************************************/
//! # Internal Atomic Operations Trait
//!
//! Defines the internal trait used by [`crate::Atomic<T>`] to delegate common
//! operations to concrete backend implementations.
//!
//! # Author
//!
//! Haixing Hu
/// Internal common trait for all backend atomic types.
///
/// Provides basic atomic operations including load, store, swap,
/// compare-and-set, and functional updates.
///
/// # Author
///
/// Haixing Hu
pub trait AtomicOps {
/// The value type stored in the atomic.
type Value;
/// Loads the current value.
///
/// Uses `Acquire` ordering by default.
///
/// # Returns
///
/// The current value.
fn load(&self) -> Self::Value;
/// Stores a new value.
///
/// Uses `Release` ordering by default.
///
/// # Parameters
///
/// * `value` - The new value to store.
fn store(&self, value: Self::Value);
/// Swaps the current value with a new value, returning the old
/// value.
///
/// Uses `AcqRel` ordering by default.
///
/// # Parameters
///
/// * `value` - The new value to swap in.
///
/// # Returns
///
/// The old value.
fn swap(&self, value: Self::Value) -> Self::Value;
/// Compares and sets the value atomically.
///
/// If the current value equals `current`, sets it to `new` and
/// returns `Ok(())`. Otherwise, returns `Err(actual)` where
/// `actual` is the current value.
///
/// Uses `AcqRel` ordering on success and `Acquire` ordering on
/// failure.
///
/// # Parameters
///
/// * `current` - The expected current value.
/// * `new` - The new value to set if current matches.
///
/// # Returns
///
/// `Ok(())` when the value was replaced.
///
/// # Errors
///
/// Returns `Err(actual)` with the observed value when the comparison
/// fails. In that case, `new` is not stored.
fn compare_set(&self, current: Self::Value, new: Self::Value) -> Result<(), Self::Value>;
/// Weak version of compare-and-set.
///
/// May spuriously fail even when the comparison succeeds. Should
/// be used in a loop.
///
/// Uses `AcqRel` ordering on success and `Acquire` ordering on
/// failure.
///
/// # Parameters
///
/// * `current` - The expected current value.
/// * `new` - The new value to set if current matches.
///
/// # Returns
///
/// `Ok(())` when the value was replaced.
///
/// # Errors
///
/// Returns `Err(actual)` with the observed value when the comparison
/// fails, including possible spurious failures. In that case, `new` is not
/// stored.
fn compare_set_weak(&self, current: Self::Value, new: Self::Value) -> Result<(), Self::Value>;
/// Compares and exchanges the value atomically, returning the
/// previous value.
///
/// If the current value equals `current`, sets it to `new` and
/// returns the old value. Otherwise, returns the actual current
/// value.
///
/// This is similar to `compare_set` but always returns the actual
/// value instead of a Result, which can be more convenient in CAS
/// loops.
///
/// Uses `AcqRel` ordering on success and `Acquire` ordering on
/// failure.
///
/// # Parameters
///
/// * `current` - The expected current value.
/// * `new` - The new value to set if current matches.
///
/// # Returns
///
/// The value before the operation. If it equals `current`, the
/// operation succeeded for non-floating-point backends. Floating-point
/// backends compare raw bit patterns, so callers must compare raw bits or
/// use `compare_set` when they need an explicit success indicator.
fn compare_exchange(&self, current: Self::Value, new: Self::Value) -> Self::Value;
/// Weak version of compare-and-exchange.
///
/// May spuriously fail even when the comparison succeeds. Should
/// be used in a loop.
///
/// Uses `AcqRel` ordering on success and `Acquire` ordering on
/// failure.
///
/// # Parameters
///
/// * `current` - The expected current value.
/// * `new` - The new value to set if current matches.
///
/// # Returns
///
/// The value observed before the operation completed. Because this
/// operation may fail spuriously, a returned value equal to `current` does
/// not by itself prove that `new` was stored; use
/// [`compare_set_weak`](Self::compare_set_weak) when the caller needs an
/// explicit success indicator.
fn compare_exchange_weak(&self, current: Self::Value, new: Self::Value) -> Self::Value;
/// Updates the value using a function, returning the old value.
///
/// Internally uses a CAS loop until the update succeeds.
///
/// # Parameters
///
/// * `f` - A function that takes the current value and returns
/// the new value.
///
/// # Returns
///
/// The old value before the update.
///
/// The closure may be called more than once when concurrent updates cause
/// CAS retries.
fn fetch_update<F>(&self, f: F) -> Self::Value
where
F: Fn(Self::Value) -> Self::Value;
/// Conditionally updates the value using a function.
///
/// Internally uses a CAS loop until the update succeeds or the closure
/// rejects the current value by returning `None`.
///
/// # Parameters
///
/// * `f` - A function that takes the current value and returns either the
/// new value, or `None` to leave the atomic unchanged.
///
/// # Returns
///
/// `Some(old_value)` when the update succeeds, or `None` when `f` rejects
/// the observed current value. The closure may be called more than once
/// when concurrent updates cause CAS retries.
fn try_update<F>(&self, f: F) -> Option<Self::Value>
where
F: Fn(Self::Value) -> Option<Self::Value>;
}