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}