//! Atomic types

//!

//! Atomic types provide primitive shared-memory communication between

//! threads, and are the building blocks of other concurrent

//! types.

//!

//! This module defines atomic versions of a select number of primitive

//! types, including [`AtomicBool`], [`AtomicIsize`], [`AtomicUsize`],

//! [`AtomicI8`], [`AtomicU16`], etc.

//! Atomic types present operations that, when used correctly, synchronize

//! updates between threads.

//!

//! Atomic variables are safe to share between threads (they implement [`Sync`])

//! but they do not themselves provide the mechanism for sharing and follow the

//! [threading model](../../../std/thread/index.html#the-threading-model) of Rust.

//! The most common way to share an atomic variable is to put it into an [`Arc`][arc] (an

//! atomically-reference-counted shared pointer).

//!

//! [arc]: ../../../std/sync/struct.Arc.html

//!

//! Atomic types may be stored in static variables, initialized using

//! the constant initializers like [`AtomicBool::new`]. Atomic statics

//! are often used for lazy global initialization.

//!

//! ## Memory model for atomic accesses

//!

//! Rust atomics currently follow the same rules as [C++20 atomics][cpp], specifically the rules

//! from the [`intro.races`][cpp-intro.races] section, without the "consume" memory ordering. Since

//! C++ uses an object-based memory model whereas Rust is access-based, a bit of translation work

//! has to be done to apply the C++ rules to Rust: whenever C++ talks about "the value of an

//! object", we understand that to mean the resulting bytes obtained when doing a read. When the C++

//! standard talks about "the value of an atomic object", this refers to the result of doing an

//! atomic load (via the operations provided in this module). A "modification of an atomic object"

//! refers to an atomic store.

//!

//! The end result is *almost* equivalent to saying that creating a *shared reference* to one of the

//! Rust atomic types corresponds to creating an `atomic_ref` in C++, with the `atomic_ref` being

//! destroyed when the lifetime of the shared reference ends. The main difference is that Rust

//! permits concurrent atomic and non-atomic reads to the same memory as those cause no issue in the

//! C++ memory model, they are just forbidden in C++ because memory is partitioned into "atomic

//! objects" and "non-atomic objects" (with `atomic_ref` temporarily converting a non-atomic object

//! into an atomic object).

//!

//! The most important aspect of this model is that *data races* are undefined behavior. A data race

//! is defined as conflicting non-synchronized accesses where at least one of the accesses is

//! non-atomic. Here, accesses are *conflicting* if they affect overlapping regions of memory and at

//! least one of them is a write. (A `compare_exchange` or `compare_exchange_weak` that does not

//! succeed is not considered a write.) They are *non-synchronized* if neither of them

//! *happens-before* the other, according to the happens-before order of the memory model.

//!

//! The other possible cause of undefined behavior in the memory model are mixed-size accesses: Rust

//! inherits the C++ limitation that non-synchronized conflicting atomic accesses may not partially

//! overlap. In other words, every pair of non-synchronized atomic accesses must be either disjoint,

//! access the exact same memory (including using the same access size), or both be reads.

//!

//! Each atomic access takes an [`Ordering`] which defines how the operation interacts with the

//! happens-before order. These orderings behave the same as the corresponding [C++20 atomic

//! orderings][cpp_memory_order]. For more information, see the [nomicon].

//!

//! [cpp]: https://en.cppreference.com/w/cpp/atomic

//! [cpp-intro.races]: https://timsong-cpp.github.io/cppwp/n4868/intro.multithread#intro.races

//! [cpp_memory_order]: https://en.cppreference.com/w/cpp/atomic/memory_order

//! [nomicon]: ../../../nomicon/atomics.html

//!

//! ```rust,no_run undefined_behavior

//! use std::sync::atomic::{AtomicU16, AtomicU8, Ordering};

//! use std::mem::transmute;

//! use std::thread;

//!

//! let atomic = AtomicU16::new(0);

//!

//! thread::scope(|s| {

//!     // This is UB: conflicting non-synchronized accesses, at least one of which is non-atomic.

//!     s.spawn(|| atomic.store(1, Ordering::Relaxed)); // atomic store

//!     s.spawn(|| unsafe { atomic.as_ptr().write(2) }); // non-atomic write

//! });

//!

//! thread::scope(|s| {

//!     // This is fine: the accesses do not conflict (as none of them performs any modification).

//!     // In C++ this would be disallowed since creating an `atomic_ref` precludes

//!     // further non-atomic accesses, but Rust does not have that limitation.

//!     s.spawn(|| atomic.load(Ordering::Relaxed)); // atomic load

//!     s.spawn(|| unsafe { atomic.as_ptr().read() }); // non-atomic read

//! });

//!

//! thread::scope(|s| {

//!     // This is fine: `join` synchronizes the code in a way such that the atomic

//!     // store happens-before the non-atomic write.

//!     let handle = s.spawn(|| atomic.store(1, Ordering::Relaxed)); // atomic store

//!     handle.join().expect("thread won't panic"); // synchronize

//!     s.spawn(|| unsafe { atomic.as_ptr().write(2) }); // non-atomic write

//! });

//!

//! thread::scope(|s| {

//!     // This is UB: non-synchronized conflicting differently-sized atomic accesses.

//!     s.spawn(|| atomic.store(1, Ordering::Relaxed));

//!     s.spawn(|| unsafe {

//!         let differently_sized = transmute::<&AtomicU16, &AtomicU8>(&atomic);

//!         differently_sized.store(2, Ordering::Relaxed);

//!     });

//! });

//!

//! thread::scope(|s| {

//!     // This is fine: `join` synchronizes the code in a way such that

//!     // the 1-byte store happens-before the 2-byte store.

//!     let handle = s.spawn(|| atomic.store(1, Ordering::Relaxed));

//!     handle.join().expect("thread won't panic");

//!     s.spawn(|| unsafe {

//!         let differently_sized = transmute::<&AtomicU16, &AtomicU8>(&atomic);

//!         differently_sized.store(2, Ordering::Relaxed);

//!     });

//! });

//! ```

//!

//! # Portability

//!

//! All atomic types in this module are guaranteed to be [lock-free] if they're

//! available. This means they don't internally acquire a global mutex. Atomic

//! types and operations are not guaranteed to be wait-free. This means that

//! operations like `fetch_or` may be implemented with a compare-and-swap loop.

//!

//! Atomic operations may be implemented at the instruction layer with

//! larger-size atomics. For example some platforms use 4-byte atomic

//! instructions to implement `AtomicI8`. Note that this emulation should not

//! have an impact on correctness of code, it's just something to be aware of.

//!

//! The atomic types in this module might not be available on all platforms. The

//! atomic types here are all widely available, however, and can generally be

//! relied upon existing. Some notable exceptions are:

//!

//! * PowerPC and MIPS platforms with 32-bit pointers do not have `AtomicU64` or

//!   `AtomicI64` types.

//! * ARM platforms like `armv5te` that aren't for Linux only provide `load`

//!   and `store` operations, and do not support Compare and Swap (CAS)

//!   operations, such as `swap`, `fetch_add`, etc. Additionally on Linux,

//!   these CAS operations are implemented via [operating system support], which

//!   may come with a performance penalty.

//! * ARM targets with `thumbv6m` only provide `load` and `store` operations,

//!   and do not support Compare and Swap (CAS) operations, such as `swap`,

//!   `fetch_add`, etc.

//!

//! [operating system support]: https://www.kernel.org/doc/Documentation/arm/kernel_user_helpers.txt

//!

//! Note that future platforms may be added that also do not have support for

//! some atomic operations. Maximally portable code will want to be careful

//! about which atomic types are used. `AtomicUsize` and `AtomicIsize` are

//! generally the most portable, but even then they're not available everywhere.

//! For reference, the `std` library requires `AtomicBool`s and pointer-sized atomics, although

//! `core` does not.

//!

//! The `#[cfg(target_has_atomic)]` attribute can be used to conditionally

//! compile based on the target's supported bit widths. It is a key-value

//! option set for each supported size, with values "8", "16", "32", "64",

//! "128", and "ptr" for pointer-sized atomics.

//!

//! [lock-free]: https://en.wikipedia.org/wiki/Non-blocking_algorithm

//!

//! # Atomic accesses to read-only memory

//!

//! In general, *all* atomic accesses on read-only memory are undefined behavior. For instance, attempting

//! to do a `compare_exchange` that will definitely fail (making it conceptually a read-only

//! operation) can still cause a segmentation fault if the underlying memory page is mapped read-only. Since

//! atomic `load`s might be implemented using compare-exchange operations, even a `load` can fault

//! on read-only memory.

//!

//! For the purpose of this section, "read-only memory" is defined as memory that is read-only in

//! the underlying target, i.e., the pages are mapped with a read-only flag and any attempt to write

//! will cause a page fault. In particular, an `&u128` reference that points to memory that is

//! read-write mapped is *not* considered to point to "read-only memory". In Rust, almost all memory

//! is read-write; the only exceptions are memory created by `const` items or `static` items without

//! interior mutability, and memory that was specifically marked as read-only by the operating

//! system via platform-specific APIs.

//!

//! As an exception from the general rule stated above, "sufficiently small" atomic loads with

//! `Ordering::Relaxed` are implemented in a way that works on read-only memory, and are hence not

//! undefined behavior. The exact size limit for what makes a load "sufficiently small" varies

//! depending on the target:

//!

//! | `target_arch` | Size limit |

//! |---------------|---------|

//! | `x86`, `arm`, `loongarch32`, `mips`, `mips32r6`, `powerpc`, `riscv32`, `sparc`, `hexagon` | 4 bytes |

//! | `x86_64`, `aarch64`, `loongarch64`, `mips64`, `mips64r6`, `powerpc64`, `riscv64`, `sparc64`, `s390x` | 8 bytes |

//!

//! Atomics loads that are larger than this limit as well as atomic loads with ordering other

//! than `Relaxed`, as well as *all* atomic loads on targets not listed in the table, might still be

//! read-only under certain conditions, but that is not a stable guarantee and should not be relied

//! upon.

//!

//! If you need to do an acquire load on read-only memory, you can do a relaxed load followed by an

//! acquire fence instead.

//!

//! # Examples

//!

//! A simple spinlock:

//!

//! ```ignore-wasm

//! use std::sync::Arc;

//! use std::sync::atomic::{AtomicUsize, Ordering};

//! use std::{hint, thread};

//!

//! fn main() {

//!     let spinlock = Arc::new(AtomicUsize::new(1));

//!

//!     let spinlock_clone = Arc::clone(&spinlock);

//!

//!     let thread = thread::spawn(move || {

//!         spinlock_clone.store(0, Ordering::Release);

//!     });

//!

//!     // Wait for the other thread to release the lock

//!     while spinlock.load(Ordering::Acquire) != 0 {

//!         hint::spin_loop();

//!     }

//!

//!     if let Err(panic) = thread.join() {

//!         println!("Thread had an error: {panic:?}");

//!     }

//! }

//! ```

//!

//! Keep a global count of live threads:

//!

//! ```

//! use std::sync::atomic::{AtomicUsize, Ordering};

//!

//! static GLOBAL_THREAD_COUNT: AtomicUsize = AtomicUsize::new(0);

//!

//! // Note that Relaxed ordering doesn't synchronize anything

//! // except the global thread counter itself.

//! let old_thread_count = GLOBAL_THREAD_COUNT.fetch_add(1, Ordering::Relaxed);

//! // Note that this number may not be true at the moment of printing

//! // because some other thread may have changed static value already.

//! println!("live threads: {}", old_thread_count + 1);

//! ```

#![stable(feature = "rust1", since = "1.0.0")]

#![cfg_attr(not(target_has_atomic_load_store = "8"), allow(dead_code))]

#![cfg_attr(not(target_has_atomic_load_store = "8"), allow(unused_imports))]

#![rustc_diagnostic_item = "atomic_mod"]

// Clippy complains about the pattern of "safe function calling unsafe function taking pointers".

// This happens with AtomicPtr intrinsics but is fine, as the pointers clippy is concerned about

// are just normal values that get loaded/stored, but not dereferenced.

#![allow(clippy::not_unsafe_ptr_arg_deref)]

use self::Ordering::*;

use crate::cell::UnsafeCell;

#[cfg(not(feature = "ferrocene_certified"))]

use crate::hint::spin_loop;

#[cfg(feature = "ferrocene_certified")]

use crate::intrinsics;

use crate::intrinsics::AtomicOrdering as AO;

#[cfg(not(feature = "ferrocene_certified"))]

use crate::{fmt, intrinsics};

trait Sealed {}

/// A marker trait for primitive types which can be modified atomically.

///

/// This is an implementation detail for <code>[Atomic]\<T></code> which may disappear or be replaced at any time.

///

/// # Safety

///

/// Types implementing this trait must be primitives that can be modified atomically.

///

/// The associated `Self::AtomicInner` type must have the same size and bit validity as `Self`,

/// but may have a higher alignment requirement, so the following `transmute`s are sound:

///

/// - `&mut Self::AtomicInner` as `&mut Self`

/// - `Self` as `Self::AtomicInner` or the reverse

#[unstable(

    feature = "atomic_internals",

    reason = "implementation detail which may disappear or be replaced at any time",

    issue = "none"

)]

#[expect(private_bounds)]

pub unsafe trait AtomicPrimitive: Sized + Copy + Sealed {

    /// Temporary implementation detail.

    type AtomicInner: Sized;

}

macro impl_atomic_primitive(

    $Atom:ident $(<$T:ident>)? ($Primitive:ty),

    size($size:literal),

    align($align:literal) $(,)?

) {

    impl $(<$T>)? Sealed for $Primitive {}

    #[unstable(

        feature = "atomic_internals",

        reason = "implementation detail which may disappear or be replaced at any time",

        issue = "none"

    )]

    #[cfg(target_has_atomic_load_store = $size)]

    unsafe impl $(<$T>)? AtomicPrimitive for $Primitive {

        type AtomicInner = $Atom $(<$T>)?;

    }

}

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicBool(bool), size("8"), align(1));

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicI8(i8), size("8"), align(1));

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicU8(u8), size("8"), align(1));

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicI16(i16), size("16"), align(2));

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicU16(u16), size("16"), align(2));

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicI32(i32), size("32"), align(4));

impl_atomic_primitive!(AtomicU32(u32), size("32"), align(4));

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicI64(i64), size("64"), align(8));

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicU64(u64), size("64"), align(8));

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicI128(i128), size("128"), align(16));

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicU128(u128), size("128"), align(16));

#[cfg(target_pointer_width = "16")]

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicIsize(isize), size("ptr"), align(2));

#[cfg(target_pointer_width = "32")]

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicIsize(isize), size("ptr"), align(4));

#[cfg(target_pointer_width = "64")]

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicIsize(isize), size("ptr"), align(8));

#[cfg(target_pointer_width = "16")]

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicUsize(usize), size("ptr"), align(2));

#[cfg(target_pointer_width = "32")]

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicUsize(usize), size("ptr"), align(4));

#[cfg(target_pointer_width = "64")]

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicUsize(usize), size("ptr"), align(8));

#[cfg(target_pointer_width = "16")]

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicPtr<T>(*mut T), size("ptr"), align(2));

#[cfg(target_pointer_width = "32")]

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicPtr<T>(*mut T), size("ptr"), align(4));

#[cfg(target_pointer_width = "64")]

#[cfg(not(feature = "ferrocene_certified"))]

impl_atomic_primitive!(AtomicPtr<T>(*mut T), size("ptr"), align(8));

/// A memory location which can be safely modified from multiple threads.

///

/// This has the same size and bit validity as the underlying type `T`. However,

/// the alignment of this type is always equal to its size, even on targets where

/// `T` has alignment less than its size.

///

/// For more about the differences between atomic types and non-atomic types as

/// well as information about the portability of this type, please see the

/// [module-level documentation].

///

/// **Note:** This type is only available on platforms that support atomic loads

/// and stores of `T`.

///

/// [module-level documentation]: crate::sync::atomic

#[unstable(feature = "generic_atomic", issue = "130539")]

#[cfg(not(feature = "ferrocene_certified"))]

pub type Atomic<T> = <T as AtomicPrimitive>::AtomicInner;

// Some architectures don't have byte-sized atomics, which results in LLVM

// emulating them using a LL/SC loop. However for AtomicBool we can take

// advantage of the fact that it only ever contains 0 or 1 and use atomic OR/AND

// instead, which LLVM can emulate using a larger atomic OR/AND operation.

//

// This list should only contain architectures which have word-sized atomic-or/

// atomic-and instructions but don't natively support byte-sized atomics.

#[cfg(target_has_atomic = "8")]

#[cfg(not(feature = "ferrocene_certified"))]

const EMULATE_ATOMIC_BOOL: bool = cfg!(any(

    target_arch = "riscv32",

    target_arch = "riscv64",

    target_arch = "loongarch32",

    target_arch = "loongarch64"

));

/// A boolean type which can be safely shared between threads.

///

/// This type has the same size, alignment, and bit validity as a [`bool`].

///

/// **Note**: This type is only available on platforms that support atomic

/// loads and stores of `u8`.

#[cfg(target_has_atomic_load_store = "8")]

#[stable(feature = "rust1", since = "1.0.0")]

#[rustc_diagnostic_item = "AtomicBool"]

#[repr(C, align(1))]

#[cfg(not(feature = "ferrocene_certified"))]

pub struct AtomicBool {

    v: UnsafeCell<u8>,

}

#[cfg(target_has_atomic_load_store = "8")]

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl Default for AtomicBool {

    /// Creates an `AtomicBool` initialized to `false`.

    #[inline]

    fn default() -> Self {

        Self::new(false)

    }

}

// Send is implicitly implemented for AtomicBool.

#[cfg(target_has_atomic_load_store = "8")]

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

unsafe impl Sync for AtomicBool {}

/// A raw pointer type which can be safely shared between threads.

///

/// This type has the same size and bit validity as a `*mut T`.

///

/// **Note**: This type is only available on platforms that support atomic

/// loads and stores of pointers. Its size depends on the target pointer's size.

#[cfg(target_has_atomic_load_store = "ptr")]

#[stable(feature = "rust1", since = "1.0.0")]

#[rustc_diagnostic_item = "AtomicPtr"]

#[cfg_attr(target_pointer_width = "16", repr(C, align(2)))]

#[cfg_attr(target_pointer_width = "32", repr(C, align(4)))]

#[cfg_attr(target_pointer_width = "64", repr(C, align(8)))]

#[cfg(not(feature = "ferrocene_certified"))]

pub struct AtomicPtr<T> {

    p: UnsafeCell<*mut T>,

}

#[cfg(target_has_atomic_load_store = "ptr")]

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl<T> Default for AtomicPtr<T> {

    /// Creates a null `AtomicPtr<T>`.

    fn default() -> AtomicPtr<T> {

        AtomicPtr::new(crate::ptr::null_mut())

    }

}

#[cfg(target_has_atomic_load_store = "ptr")]

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

unsafe impl<T> Send for AtomicPtr<T> {}

#[cfg(target_has_atomic_load_store = "ptr")]

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

unsafe impl<T> Sync for AtomicPtr<T> {}

/// Atomic memory orderings

///

/// Memory orderings specify the way atomic operations synchronize memory.

/// In its weakest [`Ordering::Relaxed`], only the memory directly touched by the

/// operation is synchronized. On the other hand, a store-load pair of [`Ordering::SeqCst`]

/// operations synchronize other memory while additionally preserving a total order of such

/// operations across all threads.

///

/// Rust's memory orderings are [the same as those of

/// C++20](https://en.cppreference.com/w/cpp/atomic/memory_order).

///

/// For more information see the [nomicon].

///

/// [nomicon]: ../../../nomicon/atomics.html

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg_attr(not(feature = "ferrocene_certified"), derive(Copy, Clone, Debug, Eq, PartialEq, Hash))]

#[cfg_attr(feature = "ferrocene_certified", derive(Copy, Clone))]

#[non_exhaustive]

#[rustc_diagnostic_item = "Ordering"]

pub enum Ordering {

    /// No ordering constraints, only atomic operations.

    ///

    /// Corresponds to [`memory_order_relaxed`] in C++20.

    ///

    /// [`memory_order_relaxed`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Relaxed_ordering

    #[stable(feature = "rust1", since = "1.0.0")]

    Relaxed,

    /// When coupled with a store, all previous operations become ordered

    /// before any load of this value with [`Acquire`] (or stronger) ordering.

    /// In particular, all previous writes become visible to all threads

    /// that perform an [`Acquire`] (or stronger) load of this value.

    ///

    /// Notice that using this ordering for an operation that combines loads

    /// and stores leads to a [`Relaxed`] load operation!

    ///

    /// This ordering is only applicable for operations that can perform a store.

    ///

    /// Corresponds to [`memory_order_release`] in C++20.

    ///

    /// [`memory_order_release`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Release-Acquire_ordering

    #[stable(feature = "rust1", since = "1.0.0")]

    Release,

    /// When coupled with a load, if the loaded value was written by a store operation with

    /// [`Release`] (or stronger) ordering, then all subsequent operations

    /// become ordered after that store. In particular, all subsequent loads will see data

    /// written before the store.

    ///

    /// Notice that using this ordering for an operation that combines loads

    /// and stores leads to a [`Relaxed`] store operation!

    ///

    /// This ordering is only applicable for operations that can perform a load.

    ///

    /// Corresponds to [`memory_order_acquire`] in C++20.

    ///

    /// [`memory_order_acquire`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Release-Acquire_ordering

    #[stable(feature = "rust1", since = "1.0.0")]

    Acquire,

    /// Has the effects of both [`Acquire`] and [`Release`] together:

    /// For loads it uses [`Acquire`] ordering. For stores it uses the [`Release`] ordering.

    ///

    /// Notice that in the case of `compare_and_swap`, it is possible that the operation ends up

    /// not performing any store and hence it has just [`Acquire`] ordering. However,

    /// `AcqRel` will never perform [`Relaxed`] accesses.

    ///

    /// This ordering is only applicable for operations that combine both loads and stores.

    ///

    /// Corresponds to [`memory_order_acq_rel`] in C++20.

    ///

    /// [`memory_order_acq_rel`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Release-Acquire_ordering

    #[stable(feature = "rust1", since = "1.0.0")]

    AcqRel,

    /// Like [`Acquire`]/[`Release`]/[`AcqRel`] (for load, store, and load-with-store

    /// operations, respectively) with the additional guarantee that all threads see all

    /// sequentially consistent operations in the same order.

    ///

    /// Corresponds to [`memory_order_seq_cst`] in C++20.

    ///

    /// [`memory_order_seq_cst`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Sequentially-consistent_ordering

    #[stable(feature = "rust1", since = "1.0.0")]

    SeqCst,

}

/// An [`AtomicBool`] initialized to `false`.

#[cfg(target_has_atomic_load_store = "8")]

#[stable(feature = "rust1", since = "1.0.0")]

#[deprecated(

    since = "1.34.0",

    note = "the `new` function is now preferred",

    suggestion = "AtomicBool::new(false)"

)]

#[cfg(not(feature = "ferrocene_certified"))]

pub const ATOMIC_BOOL_INIT: AtomicBool = AtomicBool::new(false);

#[cfg(target_has_atomic_load_store = "8")]

#[cfg(not(feature = "ferrocene_certified"))]

impl AtomicBool {

    /// Creates a new `AtomicBool`.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::AtomicBool;

    ///

    /// let atomic_true = AtomicBool::new(true);

    /// let atomic_false = AtomicBool::new(false);

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_const_stable(feature = "const_atomic_new", since = "1.24.0")]

    #[must_use]

    pub const fn new(v: bool) -> AtomicBool {

        AtomicBool { v: UnsafeCell::new(v as u8) }

    }

    /// Creates a new `AtomicBool` from a pointer.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::{self, AtomicBool};

    ///

    /// // Get a pointer to an allocated value

    /// let ptr: *mut bool = Box::into_raw(Box::new(false));

    ///

    /// assert!(ptr.cast::<AtomicBool>().is_aligned());

    ///

    /// {

    ///     // Create an atomic view of the allocated value

    ///     let atomic = unsafe { AtomicBool::from_ptr(ptr) };

    ///

    ///     // Use `atomic` for atomic operations, possibly share it with other threads

    ///     atomic.store(true, atomic::Ordering::Relaxed);

    /// }

    ///

    /// // It's ok to non-atomically access the value behind `ptr`,

    /// // since the reference to the atomic ended its lifetime in the block above

    /// assert_eq!(unsafe { *ptr }, true);

    ///

    /// // Deallocate the value

    /// unsafe { drop(Box::from_raw(ptr)) }

    /// ```

    ///

    /// # Safety

    ///

    /// * `ptr` must be aligned to `align_of::<AtomicBool>()` (note that this is always true, since

    ///   `align_of::<AtomicBool>() == 1`).

    /// * `ptr` must be [valid] for both reads and writes for the whole lifetime `'a`.

    /// * You must adhere to the [Memory model for atomic accesses]. In particular, it is not

    ///   allowed to mix conflicting atomic and non-atomic accesses, or atomic accesses of different

    ///   sizes, without synchronization.

    ///

    /// [valid]: crate::ptr#safety

    /// [Memory model for atomic accesses]: self#memory-model-for-atomic-accesses

    #[inline]

    #[stable(feature = "atomic_from_ptr", since = "1.75.0")]

    #[rustc_const_stable(feature = "const_atomic_from_ptr", since = "1.84.0")]

    pub const unsafe fn from_ptr<'a>(ptr: *mut bool) -> &'a AtomicBool {

        // SAFETY: guaranteed by the caller

        unsafe { &*ptr.cast() }

    }

    /// Returns a mutable reference to the underlying [`bool`].

    ///

    /// This is safe because the mutable reference guarantees that no other threads are

    /// concurrently accessing the atomic data.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let mut some_bool = AtomicBool::new(true);

    /// assert_eq!(*some_bool.get_mut(), true);

    /// *some_bool.get_mut() = false;

    /// assert_eq!(some_bool.load(Ordering::SeqCst), false);

    /// ```

    #[inline]

    #[stable(feature = "atomic_access", since = "1.15.0")]

    pub fn get_mut(&mut self) -> &mut bool {

        // SAFETY: the mutable reference guarantees unique ownership.

        unsafe { &mut *(self.v.get() as *mut bool) }

    }

    /// Gets atomic access to a `&mut bool`.

    ///

    /// # Examples

    ///

    /// ```

    /// #![feature(atomic_from_mut)]

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let mut some_bool = true;

    /// let a = AtomicBool::from_mut(&mut some_bool);

    /// a.store(false, Ordering::Relaxed);

    /// assert_eq!(some_bool, false);

    /// ```

    #[inline]

    #[cfg(target_has_atomic_equal_alignment = "8")]

    #[unstable(feature = "atomic_from_mut", issue = "76314")]

    pub fn from_mut(v: &mut bool) -> &mut Self {

        // SAFETY: the mutable reference guarantees unique ownership, and

        // alignment of both `bool` and `Self` is 1.

        unsafe { &mut *(v as *mut bool as *mut Self) }

    }

    /// Gets non-atomic access to a `&mut [AtomicBool]` slice.

    ///

    /// This is safe because the mutable reference guarantees that no other threads are

    /// concurrently accessing the atomic data.

    ///

    /// # Examples

    ///

    /// ```ignore-wasm

    /// #![feature(atomic_from_mut)]

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let mut some_bools = [const { AtomicBool::new(false) }; 10];

    ///

    /// let view: &mut [bool] = AtomicBool::get_mut_slice(&mut some_bools);

    /// assert_eq!(view, [false; 10]);

    /// view[..5].copy_from_slice(&[true; 5]);

    ///

    /// std::thread::scope(|s| {

    ///     for t in &some_bools[..5] {

    ///         s.spawn(move || assert_eq!(t.load(Ordering::Relaxed), true));

    ///     }

    ///

    ///     for f in &some_bools[5..] {

    ///         s.spawn(move || assert_eq!(f.load(Ordering::Relaxed), false));

    ///     }

    /// });

    /// ```

    #[inline]

    #[unstable(feature = "atomic_from_mut", issue = "76314")]

    pub fn get_mut_slice(this: &mut [Self]) -> &mut [bool] {

        // SAFETY: the mutable reference guarantees unique ownership.

        unsafe { &mut *(this as *mut [Self] as *mut [bool]) }

    }

    /// Gets atomic access to a `&mut [bool]` slice.

    ///

    /// # Examples

    ///

    /// ```rust,ignore-wasm

    /// #![feature(atomic_from_mut)]

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let mut some_bools = [false; 10];

    /// let a = &*AtomicBool::from_mut_slice(&mut some_bools);

    /// std::thread::scope(|s| {

    ///     for i in 0..a.len() {

    ///         s.spawn(move || a[i].store(true, Ordering::Relaxed));

    ///     }

    /// });

    /// assert_eq!(some_bools, [true; 10]);

    /// ```

    #[inline]

    #[cfg(target_has_atomic_equal_alignment = "8")]

    #[unstable(feature = "atomic_from_mut", issue = "76314")]

    pub fn from_mut_slice(v: &mut [bool]) -> &mut [Self] {

        // SAFETY: the mutable reference guarantees unique ownership, and

        // alignment of both `bool` and `Self` is 1.

        unsafe { &mut *(v as *mut [bool] as *mut [Self]) }

    }

    /// Consumes the atomic and returns the contained value.

    ///

    /// This is safe because passing `self` by value guarantees that no other threads are

    /// concurrently accessing the atomic data.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::AtomicBool;

    ///

    /// let some_bool = AtomicBool::new(true);

    /// assert_eq!(some_bool.into_inner(), true);

    /// ```

    #[inline]

    #[stable(feature = "atomic_access", since = "1.15.0")]

    #[rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0")]

    pub const fn into_inner(self) -> bool {

        self.v.into_inner() != 0

    }

    /// Loads a value from the bool.

    ///

    /// `load` takes an [`Ordering`] argument which describes the memory ordering

    /// of this operation. Possible values are [`SeqCst`], [`Acquire`] and [`Relaxed`].

    ///

    /// # Panics

    ///

    /// Panics if `order` is [`Release`] or [`AcqRel`].

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let some_bool = AtomicBool::new(true);

    ///

    /// assert_eq!(some_bool.load(Ordering::Relaxed), true);

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

    pub fn load(&self, order: Ordering) -> bool {

        // SAFETY: any data races are prevented by atomic intrinsics and the raw

        // pointer passed in is valid because we got it from a reference.

        unsafe { atomic_load(self.v.get(), order) != 0 }

    }

    /// Stores a value into the bool.

    ///

    /// `store` takes an [`Ordering`] argument which describes the memory ordering

    /// of this operation. Possible values are [`SeqCst`], [`Release`] and [`Relaxed`].

    ///

    /// # Panics

    ///

    /// Panics if `order` is [`Acquire`] or [`AcqRel`].

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let some_bool = AtomicBool::new(true);

    ///

    /// some_bool.store(false, Ordering::Relaxed);

    /// assert_eq!(some_bool.load(Ordering::Relaxed), false);

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

    pub fn store(&self, val: bool, order: Ordering) {

        // SAFETY: any data races are prevented by atomic intrinsics and the raw

        // pointer passed in is valid because we got it from a reference.

        unsafe {

            atomic_store(self.v.get(), val as u8, order);

        }

    }

    /// Stores a value into the bool, returning the previous value.

    ///

    /// `swap` takes an [`Ordering`] argument which describes the memory ordering

    /// of this operation. All ordering modes are possible. Note that using

    /// [`Acquire`] makes the store part of this operation [`Relaxed`], and

    /// using [`Release`] makes the load part [`Relaxed`].

    ///

    /// **Note:** This method is only available on platforms that support atomic

    /// operations on `u8`.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let some_bool = AtomicBool::new(true);

    ///

    /// assert_eq!(some_bool.swap(false, Ordering::Relaxed), true);

    /// assert_eq!(some_bool.load(Ordering::Relaxed), false);

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[cfg(target_has_atomic = "8")]

    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

    pub fn swap(&self, val: bool, order: Ordering) -> bool {

        if EMULATE_ATOMIC_BOOL {

            if val { self.fetch_or(true, order) } else { self.fetch_and(false, order) }

        } else {

            // SAFETY: data races are prevented by atomic intrinsics.

            unsafe { atomic_swap(self.v.get(), val as u8, order) != 0 }

        }

    }

    /// Stores a value into the [`bool`] if the current value is the same as the `current` value.

    ///

    /// The return value is always the previous value. If it is equal to `current`, then the value

    /// was updated.

    ///

    /// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory

    /// ordering of this operation. Notice that even when using [`AcqRel`], the operation

    /// might fail and hence just perform an `Acquire` load, but not have `Release` semantics.

    /// Using [`Acquire`] makes the store part of this operation [`Relaxed`] if it

    /// happens, and using [`Release`] makes the load part [`Relaxed`].

    ///

    /// **Note:** This method is only available on platforms that support atomic

    /// operations on `u8`.

    ///

    /// # Migrating to `compare_exchange` and `compare_exchange_weak`

    ///

    /// `compare_and_swap` is equivalent to `compare_exchange` with the following mapping for

    /// memory orderings:

    ///

    /// Original | Success | Failure

    /// -------- | ------- | -------

    /// Relaxed  | Relaxed | Relaxed

    /// Acquire  | Acquire | Acquire

    /// Release  | Release | Relaxed

    /// AcqRel   | AcqRel  | Acquire

    /// SeqCst   | SeqCst  | SeqCst

    ///

    /// `compare_and_swap` and `compare_exchange` also differ in their return type. You can use

    /// `compare_exchange(...).unwrap_or_else(|x| x)` to recover the behavior of `compare_and_swap`,

    /// but in most cases it is more idiomatic to check whether the return value is `Ok` or `Err`

    /// rather than to infer success vs failure based on the value that was read.

    ///

    /// During migration, consider whether it makes sense to use `compare_exchange_weak` instead.

    /// `compare_exchange_weak` is allowed to fail spuriously even when the comparison succeeds,

    /// which allows the compiler to generate better assembly code when the compare and swap

    /// is used in a loop.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let some_bool = AtomicBool::new(true);

    ///

    /// assert_eq!(some_bool.compare_and_swap(true, false, Ordering::Relaxed), true);

    /// assert_eq!(some_bool.load(Ordering::Relaxed), false);

    ///

    /// assert_eq!(some_bool.compare_and_swap(true, true, Ordering::Relaxed), false);

    /// assert_eq!(some_bool.load(Ordering::Relaxed), false);

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[deprecated(

        since = "1.50.0",

        note = "Use `compare_exchange` or `compare_exchange_weak` instead"

    )]

    #[cfg(target_has_atomic = "8")]

    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

    pub fn compare_and_swap(&self, current: bool, new: bool, order: Ordering) -> bool {

        match self.compare_exchange(current, new, order, strongest_failure_ordering(order)) {

            Ok(x) => x,

            Err(x) => x,

        }

    }

    /// Stores a value into the [`bool`] if the current value is the same as the `current` value.

    ///

    /// The return value is a result indicating whether the new value was written and containing

    /// the previous value. On success this value is guaranteed to be equal to `current`.

    ///

    /// `compare_exchange` takes two [`Ordering`] arguments to describe the memory

    /// ordering of this operation. `success` describes the required ordering for the

    /// read-modify-write operation that takes place if the comparison with `current` succeeds.

    /// `failure` describes the required ordering for the load operation that takes place when

    /// the comparison fails. Using [`Acquire`] as success ordering makes the store part

    /// of this operation [`Relaxed`], and using [`Release`] makes the successful load

    /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`].

    ///

    /// **Note:** This method is only available on platforms that support atomic

    /// operations on `u8`.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let some_bool = AtomicBool::new(true);

    ///

    /// assert_eq!(some_bool.compare_exchange(true,

    ///                                       false,

    ///                                       Ordering::Acquire,

    ///                                       Ordering::Relaxed),

    ///            Ok(true));

    /// assert_eq!(some_bool.load(Ordering::Relaxed), false);

    ///

    /// assert_eq!(some_bool.compare_exchange(true, true,

    ///                                       Ordering::SeqCst,

    ///                                       Ordering::Acquire),

    ///            Err(false));

    /// assert_eq!(some_bool.load(Ordering::Relaxed), false);

    /// ```

    ///

    /// # Considerations

    ///

    /// `compare_exchange` is a [compare-and-swap operation] and thus exhibits the usual downsides

    /// of CAS operations. In particular, a load of the value followed by a successful

    /// `compare_exchange` with the previous load *does not ensure* that other threads have not

    /// changed the value in the interim. This is usually important when the *equality* check in

    /// the `compare_exchange` is being used to check the *identity* of a value, but equality

    /// does not necessarily imply identity. In this case, `compare_exchange` can lead to the

    /// [ABA problem].

    ///

    /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem

    /// [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap

    #[inline]

    #[stable(feature = "extended_compare_and_swap", since = "1.10.0")]

    #[doc(alias = "compare_and_swap")]

    #[cfg(target_has_atomic = "8")]

    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

    pub fn compare_exchange(

        &self,

        current: bool,

        new: bool,

        success: Ordering,

        failure: Ordering,

    ) -> Result<bool, bool> {

        if EMULATE_ATOMIC_BOOL {

            // Pick the strongest ordering from success and failure.

            let order = match (success, failure) {

                (SeqCst, _) => SeqCst,

                (_, SeqCst) => SeqCst,

                (AcqRel, _) => AcqRel,

                (_, AcqRel) => {

                    panic!("there is no such thing as an acquire-release failure ordering")

                }

                (Release, Acquire) => AcqRel,

                (Acquire, _) => Acquire,

                (_, Acquire) => Acquire,

                (Release, Relaxed) => Release,

                (_, Release) => panic!("there is no such thing as a release failure ordering"),

                (Relaxed, Relaxed) => Relaxed,

            };

            let old = if current == new {

                // This is a no-op, but we still need to perform the operation

                // for memory ordering reasons.

                self.fetch_or(false, order)

            } else {

                // This sets the value to the new one and returns the old one.

                self.swap(new, order)

            };

            if old == current { Ok(old) } else { Err(old) }

        } else {

            // SAFETY: data races are prevented by atomic intrinsics.

            match unsafe {

                atomic_compare_exchange(self.v.get(), current as u8, new as u8, success, failure)

            } {

                Ok(x) => Ok(x != 0),

                Err(x) => Err(x != 0),

            }

        }

    }

    /// Stores a value into the [`bool`] if the current value is the same as the `current` value.

    ///

    /// Unlike [`AtomicBool::compare_exchange`], this function is allowed to spuriously fail even when the

    /// comparison succeeds, which can result in more efficient code on some platforms. The

    /// return value is a result indicating whether the new value was written and containing the

    /// previous value.

    ///

    /// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory

    /// ordering of this operation. `success` describes the required ordering for the

    /// read-modify-write operation that takes place if the comparison with `current` succeeds.

    /// `failure` describes the required ordering for the load operation that takes place when

    /// the comparison fails. Using [`Acquire`] as success ordering makes the store part

    /// of this operation [`Relaxed`], and using [`Release`] makes the successful load

    /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`].

    ///

    /// **Note:** This method is only available on platforms that support atomic

    /// operations on `u8`.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let val = AtomicBool::new(false);

    ///

    /// let new = true;

    /// let mut old = val.load(Ordering::Relaxed);

    /// loop {

    ///     match val.compare_exchange_weak(old, new, Ordering::SeqCst, Ordering::Relaxed) {

    ///         Ok(_) => break,

    ///         Err(x) => old = x,

    ///     }

    /// }

    /// ```

    ///

    /// # Considerations

    ///

    /// `compare_exchange` is a [compare-and-swap operation] and thus exhibits the usual downsides

    /// of CAS operations. In particular, a load of the value followed by a successful

    /// `compare_exchange` with the previous load *does not ensure* that other threads have not

    /// changed the value in the interim. This is usually important when the *equality* check in

    /// the `compare_exchange` is being used to check the *identity* of a value, but equality

    /// does not necessarily imply identity. In this case, `compare_exchange` can lead to the

    /// [ABA problem].

    ///

    /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem

    /// [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap

    #[inline]

    #[stable(feature = "extended_compare_and_swap", since = "1.10.0")]

    #[doc(alias = "compare_and_swap")]

    #[cfg(target_has_atomic = "8")]

    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

    pub fn compare_exchange_weak(

        &self,

        current: bool,

        new: bool,

        success: Ordering,

        failure: Ordering,

    ) -> Result<bool, bool> {

        if EMULATE_ATOMIC_BOOL {

            return self.compare_exchange(current, new, success, failure);

        }

        // SAFETY: data races are prevented by atomic intrinsics.

        match unsafe {

            atomic_compare_exchange_weak(self.v.get(), current as u8, new as u8, success, failure)

        } {

            Ok(x) => Ok(x != 0),

            Err(x) => Err(x != 0),

        }

    }

    /// Logical "and" with a boolean value.

    ///

    /// Performs a logical "and" operation on the current value and the argument `val`, and sets

    /// the new value to the result.

    ///

    /// Returns the previous value.

    ///

    /// `fetch_and` takes an [`Ordering`] argument which describes the memory ordering

    /// of this operation. All ordering modes are possible. Note that using

    /// [`Acquire`] makes the store part of this operation [`Relaxed`], and

    /// using [`Release`] makes the load part [`Relaxed`].

    ///

    /// **Note:** This method is only available on platforms that support atomic

    /// operations on `u8`.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let foo = AtomicBool::new(true);

    /// assert_eq!(foo.fetch_and(false, Ordering::SeqCst), true);

    /// assert_eq!(foo.load(Ordering::SeqCst), false);

    ///

    /// let foo = AtomicBool::new(true);

    /// assert_eq!(foo.fetch_and(true, Ordering::SeqCst), true);

    /// assert_eq!(foo.load(Ordering::SeqCst), true);

    ///

    /// let foo = AtomicBool::new(false);

    /// assert_eq!(foo.fetch_and(false, Ordering::SeqCst), false);

    /// assert_eq!(foo.load(Ordering::SeqCst), false);

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[cfg(target_has_atomic = "8")]

    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

    pub fn fetch_and(&self, val: bool, order: Ordering) -> bool {

        // SAFETY: data races are prevented by atomic intrinsics.

        unsafe { atomic_and(self.v.get(), val as u8, order) != 0 }

    }

    /// Logical "nand" with a boolean value.

    ///

    /// Performs a logical "nand" operation on the current value and the argument `val`, and sets

    /// the new value to the result.

    ///

    /// Returns the previous value.

    ///

    /// `fetch_nand` takes an [`Ordering`] argument which describes the memory ordering

    /// of this operation. All ordering modes are possible. Note that using

    /// [`Acquire`] makes the store part of this operation [`Relaxed`], and

    /// using [`Release`] makes the load part [`Relaxed`].

    ///

    /// **Note:** This method is only available on platforms that support atomic

    /// operations on `u8`.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let foo = AtomicBool::new(true);

    /// assert_eq!(foo.fetch_nand(false, Ordering::SeqCst), true);

    /// assert_eq!(foo.load(Ordering::SeqCst), true);

    ///

    /// let foo = AtomicBool::new(true);

    /// assert_eq!(foo.fetch_nand(true, Ordering::SeqCst), true);

    /// assert_eq!(foo.load(Ordering::SeqCst) as usize, 0);

    /// assert_eq!(foo.load(Ordering::SeqCst), false);

    ///

    /// let foo = AtomicBool::new(false);

    /// assert_eq!(foo.fetch_nand(false, Ordering::SeqCst), false);

    /// assert_eq!(foo.load(Ordering::SeqCst), true);

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[cfg(target_has_atomic = "8")]

    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

    pub fn fetch_nand(&self, val: bool, order: Ordering) -> bool {

        // We can't use atomic_nand here because it can result in a bool with

        // an invalid value. This happens because the atomic operation is done

        // with an 8-bit integer internally, which would set the upper 7 bits.

        // So we just use fetch_xor or swap instead.

        if val {

            // !(x & true) == !x

            // We must invert the bool.

            self.fetch_xor(true, order)

        } else {

            // !(x & false) == true

            // We must set the bool to true.

            self.swap(true, order)

        }

    }

    /// Logical "or" with a boolean value.

    ///

    /// Performs a logical "or" operation on the current value and the argument `val`, and sets the

    /// new value to the result.

    ///

    /// Returns the previous value.

    ///

    /// `fetch_or` takes an [`Ordering`] argument which describes the memory ordering

    /// of this operation. All ordering modes are possible. Note that using

    /// [`Acquire`] makes the store part of this operation [`Relaxed`], and

    /// using [`Release`] makes the load part [`Relaxed`].

    ///

    /// **Note:** This method is only available on platforms that support atomic

    /// operations on `u8`.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let foo = AtomicBool::new(true);

    /// assert_eq!(foo.fetch_or(false, Ordering::SeqCst), true);

    /// assert_eq!(foo.load(Ordering::SeqCst), true);

    ///

    /// let foo = AtomicBool::new(true);

    /// assert_eq!(foo.fetch_or(true, Ordering::SeqCst), true);

    /// assert_eq!(foo.load(Ordering::SeqCst), true);

    ///

    /// let foo = AtomicBool::new(false);

    /// assert_eq!(foo.fetch_or(false, Ordering::SeqCst), false);

    /// assert_eq!(foo.load(Ordering::SeqCst), false);

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[cfg(target_has_atomic = "8")]

    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

    pub fn fetch_or(&self, val: bool, order: Ordering) -> bool {

        // SAFETY: data races are prevented by atomic intrinsics.

        unsafe { atomic_or(self.v.get(), val as u8, order) != 0 }

    }

    /// Logical "xor" with a boolean value.

    ///

    /// Performs a logical "xor" operation on the current value and the argument `val`, and sets

    /// the new value to the result.

    ///

    /// Returns the previous value.

    ///

    /// `fetch_xor` takes an [`Ordering`] argument which describes the memory ordering

    /// of this operation. All ordering modes are possible. Note that using

    /// [`Acquire`] makes the store part of this operation [`Relaxed`], and

    /// using [`Release`] makes the load part [`Relaxed`].

    ///

    /// **Note:** This method is only available on platforms that support atomic

    /// operations on `u8`.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let foo = AtomicBool::new(true);

    /// assert_eq!(foo.fetch_xor(false, Ordering::SeqCst), true);

    /// assert_eq!(foo.load(Ordering::SeqCst), true);

    ///

    /// let foo = AtomicBool::new(true);

    /// assert_eq!(foo.fetch_xor(true, Ordering::SeqCst), true);

    /// assert_eq!(foo.load(Ordering::SeqCst), false);

    ///

    /// let foo = AtomicBool::new(false);

    /// assert_eq!(foo.fetch_xor(false, Ordering::SeqCst), false);

    /// assert_eq!(foo.load(Ordering::SeqCst), false);

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[cfg(target_has_atomic = "8")]

    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

    pub fn fetch_xor(&self, val: bool, order: Ordering) -> bool {

        // SAFETY: data races are prevented by atomic intrinsics.

        unsafe { atomic_xor(self.v.get(), val as u8, order) != 0 }

    }

    /// Logical "not" with a boolean value.

    ///

    /// Performs a logical "not" operation on the current value, and sets

    /// the new value to the result.

    ///

    /// Returns the previous value.

    ///

    /// `fetch_not` takes an [`Ordering`] argument which describes the memory ordering

    /// of this operation. All ordering modes are possible. Note that using

    /// [`Acquire`] makes the store part of this operation [`Relaxed`], and

    /// using [`Release`] makes the load part [`Relaxed`].

    ///

    /// **Note:** This method is only available on platforms that support atomic

    /// operations on `u8`.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::sync::atomic::{AtomicBool, Ordering};

    ///

    /// let foo = AtomicBool::new(true);

    /// assert_eq!(foo.fetch_not(Ordering::SeqCst), true);

    /// assert_eq!(foo.load(Ordering::SeqCst), false);

    ///

    /// let foo = AtomicBool::new(false);

    /// assert_eq!(foo.fetch_not(Ordering::SeqCst), false);

    /// assert_eq!(foo.load(Ordering::SeqCst), true);

    /// ```

    #[inline]

    #[stable(feature = "atomic_bool_fetch_not", since = "1.81.0")]

    #[cfg(target_has_atomic = "8")]

    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces

    pub fn fetch_not(&self, order: Ordering) -> bool {

        self.fetch_xor(true, order)

    }

    /// Returns a mutable pointer to the underlying [`bool`].

    ///

    /// Doing non-atomic reads and writes on the resulting boolean can be a data race.

    /// This method is mostly useful for FFI, where the function signature may use

    /// `*mut bool` instead of `&AtomicBool`.

    ///

    /// Returning an `*mut` pointer from a shared reference to this atomic is safe because the

    /// atomic types work with interior mutability. All modifications of an atomic change the value

    /// through a shared reference, and can do so safely as long as they use atomic operations. Any

    /// use of the returned raw pointer requires an `unsafe` block and still has to uphold the

    /// requirements of the [memory model].

    ///

    /// # Examples

    ///

    /// ```ignore (extern-declaration)

    /// # fn main() {

    /// use std::sync::atomic::AtomicBool;

    ///

    /// extern "C" {

    ///     fn my_atomic_op(arg: *mut bool);

    /// }

    ///

    /// let mut atomic = AtomicBool::new(true);

    /// unsafe {

    ///     my_atomic_op(atomic.as_ptr());

    /// }

    /// # }

    /// ```

    ///

    /// [memory model]: self#memory-model-for-atomic-accesses

    #[inline]

    #[stable(feature = "atomic_as_ptr", since = "1.70.0")]

    #[rustc_const_stable(feature = "atomic_as_ptr", since = "1.70.0")]

    #[rustc_never_returns_null_ptr]

    pub const fn as_ptr(&self) -> *mut bool {

        self.v.get().cast()

    }

    /// Fetches the value, and applies a function to it that returns an optional

    /// new value. Returns a `Result` of `Ok(previous_value)` if the function

    /// returned `Some(_)`, else `Err(previous_value)`.

    ///

    /// Note: This may call the function multiple times if the value has been

    /// changed from other threads in the meantime, as long as the function

    /// returns `Some(_)`, but the function will have been applied only once to

    /// the stored value.

    ///

    /// `fetch_update` takes two [`Ordering`] arguments to describe the memory

    /// ordering of this operation. The first describes the required ordering for

    /// when the operation finally succeeds while the second describes the

    /// required ordering for loads. These correspond to the success and failure

    /// orderings of [`AtomicBool::compare_exchange`] respectively.

    ///

    /// Using [`Acquire`] as success ordering makes the store part of this

    /// operation [`Relaxed`], and using [`Release`] makes the final successful

    /// load [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`],

    /// [`Acquire`] or [`Relaxed`].

    ///

    /// **Note:** This method is only available on platforms that support atomic