core/sync/atomic.rs
1//! Atomic types
2//!
3//! Atomic types provide primitive shared-memory communication between
4//! threads, and are the building blocks of other concurrent
5//! types.
6//!
7//! This module defines atomic versions of a select number of primitive
8//! types, including [`AtomicBool`], [`AtomicIsize`], [`AtomicUsize`],
9//! [`AtomicI8`], [`AtomicU16`], etc.
10//! Atomic types present operations that, when used correctly, synchronize
11//! updates between threads.
12//!
13//! Atomic variables are safe to share between threads (they implement [`Sync`])
14//! but they do not themselves provide the mechanism for sharing and follow the
15//! [threading model](../../../std/thread/index.html#the-threading-model) of Rust.
16//! The most common way to share an atomic variable is to put it into an [`Arc`][arc] (an
17//! atomically-reference-counted shared pointer).
18//!
19//! [arc]: ../../../std/sync/struct.Arc.html
20//!
21//! Atomic types may be stored in static variables, initialized using
22//! the constant initializers like [`AtomicBool::new`]. Atomic statics
23//! are often used for lazy global initialization.
24//!
25//! ## Memory model for atomic accesses
26//!
27//! Rust atomics currently follow the same rules as [C++20 atomics][cpp], specifically the rules
28//! from the [`intro.races`][cpp-intro.races] section, without the "consume" memory ordering. Since
29//! C++ uses an object-based memory model whereas Rust is access-based, a bit of translation work
30//! has to be done to apply the C++ rules to Rust: whenever C++ talks about "the value of an
31//! object", we understand that to mean the resulting bytes obtained when doing a read. When the C++
32//! standard talks about "the value of an atomic object", this refers to the result of doing an
33//! atomic load (via the operations provided in this module). A "modification of an atomic object"
34//! refers to an atomic store.
35//!
36//! The end result is *almost* equivalent to saying that creating a *shared reference* to one of the
37//! Rust atomic types corresponds to creating an `atomic_ref` in C++, with the `atomic_ref` being
38//! destroyed when the lifetime of the shared reference ends. The main difference is that Rust
39//! permits concurrent atomic and non-atomic reads to the same memory as those cause no issue in the
40//! C++ memory model, they are just forbidden in C++ because memory is partitioned into "atomic
41//! objects" and "non-atomic objects" (with `atomic_ref` temporarily converting a non-atomic object
42//! into an atomic object).
43//!
44//! The most important aspect of this model is that *data races* are undefined behavior. A data race
45//! is defined as conflicting non-synchronized accesses where at least one of the accesses is
46//! non-atomic. Here, accesses are *conflicting* if they affect overlapping regions of memory and at
47//! least one of them is a write. (A `compare_exchange` or `compare_exchange_weak` that does not
48//! succeed is not considered a write.) They are *non-synchronized* if neither of them
49//! *happens-before* the other, according to the happens-before order of the memory model.
50//!
51//! The other possible cause of undefined behavior in the memory model are mixed-size accesses: Rust
52//! inherits the C++ limitation that non-synchronized conflicting atomic accesses may not partially
53//! overlap. In other words, every pair of non-synchronized atomic accesses must be either disjoint,
54//! access the exact same memory (including using the same access size), or both be reads.
55//!
56//! Each atomic access takes an [`Ordering`] which defines how the operation interacts with the
57//! happens-before order. These orderings behave the same as the corresponding [C++20 atomic
58//! orderings][cpp_memory_order]. For more information, see the [nomicon].
59//!
60//! [cpp]: https://en.cppreference.com/w/cpp/atomic
61//! [cpp-intro.races]: https://timsong-cpp.github.io/cppwp/n4868/intro.multithread#intro.races
62//! [cpp_memory_order]: https://en.cppreference.com/w/cpp/atomic/memory_order
63//! [nomicon]: ../../../nomicon/atomics.html
64//!
65//! ```rust,no_run undefined_behavior
66//! use std::sync::atomic::{AtomicU16, AtomicU8, Ordering};
67//! use std::mem::transmute;
68//! use std::thread;
69//!
70//! let atomic = AtomicU16::new(0);
71//!
72//! thread::scope(|s| {
73//! // This is UB: conflicting non-synchronized accesses, at least one of which is non-atomic.
74//! s.spawn(|| atomic.store(1, Ordering::Relaxed)); // atomic store
75//! s.spawn(|| unsafe { atomic.as_ptr().write(2) }); // non-atomic write
76//! });
77//!
78//! thread::scope(|s| {
79//! // This is fine: the accesses do not conflict (as none of them performs any modification).
80//! // In C++ this would be disallowed since creating an `atomic_ref` precludes
81//! // further non-atomic accesses, but Rust does not have that limitation.
82//! s.spawn(|| atomic.load(Ordering::Relaxed)); // atomic load
83//! s.spawn(|| unsafe { atomic.as_ptr().read() }); // non-atomic read
84//! });
85//!
86//! thread::scope(|s| {
87//! // This is fine: `join` synchronizes the code in a way such that the atomic
88//! // store happens-before the non-atomic write.
89//! let handle = s.spawn(|| atomic.store(1, Ordering::Relaxed)); // atomic store
90//! handle.join().expect("thread won't panic"); // synchronize
91//! s.spawn(|| unsafe { atomic.as_ptr().write(2) }); // non-atomic write
92//! });
93//!
94//! thread::scope(|s| {
95//! // This is UB: non-synchronized conflicting differently-sized atomic accesses.
96//! s.spawn(|| atomic.store(1, Ordering::Relaxed));
97//! s.spawn(|| unsafe {
98//! let differently_sized = transmute::<&AtomicU16, &AtomicU8>(&atomic);
99//! differently_sized.store(2, Ordering::Relaxed);
100//! });
101//! });
102//!
103//! thread::scope(|s| {
104//! // This is fine: `join` synchronizes the code in a way such that
105//! // the 1-byte store happens-before the 2-byte store.
106//! let handle = s.spawn(|| atomic.store(1, Ordering::Relaxed));
107//! handle.join().expect("thread won't panic");
108//! s.spawn(|| unsafe {
109//! let differently_sized = transmute::<&AtomicU16, &AtomicU8>(&atomic);
110//! differently_sized.store(2, Ordering::Relaxed);
111//! });
112//! });
113//! ```
114//!
115//! # Portability
116//!
117//! All atomic types in this module are guaranteed to be [lock-free] if they're
118//! available. This means they don't internally acquire a global mutex. Atomic
119//! types and operations are not guaranteed to be wait-free. This means that
120//! operations like `fetch_or` may be implemented with a compare-and-swap loop.
121//!
122//! Atomic operations may be implemented at the instruction layer with
123//! larger-size atomics. For example some platforms use 4-byte atomic
124//! instructions to implement `AtomicI8`. Note that this emulation should not
125//! have an impact on correctness of code, it's just something to be aware of.
126//!
127//! The atomic types in this module might not be available on all platforms. The
128//! atomic types here are all widely available, however, and can generally be
129//! relied upon existing. Some notable exceptions are:
130//!
131//! * PowerPC and MIPS platforms with 32-bit pointers do not have `AtomicU64` or
132//! `AtomicI64` types.
133//! * ARM platforms like `armv5te` that aren't for Linux only provide `load`
134//! and `store` operations, and do not support Compare and Swap (CAS)
135//! operations, such as `swap`, `fetch_add`, etc. Additionally on Linux,
136//! these CAS operations are implemented via [operating system support], which
137//! may come with a performance penalty.
138//! * ARM targets with `thumbv6m` only provide `load` and `store` operations,
139//! and do not support Compare and Swap (CAS) operations, such as `swap`,
140//! `fetch_add`, etc.
141//!
142//! [operating system support]: https://www.kernel.org/doc/Documentation/arm/kernel_user_helpers.txt
143//!
144//! Note that future platforms may be added that also do not have support for
145//! some atomic operations. Maximally portable code will want to be careful
146//! about which atomic types are used. `AtomicUsize` and `AtomicIsize` are
147//! generally the most portable, but even then they're not available everywhere.
148//! For reference, the `std` library requires `AtomicBool`s and pointer-sized atomics, although
149//! `core` does not.
150//!
151//! The `#[cfg(target_has_atomic)]` attribute can be used to conditionally
152//! compile based on the target's supported bit widths. It is a key-value
153//! option set for each supported size, with values "8", "16", "32", "64",
154//! "128", and "ptr" for pointer-sized atomics.
155//!
156//! [lock-free]: https://en.wikipedia.org/wiki/Non-blocking_algorithm
157//!
158//! # Atomic accesses to read-only memory
159//!
160//! In general, *all* atomic accesses on read-only memory are undefined behavior. For instance, attempting
161//! to do a `compare_exchange` that will definitely fail (making it conceptually a read-only
162//! operation) can still cause a segmentation fault if the underlying memory page is mapped read-only. Since
163//! atomic `load`s might be implemented using compare-exchange operations, even a `load` can fault
164//! on read-only memory.
165//!
166//! For the purpose of this section, "read-only memory" is defined as memory that is read-only in
167//! the underlying target, i.e., the pages are mapped with a read-only flag and any attempt to write
168//! will cause a page fault. In particular, an `&u128` reference that points to memory that is
169//! read-write mapped is *not* considered to point to "read-only memory". In Rust, almost all memory
170//! is read-write; the only exceptions are memory created by `const` items or `static` items without
171//! interior mutability, and memory that was specifically marked as read-only by the operating
172//! system via platform-specific APIs.
173//!
174//! As an exception from the general rule stated above, "sufficiently small" atomic loads with
175//! `Ordering::Relaxed` are implemented in a way that works on read-only memory, and are hence not
176//! undefined behavior. The exact size limit for what makes a load "sufficiently small" varies
177//! depending on the target:
178//!
179//! | `target_arch` | Size limit |
180//! |---------------|---------|
181//! | `x86`, `arm`, `mips`, `mips32r6`, `powerpc`, `riscv32`, `sparc`, `hexagon` | 4 bytes |
182//! | `x86_64`, `aarch64`, `loongarch64`, `mips64`, `mips64r6`, `powerpc64`, `riscv64`, `sparc64`, `s390x` | 8 bytes |
183//!
184//! Atomics loads that are larger than this limit as well as atomic loads with ordering other
185//! than `Relaxed`, as well as *all* atomic loads on targets not listed in the table, might still be
186//! read-only under certain conditions, but that is not a stable guarantee and should not be relied
187//! upon.
188//!
189//! If you need to do an acquire load on read-only memory, you can do a relaxed load followed by an
190//! acquire fence instead.
191//!
192//! # Examples
193//!
194//! A simple spinlock:
195//!
196//! ```
197//! use std::sync::Arc;
198//! use std::sync::atomic::{AtomicUsize, Ordering};
199//! use std::{hint, thread};
200//!
201//! fn main() {
202//! let spinlock = Arc::new(AtomicUsize::new(1));
203//!
204//! let spinlock_clone = Arc::clone(&spinlock);
205//!
206//! let thread = thread::spawn(move || {
207//! spinlock_clone.store(0, Ordering::Release);
208//! });
209//!
210//! // Wait for the other thread to release the lock
211//! while spinlock.load(Ordering::Acquire) != 0 {
212//! hint::spin_loop();
213//! }
214//!
215//! if let Err(panic) = thread.join() {
216//! println!("Thread had an error: {panic:?}");
217//! }
218//! }
219//! ```
220//!
221//! Keep a global count of live threads:
222//!
223//! ```
224//! use std::sync::atomic::{AtomicUsize, Ordering};
225//!
226//! static GLOBAL_THREAD_COUNT: AtomicUsize = AtomicUsize::new(0);
227//!
228//! // Note that Relaxed ordering doesn't synchronize anything
229//! // except the global thread counter itself.
230//! let old_thread_count = GLOBAL_THREAD_COUNT.fetch_add(1, Ordering::Relaxed);
231//! // Note that this number may not be true at the moment of printing
232//! // because some other thread may have changed static value already.
233//! println!("live threads: {}", old_thread_count + 1);
234//! ```
235
236#![stable(feature = "rust1", since = "1.0.0")]
237#![cfg_attr(not(target_has_atomic_load_store = "8"), allow(dead_code))]
238#![cfg_attr(not(target_has_atomic_load_store = "8"), allow(unused_imports))]
239#![rustc_diagnostic_item = "atomic_mod"]
240// Clippy complains about the pattern of "safe function calling unsafe function taking pointers".
241// This happens with AtomicPtr intrinsics but is fine, as the pointers clippy is concerned about
242// are just normal values that get loaded/stored, but not dereferenced.
243#![allow(clippy::not_unsafe_ptr_arg_deref)]
244
245use self::Ordering::*;
246use crate::cell::UnsafeCell;
247use crate::hint::spin_loop;
248use crate::{fmt, intrinsics};
249
250// Some architectures don't have byte-sized atomics, which results in LLVM
251// emulating them using a LL/SC loop. However for AtomicBool we can take
252// advantage of the fact that it only ever contains 0 or 1 and use atomic OR/AND
253// instead, which LLVM can emulate using a larger atomic OR/AND operation.
254//
255// This list should only contain architectures which have word-sized atomic-or/
256// atomic-and instructions but don't natively support byte-sized atomics.
257#[cfg(target_has_atomic = "8")]
258const EMULATE_ATOMIC_BOOL: bool =
259 cfg!(any(target_arch = "riscv32", target_arch = "riscv64", target_arch = "loongarch64"));
260
261/// A boolean type which can be safely shared between threads.
262///
263/// This type has the same size, alignment, and bit validity as a [`bool`].
264///
265/// **Note**: This type is only available on platforms that support atomic
266/// loads and stores of `u8`.
267#[cfg(target_has_atomic_load_store = "8")]
268#[stable(feature = "rust1", since = "1.0.0")]
269#[rustc_diagnostic_item = "AtomicBool"]
270#[repr(C, align(1))]
271pub struct AtomicBool {
272 v: UnsafeCell<u8>,
273}
274
275#[cfg(target_has_atomic_load_store = "8")]
276#[stable(feature = "rust1", since = "1.0.0")]
277impl Default for AtomicBool {
278 /// Creates an `AtomicBool` initialized to `false`.
279 #[inline]
280 fn default() -> Self {
281 Self::new(false)
282 }
283}
284
285// Send is implicitly implemented for AtomicBool.
286#[cfg(target_has_atomic_load_store = "8")]
287#[stable(feature = "rust1", since = "1.0.0")]
288unsafe impl Sync for AtomicBool {}
289
290/// A raw pointer type which can be safely shared between threads.
291///
292/// This type has the same size and bit validity as a `*mut T`.
293///
294/// **Note**: This type is only available on platforms that support atomic
295/// loads and stores of pointers. Its size depends on the target pointer's size.
296#[cfg(target_has_atomic_load_store = "ptr")]
297#[stable(feature = "rust1", since = "1.0.0")]
298#[cfg_attr(not(test), rustc_diagnostic_item = "AtomicPtr")]
299#[cfg_attr(target_pointer_width = "16", repr(C, align(2)))]
300#[cfg_attr(target_pointer_width = "32", repr(C, align(4)))]
301#[cfg_attr(target_pointer_width = "64", repr(C, align(8)))]
302pub struct AtomicPtr<T> {
303 p: UnsafeCell<*mut T>,
304}
305
306#[cfg(target_has_atomic_load_store = "ptr")]
307#[stable(feature = "rust1", since = "1.0.0")]
308impl<T> Default for AtomicPtr<T> {
309 /// Creates a null `AtomicPtr<T>`.
310 fn default() -> AtomicPtr<T> {
311 AtomicPtr::new(crate::ptr::null_mut())
312 }
313}
314
315#[cfg(target_has_atomic_load_store = "ptr")]
316#[stable(feature = "rust1", since = "1.0.0")]
317unsafe impl<T> Send for AtomicPtr<T> {}
318#[cfg(target_has_atomic_load_store = "ptr")]
319#[stable(feature = "rust1", since = "1.0.0")]
320unsafe impl<T> Sync for AtomicPtr<T> {}
321
322/// Atomic memory orderings
323///
324/// Memory orderings specify the way atomic operations synchronize memory.
325/// In its weakest [`Ordering::Relaxed`], only the memory directly touched by the
326/// operation is synchronized. On the other hand, a store-load pair of [`Ordering::SeqCst`]
327/// operations synchronize other memory while additionally preserving a total order of such
328/// operations across all threads.
329///
330/// Rust's memory orderings are [the same as those of
331/// C++20](https://en.cppreference.com/w/cpp/atomic/memory_order).
332///
333/// For more information see the [nomicon].
334///
335/// [nomicon]: ../../../nomicon/atomics.html
336#[stable(feature = "rust1", since = "1.0.0")]
337#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
338#[non_exhaustive]
339#[rustc_diagnostic_item = "Ordering"]
340pub enum Ordering {
341 /// No ordering constraints, only atomic operations.
342 ///
343 /// Corresponds to [`memory_order_relaxed`] in C++20.
344 ///
345 /// [`memory_order_relaxed`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Relaxed_ordering
346 #[stable(feature = "rust1", since = "1.0.0")]
347 Relaxed,
348 /// When coupled with a store, all previous operations become ordered
349 /// before any load of this value with [`Acquire`] (or stronger) ordering.
350 /// In particular, all previous writes become visible to all threads
351 /// that perform an [`Acquire`] (or stronger) load of this value.
352 ///
353 /// Notice that using this ordering for an operation that combines loads
354 /// and stores leads to a [`Relaxed`] load operation!
355 ///
356 /// This ordering is only applicable for operations that can perform a store.
357 ///
358 /// Corresponds to [`memory_order_release`] in C++20.
359 ///
360 /// [`memory_order_release`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Release-Acquire_ordering
361 #[stable(feature = "rust1", since = "1.0.0")]
362 Release,
363 /// When coupled with a load, if the loaded value was written by a store operation with
364 /// [`Release`] (or stronger) ordering, then all subsequent operations
365 /// become ordered after that store. In particular, all subsequent loads will see data
366 /// written before the store.
367 ///
368 /// Notice that using this ordering for an operation that combines loads
369 /// and stores leads to a [`Relaxed`] store operation!
370 ///
371 /// This ordering is only applicable for operations that can perform a load.
372 ///
373 /// Corresponds to [`memory_order_acquire`] in C++20.
374 ///
375 /// [`memory_order_acquire`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Release-Acquire_ordering
376 #[stable(feature = "rust1", since = "1.0.0")]
377 Acquire,
378 /// Has the effects of both [`Acquire`] and [`Release`] together:
379 /// For loads it uses [`Acquire`] ordering. For stores it uses the [`Release`] ordering.
380 ///
381 /// Notice that in the case of `compare_and_swap`, it is possible that the operation ends up
382 /// not performing any store and hence it has just [`Acquire`] ordering. However,
383 /// `AcqRel` will never perform [`Relaxed`] accesses.
384 ///
385 /// This ordering is only applicable for operations that combine both loads and stores.
386 ///
387 /// Corresponds to [`memory_order_acq_rel`] in C++20.
388 ///
389 /// [`memory_order_acq_rel`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Release-Acquire_ordering
390 #[stable(feature = "rust1", since = "1.0.0")]
391 AcqRel,
392 /// Like [`Acquire`]/[`Release`]/[`AcqRel`] (for load, store, and load-with-store
393 /// operations, respectively) with the additional guarantee that all threads see all
394 /// sequentially consistent operations in the same order.
395 ///
396 /// Corresponds to [`memory_order_seq_cst`] in C++20.
397 ///
398 /// [`memory_order_seq_cst`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Sequentially-consistent_ordering
399 #[stable(feature = "rust1", since = "1.0.0")]
400 SeqCst,
401}
402
403/// An [`AtomicBool`] initialized to `false`.
404#[cfg(target_has_atomic_load_store = "8")]
405#[stable(feature = "rust1", since = "1.0.0")]
406#[deprecated(
407 since = "1.34.0",
408 note = "the `new` function is now preferred",
409 suggestion = "AtomicBool::new(false)"
410)]
411pub const ATOMIC_BOOL_INIT: AtomicBool = AtomicBool::new(false);
412
413#[cfg(target_has_atomic_load_store = "8")]
414impl AtomicBool {
415 /// Creates a new `AtomicBool`.
416 ///
417 /// # Examples
418 ///
419 /// ```
420 /// use std::sync::atomic::AtomicBool;
421 ///
422 /// let atomic_true = AtomicBool::new(true);
423 /// let atomic_false = AtomicBool::new(false);
424 /// ```
425 #[inline]
426 #[stable(feature = "rust1", since = "1.0.0")]
427 #[rustc_const_stable(feature = "const_atomic_new", since = "1.24.0")]
428 #[must_use]
429 pub const fn new(v: bool) -> AtomicBool {
430 AtomicBool { v: UnsafeCell::new(v as u8) }
431 }
432
433 /// Creates a new `AtomicBool` from a pointer.
434 ///
435 /// # Examples
436 ///
437 /// ```
438 /// use std::sync::atomic::{self, AtomicBool};
439 ///
440 /// // Get a pointer to an allocated value
441 /// let ptr: *mut bool = Box::into_raw(Box::new(false));
442 ///
443 /// assert!(ptr.cast::<AtomicBool>().is_aligned());
444 ///
445 /// {
446 /// // Create an atomic view of the allocated value
447 /// let atomic = unsafe { AtomicBool::from_ptr(ptr) };
448 ///
449 /// // Use `atomic` for atomic operations, possibly share it with other threads
450 /// atomic.store(true, atomic::Ordering::Relaxed);
451 /// }
452 ///
453 /// // It's ok to non-atomically access the value behind `ptr`,
454 /// // since the reference to the atomic ended its lifetime in the block above
455 /// assert_eq!(unsafe { *ptr }, true);
456 ///
457 /// // Deallocate the value
458 /// unsafe { drop(Box::from_raw(ptr)) }
459 /// ```
460 ///
461 /// # Safety
462 ///
463 /// * `ptr` must be aligned to `align_of::<AtomicBool>()` (note that this is always true, since
464 /// `align_of::<AtomicBool>() == 1`).
465 /// * `ptr` must be [valid] for both reads and writes for the whole lifetime `'a`.
466 /// * You must adhere to the [Memory model for atomic accesses]. In particular, it is not
467 /// allowed to mix atomic and non-atomic accesses, or atomic accesses of different sizes,
468 /// without synchronization.
469 ///
470 /// [valid]: crate::ptr#safety
471 /// [Memory model for atomic accesses]: self#memory-model-for-atomic-accesses
472 #[stable(feature = "atomic_from_ptr", since = "1.75.0")]
473 #[rustc_const_stable(feature = "const_atomic_from_ptr", since = "1.84.0")]
474 pub const unsafe fn from_ptr<'a>(ptr: *mut bool) -> &'a AtomicBool {
475 // SAFETY: guaranteed by the caller
476 unsafe { &*ptr.cast() }
477 }
478
479 /// Returns a mutable reference to the underlying [`bool`].
480 ///
481 /// This is safe because the mutable reference guarantees that no other threads are
482 /// concurrently accessing the atomic data.
483 ///
484 /// # Examples
485 ///
486 /// ```
487 /// use std::sync::atomic::{AtomicBool, Ordering};
488 ///
489 /// let mut some_bool = AtomicBool::new(true);
490 /// assert_eq!(*some_bool.get_mut(), true);
491 /// *some_bool.get_mut() = false;
492 /// assert_eq!(some_bool.load(Ordering::SeqCst), false);
493 /// ```
494 #[inline]
495 #[stable(feature = "atomic_access", since = "1.15.0")]
496 pub fn get_mut(&mut self) -> &mut bool {
497 // SAFETY: the mutable reference guarantees unique ownership.
498 unsafe { &mut *(self.v.get() as *mut bool) }
499 }
500
501 /// Gets atomic access to a `&mut bool`.
502 ///
503 /// # Examples
504 ///
505 /// ```
506 /// #![feature(atomic_from_mut)]
507 /// use std::sync::atomic::{AtomicBool, Ordering};
508 ///
509 /// let mut some_bool = true;
510 /// let a = AtomicBool::from_mut(&mut some_bool);
511 /// a.store(false, Ordering::Relaxed);
512 /// assert_eq!(some_bool, false);
513 /// ```
514 #[inline]
515 #[cfg(target_has_atomic_equal_alignment = "8")]
516 #[unstable(feature = "atomic_from_mut", issue = "76314")]
517 pub fn from_mut(v: &mut bool) -> &mut Self {
518 // SAFETY: the mutable reference guarantees unique ownership, and
519 // alignment of both `bool` and `Self` is 1.
520 unsafe { &mut *(v as *mut bool as *mut Self) }
521 }
522
523 /// Gets non-atomic access to a `&mut [AtomicBool]` slice.
524 ///
525 /// This is safe because the mutable reference guarantees that no other threads are
526 /// concurrently accessing the atomic data.
527 ///
528 /// # Examples
529 ///
530 /// ```
531 /// #![feature(atomic_from_mut)]
532 /// use std::sync::atomic::{AtomicBool, Ordering};
533 ///
534 /// let mut some_bools = [const { AtomicBool::new(false) }; 10];
535 ///
536 /// let view: &mut [bool] = AtomicBool::get_mut_slice(&mut some_bools);
537 /// assert_eq!(view, [false; 10]);
538 /// view[..5].copy_from_slice(&[true; 5]);
539 ///
540 /// std::thread::scope(|s| {
541 /// for t in &some_bools[..5] {
542 /// s.spawn(move || assert_eq!(t.load(Ordering::Relaxed), true));
543 /// }
544 ///
545 /// for f in &some_bools[5..] {
546 /// s.spawn(move || assert_eq!(f.load(Ordering::Relaxed), false));
547 /// }
548 /// });
549 /// ```
550 #[inline]
551 #[unstable(feature = "atomic_from_mut", issue = "76314")]
552 pub fn get_mut_slice(this: &mut [Self]) -> &mut [bool] {
553 // SAFETY: the mutable reference guarantees unique ownership.
554 unsafe { &mut *(this as *mut [Self] as *mut [bool]) }
555 }
556
557 /// Gets atomic access to a `&mut [bool]` slice.
558 ///
559 /// # Examples
560 ///
561 /// ```
562 /// #![feature(atomic_from_mut)]
563 /// use std::sync::atomic::{AtomicBool, Ordering};
564 ///
565 /// let mut some_bools = [false; 10];
566 /// let a = &*AtomicBool::from_mut_slice(&mut some_bools);
567 /// std::thread::scope(|s| {
568 /// for i in 0..a.len() {
569 /// s.spawn(move || a[i].store(true, Ordering::Relaxed));
570 /// }
571 /// });
572 /// assert_eq!(some_bools, [true; 10]);
573 /// ```
574 #[inline]
575 #[cfg(target_has_atomic_equal_alignment = "8")]
576 #[unstable(feature = "atomic_from_mut", issue = "76314")]
577 pub fn from_mut_slice(v: &mut [bool]) -> &mut [Self] {
578 // SAFETY: the mutable reference guarantees unique ownership, and
579 // alignment of both `bool` and `Self` is 1.
580 unsafe { &mut *(v as *mut [bool] as *mut [Self]) }
581 }
582
583 /// Consumes the atomic and returns the contained value.
584 ///
585 /// This is safe because passing `self` by value guarantees that no other threads are
586 /// concurrently accessing the atomic data.
587 ///
588 /// # Examples
589 ///
590 /// ```
591 /// use std::sync::atomic::AtomicBool;
592 ///
593 /// let some_bool = AtomicBool::new(true);
594 /// assert_eq!(some_bool.into_inner(), true);
595 /// ```
596 #[inline]
597 #[stable(feature = "atomic_access", since = "1.15.0")]
598 #[rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0")]
599 pub const fn into_inner(self) -> bool {
600 self.v.into_inner() != 0
601 }
602
603 /// Loads a value from the bool.
604 ///
605 /// `load` takes an [`Ordering`] argument which describes the memory ordering
606 /// of this operation. Possible values are [`SeqCst`], [`Acquire`] and [`Relaxed`].
607 ///
608 /// # Panics
609 ///
610 /// Panics if `order` is [`Release`] or [`AcqRel`].
611 ///
612 /// # Examples
613 ///
614 /// ```
615 /// use std::sync::atomic::{AtomicBool, Ordering};
616 ///
617 /// let some_bool = AtomicBool::new(true);
618 ///
619 /// assert_eq!(some_bool.load(Ordering::Relaxed), true);
620 /// ```
621 #[inline]
622 #[stable(feature = "rust1", since = "1.0.0")]
623 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
624 pub fn load(&self, order: Ordering) -> bool {
625 // SAFETY: any data races are prevented by atomic intrinsics and the raw
626 // pointer passed in is valid because we got it from a reference.
627 unsafe { atomic_load(self.v.get(), order) != 0 }
628 }
629
630 /// Stores a value into the bool.
631 ///
632 /// `store` takes an [`Ordering`] argument which describes the memory ordering
633 /// of this operation. Possible values are [`SeqCst`], [`Release`] and [`Relaxed`].
634 ///
635 /// # Panics
636 ///
637 /// Panics if `order` is [`Acquire`] or [`AcqRel`].
638 ///
639 /// # Examples
640 ///
641 /// ```
642 /// use std::sync::atomic::{AtomicBool, Ordering};
643 ///
644 /// let some_bool = AtomicBool::new(true);
645 ///
646 /// some_bool.store(false, Ordering::Relaxed);
647 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
648 /// ```
649 #[inline]
650 #[stable(feature = "rust1", since = "1.0.0")]
651 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
652 pub fn store(&self, val: bool, order: Ordering) {
653 // SAFETY: any data races are prevented by atomic intrinsics and the raw
654 // pointer passed in is valid because we got it from a reference.
655 unsafe {
656 atomic_store(self.v.get(), val as u8, order);
657 }
658 }
659
660 /// Stores a value into the bool, returning the previous value.
661 ///
662 /// `swap` takes an [`Ordering`] argument which describes the memory ordering
663 /// of this operation. All ordering modes are possible. Note that using
664 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
665 /// using [`Release`] makes the load part [`Relaxed`].
666 ///
667 /// **Note:** This method is only available on platforms that support atomic
668 /// operations on `u8`.
669 ///
670 /// # Examples
671 ///
672 /// ```
673 /// use std::sync::atomic::{AtomicBool, Ordering};
674 ///
675 /// let some_bool = AtomicBool::new(true);
676 ///
677 /// assert_eq!(some_bool.swap(false, Ordering::Relaxed), true);
678 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
679 /// ```
680 #[inline]
681 #[stable(feature = "rust1", since = "1.0.0")]
682 #[cfg(target_has_atomic = "8")]
683 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
684 pub fn swap(&self, val: bool, order: Ordering) -> bool {
685 if EMULATE_ATOMIC_BOOL {
686 if val { self.fetch_or(true, order) } else { self.fetch_and(false, order) }
687 } else {
688 // SAFETY: data races are prevented by atomic intrinsics.
689 unsafe { atomic_swap(self.v.get(), val as u8, order) != 0 }
690 }
691 }
692
693 /// Stores a value into the [`bool`] if the current value is the same as the `current` value.
694 ///
695 /// The return value is always the previous value. If it is equal to `current`, then the value
696 /// was updated.
697 ///
698 /// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory
699 /// ordering of this operation. Notice that even when using [`AcqRel`], the operation
700 /// might fail and hence just perform an `Acquire` load, but not have `Release` semantics.
701 /// Using [`Acquire`] makes the store part of this operation [`Relaxed`] if it
702 /// happens, and using [`Release`] makes the load part [`Relaxed`].
703 ///
704 /// **Note:** This method is only available on platforms that support atomic
705 /// operations on `u8`.
706 ///
707 /// # Migrating to `compare_exchange` and `compare_exchange_weak`
708 ///
709 /// `compare_and_swap` is equivalent to `compare_exchange` with the following mapping for
710 /// memory orderings:
711 ///
712 /// Original | Success | Failure
713 /// -------- | ------- | -------
714 /// Relaxed | Relaxed | Relaxed
715 /// Acquire | Acquire | Acquire
716 /// Release | Release | Relaxed
717 /// AcqRel | AcqRel | Acquire
718 /// SeqCst | SeqCst | SeqCst
719 ///
720 /// `compare_and_swap` and `compare_exchange` also differ in their return type. You can use
721 /// `compare_exchange(...).unwrap_or_else(|x| x)` to recover the behavior of `compare_and_swap`,
722 /// but in most cases it is more idiomatic to check whether the return value is `Ok` or `Err`
723 /// rather than to infer success vs failure based on the value that was read.
724 ///
725 /// During migration, consider whether it makes sense to use `compare_exchange_weak` instead.
726 /// `compare_exchange_weak` is allowed to fail spuriously even when the comparison succeeds,
727 /// which allows the compiler to generate better assembly code when the compare and swap
728 /// is used in a loop.
729 ///
730 /// # Examples
731 ///
732 /// ```
733 /// use std::sync::atomic::{AtomicBool, Ordering};
734 ///
735 /// let some_bool = AtomicBool::new(true);
736 ///
737 /// assert_eq!(some_bool.compare_and_swap(true, false, Ordering::Relaxed), true);
738 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
739 ///
740 /// assert_eq!(some_bool.compare_and_swap(true, true, Ordering::Relaxed), false);
741 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
742 /// ```
743 #[inline]
744 #[stable(feature = "rust1", since = "1.0.0")]
745 #[deprecated(
746 since = "1.50.0",
747 note = "Use `compare_exchange` or `compare_exchange_weak` instead"
748 )]
749 #[cfg(target_has_atomic = "8")]
750 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
751 pub fn compare_and_swap(&self, current: bool, new: bool, order: Ordering) -> bool {
752 match self.compare_exchange(current, new, order, strongest_failure_ordering(order)) {
753 Ok(x) => x,
754 Err(x) => x,
755 }
756 }
757
758 /// Stores a value into the [`bool`] if the current value is the same as the `current` value.
759 ///
760 /// The return value is a result indicating whether the new value was written and containing
761 /// the previous value. On success this value is guaranteed to be equal to `current`.
762 ///
763 /// `compare_exchange` takes two [`Ordering`] arguments to describe the memory
764 /// ordering of this operation. `success` describes the required ordering for the
765 /// read-modify-write operation that takes place if the comparison with `current` succeeds.
766 /// `failure` describes the required ordering for the load operation that takes place when
767 /// the comparison fails. Using [`Acquire`] as success ordering makes the store part
768 /// of this operation [`Relaxed`], and using [`Release`] makes the successful load
769 /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`].
770 ///
771 /// **Note:** This method is only available on platforms that support atomic
772 /// operations on `u8`.
773 ///
774 /// # Examples
775 ///
776 /// ```
777 /// use std::sync::atomic::{AtomicBool, Ordering};
778 ///
779 /// let some_bool = AtomicBool::new(true);
780 ///
781 /// assert_eq!(some_bool.compare_exchange(true,
782 /// false,
783 /// Ordering::Acquire,
784 /// Ordering::Relaxed),
785 /// Ok(true));
786 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
787 ///
788 /// assert_eq!(some_bool.compare_exchange(true, true,
789 /// Ordering::SeqCst,
790 /// Ordering::Acquire),
791 /// Err(false));
792 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
793 /// ```
794 #[inline]
795 #[stable(feature = "extended_compare_and_swap", since = "1.10.0")]
796 #[doc(alias = "compare_and_swap")]
797 #[cfg(target_has_atomic = "8")]
798 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
799 pub fn compare_exchange(
800 &self,
801 current: bool,
802 new: bool,
803 success: Ordering,
804 failure: Ordering,
805 ) -> Result<bool, bool> {
806 if EMULATE_ATOMIC_BOOL {
807 // Pick the strongest ordering from success and failure.
808 let order = match (success, failure) {
809 (SeqCst, _) => SeqCst,
810 (_, SeqCst) => SeqCst,
811 (AcqRel, _) => AcqRel,
812 (_, AcqRel) => {
813 panic!("there is no such thing as an acquire-release failure ordering")
814 }
815 (Release, Acquire) => AcqRel,
816 (Acquire, _) => Acquire,
817 (_, Acquire) => Acquire,
818 (Release, Relaxed) => Release,
819 (_, Release) => panic!("there is no such thing as a release failure ordering"),
820 (Relaxed, Relaxed) => Relaxed,
821 };
822 let old = if current == new {
823 // This is a no-op, but we still need to perform the operation
824 // for memory ordering reasons.
825 self.fetch_or(false, order)
826 } else {
827 // This sets the value to the new one and returns the old one.
828 self.swap(new, order)
829 };
830 if old == current { Ok(old) } else { Err(old) }
831 } else {
832 // SAFETY: data races are prevented by atomic intrinsics.
833 match unsafe {
834 atomic_compare_exchange(self.v.get(), current as u8, new as u8, success, failure)
835 } {
836 Ok(x) => Ok(x != 0),
837 Err(x) => Err(x != 0),
838 }
839 }
840 }
841
842 /// Stores a value into the [`bool`] if the current value is the same as the `current` value.
843 ///
844 /// Unlike [`AtomicBool::compare_exchange`], this function is allowed to spuriously fail even when the
845 /// comparison succeeds, which can result in more efficient code on some platforms. The
846 /// return value is a result indicating whether the new value was written and containing the
847 /// previous value.
848 ///
849 /// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory
850 /// ordering of this operation. `success` describes the required ordering for the
851 /// read-modify-write operation that takes place if the comparison with `current` succeeds.
852 /// `failure` describes the required ordering for the load operation that takes place when
853 /// the comparison fails. Using [`Acquire`] as success ordering makes the store part
854 /// of this operation [`Relaxed`], and using [`Release`] makes the successful load
855 /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`].
856 ///
857 /// **Note:** This method is only available on platforms that support atomic
858 /// operations on `u8`.
859 ///
860 /// # Examples
861 ///
862 /// ```
863 /// use std::sync::atomic::{AtomicBool, Ordering};
864 ///
865 /// let val = AtomicBool::new(false);
866 ///
867 /// let new = true;
868 /// let mut old = val.load(Ordering::Relaxed);
869 /// loop {
870 /// match val.compare_exchange_weak(old, new, Ordering::SeqCst, Ordering::Relaxed) {
871 /// Ok(_) => break,
872 /// Err(x) => old = x,
873 /// }
874 /// }
875 /// ```
876 #[inline]
877 #[stable(feature = "extended_compare_and_swap", since = "1.10.0")]
878 #[doc(alias = "compare_and_swap")]
879 #[cfg(target_has_atomic = "8")]
880 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
881 pub fn compare_exchange_weak(
882 &self,
883 current: bool,
884 new: bool,
885 success: Ordering,
886 failure: Ordering,
887 ) -> Result<bool, bool> {
888 if EMULATE_ATOMIC_BOOL {
889 return self.compare_exchange(current, new, success, failure);
890 }
891
892 // SAFETY: data races are prevented by atomic intrinsics.
893 match unsafe {
894 atomic_compare_exchange_weak(self.v.get(), current as u8, new as u8, success, failure)
895 } {
896 Ok(x) => Ok(x != 0),
897 Err(x) => Err(x != 0),
898 }
899 }
900
901 /// Logical "and" with a boolean value.
902 ///
903 /// Performs a logical "and" operation on the current value and the argument `val`, and sets
904 /// the new value to the result.
905 ///
906 /// Returns the previous value.
907 ///
908 /// `fetch_and` takes an [`Ordering`] argument which describes the memory ordering
909 /// of this operation. All ordering modes are possible. Note that using
910 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
911 /// using [`Release`] makes the load part [`Relaxed`].
912 ///
913 /// **Note:** This method is only available on platforms that support atomic
914 /// operations on `u8`.
915 ///
916 /// # Examples
917 ///
918 /// ```
919 /// use std::sync::atomic::{AtomicBool, Ordering};
920 ///
921 /// let foo = AtomicBool::new(true);
922 /// assert_eq!(foo.fetch_and(false, Ordering::SeqCst), true);
923 /// assert_eq!(foo.load(Ordering::SeqCst), false);
924 ///
925 /// let foo = AtomicBool::new(true);
926 /// assert_eq!(foo.fetch_and(true, Ordering::SeqCst), true);
927 /// assert_eq!(foo.load(Ordering::SeqCst), true);
928 ///
929 /// let foo = AtomicBool::new(false);
930 /// assert_eq!(foo.fetch_and(false, Ordering::SeqCst), false);
931 /// assert_eq!(foo.load(Ordering::SeqCst), false);
932 /// ```
933 #[inline]
934 #[stable(feature = "rust1", since = "1.0.0")]
935 #[cfg(target_has_atomic = "8")]
936 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
937 pub fn fetch_and(&self, val: bool, order: Ordering) -> bool {
938 // SAFETY: data races are prevented by atomic intrinsics.
939 unsafe { atomic_and(self.v.get(), val as u8, order) != 0 }
940 }
941
942 /// Logical "nand" with a boolean value.
943 ///
944 /// Performs a logical "nand" operation on the current value and the argument `val`, and sets
945 /// the new value to the result.
946 ///
947 /// Returns the previous value.
948 ///
949 /// `fetch_nand` takes an [`Ordering`] argument which describes the memory ordering
950 /// of this operation. All ordering modes are possible. Note that using
951 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
952 /// using [`Release`] makes the load part [`Relaxed`].
953 ///
954 /// **Note:** This method is only available on platforms that support atomic
955 /// operations on `u8`.
956 ///
957 /// # Examples
958 ///
959 /// ```
960 /// use std::sync::atomic::{AtomicBool, Ordering};
961 ///
962 /// let foo = AtomicBool::new(true);
963 /// assert_eq!(foo.fetch_nand(false, Ordering::SeqCst), true);
964 /// assert_eq!(foo.load(Ordering::SeqCst), true);
965 ///
966 /// let foo = AtomicBool::new(true);
967 /// assert_eq!(foo.fetch_nand(true, Ordering::SeqCst), true);
968 /// assert_eq!(foo.load(Ordering::SeqCst) as usize, 0);
969 /// assert_eq!(foo.load(Ordering::SeqCst), false);
970 ///
971 /// let foo = AtomicBool::new(false);
972 /// assert_eq!(foo.fetch_nand(false, Ordering::SeqCst), false);
973 /// assert_eq!(foo.load(Ordering::SeqCst), true);
974 /// ```
975 #[inline]
976 #[stable(feature = "rust1", since = "1.0.0")]
977 #[cfg(target_has_atomic = "8")]
978 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
979 pub fn fetch_nand(&self, val: bool, order: Ordering) -> bool {
980 // We can't use atomic_nand here because it can result in a bool with
981 // an invalid value. This happens because the atomic operation is done
982 // with an 8-bit integer internally, which would set the upper 7 bits.
983 // So we just use fetch_xor or swap instead.
984 if val {
985 // !(x & true) == !x
986 // We must invert the bool.
987 self.fetch_xor(true, order)
988 } else {
989 // !(x & false) == true
990 // We must set the bool to true.
991 self.swap(true, order)
992 }
993 }
994
995 /// Logical "or" with a boolean value.
996 ///
997 /// Performs a logical "or" operation on the current value and the argument `val`, and sets the
998 /// new value to the result.
999 ///
1000 /// Returns the previous value.
1001 ///
1002 /// `fetch_or` takes an [`Ordering`] argument which describes the memory ordering
1003 /// of this operation. All ordering modes are possible. Note that using
1004 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
1005 /// using [`Release`] makes the load part [`Relaxed`].
1006 ///
1007 /// **Note:** This method is only available on platforms that support atomic
1008 /// operations on `u8`.
1009 ///
1010 /// # Examples
1011 ///
1012 /// ```
1013 /// use std::sync::atomic::{AtomicBool, Ordering};
1014 ///
1015 /// let foo = AtomicBool::new(true);
1016 /// assert_eq!(foo.fetch_or(false, Ordering::SeqCst), true);
1017 /// assert_eq!(foo.load(Ordering::SeqCst), true);
1018 ///
1019 /// let foo = AtomicBool::new(true);
1020 /// assert_eq!(foo.fetch_or(true, Ordering::SeqCst), true);
1021 /// assert_eq!(foo.load(Ordering::SeqCst), true);
1022 ///
1023 /// let foo = AtomicBool::new(false);
1024 /// assert_eq!(foo.fetch_or(false, Ordering::SeqCst), false);
1025 /// assert_eq!(foo.load(Ordering::SeqCst), false);
1026 /// ```
1027 #[inline]
1028 #[stable(feature = "rust1", since = "1.0.0")]
1029 #[cfg(target_has_atomic = "8")]
1030 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1031 pub fn fetch_or(&self, val: bool, order: Ordering) -> bool {
1032 // SAFETY: data races are prevented by atomic intrinsics.
1033 unsafe { atomic_or(self.v.get(), val as u8, order) != 0 }
1034 }
1035
1036 /// Logical "xor" with a boolean value.
1037 ///
1038 /// Performs a logical "xor" operation on the current value and the argument `val`, and sets
1039 /// the new value to the result.
1040 ///
1041 /// Returns the previous value.
1042 ///
1043 /// `fetch_xor` takes an [`Ordering`] argument which describes the memory ordering
1044 /// of this operation. All ordering modes are possible. Note that using
1045 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
1046 /// using [`Release`] makes the load part [`Relaxed`].
1047 ///
1048 /// **Note:** This method is only available on platforms that support atomic
1049 /// operations on `u8`.
1050 ///
1051 /// # Examples
1052 ///
1053 /// ```
1054 /// use std::sync::atomic::{AtomicBool, Ordering};
1055 ///
1056 /// let foo = AtomicBool::new(true);
1057 /// assert_eq!(foo.fetch_xor(false, Ordering::SeqCst), true);
1058 /// assert_eq!(foo.load(Ordering::SeqCst), true);
1059 ///
1060 /// let foo = AtomicBool::new(true);
1061 /// assert_eq!(foo.fetch_xor(true, Ordering::SeqCst), true);
1062 /// assert_eq!(foo.load(Ordering::SeqCst), false);
1063 ///
1064 /// let foo = AtomicBool::new(false);
1065 /// assert_eq!(foo.fetch_xor(false, Ordering::SeqCst), false);
1066 /// assert_eq!(foo.load(Ordering::SeqCst), false);
1067 /// ```
1068 #[inline]
1069 #[stable(feature = "rust1", since = "1.0.0")]
1070 #[cfg(target_has_atomic = "8")]
1071 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1072 pub fn fetch_xor(&self, val: bool, order: Ordering) -> bool {
1073 // SAFETY: data races are prevented by atomic intrinsics.
1074 unsafe { atomic_xor(self.v.get(), val as u8, order) != 0 }
1075 }
1076
1077 /// Logical "not" with a boolean value.
1078 ///
1079 /// Performs a logical "not" operation on the current value, and sets
1080 /// the new value to the result.
1081 ///
1082 /// Returns the previous value.
1083 ///
1084 /// `fetch_not` takes an [`Ordering`] argument which describes the memory ordering
1085 /// of this operation. All ordering modes are possible. Note that using
1086 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
1087 /// using [`Release`] makes the load part [`Relaxed`].
1088 ///
1089 /// **Note:** This method is only available on platforms that support atomic
1090 /// operations on `u8`.
1091 ///
1092 /// # Examples
1093 ///
1094 /// ```
1095 /// use std::sync::atomic::{AtomicBool, Ordering};
1096 ///
1097 /// let foo = AtomicBool::new(true);
1098 /// assert_eq!(foo.fetch_not(Ordering::SeqCst), true);
1099 /// assert_eq!(foo.load(Ordering::SeqCst), false);
1100 ///
1101 /// let foo = AtomicBool::new(false);
1102 /// assert_eq!(foo.fetch_not(Ordering::SeqCst), false);
1103 /// assert_eq!(foo.load(Ordering::SeqCst), true);
1104 /// ```
1105 #[inline]
1106 #[stable(feature = "atomic_bool_fetch_not", since = "1.81.0")]
1107 #[cfg(target_has_atomic = "8")]
1108 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1109 pub fn fetch_not(&self, order: Ordering) -> bool {
1110 self.fetch_xor(true, order)
1111 }
1112
1113 /// Returns a mutable pointer to the underlying [`bool`].
1114 ///
1115 /// Doing non-atomic reads and writes on the resulting boolean can be a data race.
1116 /// This method is mostly useful for FFI, where the function signature may use
1117 /// `*mut bool` instead of `&AtomicBool`.
1118 ///
1119 /// Returning an `*mut` pointer from a shared reference to this atomic is safe because the
1120 /// atomic types work with interior mutability. All modifications of an atomic change the value
1121 /// through a shared reference, and can do so safely as long as they use atomic operations. Any
1122 /// use of the returned raw pointer requires an `unsafe` block and still has to uphold the same
1123 /// restriction: operations on it must be atomic.
1124 ///
1125 /// # Examples
1126 ///
1127 /// ```ignore (extern-declaration)
1128 /// # fn main() {
1129 /// use std::sync::atomic::AtomicBool;
1130 ///
1131 /// extern "C" {
1132 /// fn my_atomic_op(arg: *mut bool);
1133 /// }
1134 ///
1135 /// let mut atomic = AtomicBool::new(true);
1136 /// unsafe {
1137 /// my_atomic_op(atomic.as_ptr());
1138 /// }
1139 /// # }
1140 /// ```
1141 #[inline]
1142 #[stable(feature = "atomic_as_ptr", since = "1.70.0")]
1143 #[rustc_const_stable(feature = "atomic_as_ptr", since = "1.70.0")]
1144 #[rustc_never_returns_null_ptr]
1145 pub const fn as_ptr(&self) -> *mut bool {
1146 self.v.get().cast()
1147 }
1148
1149 /// Fetches the value, and applies a function to it that returns an optional
1150 /// new value. Returns a `Result` of `Ok(previous_value)` if the function
1151 /// returned `Some(_)`, else `Err(previous_value)`.
1152 ///
1153 /// Note: This may call the function multiple times if the value has been
1154 /// changed from other threads in the meantime, as long as the function
1155 /// returns `Some(_)`, but the function will have been applied only once to
1156 /// the stored value.
1157 ///
1158 /// `fetch_update` takes two [`Ordering`] arguments to describe the memory
1159 /// ordering of this operation. The first describes the required ordering for
1160 /// when the operation finally succeeds while the second describes the
1161 /// required ordering for loads. These correspond to the success and failure
1162 /// orderings of [`AtomicBool::compare_exchange`] respectively.
1163 ///
1164 /// Using [`Acquire`] as success ordering makes the store part of this
1165 /// operation [`Relaxed`], and using [`Release`] makes the final successful
1166 /// load [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`],
1167 /// [`Acquire`] or [`Relaxed`].
1168 ///
1169 /// **Note:** This method is only available on platforms that support atomic
1170 /// operations on `u8`.
1171 ///
1172 /// # Considerations
1173 ///
1174 /// This method is not magic; it is not provided by the hardware.
1175 /// It is implemented in terms of [`AtomicBool::compare_exchange_weak`], and suffers from the same drawbacks.
1176 /// In particular, this method will not circumvent the [ABA Problem].
1177 ///
1178 /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
1179 ///
1180 /// # Examples
1181 ///
1182 /// ```rust
1183 /// use std::sync::atomic::{AtomicBool, Ordering};
1184 ///
1185 /// let x = AtomicBool::new(false);
1186 /// assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |_| None), Err(false));
1187 /// assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(!x)), Ok(false));
1188 /// assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(!x)), Ok(true));
1189 /// assert_eq!(x.load(Ordering::SeqCst), false);
1190 /// ```
1191 #[inline]
1192 #[stable(feature = "atomic_fetch_update", since = "1.53.0")]
1193 #[cfg(target_has_atomic = "8")]
1194 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1195 pub fn fetch_update<F>(
1196 &self,
1197 set_order: Ordering,
1198 fetch_order: Ordering,
1199 mut f: F,
1200 ) -> Result<bool, bool>
1201 where
1202 F: FnMut(bool) -> Option<bool>,
1203 {
1204 let mut prev = self.load(fetch_order);
1205 while let Some(next) = f(prev) {
1206 match self.compare_exchange_weak(prev, next, set_order, fetch_order) {
1207 x @ Ok(_) => return x,
1208 Err(next_prev) => prev = next_prev,
1209 }
1210 }
1211 Err(prev)
1212 }
1213
1214 /// Fetches the value, and applies a function to it that returns an optional
1215 /// new value. Returns a `Result` of `Ok(previous_value)` if the function
1216 /// returned `Some(_)`, else `Err(previous_value)`.
1217 ///
1218 /// See also: [`update`](`AtomicBool::update`).
1219 ///
1220 /// Note: This may call the function multiple times if the value has been
1221 /// changed from other threads in the meantime, as long as the function
1222 /// returns `Some(_)`, but the function will have been applied only once to
1223 /// the stored value.
1224 ///
1225 /// `try_update` takes two [`Ordering`] arguments to describe the memory
1226 /// ordering of this operation. The first describes the required ordering for
1227 /// when the operation finally succeeds while the second describes the
1228 /// required ordering for loads. These correspond to the success and failure
1229 /// orderings of [`AtomicBool::compare_exchange`] respectively.
1230 ///
1231 /// Using [`Acquire`] as success ordering makes the store part of this
1232 /// operation [`Relaxed`], and using [`Release`] makes the final successful
1233 /// load [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`],
1234 /// [`Acquire`] or [`Relaxed`].
1235 ///
1236 /// **Note:** This method is only available on platforms that support atomic
1237 /// operations on `u8`.
1238 ///
1239 /// # Considerations
1240 ///
1241 /// This method is not magic; it is not provided by the hardware.
1242 /// It is implemented in terms of [`AtomicBool::compare_exchange_weak`], and suffers from the same drawbacks.
1243 /// In particular, this method will not circumvent the [ABA Problem].
1244 ///
1245 /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
1246 ///
1247 /// # Examples
1248 ///
1249 /// ```rust
1250 /// #![feature(atomic_try_update)]
1251 /// use std::sync::atomic::{AtomicBool, Ordering};
1252 ///
1253 /// let x = AtomicBool::new(false);
1254 /// assert_eq!(x.try_update(Ordering::SeqCst, Ordering::SeqCst, |_| None), Err(false));
1255 /// assert_eq!(x.try_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(!x)), Ok(false));
1256 /// assert_eq!(x.try_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(!x)), Ok(true));
1257 /// assert_eq!(x.load(Ordering::SeqCst), false);
1258 /// ```
1259 #[inline]
1260 #[unstable(feature = "atomic_try_update", issue = "135894")]
1261 #[cfg(target_has_atomic = "8")]
1262 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1263 pub fn try_update(
1264 &self,
1265 set_order: Ordering,
1266 fetch_order: Ordering,
1267 f: impl FnMut(bool) -> Option<bool>,
1268 ) -> Result<bool, bool> {
1269 // FIXME(atomic_try_update): this is currently an unstable alias to `fetch_update`;
1270 // when stabilizing, turn `fetch_update` into a deprecated alias to `try_update`.
1271 self.fetch_update(set_order, fetch_order, f)
1272 }
1273
1274 /// Fetches the value, applies a function to it that it return a new value.
1275 /// The new value is stored and the old value is returned.
1276 ///
1277 /// See also: [`try_update`](`AtomicBool::try_update`).
1278 ///
1279 /// Note: This may call the function multiple times if the value has been changed from other threads in
1280 /// the meantime, but the function will have been applied only once to the stored value.
1281 ///
1282 /// `update` takes two [`Ordering`] arguments to describe the memory
1283 /// ordering of this operation. The first describes the required ordering for
1284 /// when the operation finally succeeds while the second describes the
1285 /// required ordering for loads. These correspond to the success and failure
1286 /// orderings of [`AtomicBool::compare_exchange`] respectively.
1287 ///
1288 /// Using [`Acquire`] as success ordering makes the store part
1289 /// of this operation [`Relaxed`], and using [`Release`] makes the final successful load
1290 /// [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`].
1291 ///
1292 /// **Note:** This method is only available on platforms that support atomic operations on `u8`.
1293 ///
1294 /// # Considerations
1295 ///
1296 /// This method is not magic; it is not provided by the hardware.
1297 /// It is implemented in terms of [`AtomicBool::compare_exchange_weak`], and suffers from the same drawbacks.
1298 /// In particular, this method will not circumvent the [ABA Problem].
1299 ///
1300 /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
1301 ///
1302 /// # Examples
1303 ///
1304 /// ```rust
1305 /// #![feature(atomic_try_update)]
1306 ///
1307 /// use std::sync::atomic::{AtomicBool, Ordering};
1308 ///
1309 /// let x = AtomicBool::new(false);
1310 /// assert_eq!(x.update(Ordering::SeqCst, Ordering::SeqCst, |x| !x), false);
1311 /// assert_eq!(x.update(Ordering::SeqCst, Ordering::SeqCst, |x| !x), true);
1312 /// assert_eq!(x.load(Ordering::SeqCst), false);
1313 /// ```
1314 #[inline]
1315 #[unstable(feature = "atomic_try_update", issue = "135894")]
1316 #[cfg(target_has_atomic = "8")]
1317 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1318 pub fn update(
1319 &self,
1320 set_order: Ordering,
1321 fetch_order: Ordering,
1322 mut f: impl FnMut(bool) -> bool,
1323 ) -> bool {
1324 let mut prev = self.load(fetch_order);
1325 loop {
1326 match self.compare_exchange_weak(prev, f(prev), set_order, fetch_order) {
1327 Ok(x) => break x,
1328 Err(next_prev) => prev = next_prev,
1329 }
1330 }
1331 }
1332}
1333
1334#[cfg(target_has_atomic_load_store = "ptr")]
1335impl<T> AtomicPtr<T> {
1336 /// Creates a new `AtomicPtr`.
1337 ///
1338 /// # Examples
1339 ///
1340 /// ```
1341 /// use std::sync::atomic::AtomicPtr;
1342 ///
1343 /// let ptr = &mut 5;
1344 /// let atomic_ptr = AtomicPtr::new(ptr);
1345 /// ```
1346 #[inline]
1347 #[stable(feature = "rust1", since = "1.0.0")]
1348 #[rustc_const_stable(feature = "const_atomic_new", since = "1.24.0")]
1349 pub const fn new(p: *mut T) -> AtomicPtr<T> {
1350 AtomicPtr { p: UnsafeCell::new(p) }
1351 }
1352
1353 /// Creates a new `AtomicPtr` from a pointer.
1354 ///
1355 /// # Examples
1356 ///
1357 /// ```
1358 /// use std::sync::atomic::{self, AtomicPtr};
1359 ///
1360 /// // Get a pointer to an allocated value
1361 /// let ptr: *mut *mut u8 = Box::into_raw(Box::new(std::ptr::null_mut()));
1362 ///
1363 /// assert!(ptr.cast::<AtomicPtr<u8>>().is_aligned());
1364 ///
1365 /// {
1366 /// // Create an atomic view of the allocated value
1367 /// let atomic = unsafe { AtomicPtr::from_ptr(ptr) };
1368 ///
1369 /// // Use `atomic` for atomic operations, possibly share it with other threads
1370 /// atomic.store(std::ptr::NonNull::dangling().as_ptr(), atomic::Ordering::Relaxed);
1371 /// }
1372 ///
1373 /// // It's ok to non-atomically access the value behind `ptr`,
1374 /// // since the reference to the atomic ended its lifetime in the block above
1375 /// assert!(!unsafe { *ptr }.is_null());
1376 ///
1377 /// // Deallocate the value
1378 /// unsafe { drop(Box::from_raw(ptr)) }
1379 /// ```
1380 ///
1381 /// # Safety
1382 ///
1383 /// * `ptr` must be aligned to `align_of::<AtomicPtr<T>>()` (note that on some platforms this
1384 /// can be bigger than `align_of::<*mut T>()`).
1385 /// * `ptr` must be [valid] for both reads and writes for the whole lifetime `'a`.
1386 /// * You must adhere to the [Memory model for atomic accesses]. In particular, it is not
1387 /// allowed to mix atomic and non-atomic accesses, or atomic accesses of different sizes,
1388 /// without synchronization.
1389 ///
1390 /// [valid]: crate::ptr#safety
1391 /// [Memory model for atomic accesses]: self#memory-model-for-atomic-accesses
1392 #[stable(feature = "atomic_from_ptr", since = "1.75.0")]
1393 #[rustc_const_stable(feature = "const_atomic_from_ptr", since = "1.84.0")]
1394 pub const unsafe fn from_ptr<'a>(ptr: *mut *mut T) -> &'a AtomicPtr<T> {
1395 // SAFETY: guaranteed by the caller
1396 unsafe { &*ptr.cast() }
1397 }
1398
1399 /// Returns a mutable reference to the underlying pointer.
1400 ///
1401 /// This is safe because the mutable reference guarantees that no other threads are
1402 /// concurrently accessing the atomic data.
1403 ///
1404 /// # Examples
1405 ///
1406 /// ```
1407 /// use std::sync::atomic::{AtomicPtr, Ordering};
1408 ///
1409 /// let mut data = 10;
1410 /// let mut atomic_ptr = AtomicPtr::new(&mut data);
1411 /// let mut other_data = 5;
1412 /// *atomic_ptr.get_mut() = &mut other_data;
1413 /// assert_eq!(unsafe { *atomic_ptr.load(Ordering::SeqCst) }, 5);
1414 /// ```
1415 #[inline]
1416 #[stable(feature = "atomic_access", since = "1.15.0")]
1417 pub fn get_mut(&mut self) -> &mut *mut T {
1418 self.p.get_mut()
1419 }
1420
1421 /// Gets atomic access to a pointer.
1422 ///
1423 /// # Examples
1424 ///
1425 /// ```
1426 /// #![feature(atomic_from_mut)]
1427 /// use std::sync::atomic::{AtomicPtr, Ordering};
1428 ///
1429 /// let mut data = 123;
1430 /// let mut some_ptr = &mut data as *mut i32;
1431 /// let a = AtomicPtr::from_mut(&mut some_ptr);
1432 /// let mut other_data = 456;
1433 /// a.store(&mut other_data, Ordering::Relaxed);
1434 /// assert_eq!(unsafe { *some_ptr }, 456);
1435 /// ```
1436 #[inline]
1437 #[cfg(target_has_atomic_equal_alignment = "ptr")]
1438 #[unstable(feature = "atomic_from_mut", issue = "76314")]
1439 pub fn from_mut(v: &mut *mut T) -> &mut Self {
1440 let [] = [(); align_of::<AtomicPtr<()>>() - align_of::<*mut ()>()];
1441 // SAFETY:
1442 // - the mutable reference guarantees unique ownership.
1443 // - the alignment of `*mut T` and `Self` is the same on all platforms
1444 // supported by rust, as verified above.
1445 unsafe { &mut *(v as *mut *mut T as *mut Self) }
1446 }
1447
1448 /// Gets non-atomic access to a `&mut [AtomicPtr]` slice.
1449 ///
1450 /// This is safe because the mutable reference guarantees that no other threads are
1451 /// concurrently accessing the atomic data.
1452 ///
1453 /// # Examples
1454 ///
1455 /// ```
1456 /// #![feature(atomic_from_mut)]
1457 /// use std::ptr::null_mut;
1458 /// use std::sync::atomic::{AtomicPtr, Ordering};
1459 ///
1460 /// let mut some_ptrs = [const { AtomicPtr::new(null_mut::<String>()) }; 10];
1461 ///
1462 /// let view: &mut [*mut String] = AtomicPtr::get_mut_slice(&mut some_ptrs);
1463 /// assert_eq!(view, [null_mut::<String>(); 10]);
1464 /// view
1465 /// .iter_mut()
1466 /// .enumerate()
1467 /// .for_each(|(i, ptr)| *ptr = Box::into_raw(Box::new(format!("iteration#{i}"))));
1468 ///
1469 /// std::thread::scope(|s| {
1470 /// for ptr in &some_ptrs {
1471 /// s.spawn(move || {
1472 /// let ptr = ptr.load(Ordering::Relaxed);
1473 /// assert!(!ptr.is_null());
1474 ///
1475 /// let name = unsafe { Box::from_raw(ptr) };
1476 /// println!("Hello, {name}!");
1477 /// });
1478 /// }
1479 /// });
1480 /// ```
1481 #[inline]
1482 #[unstable(feature = "atomic_from_mut", issue = "76314")]
1483 pub fn get_mut_slice(this: &mut [Self]) -> &mut [*mut T] {
1484 // SAFETY: the mutable reference guarantees unique ownership.
1485 unsafe { &mut *(this as *mut [Self] as *mut [*mut T]) }
1486 }
1487
1488 /// Gets atomic access to a slice of pointers.
1489 ///
1490 /// # Examples
1491 ///
1492 /// ```
1493 /// #![feature(atomic_from_mut)]
1494 /// use std::ptr::null_mut;
1495 /// use std::sync::atomic::{AtomicPtr, Ordering};
1496 ///
1497 /// let mut some_ptrs = [null_mut::<String>(); 10];
1498 /// let a = &*AtomicPtr::from_mut_slice(&mut some_ptrs);
1499 /// std::thread::scope(|s| {
1500 /// for i in 0..a.len() {
1501 /// s.spawn(move || {
1502 /// let name = Box::new(format!("thread{i}"));
1503 /// a[i].store(Box::into_raw(name), Ordering::Relaxed);
1504 /// });
1505 /// }
1506 /// });
1507 /// for p in some_ptrs {
1508 /// assert!(!p.is_null());
1509 /// let name = unsafe { Box::from_raw(p) };
1510 /// println!("Hello, {name}!");
1511 /// }
1512 /// ```
1513 #[inline]
1514 #[cfg(target_has_atomic_equal_alignment = "ptr")]
1515 #[unstable(feature = "atomic_from_mut", issue = "76314")]
1516 pub fn from_mut_slice(v: &mut [*mut T]) -> &mut [Self] {
1517 // SAFETY:
1518 // - the mutable reference guarantees unique ownership.
1519 // - the alignment of `*mut T` and `Self` is the same on all platforms
1520 // supported by rust, as verified above.
1521 unsafe { &mut *(v as *mut [*mut T] as *mut [Self]) }
1522 }
1523
1524 /// Consumes the atomic and returns the contained value.
1525 ///
1526 /// This is safe because passing `self` by value guarantees that no other threads are
1527 /// concurrently accessing the atomic data.
1528 ///
1529 /// # Examples
1530 ///
1531 /// ```
1532 /// use std::sync::atomic::AtomicPtr;
1533 ///
1534 /// let mut data = 5;
1535 /// let atomic_ptr = AtomicPtr::new(&mut data);
1536 /// assert_eq!(unsafe { *atomic_ptr.into_inner() }, 5);
1537 /// ```
1538 #[inline]
1539 #[stable(feature = "atomic_access", since = "1.15.0")]
1540 #[rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0")]
1541 pub const fn into_inner(self) -> *mut T {
1542 self.p.into_inner()
1543 }
1544
1545 /// Loads a value from the pointer.
1546 ///
1547 /// `load` takes an [`Ordering`] argument which describes the memory ordering
1548 /// of this operation. Possible values are [`SeqCst`], [`Acquire`] and [`Relaxed`].
1549 ///
1550 /// # Panics
1551 ///
1552 /// Panics if `order` is [`Release`] or [`AcqRel`].
1553 ///
1554 /// # Examples
1555 ///
1556 /// ```
1557 /// use std::sync::atomic::{AtomicPtr, Ordering};
1558 ///
1559 /// let ptr = &mut 5;
1560 /// let some_ptr = AtomicPtr::new(ptr);
1561 ///
1562 /// let value = some_ptr.load(Ordering::Relaxed);
1563 /// ```
1564 #[inline]
1565 #[stable(feature = "rust1", since = "1.0.0")]
1566 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1567 pub fn load(&self, order: Ordering) -> *mut T {
1568 // SAFETY: data races are prevented by atomic intrinsics.
1569 unsafe { atomic_load(self.p.get(), order) }
1570 }
1571
1572 /// Stores a value into the pointer.
1573 ///
1574 /// `store` takes an [`Ordering`] argument which describes the memory ordering
1575 /// of this operation. Possible values are [`SeqCst`], [`Release`] and [`Relaxed`].
1576 ///
1577 /// # Panics
1578 ///
1579 /// Panics if `order` is [`Acquire`] or [`AcqRel`].
1580 ///
1581 /// # Examples
1582 ///
1583 /// ```
1584 /// use std::sync::atomic::{AtomicPtr, Ordering};
1585 ///
1586 /// let ptr = &mut 5;
1587 /// let some_ptr = AtomicPtr::new(ptr);
1588 ///
1589 /// let other_ptr = &mut 10;
1590 ///
1591 /// some_ptr.store(other_ptr, Ordering::Relaxed);
1592 /// ```
1593 #[inline]
1594 #[stable(feature = "rust1", since = "1.0.0")]
1595 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1596 pub fn store(&self, ptr: *mut T, order: Ordering) {
1597 // SAFETY: data races are prevented by atomic intrinsics.
1598 unsafe {
1599 atomic_store(self.p.get(), ptr, order);
1600 }
1601 }
1602
1603 /// Stores a value into the pointer, returning the previous value.
1604 ///
1605 /// `swap` takes an [`Ordering`] argument which describes the memory ordering
1606 /// of this operation. All ordering modes are possible. Note that using
1607 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
1608 /// using [`Release`] makes the load part [`Relaxed`].
1609 ///
1610 /// **Note:** This method is only available on platforms that support atomic
1611 /// operations on pointers.
1612 ///
1613 /// # Examples
1614 ///
1615 /// ```
1616 /// use std::sync::atomic::{AtomicPtr, Ordering};
1617 ///
1618 /// let ptr = &mut 5;
1619 /// let some_ptr = AtomicPtr::new(ptr);
1620 ///
1621 /// let other_ptr = &mut 10;
1622 ///
1623 /// let value = some_ptr.swap(other_ptr, Ordering::Relaxed);
1624 /// ```
1625 #[inline]
1626 #[stable(feature = "rust1", since = "1.0.0")]
1627 #[cfg(target_has_atomic = "ptr")]
1628 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1629 pub fn swap(&self, ptr: *mut T, order: Ordering) -> *mut T {
1630 // SAFETY: data races are prevented by atomic intrinsics.
1631 unsafe { atomic_swap(self.p.get(), ptr, order) }
1632 }
1633
1634 /// Stores a value into the pointer if the current value is the same as the `current` value.
1635 ///
1636 /// The return value is always the previous value. If it is equal to `current`, then the value
1637 /// was updated.
1638 ///
1639 /// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory
1640 /// ordering of this operation. Notice that even when using [`AcqRel`], the operation
1641 /// might fail and hence just perform an `Acquire` load, but not have `Release` semantics.
1642 /// Using [`Acquire`] makes the store part of this operation [`Relaxed`] if it
1643 /// happens, and using [`Release`] makes the load part [`Relaxed`].
1644 ///
1645 /// **Note:** This method is only available on platforms that support atomic
1646 /// operations on pointers.
1647 ///
1648 /// # Migrating to `compare_exchange` and `compare_exchange_weak`
1649 ///
1650 /// `compare_and_swap` is equivalent to `compare_exchange` with the following mapping for
1651 /// memory orderings:
1652 ///
1653 /// Original | Success | Failure
1654 /// -------- | ------- | -------
1655 /// Relaxed | Relaxed | Relaxed
1656 /// Acquire | Acquire | Acquire
1657 /// Release | Release | Relaxed
1658 /// AcqRel | AcqRel | Acquire
1659 /// SeqCst | SeqCst | SeqCst
1660 ///
1661 /// `compare_and_swap` and `compare_exchange` also differ in their return type. You can use
1662 /// `compare_exchange(...).unwrap_or_else(|x| x)` to recover the behavior of `compare_and_swap`,
1663 /// but in most cases it is more idiomatic to check whether the return value is `Ok` or `Err`
1664 /// rather than to infer success vs failure based on the value that was read.
1665 ///
1666 /// During migration, consider whether it makes sense to use `compare_exchange_weak` instead.
1667 /// `compare_exchange_weak` is allowed to fail spuriously even when the comparison succeeds,
1668 /// which allows the compiler to generate better assembly code when the compare and swap
1669 /// is used in a loop.
1670 ///
1671 /// # Examples
1672 ///
1673 /// ```
1674 /// use std::sync::atomic::{AtomicPtr, Ordering};
1675 ///
1676 /// let ptr = &mut 5;
1677 /// let some_ptr = AtomicPtr::new(ptr);
1678 ///
1679 /// let other_ptr = &mut 10;
1680 ///
1681 /// let value = some_ptr.compare_and_swap(ptr, other_ptr, Ordering::Relaxed);
1682 /// ```
1683 #[inline]
1684 #[stable(feature = "rust1", since = "1.0.0")]
1685 #[deprecated(
1686 since = "1.50.0",
1687 note = "Use `compare_exchange` or `compare_exchange_weak` instead"
1688 )]
1689 #[cfg(target_has_atomic = "ptr")]
1690 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1691 pub fn compare_and_swap(&self, current: *mut T, new: *mut T, order: Ordering) -> *mut T {
1692 match self.compare_exchange(current, new, order, strongest_failure_ordering(order)) {
1693 Ok(x) => x,
1694 Err(x) => x,
1695 }
1696 }
1697
1698 /// Stores a value into the pointer if the current value is the same as the `current` value.
1699 ///
1700 /// The return value is a result indicating whether the new value was written and containing
1701 /// the previous value. On success this value is guaranteed to be equal to `current`.
1702 ///
1703 /// `compare_exchange` takes two [`Ordering`] arguments to describe the memory
1704 /// ordering of this operation. `success` describes the required ordering for the
1705 /// read-modify-write operation that takes place if the comparison with `current` succeeds.
1706 /// `failure` describes the required ordering for the load operation that takes place when
1707 /// the comparison fails. Using [`Acquire`] as success ordering makes the store part
1708 /// of this operation [`Relaxed`], and using [`Release`] makes the successful load
1709 /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`].
1710 ///
1711 /// **Note:** This method is only available on platforms that support atomic
1712 /// operations on pointers.
1713 ///
1714 /// # Examples
1715 ///
1716 /// ```
1717 /// use std::sync::atomic::{AtomicPtr, Ordering};
1718 ///
1719 /// let ptr = &mut 5;
1720 /// let some_ptr = AtomicPtr::new(ptr);
1721 ///
1722 /// let other_ptr = &mut 10;
1723 ///
1724 /// let value = some_ptr.compare_exchange(ptr, other_ptr,
1725 /// Ordering::SeqCst, Ordering::Relaxed);
1726 /// ```
1727 #[inline]
1728 #[stable(feature = "extended_compare_and_swap", since = "1.10.0")]
1729 #[cfg(target_has_atomic = "ptr")]
1730 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1731 pub fn compare_exchange(
1732 &self,
1733 current: *mut T,
1734 new: *mut T,
1735 success: Ordering,
1736 failure: Ordering,
1737 ) -> Result<*mut T, *mut T> {
1738 // SAFETY: data races are prevented by atomic intrinsics.
1739 unsafe { atomic_compare_exchange(self.p.get(), current, new, success, failure) }
1740 }
1741
1742 /// Stores a value into the pointer if the current value is the same as the `current` value.
1743 ///
1744 /// Unlike [`AtomicPtr::compare_exchange`], this function is allowed to spuriously fail even when the
1745 /// comparison succeeds, which can result in more efficient code on some platforms. The
1746 /// return value is a result indicating whether the new value was written and containing the
1747 /// previous value.
1748 ///
1749 /// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory
1750 /// ordering of this operation. `success` describes the required ordering for the
1751 /// read-modify-write operation that takes place if the comparison with `current` succeeds.
1752 /// `failure` describes the required ordering for the load operation that takes place when
1753 /// the comparison fails. Using [`Acquire`] as success ordering makes the store part
1754 /// of this operation [`Relaxed`], and using [`Release`] makes the successful load
1755 /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`].
1756 ///
1757 /// **Note:** This method is only available on platforms that support atomic
1758 /// operations on pointers.
1759 ///
1760 /// # Examples
1761 ///
1762 /// ```
1763 /// use std::sync::atomic::{AtomicPtr, Ordering};
1764 ///
1765 /// let some_ptr = AtomicPtr::new(&mut 5);
1766 ///
1767 /// let new = &mut 10;
1768 /// let mut old = some_ptr.load(Ordering::Relaxed);
1769 /// loop {
1770 /// match some_ptr.compare_exchange_weak(old, new, Ordering::SeqCst, Ordering::Relaxed) {
1771 /// Ok(_) => break,
1772 /// Err(x) => old = x,
1773 /// }
1774 /// }
1775 /// ```
1776 #[inline]
1777 #[stable(feature = "extended_compare_and_swap", since = "1.10.0")]
1778 #[cfg(target_has_atomic = "ptr")]
1779 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1780 pub fn compare_exchange_weak(
1781 &self,
1782 current: *mut T,
1783 new: *mut T,
1784 success: Ordering,
1785 failure: Ordering,
1786 ) -> Result<*mut T, *mut T> {
1787 // SAFETY: This intrinsic is unsafe because it operates on a raw pointer
1788 // but we know for sure that the pointer is valid (we just got it from
1789 // an `UnsafeCell` that we have by reference) and the atomic operation
1790 // itself allows us to safely mutate the `UnsafeCell` contents.
1791 unsafe { atomic_compare_exchange_weak(self.p.get(), current, new, success, failure) }
1792 }
1793
1794 /// Fetches the value, and applies a function to it that returns an optional
1795 /// new value. Returns a `Result` of `Ok(previous_value)` if the function
1796 /// returned `Some(_)`, else `Err(previous_value)`.
1797 ///
1798 /// Note: This may call the function multiple times if the value has been
1799 /// changed from other threads in the meantime, as long as the function
1800 /// returns `Some(_)`, but the function will have been applied only once to
1801 /// the stored value.
1802 ///
1803 /// `fetch_update` takes two [`Ordering`] arguments to describe the memory
1804 /// ordering of this operation. The first describes the required ordering for
1805 /// when the operation finally succeeds while the second describes the
1806 /// required ordering for loads. These correspond to the success and failure
1807 /// orderings of [`AtomicPtr::compare_exchange`] respectively.
1808 ///
1809 /// Using [`Acquire`] as success ordering makes the store part of this
1810 /// operation [`Relaxed`], and using [`Release`] makes the final successful
1811 /// load [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`],
1812 /// [`Acquire`] or [`Relaxed`].
1813 ///
1814 /// **Note:** This method is only available on platforms that support atomic
1815 /// operations on pointers.
1816 ///
1817 /// # Considerations
1818 ///
1819 /// This method is not magic; it is not provided by the hardware.
1820 /// It is implemented in terms of [`AtomicPtr::compare_exchange_weak`], and suffers from the same drawbacks.
1821 /// In particular, this method will not circumvent the [ABA Problem].
1822 ///
1823 /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
1824 ///
1825 /// # Examples
1826 ///
1827 /// ```rust
1828 /// use std::sync::atomic::{AtomicPtr, Ordering};
1829 ///
1830 /// let ptr: *mut _ = &mut 5;
1831 /// let some_ptr = AtomicPtr::new(ptr);
1832 ///
1833 /// let new: *mut _ = &mut 10;
1834 /// assert_eq!(some_ptr.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |_| None), Err(ptr));
1835 /// let result = some_ptr.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| {
1836 /// if x == ptr {
1837 /// Some(new)
1838 /// } else {
1839 /// None
1840 /// }
1841 /// });
1842 /// assert_eq!(result, Ok(ptr));
1843 /// assert_eq!(some_ptr.load(Ordering::SeqCst), new);
1844 /// ```
1845 #[inline]
1846 #[stable(feature = "atomic_fetch_update", since = "1.53.0")]
1847 #[cfg(target_has_atomic = "ptr")]
1848 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1849 pub fn fetch_update<F>(
1850 &self,
1851 set_order: Ordering,
1852 fetch_order: Ordering,
1853 mut f: F,
1854 ) -> Result<*mut T, *mut T>
1855 where
1856 F: FnMut(*mut T) -> Option<*mut T>,
1857 {
1858 let mut prev = self.load(fetch_order);
1859 while let Some(next) = f(prev) {
1860 match self.compare_exchange_weak(prev, next, set_order, fetch_order) {
1861 x @ Ok(_) => return x,
1862 Err(next_prev) => prev = next_prev,
1863 }
1864 }
1865 Err(prev)
1866 }
1867 /// Fetches the value, and applies a function to it that returns an optional
1868 /// new value. Returns a `Result` of `Ok(previous_value)` if the function
1869 /// returned `Some(_)`, else `Err(previous_value)`.
1870 ///
1871 /// See also: [`update`](`AtomicPtr::update`).
1872 ///
1873 /// Note: This may call the function multiple times if the value has been
1874 /// changed from other threads in the meantime, as long as the function
1875 /// returns `Some(_)`, but the function will have been applied only once to
1876 /// the stored value.
1877 ///
1878 /// `try_update` takes two [`Ordering`] arguments to describe the memory
1879 /// ordering of this operation. The first describes the required ordering for
1880 /// when the operation finally succeeds while the second describes the
1881 /// required ordering for loads. These correspond to the success and failure
1882 /// orderings of [`AtomicPtr::compare_exchange`] respectively.
1883 ///
1884 /// Using [`Acquire`] as success ordering makes the store part of this
1885 /// operation [`Relaxed`], and using [`Release`] makes the final successful
1886 /// load [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`],
1887 /// [`Acquire`] or [`Relaxed`].
1888 ///
1889 /// **Note:** This method is only available on platforms that support atomic
1890 /// operations on pointers.
1891 ///
1892 /// # Considerations
1893 ///
1894 /// This method is not magic; it is not provided by the hardware.
1895 /// It is implemented in terms of [`AtomicPtr::compare_exchange_weak`], and suffers from the same drawbacks.
1896 /// In particular, this method will not circumvent the [ABA Problem].
1897 ///
1898 /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
1899 ///
1900 /// # Examples
1901 ///
1902 /// ```rust
1903 /// #![feature(atomic_try_update)]
1904 /// use std::sync::atomic::{AtomicPtr, Ordering};
1905 ///
1906 /// let ptr: *mut _ = &mut 5;
1907 /// let some_ptr = AtomicPtr::new(ptr);
1908 ///
1909 /// let new: *mut _ = &mut 10;
1910 /// assert_eq!(some_ptr.try_update(Ordering::SeqCst, Ordering::SeqCst, |_| None), Err(ptr));
1911 /// let result = some_ptr.try_update(Ordering::SeqCst, Ordering::SeqCst, |x| {
1912 /// if x == ptr {
1913 /// Some(new)
1914 /// } else {
1915 /// None
1916 /// }
1917 /// });
1918 /// assert_eq!(result, Ok(ptr));
1919 /// assert_eq!(some_ptr.load(Ordering::SeqCst), new);
1920 /// ```
1921 #[inline]
1922 #[unstable(feature = "atomic_try_update", issue = "135894")]
1923 #[cfg(target_has_atomic = "ptr")]
1924 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1925 pub fn try_update(
1926 &self,
1927 set_order: Ordering,
1928 fetch_order: Ordering,
1929 f: impl FnMut(*mut T) -> Option<*mut T>,
1930 ) -> Result<*mut T, *mut T> {
1931 // FIXME(atomic_try_update): this is currently an unstable alias to `fetch_update`;
1932 // when stabilizing, turn `fetch_update` into a deprecated alias to `try_update`.
1933 self.fetch_update(set_order, fetch_order, f)
1934 }
1935
1936 /// Fetches the value, applies a function to it that it return a new value.
1937 /// The new value is stored and the old value is returned.
1938 ///
1939 /// See also: [`try_update`](`AtomicPtr::try_update`).
1940 ///
1941 /// Note: This may call the function multiple times if the value has been changed from other threads in
1942 /// the meantime, but the function will have been applied only once to the stored value.
1943 ///
1944 /// `update` takes two [`Ordering`] arguments to describe the memory
1945 /// ordering of this operation. The first describes the required ordering for
1946 /// when the operation finally succeeds while the second describes the
1947 /// required ordering for loads. These correspond to the success and failure
1948 /// orderings of [`AtomicPtr::compare_exchange`] respectively.
1949 ///
1950 /// Using [`Acquire`] as success ordering makes the store part
1951 /// of this operation [`Relaxed`], and using [`Release`] makes the final successful load
1952 /// [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`].
1953 ///
1954 /// **Note:** This method is only available on platforms that support atomic
1955 /// operations on pointers.
1956 ///
1957 /// # Considerations
1958 ///
1959 /// This method is not magic; it is not provided by the hardware.
1960 /// It is implemented in terms of [`AtomicPtr::compare_exchange_weak`], and suffers from the same drawbacks.
1961 /// In particular, this method will not circumvent the [ABA Problem].
1962 ///
1963 /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
1964 ///
1965 /// # Examples
1966 ///
1967 /// ```rust
1968 /// #![feature(atomic_try_update)]
1969 ///
1970 /// use std::sync::atomic::{AtomicPtr, Ordering};
1971 ///
1972 /// let ptr: *mut _ = &mut 5;
1973 /// let some_ptr = AtomicPtr::new(ptr);
1974 ///
1975 /// let new: *mut _ = &mut 10;
1976 /// let result = some_ptr.update(Ordering::SeqCst, Ordering::SeqCst, |_| new);
1977 /// assert_eq!(result, ptr);
1978 /// assert_eq!(some_ptr.load(Ordering::SeqCst), new);
1979 /// ```
1980 #[inline]
1981 #[unstable(feature = "atomic_try_update", issue = "135894")]
1982 #[cfg(target_has_atomic = "8")]
1983 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1984 pub fn update(
1985 &self,
1986 set_order: Ordering,
1987 fetch_order: Ordering,
1988 mut f: impl FnMut(*mut T) -> *mut T,
1989 ) -> *mut T {
1990 let mut prev = self.load(fetch_order);
1991 loop {
1992 match self.compare_exchange_weak(prev, f(prev), set_order, fetch_order) {
1993 Ok(x) => break x,
1994 Err(next_prev) => prev = next_prev,
1995 }
1996 }
1997 }
1998
1999 /// Offsets the pointer's address by adding `val` (in units of `T`),
2000 /// returning the previous pointer.
2001 ///
2002 /// This is equivalent to using [`wrapping_add`] to atomically perform the
2003 /// equivalent of `ptr = ptr.wrapping_add(val);`.
2004 ///
2005 /// This method operates in units of `T`, which means that it cannot be used
2006 /// to offset the pointer by an amount which is not a multiple of
2007 /// `size_of::<T>()`. This can sometimes be inconvenient, as you may want to
2008 /// work with a deliberately misaligned pointer. In such cases, you may use
2009 /// the [`fetch_byte_add`](Self::fetch_byte_add) method instead.
2010 ///
2011 /// `fetch_ptr_add` takes an [`Ordering`] argument which describes the
2012 /// memory ordering of this operation. All ordering modes are possible. Note
2013 /// that using [`Acquire`] makes the store part of this operation
2014 /// [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`].
2015 ///
2016 /// **Note**: This method is only available on platforms that support atomic
2017 /// operations on [`AtomicPtr`].
2018 ///
2019 /// [`wrapping_add`]: pointer::wrapping_add
2020 ///
2021 /// # Examples
2022 ///
2023 /// ```
2024 /// #![feature(strict_provenance_atomic_ptr)]
2025 /// use core::sync::atomic::{AtomicPtr, Ordering};
2026 ///
2027 /// let atom = AtomicPtr::<i64>::new(core::ptr::null_mut());
2028 /// assert_eq!(atom.fetch_ptr_add(1, Ordering::Relaxed).addr(), 0);
2029 /// // Note: units of `size_of::<i64>()`.
2030 /// assert_eq!(atom.load(Ordering::Relaxed).addr(), 8);
2031 /// ```
2032 #[inline]
2033 #[cfg(target_has_atomic = "ptr")]
2034 #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")]
2035 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2036 pub fn fetch_ptr_add(&self, val: usize, order: Ordering) -> *mut T {
2037 self.fetch_byte_add(val.wrapping_mul(size_of::<T>()), order)
2038 }
2039
2040 /// Offsets the pointer's address by subtracting `val` (in units of `T`),
2041 /// returning the previous pointer.
2042 ///
2043 /// This is equivalent to using [`wrapping_sub`] to atomically perform the
2044 /// equivalent of `ptr = ptr.wrapping_sub(val);`.
2045 ///
2046 /// This method operates in units of `T`, which means that it cannot be used
2047 /// to offset the pointer by an amount which is not a multiple of
2048 /// `size_of::<T>()`. This can sometimes be inconvenient, as you may want to
2049 /// work with a deliberately misaligned pointer. In such cases, you may use
2050 /// the [`fetch_byte_sub`](Self::fetch_byte_sub) method instead.
2051 ///
2052 /// `fetch_ptr_sub` takes an [`Ordering`] argument which describes the memory
2053 /// ordering of this operation. All ordering modes are possible. Note that
2054 /// using [`Acquire`] makes the store part of this operation [`Relaxed`],
2055 /// and using [`Release`] makes the load part [`Relaxed`].
2056 ///
2057 /// **Note**: This method is only available on platforms that support atomic
2058 /// operations on [`AtomicPtr`].
2059 ///
2060 /// [`wrapping_sub`]: pointer::wrapping_sub
2061 ///
2062 /// # Examples
2063 ///
2064 /// ```
2065 /// #![feature(strict_provenance_atomic_ptr)]
2066 /// use core::sync::atomic::{AtomicPtr, Ordering};
2067 ///
2068 /// let array = [1i32, 2i32];
2069 /// let atom = AtomicPtr::new(array.as_ptr().wrapping_add(1) as *mut _);
2070 ///
2071 /// assert!(core::ptr::eq(
2072 /// atom.fetch_ptr_sub(1, Ordering::Relaxed),
2073 /// &array[1],
2074 /// ));
2075 /// assert!(core::ptr::eq(atom.load(Ordering::Relaxed), &array[0]));
2076 /// ```
2077 #[inline]
2078 #[cfg(target_has_atomic = "ptr")]
2079 #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")]
2080 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2081 pub fn fetch_ptr_sub(&self, val: usize, order: Ordering) -> *mut T {
2082 self.fetch_byte_sub(val.wrapping_mul(size_of::<T>()), order)
2083 }
2084
2085 /// Offsets the pointer's address by adding `val` *bytes*, returning the
2086 /// previous pointer.
2087 ///
2088 /// This is equivalent to using [`wrapping_byte_add`] to atomically
2089 /// perform `ptr = ptr.wrapping_byte_add(val)`.
2090 ///
2091 /// `fetch_byte_add` takes an [`Ordering`] argument which describes the
2092 /// memory ordering of this operation. All ordering modes are possible. Note
2093 /// that using [`Acquire`] makes the store part of this operation
2094 /// [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`].
2095 ///
2096 /// **Note**: This method is only available on platforms that support atomic
2097 /// operations on [`AtomicPtr`].
2098 ///
2099 /// [`wrapping_byte_add`]: pointer::wrapping_byte_add
2100 ///
2101 /// # Examples
2102 ///
2103 /// ```
2104 /// #![feature(strict_provenance_atomic_ptr)]
2105 /// use core::sync::atomic::{AtomicPtr, Ordering};
2106 ///
2107 /// let atom = AtomicPtr::<i64>::new(core::ptr::null_mut());
2108 /// assert_eq!(atom.fetch_byte_add(1, Ordering::Relaxed).addr(), 0);
2109 /// // Note: in units of bytes, not `size_of::<i64>()`.
2110 /// assert_eq!(atom.load(Ordering::Relaxed).addr(), 1);
2111 /// ```
2112 #[inline]
2113 #[cfg(target_has_atomic = "ptr")]
2114 #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")]
2115 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2116 pub fn fetch_byte_add(&self, val: usize, order: Ordering) -> *mut T {
2117 // SAFETY: data races are prevented by atomic intrinsics.
2118 unsafe { atomic_add(self.p.get(), core::ptr::without_provenance_mut(val), order).cast() }
2119 }
2120
2121 /// Offsets the pointer's address by subtracting `val` *bytes*, returning the
2122 /// previous pointer.
2123 ///
2124 /// This is equivalent to using [`wrapping_byte_sub`] to atomically
2125 /// perform `ptr = ptr.wrapping_byte_sub(val)`.
2126 ///
2127 /// `fetch_byte_sub` takes an [`Ordering`] argument which describes the
2128 /// memory ordering of this operation. All ordering modes are possible. Note
2129 /// that using [`Acquire`] makes the store part of this operation
2130 /// [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`].
2131 ///
2132 /// **Note**: This method is only available on platforms that support atomic
2133 /// operations on [`AtomicPtr`].
2134 ///
2135 /// [`wrapping_byte_sub`]: pointer::wrapping_byte_sub
2136 ///
2137 /// # Examples
2138 ///
2139 /// ```
2140 /// #![feature(strict_provenance_atomic_ptr)]
2141 /// use core::sync::atomic::{AtomicPtr, Ordering};
2142 ///
2143 /// let atom = AtomicPtr::<i64>::new(core::ptr::without_provenance_mut(1));
2144 /// assert_eq!(atom.fetch_byte_sub(1, Ordering::Relaxed).addr(), 1);
2145 /// assert_eq!(atom.load(Ordering::Relaxed).addr(), 0);
2146 /// ```
2147 #[inline]
2148 #[cfg(target_has_atomic = "ptr")]
2149 #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")]
2150 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2151 pub fn fetch_byte_sub(&self, val: usize, order: Ordering) -> *mut T {
2152 // SAFETY: data races are prevented by atomic intrinsics.
2153 unsafe { atomic_sub(self.p.get(), core::ptr::without_provenance_mut(val), order).cast() }
2154 }
2155
2156 /// Performs a bitwise "or" operation on the address of the current pointer,
2157 /// and the argument `val`, and stores a pointer with provenance of the
2158 /// current pointer and the resulting address.
2159 ///
2160 /// This is equivalent to using [`map_addr`] to atomically perform
2161 /// `ptr = ptr.map_addr(|a| a | val)`. This can be used in tagged
2162 /// pointer schemes to atomically set tag bits.
2163 ///
2164 /// **Caveat**: This operation returns the previous value. To compute the
2165 /// stored value without losing provenance, you may use [`map_addr`]. For
2166 /// example: `a.fetch_or(val).map_addr(|a| a | val)`.
2167 ///
2168 /// `fetch_or` takes an [`Ordering`] argument which describes the memory
2169 /// ordering of this operation. All ordering modes are possible. Note that
2170 /// using [`Acquire`] makes the store part of this operation [`Relaxed`],
2171 /// and using [`Release`] makes the load part [`Relaxed`].
2172 ///
2173 /// **Note**: This method is only available on platforms that support atomic
2174 /// operations on [`AtomicPtr`].
2175 ///
2176 /// This API and its claimed semantics are part of the Strict Provenance
2177 /// experiment, see the [module documentation for `ptr`][crate::ptr] for
2178 /// details.
2179 ///
2180 /// [`map_addr`]: pointer::map_addr
2181 ///
2182 /// # Examples
2183 ///
2184 /// ```
2185 /// #![feature(strict_provenance_atomic_ptr)]
2186 /// use core::sync::atomic::{AtomicPtr, Ordering};
2187 ///
2188 /// let pointer = &mut 3i64 as *mut i64;
2189 ///
2190 /// let atom = AtomicPtr::<i64>::new(pointer);
2191 /// // Tag the bottom bit of the pointer.
2192 /// assert_eq!(atom.fetch_or(1, Ordering::Relaxed).addr() & 1, 0);
2193 /// // Extract and untag.
2194 /// let tagged = atom.load(Ordering::Relaxed);
2195 /// assert_eq!(tagged.addr() & 1, 1);
2196 /// assert_eq!(tagged.map_addr(|p| p & !1), pointer);
2197 /// ```
2198 #[inline]
2199 #[cfg(target_has_atomic = "ptr")]
2200 #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")]
2201 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2202 pub fn fetch_or(&self, val: usize, order: Ordering) -> *mut T {
2203 // SAFETY: data races are prevented by atomic intrinsics.
2204 unsafe { atomic_or(self.p.get(), core::ptr::without_provenance_mut(val), order).cast() }
2205 }
2206
2207 /// Performs a bitwise "and" operation on the address of the current
2208 /// pointer, and the argument `val`, and stores a pointer with provenance of
2209 /// the current pointer and the resulting address.
2210 ///
2211 /// This is equivalent to using [`map_addr`] to atomically perform
2212 /// `ptr = ptr.map_addr(|a| a & val)`. This can be used in tagged
2213 /// pointer schemes to atomically unset tag bits.
2214 ///
2215 /// **Caveat**: This operation returns the previous value. To compute the
2216 /// stored value without losing provenance, you may use [`map_addr`]. For
2217 /// example: `a.fetch_and(val).map_addr(|a| a & val)`.
2218 ///
2219 /// `fetch_and` takes an [`Ordering`] argument which describes the memory
2220 /// ordering of this operation. All ordering modes are possible. Note that
2221 /// using [`Acquire`] makes the store part of this operation [`Relaxed`],
2222 /// and using [`Release`] makes the load part [`Relaxed`].
2223 ///
2224 /// **Note**: This method is only available on platforms that support atomic
2225 /// operations on [`AtomicPtr`].
2226 ///
2227 /// This API and its claimed semantics are part of the Strict Provenance
2228 /// experiment, see the [module documentation for `ptr`][crate::ptr] for
2229 /// details.
2230 ///
2231 /// [`map_addr`]: pointer::map_addr
2232 ///
2233 /// # Examples
2234 ///
2235 /// ```
2236 /// #![feature(strict_provenance_atomic_ptr)]
2237 /// use core::sync::atomic::{AtomicPtr, Ordering};
2238 ///
2239 /// let pointer = &mut 3i64 as *mut i64;
2240 /// // A tagged pointer
2241 /// let atom = AtomicPtr::<i64>::new(pointer.map_addr(|a| a | 1));
2242 /// assert_eq!(atom.fetch_or(1, Ordering::Relaxed).addr() & 1, 1);
2243 /// // Untag, and extract the previously tagged pointer.
2244 /// let untagged = atom.fetch_and(!1, Ordering::Relaxed)
2245 /// .map_addr(|a| a & !1);
2246 /// assert_eq!(untagged, pointer);
2247 /// ```
2248 #[inline]
2249 #[cfg(target_has_atomic = "ptr")]
2250 #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")]
2251 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2252 pub fn fetch_and(&self, val: usize, order: Ordering) -> *mut T {
2253 // SAFETY: data races are prevented by atomic intrinsics.
2254 unsafe { atomic_and(self.p.get(), core::ptr::without_provenance_mut(val), order).cast() }
2255 }
2256
2257 /// Performs a bitwise "xor" operation on the address of the current
2258 /// pointer, and the argument `val`, and stores a pointer with provenance of
2259 /// the current pointer and the resulting address.
2260 ///
2261 /// This is equivalent to using [`map_addr`] to atomically perform
2262 /// `ptr = ptr.map_addr(|a| a ^ val)`. This can be used in tagged
2263 /// pointer schemes to atomically toggle tag bits.
2264 ///
2265 /// **Caveat**: This operation returns the previous value. To compute the
2266 /// stored value without losing provenance, you may use [`map_addr`]. For
2267 /// example: `a.fetch_xor(val).map_addr(|a| a ^ val)`.
2268 ///
2269 /// `fetch_xor` takes an [`Ordering`] argument which describes the memory
2270 /// ordering of this operation. All ordering modes are possible. Note that
2271 /// using [`Acquire`] makes the store part of this operation [`Relaxed`],
2272 /// and using [`Release`] makes the load part [`Relaxed`].
2273 ///
2274 /// **Note**: This method is only available on platforms that support atomic
2275 /// operations on [`AtomicPtr`].
2276 ///
2277 /// This API and its claimed semantics are part of the Strict Provenance
2278 /// experiment, see the [module documentation for `ptr`][crate::ptr] for
2279 /// details.
2280 ///
2281 /// [`map_addr`]: pointer::map_addr
2282 ///
2283 /// # Examples
2284 ///
2285 /// ```
2286 /// #![feature(strict_provenance_atomic_ptr)]
2287 /// use core::sync::atomic::{AtomicPtr, Ordering};
2288 ///
2289 /// let pointer = &mut 3i64 as *mut i64;
2290 /// let atom = AtomicPtr::<i64>::new(pointer);
2291 ///
2292 /// // Toggle a tag bit on the pointer.
2293 /// atom.fetch_xor(1, Ordering::Relaxed);
2294 /// assert_eq!(atom.load(Ordering::Relaxed).addr() & 1, 1);
2295 /// ```
2296 #[inline]
2297 #[cfg(target_has_atomic = "ptr")]
2298 #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")]
2299 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2300 pub fn fetch_xor(&self, val: usize, order: Ordering) -> *mut T {
2301 // SAFETY: data races are prevented by atomic intrinsics.
2302 unsafe { atomic_xor(self.p.get(), core::ptr::without_provenance_mut(val), order).cast() }
2303 }
2304
2305 /// Returns a mutable pointer to the underlying pointer.
2306 ///
2307 /// Doing non-atomic reads and writes on the resulting pointer can be a data race.
2308 /// This method is mostly useful for FFI, where the function signature may use
2309 /// `*mut *mut T` instead of `&AtomicPtr<T>`.
2310 ///
2311 /// Returning an `*mut` pointer from a shared reference to this atomic is safe because the
2312 /// atomic types work with interior mutability. All modifications of an atomic change the value
2313 /// through a shared reference, and can do so safely as long as they use atomic operations. Any
2314 /// use of the returned raw pointer requires an `unsafe` block and still has to uphold the same
2315 /// restriction: operations on it must be atomic.
2316 ///
2317 /// # Examples
2318 ///
2319 /// ```ignore (extern-declaration)
2320 /// use std::sync::atomic::AtomicPtr;
2321 ///
2322 /// extern "C" {
2323 /// fn my_atomic_op(arg: *mut *mut u32);
2324 /// }
2325 ///
2326 /// let mut value = 17;
2327 /// let atomic = AtomicPtr::new(&mut value);
2328 ///
2329 /// // SAFETY: Safe as long as `my_atomic_op` is atomic.
2330 /// unsafe {
2331 /// my_atomic_op(atomic.as_ptr());
2332 /// }
2333 /// ```
2334 #[inline]
2335 #[stable(feature = "atomic_as_ptr", since = "1.70.0")]
2336 #[rustc_const_stable(feature = "atomic_as_ptr", since = "1.70.0")]
2337 #[rustc_never_returns_null_ptr]
2338 pub const fn as_ptr(&self) -> *mut *mut T {
2339 self.p.get()
2340 }
2341}
2342
2343#[cfg(target_has_atomic_load_store = "8")]
2344#[stable(feature = "atomic_bool_from", since = "1.24.0")]
2345impl From<bool> for AtomicBool {
2346 /// Converts a `bool` into an `AtomicBool`.
2347 ///
2348 /// # Examples
2349 ///
2350 /// ```
2351 /// use std::sync::atomic::AtomicBool;
2352 /// let atomic_bool = AtomicBool::from(true);
2353 /// assert_eq!(format!("{atomic_bool:?}"), "true")
2354 /// ```
2355 #[inline]
2356 fn from(b: bool) -> Self {
2357 Self::new(b)
2358 }
2359}
2360
2361#[cfg(target_has_atomic_load_store = "ptr")]
2362#[stable(feature = "atomic_from", since = "1.23.0")]
2363impl<T> From<*mut T> for AtomicPtr<T> {
2364 /// Converts a `*mut T` into an `AtomicPtr<T>`.
2365 #[inline]
2366 fn from(p: *mut T) -> Self {
2367 Self::new(p)
2368 }
2369}
2370
2371#[allow(unused_macros)] // This macro ends up being unused on some architectures.
2372macro_rules! if_8_bit {
2373 (u8, $( yes = [$($yes:tt)*], )? $( no = [$($no:tt)*], )? ) => { concat!("", $($($yes)*)?) };
2374 (i8, $( yes = [$($yes:tt)*], )? $( no = [$($no:tt)*], )? ) => { concat!("", $($($yes)*)?) };
2375 ($_:ident, $( yes = [$($yes:tt)*], )? $( no = [$($no:tt)*], )? ) => { concat!("", $($($no)*)?) };
2376}
2377
2378#[cfg(target_has_atomic_load_store)]
2379macro_rules! atomic_int {
2380 ($cfg_cas:meta,
2381 $cfg_align:meta,
2382 $stable:meta,
2383 $stable_cxchg:meta,
2384 $stable_debug:meta,
2385 $stable_access:meta,
2386 $stable_from:meta,
2387 $stable_nand:meta,
2388 $const_stable_new:meta,
2389 $const_stable_into_inner:meta,
2390 $diagnostic_item:meta,
2391 $s_int_type:literal,
2392 $extra_feature:expr,
2393 $min_fn:ident, $max_fn:ident,
2394 $align:expr,
2395 $int_type:ident $atomic_type:ident) => {
2396 /// An integer type which can be safely shared between threads.
2397 ///
2398 /// This type has the same
2399 #[doc = if_8_bit!(
2400 $int_type,
2401 yes = ["size, alignment, and bit validity"],
2402 no = ["size and bit validity"],
2403 )]
2404 /// as the underlying integer type, [`
2405 #[doc = $s_int_type]
2406 /// `].
2407 #[doc = if_8_bit! {
2408 $int_type,
2409 no = [
2410 "However, the alignment of this type is always equal to its ",
2411 "size, even on targets where [`", $s_int_type, "`] has a ",
2412 "lesser alignment."
2413 ],
2414 }]
2415 ///
2416 /// For more about the differences between atomic types and
2417 /// non-atomic types as well as information about the portability of
2418 /// this type, please see the [module-level documentation].
2419 ///
2420 /// **Note:** This type is only available on platforms that support
2421 /// atomic loads and stores of [`
2422 #[doc = $s_int_type]
2423 /// `].
2424 ///
2425 /// [module-level documentation]: crate::sync::atomic
2426 #[$stable]
2427 #[$diagnostic_item]
2428 #[repr(C, align($align))]
2429 pub struct $atomic_type {
2430 v: UnsafeCell<$int_type>,
2431 }
2432
2433 #[$stable]
2434 impl Default for $atomic_type {
2435 #[inline]
2436 fn default() -> Self {
2437 Self::new(Default::default())
2438 }
2439 }
2440
2441 #[$stable_from]
2442 impl From<$int_type> for $atomic_type {
2443 #[doc = concat!("Converts an `", stringify!($int_type), "` into an `", stringify!($atomic_type), "`.")]
2444 #[inline]
2445 fn from(v: $int_type) -> Self { Self::new(v) }
2446 }
2447
2448 #[$stable_debug]
2449 impl fmt::Debug for $atomic_type {
2450 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2451 fmt::Debug::fmt(&self.load(Ordering::Relaxed), f)
2452 }
2453 }
2454
2455 // Send is implicitly implemented.
2456 #[$stable]
2457 unsafe impl Sync for $atomic_type {}
2458
2459 impl $atomic_type {
2460 /// Creates a new atomic integer.
2461 ///
2462 /// # Examples
2463 ///
2464 /// ```
2465 #[doc = concat!($extra_feature, "use std::sync::atomic::", stringify!($atomic_type), ";")]
2466 ///
2467 #[doc = concat!("let atomic_forty_two = ", stringify!($atomic_type), "::new(42);")]
2468 /// ```
2469 #[inline]
2470 #[$stable]
2471 #[$const_stable_new]
2472 #[must_use]
2473 pub const fn new(v: $int_type) -> Self {
2474 Self {v: UnsafeCell::new(v)}
2475 }
2476
2477 /// Creates a new reference to an atomic integer from a pointer.
2478 ///
2479 /// # Examples
2480 ///
2481 /// ```
2482 #[doc = concat!($extra_feature, "use std::sync::atomic::{self, ", stringify!($atomic_type), "};")]
2483 ///
2484 /// // Get a pointer to an allocated value
2485 #[doc = concat!("let ptr: *mut ", stringify!($int_type), " = Box::into_raw(Box::new(0));")]
2486 ///
2487 #[doc = concat!("assert!(ptr.cast::<", stringify!($atomic_type), ">().is_aligned());")]
2488 ///
2489 /// {
2490 /// // Create an atomic view of the allocated value
2491 // SAFETY: this is a doc comment, tidy, it can't hurt you (also guaranteed by the construction of `ptr` and the assert above)
2492 #[doc = concat!(" let atomic = unsafe {", stringify!($atomic_type), "::from_ptr(ptr) };")]
2493 ///
2494 /// // Use `atomic` for atomic operations, possibly share it with other threads
2495 /// atomic.store(1, atomic::Ordering::Relaxed);
2496 /// }
2497 ///
2498 /// // It's ok to non-atomically access the value behind `ptr`,
2499 /// // since the reference to the atomic ended its lifetime in the block above
2500 /// assert_eq!(unsafe { *ptr }, 1);
2501 ///
2502 /// // Deallocate the value
2503 /// unsafe { drop(Box::from_raw(ptr)) }
2504 /// ```
2505 ///
2506 /// # Safety
2507 ///
2508 /// * `ptr` must be aligned to
2509 #[doc = concat!(" `align_of::<", stringify!($atomic_type), ">()`")]
2510 #[doc = if_8_bit!{
2511 $int_type,
2512 yes = [
2513 " (note that this is always true, since `align_of::<",
2514 stringify!($atomic_type), ">() == 1`)."
2515 ],
2516 no = [
2517 " (note that on some platforms this can be bigger than `align_of::<",
2518 stringify!($int_type), ">()`)."
2519 ],
2520 }]
2521 /// * `ptr` must be [valid] for both reads and writes for the whole lifetime `'a`.
2522 /// * You must adhere to the [Memory model for atomic accesses]. In particular, it is not
2523 /// allowed to mix atomic and non-atomic accesses, or atomic accesses of different sizes,
2524 /// without synchronization.
2525 ///
2526 /// [valid]: crate::ptr#safety
2527 /// [Memory model for atomic accesses]: self#memory-model-for-atomic-accesses
2528 #[stable(feature = "atomic_from_ptr", since = "1.75.0")]
2529 #[rustc_const_stable(feature = "const_atomic_from_ptr", since = "1.84.0")]
2530 pub const unsafe fn from_ptr<'a>(ptr: *mut $int_type) -> &'a $atomic_type {
2531 // SAFETY: guaranteed by the caller
2532 unsafe { &*ptr.cast() }
2533 }
2534
2535
2536 /// Returns a mutable reference to the underlying integer.
2537 ///
2538 /// This is safe because the mutable reference guarantees that no other threads are
2539 /// concurrently accessing the atomic data.
2540 ///
2541 /// # Examples
2542 ///
2543 /// ```
2544 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
2545 ///
2546 #[doc = concat!("let mut some_var = ", stringify!($atomic_type), "::new(10);")]
2547 /// assert_eq!(*some_var.get_mut(), 10);
2548 /// *some_var.get_mut() = 5;
2549 /// assert_eq!(some_var.load(Ordering::SeqCst), 5);
2550 /// ```
2551 #[inline]
2552 #[$stable_access]
2553 pub fn get_mut(&mut self) -> &mut $int_type {
2554 self.v.get_mut()
2555 }
2556
2557 #[doc = concat!("Get atomic access to a `&mut ", stringify!($int_type), "`.")]
2558 ///
2559 #[doc = if_8_bit! {
2560 $int_type,
2561 no = [
2562 "**Note:** This function is only available on targets where `",
2563 stringify!($atomic_type), "` has the same alignment as `", stringify!($int_type), "`."
2564 ],
2565 }]
2566 ///
2567 /// # Examples
2568 ///
2569 /// ```
2570 /// #![feature(atomic_from_mut)]
2571 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
2572 ///
2573 /// let mut some_int = 123;
2574 #[doc = concat!("let a = ", stringify!($atomic_type), "::from_mut(&mut some_int);")]
2575 /// a.store(100, Ordering::Relaxed);
2576 /// assert_eq!(some_int, 100);
2577 /// ```
2578 ///
2579 #[inline]
2580 #[$cfg_align]
2581 #[unstable(feature = "atomic_from_mut", issue = "76314")]
2582 pub fn from_mut(v: &mut $int_type) -> &mut Self {
2583 let [] = [(); align_of::<Self>() - align_of::<$int_type>()];
2584 // SAFETY:
2585 // - the mutable reference guarantees unique ownership.
2586 // - the alignment of `$int_type` and `Self` is the
2587 // same, as promised by $cfg_align and verified above.
2588 unsafe { &mut *(v as *mut $int_type as *mut Self) }
2589 }
2590
2591 #[doc = concat!("Get non-atomic access to a `&mut [", stringify!($atomic_type), "]` slice")]
2592 ///
2593 /// This is safe because the mutable reference guarantees that no other threads are
2594 /// concurrently accessing the atomic data.
2595 ///
2596 /// # Examples
2597 ///
2598 /// ```
2599 /// #![feature(atomic_from_mut)]
2600 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
2601 ///
2602 #[doc = concat!("let mut some_ints = [const { ", stringify!($atomic_type), "::new(0) }; 10];")]
2603 ///
2604 #[doc = concat!("let view: &mut [", stringify!($int_type), "] = ", stringify!($atomic_type), "::get_mut_slice(&mut some_ints);")]
2605 /// assert_eq!(view, [0; 10]);
2606 /// view
2607 /// .iter_mut()
2608 /// .enumerate()
2609 /// .for_each(|(idx, int)| *int = idx as _);
2610 ///
2611 /// std::thread::scope(|s| {
2612 /// some_ints
2613 /// .iter()
2614 /// .enumerate()
2615 /// .for_each(|(idx, int)| {
2616 /// s.spawn(move || assert_eq!(int.load(Ordering::Relaxed), idx as _));
2617 /// })
2618 /// });
2619 /// ```
2620 #[inline]
2621 #[unstable(feature = "atomic_from_mut", issue = "76314")]
2622 pub fn get_mut_slice(this: &mut [Self]) -> &mut [$int_type] {
2623 // SAFETY: the mutable reference guarantees unique ownership.
2624 unsafe { &mut *(this as *mut [Self] as *mut [$int_type]) }
2625 }
2626
2627 #[doc = concat!("Get atomic access to a `&mut [", stringify!($int_type), "]` slice.")]
2628 ///
2629 /// # Examples
2630 ///
2631 /// ```
2632 /// #![feature(atomic_from_mut)]
2633 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
2634 ///
2635 /// let mut some_ints = [0; 10];
2636 #[doc = concat!("let a = &*", stringify!($atomic_type), "::from_mut_slice(&mut some_ints);")]
2637 /// std::thread::scope(|s| {
2638 /// for i in 0..a.len() {
2639 /// s.spawn(move || a[i].store(i as _, Ordering::Relaxed));
2640 /// }
2641 /// });
2642 /// for (i, n) in some_ints.into_iter().enumerate() {
2643 /// assert_eq!(i, n as usize);
2644 /// }
2645 /// ```
2646 #[inline]
2647 #[$cfg_align]
2648 #[unstable(feature = "atomic_from_mut", issue = "76314")]
2649 pub fn from_mut_slice(v: &mut [$int_type]) -> &mut [Self] {
2650 let [] = [(); align_of::<Self>() - align_of::<$int_type>()];
2651 // SAFETY:
2652 // - the mutable reference guarantees unique ownership.
2653 // - the alignment of `$int_type` and `Self` is the
2654 // same, as promised by $cfg_align and verified above.
2655 unsafe { &mut *(v as *mut [$int_type] as *mut [Self]) }
2656 }
2657
2658 /// Consumes the atomic and returns the contained value.
2659 ///
2660 /// This is safe because passing `self` by value guarantees that no other threads are
2661 /// concurrently accessing the atomic data.
2662 ///
2663 /// # Examples
2664 ///
2665 /// ```
2666 #[doc = concat!($extra_feature, "use std::sync::atomic::", stringify!($atomic_type), ";")]
2667 ///
2668 #[doc = concat!("let some_var = ", stringify!($atomic_type), "::new(5);")]
2669 /// assert_eq!(some_var.into_inner(), 5);
2670 /// ```
2671 #[inline]
2672 #[$stable_access]
2673 #[$const_stable_into_inner]
2674 pub const fn into_inner(self) -> $int_type {
2675 self.v.into_inner()
2676 }
2677
2678 /// Loads a value from the atomic integer.
2679 ///
2680 /// `load` takes an [`Ordering`] argument which describes the memory ordering of this operation.
2681 /// Possible values are [`SeqCst`], [`Acquire`] and [`Relaxed`].
2682 ///
2683 /// # Panics
2684 ///
2685 /// Panics if `order` is [`Release`] or [`AcqRel`].
2686 ///
2687 /// # Examples
2688 ///
2689 /// ```
2690 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
2691 ///
2692 #[doc = concat!("let some_var = ", stringify!($atomic_type), "::new(5);")]
2693 ///
2694 /// assert_eq!(some_var.load(Ordering::Relaxed), 5);
2695 /// ```
2696 #[inline]
2697 #[$stable]
2698 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2699 pub fn load(&self, order: Ordering) -> $int_type {
2700 // SAFETY: data races are prevented by atomic intrinsics.
2701 unsafe { atomic_load(self.v.get(), order) }
2702 }
2703
2704 /// Stores a value into the atomic integer.
2705 ///
2706 /// `store` takes an [`Ordering`] argument which describes the memory ordering of this operation.
2707 /// Possible values are [`SeqCst`], [`Release`] and [`Relaxed`].
2708 ///
2709 /// # Panics
2710 ///
2711 /// Panics if `order` is [`Acquire`] or [`AcqRel`].
2712 ///
2713 /// # Examples
2714 ///
2715 /// ```
2716 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
2717 ///
2718 #[doc = concat!("let some_var = ", stringify!($atomic_type), "::new(5);")]
2719 ///
2720 /// some_var.store(10, Ordering::Relaxed);
2721 /// assert_eq!(some_var.load(Ordering::Relaxed), 10);
2722 /// ```
2723 #[inline]
2724 #[$stable]
2725 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2726 pub fn store(&self, val: $int_type, order: Ordering) {
2727 // SAFETY: data races are prevented by atomic intrinsics.
2728 unsafe { atomic_store(self.v.get(), val, order); }
2729 }
2730
2731 /// Stores a value into the atomic integer, returning the previous value.
2732 ///
2733 /// `swap` takes an [`Ordering`] argument which describes the memory ordering
2734 /// of this operation. All ordering modes are possible. Note that using
2735 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
2736 /// using [`Release`] makes the load part [`Relaxed`].
2737 ///
2738 /// **Note**: This method is only available on platforms that support atomic operations on
2739 #[doc = concat!("[`", $s_int_type, "`].")]
2740 ///
2741 /// # Examples
2742 ///
2743 /// ```
2744 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
2745 ///
2746 #[doc = concat!("let some_var = ", stringify!($atomic_type), "::new(5);")]
2747 ///
2748 /// assert_eq!(some_var.swap(10, Ordering::Relaxed), 5);
2749 /// ```
2750 #[inline]
2751 #[$stable]
2752 #[$cfg_cas]
2753 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2754 pub fn swap(&self, val: $int_type, order: Ordering) -> $int_type {
2755 // SAFETY: data races are prevented by atomic intrinsics.
2756 unsafe { atomic_swap(self.v.get(), val, order) }
2757 }
2758
2759 /// Stores a value into the atomic integer if the current value is the same as
2760 /// the `current` value.
2761 ///
2762 /// The return value is always the previous value. If it is equal to `current`, then the
2763 /// value was updated.
2764 ///
2765 /// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory
2766 /// ordering of this operation. Notice that even when using [`AcqRel`], the operation
2767 /// might fail and hence just perform an `Acquire` load, but not have `Release` semantics.
2768 /// Using [`Acquire`] makes the store part of this operation [`Relaxed`] if it
2769 /// happens, and using [`Release`] makes the load part [`Relaxed`].
2770 ///
2771 /// **Note**: This method is only available on platforms that support atomic operations on
2772 #[doc = concat!("[`", $s_int_type, "`].")]
2773 ///
2774 /// # Migrating to `compare_exchange` and `compare_exchange_weak`
2775 ///
2776 /// `compare_and_swap` is equivalent to `compare_exchange` with the following mapping for
2777 /// memory orderings:
2778 ///
2779 /// Original | Success | Failure
2780 /// -------- | ------- | -------
2781 /// Relaxed | Relaxed | Relaxed
2782 /// Acquire | Acquire | Acquire
2783 /// Release | Release | Relaxed
2784 /// AcqRel | AcqRel | Acquire
2785 /// SeqCst | SeqCst | SeqCst
2786 ///
2787 /// `compare_and_swap` and `compare_exchange` also differ in their return type. You can use
2788 /// `compare_exchange(...).unwrap_or_else(|x| x)` to recover the behavior of `compare_and_swap`,
2789 /// but in most cases it is more idiomatic to check whether the return value is `Ok` or `Err`
2790 /// rather than to infer success vs failure based on the value that was read.
2791 ///
2792 /// During migration, consider whether it makes sense to use `compare_exchange_weak` instead.
2793 /// `compare_exchange_weak` is allowed to fail spuriously even when the comparison succeeds,
2794 /// which allows the compiler to generate better assembly code when the compare and swap
2795 /// is used in a loop.
2796 ///
2797 /// # Examples
2798 ///
2799 /// ```
2800 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
2801 ///
2802 #[doc = concat!("let some_var = ", stringify!($atomic_type), "::new(5);")]
2803 ///
2804 /// assert_eq!(some_var.compare_and_swap(5, 10, Ordering::Relaxed), 5);
2805 /// assert_eq!(some_var.load(Ordering::Relaxed), 10);
2806 ///
2807 /// assert_eq!(some_var.compare_and_swap(6, 12, Ordering::Relaxed), 10);
2808 /// assert_eq!(some_var.load(Ordering::Relaxed), 10);
2809 /// ```
2810 #[inline]
2811 #[$stable]
2812 #[deprecated(
2813 since = "1.50.0",
2814 note = "Use `compare_exchange` or `compare_exchange_weak` instead")
2815 ]
2816 #[$cfg_cas]
2817 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2818 pub fn compare_and_swap(&self,
2819 current: $int_type,
2820 new: $int_type,
2821 order: Ordering) -> $int_type {
2822 match self.compare_exchange(current,
2823 new,
2824 order,
2825 strongest_failure_ordering(order)) {
2826 Ok(x) => x,
2827 Err(x) => x,
2828 }
2829 }
2830
2831 /// Stores a value into the atomic integer if the current value is the same as
2832 /// the `current` value.
2833 ///
2834 /// The return value is a result indicating whether the new value was written and
2835 /// containing the previous value. On success this value is guaranteed to be equal to
2836 /// `current`.
2837 ///
2838 /// `compare_exchange` takes two [`Ordering`] arguments to describe the memory
2839 /// ordering of this operation. `success` describes the required ordering for the
2840 /// read-modify-write operation that takes place if the comparison with `current` succeeds.
2841 /// `failure` describes the required ordering for the load operation that takes place when
2842 /// the comparison fails. Using [`Acquire`] as success ordering makes the store part
2843 /// of this operation [`Relaxed`], and using [`Release`] makes the successful load
2844 /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`].
2845 ///
2846 /// **Note**: This method is only available on platforms that support atomic operations on
2847 #[doc = concat!("[`", $s_int_type, "`].")]
2848 ///
2849 /// # Examples
2850 ///
2851 /// ```
2852 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
2853 ///
2854 #[doc = concat!("let some_var = ", stringify!($atomic_type), "::new(5);")]
2855 ///
2856 /// assert_eq!(some_var.compare_exchange(5, 10,
2857 /// Ordering::Acquire,
2858 /// Ordering::Relaxed),
2859 /// Ok(5));
2860 /// assert_eq!(some_var.load(Ordering::Relaxed), 10);
2861 ///
2862 /// assert_eq!(some_var.compare_exchange(6, 12,
2863 /// Ordering::SeqCst,
2864 /// Ordering::Acquire),
2865 /// Err(10));
2866 /// assert_eq!(some_var.load(Ordering::Relaxed), 10);
2867 /// ```
2868 #[inline]
2869 #[$stable_cxchg]
2870 #[$cfg_cas]
2871 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2872 pub fn compare_exchange(&self,
2873 current: $int_type,
2874 new: $int_type,
2875 success: Ordering,
2876 failure: Ordering) -> Result<$int_type, $int_type> {
2877 // SAFETY: data races are prevented by atomic intrinsics.
2878 unsafe { atomic_compare_exchange(self.v.get(), current, new, success, failure) }
2879 }
2880
2881 /// Stores a value into the atomic integer if the current value is the same as
2882 /// the `current` value.
2883 ///
2884 #[doc = concat!("Unlike [`", stringify!($atomic_type), "::compare_exchange`],")]
2885 /// this function is allowed to spuriously fail even
2886 /// when the comparison succeeds, which can result in more efficient code on some
2887 /// platforms. The return value is a result indicating whether the new value was
2888 /// written and containing the previous value.
2889 ///
2890 /// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory
2891 /// ordering of this operation. `success` describes the required ordering for the
2892 /// read-modify-write operation that takes place if the comparison with `current` succeeds.
2893 /// `failure` describes the required ordering for the load operation that takes place when
2894 /// the comparison fails. Using [`Acquire`] as success ordering makes the store part
2895 /// of this operation [`Relaxed`], and using [`Release`] makes the successful load
2896 /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`].
2897 ///
2898 /// **Note**: This method is only available on platforms that support atomic operations on
2899 #[doc = concat!("[`", $s_int_type, "`].")]
2900 ///
2901 /// # Examples
2902 ///
2903 /// ```
2904 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
2905 ///
2906 #[doc = concat!("let val = ", stringify!($atomic_type), "::new(4);")]
2907 ///
2908 /// let mut old = val.load(Ordering::Relaxed);
2909 /// loop {
2910 /// let new = old * 2;
2911 /// match val.compare_exchange_weak(old, new, Ordering::SeqCst, Ordering::Relaxed) {
2912 /// Ok(_) => break,
2913 /// Err(x) => old = x,
2914 /// }
2915 /// }
2916 /// ```
2917 #[inline]
2918 #[$stable_cxchg]
2919 #[$cfg_cas]
2920 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2921 pub fn compare_exchange_weak(&self,
2922 current: $int_type,
2923 new: $int_type,
2924 success: Ordering,
2925 failure: Ordering) -> Result<$int_type, $int_type> {
2926 // SAFETY: data races are prevented by atomic intrinsics.
2927 unsafe {
2928 atomic_compare_exchange_weak(self.v.get(), current, new, success, failure)
2929 }
2930 }
2931
2932 /// Adds to the current value, returning the previous value.
2933 ///
2934 /// This operation wraps around on overflow.
2935 ///
2936 /// `fetch_add` takes an [`Ordering`] argument which describes the memory ordering
2937 /// of this operation. All ordering modes are possible. Note that using
2938 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
2939 /// using [`Release`] makes the load part [`Relaxed`].
2940 ///
2941 /// **Note**: This method is only available on platforms that support atomic operations on
2942 #[doc = concat!("[`", $s_int_type, "`].")]
2943 ///
2944 /// # Examples
2945 ///
2946 /// ```
2947 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
2948 ///
2949 #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(0);")]
2950 /// assert_eq!(foo.fetch_add(10, Ordering::SeqCst), 0);
2951 /// assert_eq!(foo.load(Ordering::SeqCst), 10);
2952 /// ```
2953 #[inline]
2954 #[$stable]
2955 #[$cfg_cas]
2956 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2957 pub fn fetch_add(&self, val: $int_type, order: Ordering) -> $int_type {
2958 // SAFETY: data races are prevented by atomic intrinsics.
2959 unsafe { atomic_add(self.v.get(), val, order) }
2960 }
2961
2962 /// Subtracts from the current value, returning the previous value.
2963 ///
2964 /// This operation wraps around on overflow.
2965 ///
2966 /// `fetch_sub` takes an [`Ordering`] argument which describes the memory ordering
2967 /// of this operation. All ordering modes are possible. Note that using
2968 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
2969 /// using [`Release`] makes the load part [`Relaxed`].
2970 ///
2971 /// **Note**: This method is only available on platforms that support atomic operations on
2972 #[doc = concat!("[`", $s_int_type, "`].")]
2973 ///
2974 /// # Examples
2975 ///
2976 /// ```
2977 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
2978 ///
2979 #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(20);")]
2980 /// assert_eq!(foo.fetch_sub(10, Ordering::SeqCst), 20);
2981 /// assert_eq!(foo.load(Ordering::SeqCst), 10);
2982 /// ```
2983 #[inline]
2984 #[$stable]
2985 #[$cfg_cas]
2986 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
2987 pub fn fetch_sub(&self, val: $int_type, order: Ordering) -> $int_type {
2988 // SAFETY: data races are prevented by atomic intrinsics.
2989 unsafe { atomic_sub(self.v.get(), val, order) }
2990 }
2991
2992 /// Bitwise "and" with the current value.
2993 ///
2994 /// Performs a bitwise "and" operation on the current value and the argument `val`, and
2995 /// sets the new value to the result.
2996 ///
2997 /// Returns the previous value.
2998 ///
2999 /// `fetch_and` takes an [`Ordering`] argument which describes the memory ordering
3000 /// of this operation. All ordering modes are possible. Note that using
3001 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
3002 /// using [`Release`] makes the load part [`Relaxed`].
3003 ///
3004 /// **Note**: This method is only available on platforms that support atomic operations on
3005 #[doc = concat!("[`", $s_int_type, "`].")]
3006 ///
3007 /// # Examples
3008 ///
3009 /// ```
3010 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
3011 ///
3012 #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(0b101101);")]
3013 /// assert_eq!(foo.fetch_and(0b110011, Ordering::SeqCst), 0b101101);
3014 /// assert_eq!(foo.load(Ordering::SeqCst), 0b100001);
3015 /// ```
3016 #[inline]
3017 #[$stable]
3018 #[$cfg_cas]
3019 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3020 pub fn fetch_and(&self, val: $int_type, order: Ordering) -> $int_type {
3021 // SAFETY: data races are prevented by atomic intrinsics.
3022 unsafe { atomic_and(self.v.get(), val, order) }
3023 }
3024
3025 /// Bitwise "nand" with the current value.
3026 ///
3027 /// Performs a bitwise "nand" operation on the current value and the argument `val`, and
3028 /// sets the new value to the result.
3029 ///
3030 /// Returns the previous value.
3031 ///
3032 /// `fetch_nand` takes an [`Ordering`] argument which describes the memory ordering
3033 /// of this operation. All ordering modes are possible. Note that using
3034 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
3035 /// using [`Release`] makes the load part [`Relaxed`].
3036 ///
3037 /// **Note**: This method is only available on platforms that support atomic operations on
3038 #[doc = concat!("[`", $s_int_type, "`].")]
3039 ///
3040 /// # Examples
3041 ///
3042 /// ```
3043 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
3044 ///
3045 #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(0x13);")]
3046 /// assert_eq!(foo.fetch_nand(0x31, Ordering::SeqCst), 0x13);
3047 /// assert_eq!(foo.load(Ordering::SeqCst), !(0x13 & 0x31));
3048 /// ```
3049 #[inline]
3050 #[$stable_nand]
3051 #[$cfg_cas]
3052 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3053 pub fn fetch_nand(&self, val: $int_type, order: Ordering) -> $int_type {
3054 // SAFETY: data races are prevented by atomic intrinsics.
3055 unsafe { atomic_nand(self.v.get(), val, order) }
3056 }
3057
3058 /// Bitwise "or" with the current value.
3059 ///
3060 /// Performs a bitwise "or" operation on the current value and the argument `val`, and
3061 /// sets the new value to the result.
3062 ///
3063 /// Returns the previous value.
3064 ///
3065 /// `fetch_or` takes an [`Ordering`] argument which describes the memory ordering
3066 /// of this operation. All ordering modes are possible. Note that using
3067 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
3068 /// using [`Release`] makes the load part [`Relaxed`].
3069 ///
3070 /// **Note**: This method is only available on platforms that support atomic operations on
3071 #[doc = concat!("[`", $s_int_type, "`].")]
3072 ///
3073 /// # Examples
3074 ///
3075 /// ```
3076 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
3077 ///
3078 #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(0b101101);")]
3079 /// assert_eq!(foo.fetch_or(0b110011, Ordering::SeqCst), 0b101101);
3080 /// assert_eq!(foo.load(Ordering::SeqCst), 0b111111);
3081 /// ```
3082 #[inline]
3083 #[$stable]
3084 #[$cfg_cas]
3085 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3086 pub fn fetch_or(&self, val: $int_type, order: Ordering) -> $int_type {
3087 // SAFETY: data races are prevented by atomic intrinsics.
3088 unsafe { atomic_or(self.v.get(), val, order) }
3089 }
3090
3091 /// Bitwise "xor" with the current value.
3092 ///
3093 /// Performs a bitwise "xor" operation on the current value and the argument `val`, and
3094 /// sets the new value to the result.
3095 ///
3096 /// Returns the previous value.
3097 ///
3098 /// `fetch_xor` takes an [`Ordering`] argument which describes the memory ordering
3099 /// of this operation. All ordering modes are possible. Note that using
3100 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
3101 /// using [`Release`] makes the load part [`Relaxed`].
3102 ///
3103 /// **Note**: This method is only available on platforms that support atomic operations on
3104 #[doc = concat!("[`", $s_int_type, "`].")]
3105 ///
3106 /// # Examples
3107 ///
3108 /// ```
3109 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
3110 ///
3111 #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(0b101101);")]
3112 /// assert_eq!(foo.fetch_xor(0b110011, Ordering::SeqCst), 0b101101);
3113 /// assert_eq!(foo.load(Ordering::SeqCst), 0b011110);
3114 /// ```
3115 #[inline]
3116 #[$stable]
3117 #[$cfg_cas]
3118 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3119 pub fn fetch_xor(&self, val: $int_type, order: Ordering) -> $int_type {
3120 // SAFETY: data races are prevented by atomic intrinsics.
3121 unsafe { atomic_xor(self.v.get(), val, order) }
3122 }
3123
3124 /// Fetches the value, and applies a function to it that returns an optional
3125 /// new value. Returns a `Result` of `Ok(previous_value)` if the function returned `Some(_)`, else
3126 /// `Err(previous_value)`.
3127 ///
3128 /// Note: This may call the function multiple times if the value has been changed from other threads in
3129 /// the meantime, as long as the function returns `Some(_)`, but the function will have been applied
3130 /// only once to the stored value.
3131 ///
3132 /// `fetch_update` takes two [`Ordering`] arguments to describe the memory ordering of this operation.
3133 /// The first describes the required ordering for when the operation finally succeeds while the second
3134 /// describes the required ordering for loads. These correspond to the success and failure orderings of
3135 #[doc = concat!("[`", stringify!($atomic_type), "::compare_exchange`]")]
3136 /// respectively.
3137 ///
3138 /// Using [`Acquire`] as success ordering makes the store part
3139 /// of this operation [`Relaxed`], and using [`Release`] makes the final successful load
3140 /// [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`].
3141 ///
3142 /// **Note**: This method is only available on platforms that support atomic operations on
3143 #[doc = concat!("[`", $s_int_type, "`].")]
3144 ///
3145 /// # Considerations
3146 ///
3147 /// This method is not magic; it is not provided by the hardware.
3148 /// It is implemented in terms of
3149 #[doc = concat!("[`", stringify!($atomic_type), "::compare_exchange_weak`],")]
3150 /// and suffers from the same drawbacks.
3151 /// In particular, this method will not circumvent the [ABA Problem].
3152 ///
3153 /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
3154 ///
3155 /// # Examples
3156 ///
3157 /// ```rust
3158 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
3159 ///
3160 #[doc = concat!("let x = ", stringify!($atomic_type), "::new(7);")]
3161 /// assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |_| None), Err(7));
3162 /// assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(x + 1)), Ok(7));
3163 /// assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(x + 1)), Ok(8));
3164 /// assert_eq!(x.load(Ordering::SeqCst), 9);
3165 /// ```
3166 #[inline]
3167 #[stable(feature = "no_more_cas", since = "1.45.0")]
3168 #[$cfg_cas]
3169 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3170 pub fn fetch_update<F>(&self,
3171 set_order: Ordering,
3172 fetch_order: Ordering,
3173 mut f: F) -> Result<$int_type, $int_type>
3174 where F: FnMut($int_type) -> Option<$int_type> {
3175 let mut prev = self.load(fetch_order);
3176 while let Some(next) = f(prev) {
3177 match self.compare_exchange_weak(prev, next, set_order, fetch_order) {
3178 x @ Ok(_) => return x,
3179 Err(next_prev) => prev = next_prev
3180 }
3181 }
3182 Err(prev)
3183 }
3184
3185 /// Fetches the value, and applies a function to it that returns an optional
3186 /// new value. Returns a `Result` of `Ok(previous_value)` if the function returned `Some(_)`, else
3187 /// `Err(previous_value)`.
3188 ///
3189 #[doc = concat!("See also: [`update`](`", stringify!($atomic_type), "::update`).")]
3190 ///
3191 /// Note: This may call the function multiple times if the value has been changed from other threads in
3192 /// the meantime, as long as the function returns `Some(_)`, but the function will have been applied
3193 /// only once to the stored value.
3194 ///
3195 /// `try_update` takes two [`Ordering`] arguments to describe the memory ordering of this operation.
3196 /// The first describes the required ordering for when the operation finally succeeds while the second
3197 /// describes the required ordering for loads. These correspond to the success and failure orderings of
3198 #[doc = concat!("[`", stringify!($atomic_type), "::compare_exchange`]")]
3199 /// respectively.
3200 ///
3201 /// Using [`Acquire`] as success ordering makes the store part
3202 /// of this operation [`Relaxed`], and using [`Release`] makes the final successful load
3203 /// [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`].
3204 ///
3205 /// **Note**: This method is only available on platforms that support atomic operations on
3206 #[doc = concat!("[`", $s_int_type, "`].")]
3207 ///
3208 /// # Considerations
3209 ///
3210 /// This method is not magic; it is not provided by the hardware.
3211 /// It is implemented in terms of
3212 #[doc = concat!("[`", stringify!($atomic_type), "::compare_exchange_weak`],")]
3213 /// and suffers from the same drawbacks.
3214 /// In particular, this method will not circumvent the [ABA Problem].
3215 ///
3216 /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
3217 ///
3218 /// # Examples
3219 ///
3220 /// ```rust
3221 /// #![feature(atomic_try_update)]
3222 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
3223 ///
3224 #[doc = concat!("let x = ", stringify!($atomic_type), "::new(7);")]
3225 /// assert_eq!(x.try_update(Ordering::SeqCst, Ordering::SeqCst, |_| None), Err(7));
3226 /// assert_eq!(x.try_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(x + 1)), Ok(7));
3227 /// assert_eq!(x.try_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(x + 1)), Ok(8));
3228 /// assert_eq!(x.load(Ordering::SeqCst), 9);
3229 /// ```
3230 #[inline]
3231 #[unstable(feature = "atomic_try_update", issue = "135894")]
3232 #[$cfg_cas]
3233 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3234 pub fn try_update(
3235 &self,
3236 set_order: Ordering,
3237 fetch_order: Ordering,
3238 f: impl FnMut($int_type) -> Option<$int_type>,
3239 ) -> Result<$int_type, $int_type> {
3240 // FIXME(atomic_try_update): this is currently an unstable alias to `fetch_update`;
3241 // when stabilizing, turn `fetch_update` into a deprecated alias to `try_update`.
3242 self.fetch_update(set_order, fetch_order, f)
3243 }
3244
3245 /// Fetches the value, applies a function to it that it return a new value.
3246 /// The new value is stored and the old value is returned.
3247 ///
3248 #[doc = concat!("See also: [`try_update`](`", stringify!($atomic_type), "::try_update`).")]
3249 ///
3250 /// Note: This may call the function multiple times if the value has been changed from other threads in
3251 /// the meantime, but the function will have been applied only once to the stored value.
3252 ///
3253 /// `update` takes two [`Ordering`] arguments to describe the memory ordering of this operation.
3254 /// The first describes the required ordering for when the operation finally succeeds while the second
3255 /// describes the required ordering for loads. These correspond to the success and failure orderings of
3256 #[doc = concat!("[`", stringify!($atomic_type), "::compare_exchange`]")]
3257 /// respectively.
3258 ///
3259 /// Using [`Acquire`] as success ordering makes the store part
3260 /// of this operation [`Relaxed`], and using [`Release`] makes the final successful load
3261 /// [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`].
3262 ///
3263 /// **Note**: This method is only available on platforms that support atomic operations on
3264 #[doc = concat!("[`", $s_int_type, "`].")]
3265 ///
3266 /// # Considerations
3267 ///
3268 /// This method is not magic; it is not provided by the hardware.
3269 /// It is implemented in terms of
3270 #[doc = concat!("[`", stringify!($atomic_type), "::compare_exchange_weak`],")]
3271 /// and suffers from the same drawbacks.
3272 /// In particular, this method will not circumvent the [ABA Problem].
3273 ///
3274 /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
3275 ///
3276 /// # Examples
3277 ///
3278 /// ```rust
3279 /// #![feature(atomic_try_update)]
3280 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
3281 ///
3282 #[doc = concat!("let x = ", stringify!($atomic_type), "::new(7);")]
3283 /// assert_eq!(x.update(Ordering::SeqCst, Ordering::SeqCst, |x| x + 1), 7);
3284 /// assert_eq!(x.update(Ordering::SeqCst, Ordering::SeqCst, |x| x + 1), 8);
3285 /// assert_eq!(x.load(Ordering::SeqCst), 9);
3286 /// ```
3287 #[inline]
3288 #[unstable(feature = "atomic_try_update", issue = "135894")]
3289 #[$cfg_cas]
3290 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3291 pub fn update(
3292 &self,
3293 set_order: Ordering,
3294 fetch_order: Ordering,
3295 mut f: impl FnMut($int_type) -> $int_type,
3296 ) -> $int_type {
3297 let mut prev = self.load(fetch_order);
3298 loop {
3299 match self.compare_exchange_weak(prev, f(prev), set_order, fetch_order) {
3300 Ok(x) => break x,
3301 Err(next_prev) => prev = next_prev,
3302 }
3303 }
3304 }
3305
3306 /// Maximum with the current value.
3307 ///
3308 /// Finds the maximum of the current value and the argument `val`, and
3309 /// sets the new value to the result.
3310 ///
3311 /// Returns the previous value.
3312 ///
3313 /// `fetch_max` takes an [`Ordering`] argument which describes the memory ordering
3314 /// of this operation. All ordering modes are possible. Note that using
3315 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
3316 /// using [`Release`] makes the load part [`Relaxed`].
3317 ///
3318 /// **Note**: This method is only available on platforms that support atomic operations on
3319 #[doc = concat!("[`", $s_int_type, "`].")]
3320 ///
3321 /// # Examples
3322 ///
3323 /// ```
3324 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
3325 ///
3326 #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(23);")]
3327 /// assert_eq!(foo.fetch_max(42, Ordering::SeqCst), 23);
3328 /// assert_eq!(foo.load(Ordering::SeqCst), 42);
3329 /// ```
3330 ///
3331 /// If you want to obtain the maximum value in one step, you can use the following:
3332 ///
3333 /// ```
3334 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
3335 ///
3336 #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(23);")]
3337 /// let bar = 42;
3338 /// let max_foo = foo.fetch_max(bar, Ordering::SeqCst).max(bar);
3339 /// assert!(max_foo == 42);
3340 /// ```
3341 #[inline]
3342 #[stable(feature = "atomic_min_max", since = "1.45.0")]
3343 #[$cfg_cas]
3344 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3345 pub fn fetch_max(&self, val: $int_type, order: Ordering) -> $int_type {
3346 // SAFETY: data races are prevented by atomic intrinsics.
3347 unsafe { $max_fn(self.v.get(), val, order) }
3348 }
3349
3350 /// Minimum with the current value.
3351 ///
3352 /// Finds the minimum of the current value and the argument `val`, and
3353 /// sets the new value to the result.
3354 ///
3355 /// Returns the previous value.
3356 ///
3357 /// `fetch_min` takes an [`Ordering`] argument which describes the memory ordering
3358 /// of this operation. All ordering modes are possible. Note that using
3359 /// [`Acquire`] makes the store part of this operation [`Relaxed`], and
3360 /// using [`Release`] makes the load part [`Relaxed`].
3361 ///
3362 /// **Note**: This method is only available on platforms that support atomic operations on
3363 #[doc = concat!("[`", $s_int_type, "`].")]
3364 ///
3365 /// # Examples
3366 ///
3367 /// ```
3368 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
3369 ///
3370 #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(23);")]
3371 /// assert_eq!(foo.fetch_min(42, Ordering::Relaxed), 23);
3372 /// assert_eq!(foo.load(Ordering::Relaxed), 23);
3373 /// assert_eq!(foo.fetch_min(22, Ordering::Relaxed), 23);
3374 /// assert_eq!(foo.load(Ordering::Relaxed), 22);
3375 /// ```
3376 ///
3377 /// If you want to obtain the minimum value in one step, you can use the following:
3378 ///
3379 /// ```
3380 #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")]
3381 ///
3382 #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(23);")]
3383 /// let bar = 12;
3384 /// let min_foo = foo.fetch_min(bar, Ordering::SeqCst).min(bar);
3385 /// assert_eq!(min_foo, 12);
3386 /// ```
3387 #[inline]
3388 #[stable(feature = "atomic_min_max", since = "1.45.0")]
3389 #[$cfg_cas]
3390 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3391 pub fn fetch_min(&self, val: $int_type, order: Ordering) -> $int_type {
3392 // SAFETY: data races are prevented by atomic intrinsics.
3393 unsafe { $min_fn(self.v.get(), val, order) }
3394 }
3395
3396 /// Returns a mutable pointer to the underlying integer.
3397 ///
3398 /// Doing non-atomic reads and writes on the resulting integer can be a data race.
3399 /// This method is mostly useful for FFI, where the function signature may use
3400 #[doc = concat!("`*mut ", stringify!($int_type), "` instead of `&", stringify!($atomic_type), "`.")]
3401 ///
3402 /// Returning an `*mut` pointer from a shared reference to this atomic is safe because the
3403 /// atomic types work with interior mutability. All modifications of an atomic change the value
3404 /// through a shared reference, and can do so safely as long as they use atomic operations. Any
3405 /// use of the returned raw pointer requires an `unsafe` block and still has to uphold the same
3406 /// restriction: operations on it must be atomic.
3407 ///
3408 /// # Examples
3409 ///
3410 /// ```ignore (extern-declaration)
3411 /// # fn main() {
3412 #[doc = concat!($extra_feature, "use std::sync::atomic::", stringify!($atomic_type), ";")]
3413 ///
3414 /// extern "C" {
3415 #[doc = concat!(" fn my_atomic_op(arg: *mut ", stringify!($int_type), ");")]
3416 /// }
3417 ///
3418 #[doc = concat!("let atomic = ", stringify!($atomic_type), "::new(1);")]
3419 ///
3420 /// // SAFETY: Safe as long as `my_atomic_op` is atomic.
3421 /// unsafe {
3422 /// my_atomic_op(atomic.as_ptr());
3423 /// }
3424 /// # }
3425 /// ```
3426 #[inline]
3427 #[stable(feature = "atomic_as_ptr", since = "1.70.0")]
3428 #[rustc_const_stable(feature = "atomic_as_ptr", since = "1.70.0")]
3429 #[rustc_never_returns_null_ptr]
3430 pub const fn as_ptr(&self) -> *mut $int_type {
3431 self.v.get()
3432 }
3433 }
3434 }
3435}
3436
3437#[cfg(target_has_atomic_load_store = "8")]
3438atomic_int! {
3439 cfg(target_has_atomic = "8"),
3440 cfg(target_has_atomic_equal_alignment = "8"),
3441 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3442 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3443 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3444 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3445 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3446 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3447 rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"),
3448 rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0"),
3449 cfg_attr(not(test), rustc_diagnostic_item = "AtomicI8"),
3450 "i8",
3451 "",
3452 atomic_min, atomic_max,
3453 1,
3454 i8 AtomicI8
3455}
3456#[cfg(target_has_atomic_load_store = "8")]
3457atomic_int! {
3458 cfg(target_has_atomic = "8"),
3459 cfg(target_has_atomic_equal_alignment = "8"),
3460 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3461 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3462 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3463 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3464 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3465 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3466 rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"),
3467 rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0"),
3468 cfg_attr(not(test), rustc_diagnostic_item = "AtomicU8"),
3469 "u8",
3470 "",
3471 atomic_umin, atomic_umax,
3472 1,
3473 u8 AtomicU8
3474}
3475#[cfg(target_has_atomic_load_store = "16")]
3476atomic_int! {
3477 cfg(target_has_atomic = "16"),
3478 cfg(target_has_atomic_equal_alignment = "16"),
3479 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3480 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3481 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3482 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3483 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3484 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3485 rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"),
3486 rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0"),
3487 cfg_attr(not(test), rustc_diagnostic_item = "AtomicI16"),
3488 "i16",
3489 "",
3490 atomic_min, atomic_max,
3491 2,
3492 i16 AtomicI16
3493}
3494#[cfg(target_has_atomic_load_store = "16")]
3495atomic_int! {
3496 cfg(target_has_atomic = "16"),
3497 cfg(target_has_atomic_equal_alignment = "16"),
3498 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3499 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3500 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3501 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3502 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3503 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3504 rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"),
3505 rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0"),
3506 cfg_attr(not(test), rustc_diagnostic_item = "AtomicU16"),
3507 "u16",
3508 "",
3509 atomic_umin, atomic_umax,
3510 2,
3511 u16 AtomicU16
3512}
3513#[cfg(target_has_atomic_load_store = "32")]
3514atomic_int! {
3515 cfg(target_has_atomic = "32"),
3516 cfg(target_has_atomic_equal_alignment = "32"),
3517 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3518 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3519 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3520 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3521 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3522 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3523 rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"),
3524 rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0"),
3525 cfg_attr(not(test), rustc_diagnostic_item = "AtomicI32"),
3526 "i32",
3527 "",
3528 atomic_min, atomic_max,
3529 4,
3530 i32 AtomicI32
3531}
3532#[cfg(target_has_atomic_load_store = "32")]
3533atomic_int! {
3534 cfg(target_has_atomic = "32"),
3535 cfg(target_has_atomic_equal_alignment = "32"),
3536 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3537 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3538 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3539 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3540 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3541 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3542 rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"),
3543 rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0"),
3544 cfg_attr(not(test), rustc_diagnostic_item = "AtomicU32"),
3545 "u32",
3546 "",
3547 atomic_umin, atomic_umax,
3548 4,
3549 u32 AtomicU32
3550}
3551#[cfg(target_has_atomic_load_store = "64")]
3552atomic_int! {
3553 cfg(target_has_atomic = "64"),
3554 cfg(target_has_atomic_equal_alignment = "64"),
3555 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3556 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3557 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3558 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3559 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3560 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3561 rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"),
3562 rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0"),
3563 cfg_attr(not(test), rustc_diagnostic_item = "AtomicI64"),
3564 "i64",
3565 "",
3566 atomic_min, atomic_max,
3567 8,
3568 i64 AtomicI64
3569}
3570#[cfg(target_has_atomic_load_store = "64")]
3571atomic_int! {
3572 cfg(target_has_atomic = "64"),
3573 cfg(target_has_atomic_equal_alignment = "64"),
3574 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3575 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3576 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3577 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3578 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3579 stable(feature = "integer_atomics_stable", since = "1.34.0"),
3580 rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"),
3581 rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0"),
3582 cfg_attr(not(test), rustc_diagnostic_item = "AtomicU64"),
3583 "u64",
3584 "",
3585 atomic_umin, atomic_umax,
3586 8,
3587 u64 AtomicU64
3588}
3589#[cfg(target_has_atomic_load_store = "128")]
3590atomic_int! {
3591 cfg(target_has_atomic = "128"),
3592 cfg(target_has_atomic_equal_alignment = "128"),
3593 unstable(feature = "integer_atomics", issue = "99069"),
3594 unstable(feature = "integer_atomics", issue = "99069"),
3595 unstable(feature = "integer_atomics", issue = "99069"),
3596 unstable(feature = "integer_atomics", issue = "99069"),
3597 unstable(feature = "integer_atomics", issue = "99069"),
3598 unstable(feature = "integer_atomics", issue = "99069"),
3599 rustc_const_unstable(feature = "integer_atomics", issue = "99069"),
3600 rustc_const_unstable(feature = "integer_atomics", issue = "99069"),
3601 cfg_attr(not(test), rustc_diagnostic_item = "AtomicI128"),
3602 "i128",
3603 "#![feature(integer_atomics)]\n\n",
3604 atomic_min, atomic_max,
3605 16,
3606 i128 AtomicI128
3607}
3608#[cfg(target_has_atomic_load_store = "128")]
3609atomic_int! {
3610 cfg(target_has_atomic = "128"),
3611 cfg(target_has_atomic_equal_alignment = "128"),
3612 unstable(feature = "integer_atomics", issue = "99069"),
3613 unstable(feature = "integer_atomics", issue = "99069"),
3614 unstable(feature = "integer_atomics", issue = "99069"),
3615 unstable(feature = "integer_atomics", issue = "99069"),
3616 unstable(feature = "integer_atomics", issue = "99069"),
3617 unstable(feature = "integer_atomics", issue = "99069"),
3618 rustc_const_unstable(feature = "integer_atomics", issue = "99069"),
3619 rustc_const_unstable(feature = "integer_atomics", issue = "99069"),
3620 cfg_attr(not(test), rustc_diagnostic_item = "AtomicU128"),
3621 "u128",
3622 "#![feature(integer_atomics)]\n\n",
3623 atomic_umin, atomic_umax,
3624 16,
3625 u128 AtomicU128
3626}
3627
3628#[cfg(target_has_atomic_load_store = "ptr")]
3629macro_rules! atomic_int_ptr_sized {
3630 ( $($target_pointer_width:literal $align:literal)* ) => { $(
3631 #[cfg(target_pointer_width = $target_pointer_width)]
3632 atomic_int! {
3633 cfg(target_has_atomic = "ptr"),
3634 cfg(target_has_atomic_equal_alignment = "ptr"),
3635 stable(feature = "rust1", since = "1.0.0"),
3636 stable(feature = "extended_compare_and_swap", since = "1.10.0"),
3637 stable(feature = "atomic_debug", since = "1.3.0"),
3638 stable(feature = "atomic_access", since = "1.15.0"),
3639 stable(feature = "atomic_from", since = "1.23.0"),
3640 stable(feature = "atomic_nand", since = "1.27.0"),
3641 rustc_const_stable(feature = "const_ptr_sized_atomics", since = "1.24.0"),
3642 rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0"),
3643 cfg_attr(not(test), rustc_diagnostic_item = "AtomicIsize"),
3644 "isize",
3645 "",
3646 atomic_min, atomic_max,
3647 $align,
3648 isize AtomicIsize
3649 }
3650 #[cfg(target_pointer_width = $target_pointer_width)]
3651 atomic_int! {
3652 cfg(target_has_atomic = "ptr"),
3653 cfg(target_has_atomic_equal_alignment = "ptr"),
3654 stable(feature = "rust1", since = "1.0.0"),
3655 stable(feature = "extended_compare_and_swap", since = "1.10.0"),
3656 stable(feature = "atomic_debug", since = "1.3.0"),
3657 stable(feature = "atomic_access", since = "1.15.0"),
3658 stable(feature = "atomic_from", since = "1.23.0"),
3659 stable(feature = "atomic_nand", since = "1.27.0"),
3660 rustc_const_stable(feature = "const_ptr_sized_atomics", since = "1.24.0"),
3661 rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0"),
3662 cfg_attr(not(test), rustc_diagnostic_item = "AtomicUsize"),
3663 "usize",
3664 "",
3665 atomic_umin, atomic_umax,
3666 $align,
3667 usize AtomicUsize
3668 }
3669
3670 /// An [`AtomicIsize`] initialized to `0`.
3671 #[cfg(target_pointer_width = $target_pointer_width)]
3672 #[stable(feature = "rust1", since = "1.0.0")]
3673 #[deprecated(
3674 since = "1.34.0",
3675 note = "the `new` function is now preferred",
3676 suggestion = "AtomicIsize::new(0)",
3677 )]
3678 pub const ATOMIC_ISIZE_INIT: AtomicIsize = AtomicIsize::new(0);
3679
3680 /// An [`AtomicUsize`] initialized to `0`.
3681 #[cfg(target_pointer_width = $target_pointer_width)]
3682 #[stable(feature = "rust1", since = "1.0.0")]
3683 #[deprecated(
3684 since = "1.34.0",
3685 note = "the `new` function is now preferred",
3686 suggestion = "AtomicUsize::new(0)",
3687 )]
3688 pub const ATOMIC_USIZE_INIT: AtomicUsize = AtomicUsize::new(0);
3689 )* };
3690}
3691
3692#[cfg(target_has_atomic_load_store = "ptr")]
3693atomic_int_ptr_sized! {
3694 "16" 2
3695 "32" 4
3696 "64" 8
3697}
3698
3699#[inline]
3700#[cfg(target_has_atomic)]
3701fn strongest_failure_ordering(order: Ordering) -> Ordering {
3702 match order {
3703 Release => Relaxed,
3704 Relaxed => Relaxed,
3705 SeqCst => SeqCst,
3706 Acquire => Acquire,
3707 AcqRel => Acquire,
3708 }
3709}
3710
3711#[inline]
3712#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3713unsafe fn atomic_store<T: Copy>(dst: *mut T, val: T, order: Ordering) {
3714 // SAFETY: the caller must uphold the safety contract for `atomic_store`.
3715 unsafe {
3716 match order {
3717 Relaxed => intrinsics::atomic_store_relaxed(dst, val),
3718 Release => intrinsics::atomic_store_release(dst, val),
3719 SeqCst => intrinsics::atomic_store_seqcst(dst, val),
3720 Acquire => panic!("there is no such thing as an acquire store"),
3721 AcqRel => panic!("there is no such thing as an acquire-release store"),
3722 }
3723 }
3724}
3725
3726#[inline]
3727#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3728unsafe fn atomic_load<T: Copy>(dst: *const T, order: Ordering) -> T {
3729 // SAFETY: the caller must uphold the safety contract for `atomic_load`.
3730 unsafe {
3731 match order {
3732 Relaxed => intrinsics::atomic_load_relaxed(dst),
3733 Acquire => intrinsics::atomic_load_acquire(dst),
3734 SeqCst => intrinsics::atomic_load_seqcst(dst),
3735 Release => panic!("there is no such thing as a release load"),
3736 AcqRel => panic!("there is no such thing as an acquire-release load"),
3737 }
3738 }
3739}
3740
3741#[inline]
3742#[cfg(target_has_atomic)]
3743#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3744unsafe fn atomic_swap<T: Copy>(dst: *mut T, val: T, order: Ordering) -> T {
3745 // SAFETY: the caller must uphold the safety contract for `atomic_swap`.
3746 unsafe {
3747 match order {
3748 Relaxed => intrinsics::atomic_xchg_relaxed(dst, val),
3749 Acquire => intrinsics::atomic_xchg_acquire(dst, val),
3750 Release => intrinsics::atomic_xchg_release(dst, val),
3751 AcqRel => intrinsics::atomic_xchg_acqrel(dst, val),
3752 SeqCst => intrinsics::atomic_xchg_seqcst(dst, val),
3753 }
3754 }
3755}
3756
3757/// Returns the previous value (like __sync_fetch_and_add).
3758#[inline]
3759#[cfg(target_has_atomic)]
3760#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3761unsafe fn atomic_add<T: Copy>(dst: *mut T, val: T, order: Ordering) -> T {
3762 // SAFETY: the caller must uphold the safety contract for `atomic_add`.
3763 unsafe {
3764 match order {
3765 Relaxed => intrinsics::atomic_xadd_relaxed(dst, val),
3766 Acquire => intrinsics::atomic_xadd_acquire(dst, val),
3767 Release => intrinsics::atomic_xadd_release(dst, val),
3768 AcqRel => intrinsics::atomic_xadd_acqrel(dst, val),
3769 SeqCst => intrinsics::atomic_xadd_seqcst(dst, val),
3770 }
3771 }
3772}
3773
3774/// Returns the previous value (like __sync_fetch_and_sub).
3775#[inline]
3776#[cfg(target_has_atomic)]
3777#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3778unsafe fn atomic_sub<T: Copy>(dst: *mut T, val: T, order: Ordering) -> T {
3779 // SAFETY: the caller must uphold the safety contract for `atomic_sub`.
3780 unsafe {
3781 match order {
3782 Relaxed => intrinsics::atomic_xsub_relaxed(dst, val),
3783 Acquire => intrinsics::atomic_xsub_acquire(dst, val),
3784 Release => intrinsics::atomic_xsub_release(dst, val),
3785 AcqRel => intrinsics::atomic_xsub_acqrel(dst, val),
3786 SeqCst => intrinsics::atomic_xsub_seqcst(dst, val),
3787 }
3788 }
3789}
3790
3791#[inline]
3792#[cfg(target_has_atomic)]
3793#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3794unsafe fn atomic_compare_exchange<T: Copy>(
3795 dst: *mut T,
3796 old: T,
3797 new: T,
3798 success: Ordering,
3799 failure: Ordering,
3800) -> Result<T, T> {
3801 // SAFETY: the caller must uphold the safety contract for `atomic_compare_exchange`.
3802 let (val, ok) = unsafe {
3803 match (success, failure) {
3804 (Relaxed, Relaxed) => intrinsics::atomic_cxchg_relaxed_relaxed(dst, old, new),
3805 (Relaxed, Acquire) => intrinsics::atomic_cxchg_relaxed_acquire(dst, old, new),
3806 (Relaxed, SeqCst) => intrinsics::atomic_cxchg_relaxed_seqcst(dst, old, new),
3807 (Acquire, Relaxed) => intrinsics::atomic_cxchg_acquire_relaxed(dst, old, new),
3808 (Acquire, Acquire) => intrinsics::atomic_cxchg_acquire_acquire(dst, old, new),
3809 (Acquire, SeqCst) => intrinsics::atomic_cxchg_acquire_seqcst(dst, old, new),
3810 (Release, Relaxed) => intrinsics::atomic_cxchg_release_relaxed(dst, old, new),
3811 (Release, Acquire) => intrinsics::atomic_cxchg_release_acquire(dst, old, new),
3812 (Release, SeqCst) => intrinsics::atomic_cxchg_release_seqcst(dst, old, new),
3813 (AcqRel, Relaxed) => intrinsics::atomic_cxchg_acqrel_relaxed(dst, old, new),
3814 (AcqRel, Acquire) => intrinsics::atomic_cxchg_acqrel_acquire(dst, old, new),
3815 (AcqRel, SeqCst) => intrinsics::atomic_cxchg_acqrel_seqcst(dst, old, new),
3816 (SeqCst, Relaxed) => intrinsics::atomic_cxchg_seqcst_relaxed(dst, old, new),
3817 (SeqCst, Acquire) => intrinsics::atomic_cxchg_seqcst_acquire(dst, old, new),
3818 (SeqCst, SeqCst) => intrinsics::atomic_cxchg_seqcst_seqcst(dst, old, new),
3819 (_, AcqRel) => panic!("there is no such thing as an acquire-release failure ordering"),
3820 (_, Release) => panic!("there is no such thing as a release failure ordering"),
3821 }
3822 };
3823 if ok { Ok(val) } else { Err(val) }
3824}
3825
3826#[inline]
3827#[cfg(target_has_atomic)]
3828#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3829unsafe fn atomic_compare_exchange_weak<T: Copy>(
3830 dst: *mut T,
3831 old: T,
3832 new: T,
3833 success: Ordering,
3834 failure: Ordering,
3835) -> Result<T, T> {
3836 // SAFETY: the caller must uphold the safety contract for `atomic_compare_exchange_weak`.
3837 let (val, ok) = unsafe {
3838 match (success, failure) {
3839 (Relaxed, Relaxed) => intrinsics::atomic_cxchgweak_relaxed_relaxed(dst, old, new),
3840 (Relaxed, Acquire) => intrinsics::atomic_cxchgweak_relaxed_acquire(dst, old, new),
3841 (Relaxed, SeqCst) => intrinsics::atomic_cxchgweak_relaxed_seqcst(dst, old, new),
3842 (Acquire, Relaxed) => intrinsics::atomic_cxchgweak_acquire_relaxed(dst, old, new),
3843 (Acquire, Acquire) => intrinsics::atomic_cxchgweak_acquire_acquire(dst, old, new),
3844 (Acquire, SeqCst) => intrinsics::atomic_cxchgweak_acquire_seqcst(dst, old, new),
3845 (Release, Relaxed) => intrinsics::atomic_cxchgweak_release_relaxed(dst, old, new),
3846 (Release, Acquire) => intrinsics::atomic_cxchgweak_release_acquire(dst, old, new),
3847 (Release, SeqCst) => intrinsics::atomic_cxchgweak_release_seqcst(dst, old, new),
3848 (AcqRel, Relaxed) => intrinsics::atomic_cxchgweak_acqrel_relaxed(dst, old, new),
3849 (AcqRel, Acquire) => intrinsics::atomic_cxchgweak_acqrel_acquire(dst, old, new),
3850 (AcqRel, SeqCst) => intrinsics::atomic_cxchgweak_acqrel_seqcst(dst, old, new),
3851 (SeqCst, Relaxed) => intrinsics::atomic_cxchgweak_seqcst_relaxed(dst, old, new),
3852 (SeqCst, Acquire) => intrinsics::atomic_cxchgweak_seqcst_acquire(dst, old, new),
3853 (SeqCst, SeqCst) => intrinsics::atomic_cxchgweak_seqcst_seqcst(dst, old, new),
3854 (_, AcqRel) => panic!("there is no such thing as an acquire-release failure ordering"),
3855 (_, Release) => panic!("there is no such thing as a release failure ordering"),
3856 }
3857 };
3858 if ok { Ok(val) } else { Err(val) }
3859}
3860
3861#[inline]
3862#[cfg(target_has_atomic)]
3863#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3864unsafe fn atomic_and<T: Copy>(dst: *mut T, val: T, order: Ordering) -> T {
3865 // SAFETY: the caller must uphold the safety contract for `atomic_and`
3866 unsafe {
3867 match order {
3868 Relaxed => intrinsics::atomic_and_relaxed(dst, val),
3869 Acquire => intrinsics::atomic_and_acquire(dst, val),
3870 Release => intrinsics::atomic_and_release(dst, val),
3871 AcqRel => intrinsics::atomic_and_acqrel(dst, val),
3872 SeqCst => intrinsics::atomic_and_seqcst(dst, val),
3873 }
3874 }
3875}
3876
3877#[inline]
3878#[cfg(target_has_atomic)]
3879#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3880unsafe fn atomic_nand<T: Copy>(dst: *mut T, val: T, order: Ordering) -> T {
3881 // SAFETY: the caller must uphold the safety contract for `atomic_nand`
3882 unsafe {
3883 match order {
3884 Relaxed => intrinsics::atomic_nand_relaxed(dst, val),
3885 Acquire => intrinsics::atomic_nand_acquire(dst, val),
3886 Release => intrinsics::atomic_nand_release(dst, val),
3887 AcqRel => intrinsics::atomic_nand_acqrel(dst, val),
3888 SeqCst => intrinsics::atomic_nand_seqcst(dst, val),
3889 }
3890 }
3891}
3892
3893#[inline]
3894#[cfg(target_has_atomic)]
3895#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3896unsafe fn atomic_or<T: Copy>(dst: *mut T, val: T, order: Ordering) -> T {
3897 // SAFETY: the caller must uphold the safety contract for `atomic_or`
3898 unsafe {
3899 match order {
3900 SeqCst => intrinsics::atomic_or_seqcst(dst, val),
3901 Acquire => intrinsics::atomic_or_acquire(dst, val),
3902 Release => intrinsics::atomic_or_release(dst, val),
3903 AcqRel => intrinsics::atomic_or_acqrel(dst, val),
3904 Relaxed => intrinsics::atomic_or_relaxed(dst, val),
3905 }
3906 }
3907}
3908
3909#[inline]
3910#[cfg(target_has_atomic)]
3911#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3912unsafe fn atomic_xor<T: Copy>(dst: *mut T, val: T, order: Ordering) -> T {
3913 // SAFETY: the caller must uphold the safety contract for `atomic_xor`
3914 unsafe {
3915 match order {
3916 SeqCst => intrinsics::atomic_xor_seqcst(dst, val),
3917 Acquire => intrinsics::atomic_xor_acquire(dst, val),
3918 Release => intrinsics::atomic_xor_release(dst, val),
3919 AcqRel => intrinsics::atomic_xor_acqrel(dst, val),
3920 Relaxed => intrinsics::atomic_xor_relaxed(dst, val),
3921 }
3922 }
3923}
3924
3925/// returns the max value (signed comparison)
3926#[inline]
3927#[cfg(target_has_atomic)]
3928#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3929unsafe fn atomic_max<T: Copy>(dst: *mut T, val: T, order: Ordering) -> T {
3930 // SAFETY: the caller must uphold the safety contract for `atomic_max`
3931 unsafe {
3932 match order {
3933 Relaxed => intrinsics::atomic_max_relaxed(dst, val),
3934 Acquire => intrinsics::atomic_max_acquire(dst, val),
3935 Release => intrinsics::atomic_max_release(dst, val),
3936 AcqRel => intrinsics::atomic_max_acqrel(dst, val),
3937 SeqCst => intrinsics::atomic_max_seqcst(dst, val),
3938 }
3939 }
3940}
3941
3942/// returns the min value (signed comparison)
3943#[inline]
3944#[cfg(target_has_atomic)]
3945#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3946unsafe fn atomic_min<T: Copy>(dst: *mut T, val: T, order: Ordering) -> T {
3947 // SAFETY: the caller must uphold the safety contract for `atomic_min`
3948 unsafe {
3949 match order {
3950 Relaxed => intrinsics::atomic_min_relaxed(dst, val),
3951 Acquire => intrinsics::atomic_min_acquire(dst, val),
3952 Release => intrinsics::atomic_min_release(dst, val),
3953 AcqRel => intrinsics::atomic_min_acqrel(dst, val),
3954 SeqCst => intrinsics::atomic_min_seqcst(dst, val),
3955 }
3956 }
3957}
3958
3959/// returns the max value (unsigned comparison)
3960#[inline]
3961#[cfg(target_has_atomic)]
3962#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3963unsafe fn atomic_umax<T: Copy>(dst: *mut T, val: T, order: Ordering) -> T {
3964 // SAFETY: the caller must uphold the safety contract for `atomic_umax`
3965 unsafe {
3966 match order {
3967 Relaxed => intrinsics::atomic_umax_relaxed(dst, val),
3968 Acquire => intrinsics::atomic_umax_acquire(dst, val),
3969 Release => intrinsics::atomic_umax_release(dst, val),
3970 AcqRel => intrinsics::atomic_umax_acqrel(dst, val),
3971 SeqCst => intrinsics::atomic_umax_seqcst(dst, val),
3972 }
3973 }
3974}
3975
3976/// returns the min value (unsigned comparison)
3977#[inline]
3978#[cfg(target_has_atomic)]
3979#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
3980unsafe fn atomic_umin<T: Copy>(dst: *mut T, val: T, order: Ordering) -> T {
3981 // SAFETY: the caller must uphold the safety contract for `atomic_umin`
3982 unsafe {
3983 match order {
3984 Relaxed => intrinsics::atomic_umin_relaxed(dst, val),
3985 Acquire => intrinsics::atomic_umin_acquire(dst, val),
3986 Release => intrinsics::atomic_umin_release(dst, val),
3987 AcqRel => intrinsics::atomic_umin_acqrel(dst, val),
3988 SeqCst => intrinsics::atomic_umin_seqcst(dst, val),
3989 }
3990 }
3991}
3992
3993/// An atomic fence.
3994///
3995/// Fences create synchronization between themselves and atomic operations or fences in other
3996/// threads. To achieve this, a fence prevents the compiler and CPU from reordering certain types of
3997/// memory operations around it.
3998///
3999/// A fence 'A' which has (at least) [`Release`] ordering semantics, synchronizes
4000/// with a fence 'B' with (at least) [`Acquire`] semantics, if and only if there
4001/// exist operations X and Y, both operating on some atomic object 'm' such
4002/// that A is sequenced before X, Y is sequenced before B and Y observes
4003/// the change to m. This provides a happens-before dependence between A and B.
4004///
4005/// ```text
4006/// Thread 1 Thread 2
4007///
4008/// fence(Release); A --------------
4009/// m.store(3, Relaxed); X --------- |
4010/// | |
4011/// | |
4012/// -------------> Y if m.load(Relaxed) == 3 {
4013/// |-------> B fence(Acquire);
4014/// ...
4015/// }
4016/// ```
4017///
4018/// Note that in the example above, it is crucial that the accesses to `m` are atomic. Fences cannot
4019/// be used to establish synchronization among non-atomic accesses in different threads. However,
4020/// thanks to the happens-before relationship between A and B, any non-atomic accesses that
4021/// happen-before A are now also properly synchronized with any non-atomic accesses that
4022/// happen-after B.
4023///
4024/// Atomic operations with [`Release`] or [`Acquire`] semantics can also synchronize
4025/// with a fence.
4026///
4027/// A fence which has [`SeqCst`] ordering, in addition to having both [`Acquire`]
4028/// and [`Release`] semantics, participates in the global program order of the
4029/// other [`SeqCst`] operations and/or fences.
4030///
4031/// Accepts [`Acquire`], [`Release`], [`AcqRel`] and [`SeqCst`] orderings.
4032///
4033/// # Panics
4034///
4035/// Panics if `order` is [`Relaxed`].
4036///
4037/// # Examples
4038///
4039/// ```
4040/// use std::sync::atomic::AtomicBool;
4041/// use std::sync::atomic::fence;
4042/// use std::sync::atomic::Ordering;
4043///
4044/// // A mutual exclusion primitive based on spinlock.
4045/// pub struct Mutex {
4046/// flag: AtomicBool,
4047/// }
4048///
4049/// impl Mutex {
4050/// pub fn new() -> Mutex {
4051/// Mutex {
4052/// flag: AtomicBool::new(false),
4053/// }
4054/// }
4055///
4056/// pub fn lock(&self) {
4057/// // Wait until the old value is `false`.
4058/// while self
4059/// .flag
4060/// .compare_exchange_weak(false, true, Ordering::Relaxed, Ordering::Relaxed)
4061/// .is_err()
4062/// {}
4063/// // This fence synchronizes-with store in `unlock`.
4064/// fence(Ordering::Acquire);
4065/// }
4066///
4067/// pub fn unlock(&self) {
4068/// self.flag.store(false, Ordering::Release);
4069/// }
4070/// }
4071/// ```
4072#[inline]
4073#[stable(feature = "rust1", since = "1.0.0")]
4074#[rustc_diagnostic_item = "fence"]
4075#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
4076pub fn fence(order: Ordering) {
4077 // SAFETY: using an atomic fence is safe.
4078 unsafe {
4079 match order {
4080 Acquire => intrinsics::atomic_fence_acquire(),
4081 Release => intrinsics::atomic_fence_release(),
4082 AcqRel => intrinsics::atomic_fence_acqrel(),
4083 SeqCst => intrinsics::atomic_fence_seqcst(),
4084 Relaxed => panic!("there is no such thing as a relaxed fence"),
4085 }
4086 }
4087}
4088
4089/// A "compiler-only" atomic fence.
4090///
4091/// Like [`fence`], this function establishes synchronization with other atomic operations and
4092/// fences. However, unlike [`fence`], `compiler_fence` only establishes synchronization with
4093/// operations *in the same thread*. This may at first sound rather useless, since code within a
4094/// thread is typically already totally ordered and does not need any further synchronization.
4095/// However, there are cases where code can run on the same thread without being ordered:
4096/// - The most common case is that of a *signal handler*: a signal handler runs in the same thread
4097/// as the code it interrupted, but it is not ordered with respect to that code. `compiler_fence`
4098/// can be used to establish synchronization between a thread and its signal handler, the same way
4099/// that `fence` can be used to establish synchronization across threads.
4100/// - Similar situations can arise in embedded programming with interrupt handlers, or in custom
4101/// implementations of preemptive green threads. In general, `compiler_fence` can establish
4102/// synchronization with code that is guaranteed to run on the same hardware CPU.
4103///
4104/// See [`fence`] for how a fence can be used to achieve synchronization. Note that just like
4105/// [`fence`], synchronization still requires atomic operations to be used in both threads -- it is
4106/// not possible to perform synchronization entirely with fences and non-atomic operations.
4107///
4108/// `compiler_fence` does not emit any machine code, but restricts the kinds of memory re-ordering
4109/// the compiler is allowed to do. `compiler_fence` corresponds to [`atomic_signal_fence`] in C and
4110/// C++.
4111///
4112/// [`atomic_signal_fence`]: https://en.cppreference.com/w/cpp/atomic/atomic_signal_fence
4113///
4114/// # Panics
4115///
4116/// Panics if `order` is [`Relaxed`].
4117///
4118/// # Examples
4119///
4120/// Without the two `compiler_fence` calls, the read of `IMPORTANT_VARIABLE` in `signal_handler`
4121/// is *undefined behavior* due to a data race, despite everything happening in a single thread.
4122/// This is because the signal handler is considered to run concurrently with its associated
4123/// thread, and explicit synchronization is required to pass data between a thread and its
4124/// signal handler. The code below uses two `compiler_fence` calls to establish the usual
4125/// release-acquire synchronization pattern (see [`fence`] for an image).
4126///
4127/// ```
4128/// use std::sync::atomic::AtomicBool;
4129/// use std::sync::atomic::Ordering;
4130/// use std::sync::atomic::compiler_fence;
4131///
4132/// static mut IMPORTANT_VARIABLE: usize = 0;
4133/// static IS_READY: AtomicBool = AtomicBool::new(false);
4134///
4135/// fn main() {
4136/// unsafe { IMPORTANT_VARIABLE = 42 };
4137/// // Marks earlier writes as being released with future relaxed stores.
4138/// compiler_fence(Ordering::Release);
4139/// IS_READY.store(true, Ordering::Relaxed);
4140/// }
4141///
4142/// fn signal_handler() {
4143/// if IS_READY.load(Ordering::Relaxed) {
4144/// // Acquires writes that were released with relaxed stores that we read from.
4145/// compiler_fence(Ordering::Acquire);
4146/// assert_eq!(unsafe { IMPORTANT_VARIABLE }, 42);
4147/// }
4148/// }
4149/// ```
4150#[inline]
4151#[stable(feature = "compiler_fences", since = "1.21.0")]
4152#[rustc_diagnostic_item = "compiler_fence"]
4153#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
4154pub fn compiler_fence(order: Ordering) {
4155 // SAFETY: using an atomic fence is safe.
4156 unsafe {
4157 match order {
4158 Acquire => intrinsics::atomic_singlethreadfence_acquire(),
4159 Release => intrinsics::atomic_singlethreadfence_release(),
4160 AcqRel => intrinsics::atomic_singlethreadfence_acqrel(),
4161 SeqCst => intrinsics::atomic_singlethreadfence_seqcst(),
4162 Relaxed => panic!("there is no such thing as a relaxed compiler fence"),
4163 }
4164 }
4165}
4166
4167#[cfg(target_has_atomic_load_store = "8")]
4168#[stable(feature = "atomic_debug", since = "1.3.0")]
4169impl fmt::Debug for AtomicBool {
4170 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
4171 fmt::Debug::fmt(&self.load(Ordering::Relaxed), f)
4172 }
4173}
4174
4175#[cfg(target_has_atomic_load_store = "ptr")]
4176#[stable(feature = "atomic_debug", since = "1.3.0")]
4177impl<T> fmt::Debug for AtomicPtr<T> {
4178 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
4179 fmt::Debug::fmt(&self.load(Ordering::Relaxed), f)
4180 }
4181}
4182
4183#[cfg(target_has_atomic_load_store = "ptr")]
4184#[stable(feature = "atomic_pointer", since = "1.24.0")]
4185impl<T> fmt::Pointer for AtomicPtr<T> {
4186 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
4187 fmt::Pointer::fmt(&self.load(Ordering::Relaxed), f)
4188 }
4189}
4190
4191/// Signals the processor that it is inside a busy-wait spin-loop ("spin lock").
4192///
4193/// This function is deprecated in favor of [`hint::spin_loop`].
4194///
4195/// [`hint::spin_loop`]: crate::hint::spin_loop
4196#[inline]
4197#[stable(feature = "spin_loop_hint", since = "1.24.0")]
4198#[deprecated(since = "1.51.0", note = "use hint::spin_loop instead")]
4199pub fn spin_loop_hint() {
4200 spin_loop()
4201}