# Struct atomic_polyfill::AtomicBool

1.0.0 ·

    #[repr(C, align(1))]pub struct AtomicBool { /* private fields */ }

Expand description

A boolean type which can be safely shared between threads.

This type has the same in-memory representation as a [`bool`].

Note: This type is only available on platforms that support atomic loads and stores of `u8`.

## Implementations§

§

### impl AtomicBool

const: 1.24.0

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

Creates a new `AtomicBool`.

##### Examples

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

    let atomic_true = AtomicBool::new(true);
    let atomic_false = AtomicBool::new(false);

const: unstable

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

🔬This is a nightly-only experimental API. (`atomic_from_ptr`)

Creates a new `AtomicBool` from a pointer.

##### Examples

    #![feature(atomic_from_ptr, pointer_is_aligned)]
    use std::sync::atomic::{self, AtomicBool};
    use std::mem::align_of;

    // Get a pointer to an allocated value
    let ptr: *mut bool = Box::into_raw(Box::new(false));

    assert!(ptr.is_aligned_to(align_of::<AtomicBool>()));

    {
        // 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 on some platforms this can be bigger than `align_of::<bool>()`).
- `ptr` must be valid for both reads and writes for the whole lifetime `'a`.
- The value behind `ptr` must not be accessed through non-atomic operations for the whole lifetime `'a`.

1.15.0

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

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);

#### pub fn from_mut(v: &mut bool) -> &mut AtomicBool

🔬This is a nightly-only experimental API. (`atomic_from_mut`)

Get 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);

#### pub fn get_mut_slice(this: &mut [AtomicBool]) -> &mut [bool]

🔬This is a nightly-only experimental API. (`atomic_from_mut`)

Get 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

    #![feature(atomic_from_mut, inline_const)]
    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));
        }
    });

#### pub fn from_mut_slice(v: &mut [bool]) -> &mut [AtomicBool]

🔬This is a nightly-only experimental API. (`atomic_from_mut`)

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

##### Examples

    #![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]);

1.15.0 (const: unstable)

#### pub fn into_inner(self) -> bool

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);

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

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);

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

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);

1.70.0 (const: 1.70.0)

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

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

Doing non-atomic reads and writes on the resulting integer 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 same restriction: operations on it must be atomic.

##### Examples

ⓘ

    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());
    }

## Trait Implementations§

1.3.0 §

### impl Debug for AtomicBool

§

#### fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
§

### impl Default for AtomicBool

§

#### fn default() -> AtomicBool

Creates an `AtomicBool` initialized to `false`.

1.24.0 §

### impl From<bool> for AtomicBool

§

#### fn from(b: bool) -> AtomicBool

Converts a `bool` into an `AtomicBool`.

##### Examples

    use std::sync::atomic::AtomicBool;
    let atomic_bool = AtomicBool::from(true);
    assert_eq!(format!("{atomic_bool:?}"), "true")

1.14.0 §

### impl RefUnwindSafe for AtomicBool

§

### impl Sync for AtomicBool

## Auto Trait Implementations§

§

### impl Send for AtomicBool

§

### impl Unpin for AtomicBool

§

### impl UnwindSafe for AtomicBool

## Blanket Implementations§

§

### impl<T> Any for Twhere T: 'static + ?Sized,

§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
§

### impl<T> Borrow<T> for Twhere T: ?Sized,

§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
§

### impl<T> BorrowMut<T> for Twhere T: ?Sized,

§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

### impl<T> From<T> for T

§

#### fn from(t: T) -> T

Returns the argument unchanged.

§

### impl<T, U> Into<U> for Twhere U: From<T>,

§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `[From]<T> for U` chooses to do.

§

### impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

#### type Error = Infallible

The type returned in the event of a conversion error.
§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
§

### impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.