Struct core::sync::atomic::AtomicBool

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

可以在线程之间安全共享的布尔类型。

此类型与 bool 具有相同的内存表示形式。

Note: 此类型仅在支持 u8 的原子加载和存储的平台上可用。

Implementations

impl AtomicBool

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

创建一个新的 AtomicBool。

Examples

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

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

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

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

从指针创建一个新的 AtomicBool。

Examples

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

// 获取指向分配值的指针
let ptr: *mut bool = Box::into_raw(Box::new(false));

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

{
    // 创建分配值的原子视图
    let atomic = unsafe { AtomicBool::from_ptr(ptr) };

    // 使用 `atomic` 进行原子操作，可能与其他线程共享
    atomic.store(true, atomic::Ordering::Relaxed);
}

// 可以非原子地访问 `ptr` 后面的值，因为对原子的引用在上面的块中结束了它的生命周期
assert_eq!(unsafe { *ptr }, true);

// 释放值
unsafe { drop(Box::from_raw(ptr)) }

Safety

• ptr 必须与 align_of::<AtomicBool>() 对齐 (请注意，在某些平台上，它可能比 align_of::<bool>() 大)。
• 对于整个生命周 'a 的读取和写入，ptr 必须是 valid。
• 整个生命周 'a 都不能通过非原子操作访问到 ptr 后面的值。

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

返回底层 bool 的可变引用。

这是安全的，因为可变引用保证没有其他线程同时访问原子数据。

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 Self

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

获得对 &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 [Self]) -> &mut [bool]

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

获得对 &mut [AtomicBool] 切片的非原子访问。

这是安全的，因为可变引用保证没有其他线程同时访问原子数据。

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 [Self]

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

获得对 &mut [bool] 切片的原子访问。

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

pub fn into_inner(self) -> bool

消耗原子并返回包含的值。

这是安全的，因为按值传递 self 可以确保没有其他线程同时访问原子数据。

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

从 bool 加载一个值。

load 需要一个 Ordering 参数，它描述了这个操作的内存顺序。 可能的值为 SeqCst，Acquire 和 Relaxed。

Panics

如果 order 是 Release 或 AcqRel，就会出现 panics。

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)

将值存储到 bool 中。

store 需要一个 Ordering 参数，它描述了这个操作的内存顺序。 可能的值为 SeqCst，Release 和 Relaxed。

Panics

如果 order 是 Acquire 或 AcqRel，就会出现 panics。

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

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

将值存储到 bool 中，返回前一个值。

swap 需要一个 Ordering 参数，它描述了这个操作的内存顺序。所有排序模式都是可能的。 请注意，使用 Acquire 会使该操作成为存储部分 Relaxed，而使用 Release 会使装入部分成为 Relaxed。

Note: 此方法仅在支持 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);

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

👎Deprecated since 1.50.0: Use compare_exchange or compare_exchange_weak instead

如果当前值与 current 值相同，则将值存储到 bool 中。

返回值始终是前一个值。如果等于 current，则该值已更新。

compare_and_swap 还带有一个 Ordering 参数，它描述了此操作的内存顺序。 请注意，即使使用 AcqRel，该操作也可能失败，因此仅执行 Acquire 加载，但没有 Release 语义。 如果发生此操作，则使用 Acquire 使其成为该操作 Relaxed 的存储部分，而使用 Release 使该操作成为存储部分 Relaxed。

Note: 此方法仅在支持 u8 上原子操作的平台上可用。

迁移到 compare_exchange 和 compare_exchange_weak

compare_and_swap 等效于 compare_exchange，具有以下内存排序映射：

Original	Success	Failure
Relaxed	Relaxed	Relaxed Acquire

即使比较成功，compare_exchange_weak 也允许虚假失败，这允许编译器在循环中使用比较和交换时生成更好的汇编代码。

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

pub fn compare_exchange( &self, current: bool, new: bool, success: Ordering, failure: Ordering ) -> Result<bool, bool>

如果当前值与 current 值相同，则将值存储到 bool 中。

返回值是指示是否写入了新值并包含先前值的结果。 成功后，此值保证等于 current。

compare_exchange 需要两个 Ordering 参数来描述这个操作的内存顺序。 success 描述了在与 current 的比较成功时发生的读取 - 修改 - 写入操作所需的顺序。 failure 描述了比较失败时发生的加载操作所需的排序。 使用 Acquire 作为成功排序，使存储成为操作 Relaxed 的一部分，而使用 Release，则使装载成功 Relaxed。

故障顺序只能是 SeqCst、Acquire 或 Relaxed。

Note: 此方法仅在支持 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);

pub fn compare_exchange_weak( &self, current: bool, new: bool, success: Ordering, failure: Ordering ) -> Result<bool, bool>

如果当前值与 current 值相同，则将值存储到 bool 中。

与 AtomicBool::compare_exchange 不同，即使比较成功，也允许该函数错误地失败，这可能导致某些平台上的代码效率更高。

返回值是指示是否写入了新值并包含先前值的结果。

compare_exchange_weak 需要两个 Ordering 参数来描述这个操作的内存顺序。 success 描述了在与 current 的比较成功时发生的读取 - 修改 - 写入操作所需的顺序。 failure 描述了比较失败时发生的加载操作所需的排序。 使用 Acquire 作为成功排序，使存储成为操作 Relaxed 的一部分，而使用 Release，则使装载成功 Relaxed。 故障顺序只能是 SeqCst、Acquire 或 Relaxed。

Note: 此方法仅在支持 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,
    }
}

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

具有布尔值的逻辑 “and”。

对当前值和参数 val 执行逻辑 “and” 运算，并将新值设置为结果。

返回前一个值。

fetch_and 需要一个 Ordering 参数，它描述了这个操作的内存顺序。所有排序模式都是可能的。 请注意，使用 Acquire 会使该操作成为存储部分 Relaxed，而使用 Release 会使装入部分成为 Relaxed。

Note: 此方法仅在支持 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);

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

具有布尔值的逻辑 “nand”。

对当前值和参数 val 执行逻辑 “nand” 运算，并将新值设置为结果。

返回前一个值。

fetch_nand 需要一个 Ordering 参数，它描述了这个操作的内存顺序。所有排序模式都是可能的。 请注意，使用 Acquire 会使该操作成为存储部分 Relaxed，而使用 Release 会使装入部分成为 Relaxed。

Note: 此方法仅在支持 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);

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

具有布尔值的逻辑 “or”。

对当前值和参数 val 执行逻辑 “or” 运算，并将新值设置为结果。

返回前一个值。

fetch_or 需要一个 Ordering 参数，它描述了这个操作的内存顺序。所有排序模式都是可能的。 请注意，使用 Acquire 会使该操作成为存储部分 Relaxed，而使用 Release 会使装入部分成为 Relaxed。

Note: 此方法仅在支持 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);

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

具有布尔值的逻辑 “xor”。

对当前值和参数 val 执行逻辑 “xor” 运算，并将新值设置为结果。

返回前一个值。

fetch_xor 需要一个 Ordering 参数，它描述了这个操作的内存顺序。所有排序模式都是可能的。 请注意，使用 Acquire 会使该操作成为存储部分 Relaxed，而使用 Release 会使装入部分成为 Relaxed。

Note: 此方法仅在支持 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);

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

🔬This is a nightly-only experimental API. (atomic_bool_fetch_not #98485)

具有布尔值的逻辑 “not”。

对当前值执行逻辑 “not” 运算，并将新值设置为结果。

返回前一个值。

fetch_not 接受一个 Ordering 参数，它描述了这个操作的内存顺序。所有排序模式都是可能的。 请注意，使用 Acquire 会使该操作成为存储部分 Relaxed，而使用 Release 会使装入部分成为 Relaxed。

Note: 此方法仅在支持 u8 上原子操作的平台上可用。

Examples

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

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

返回指向底层 bool 的可变指针。

在结果整数上进行非原子读取和写入可以是数据竞争。 此方法对 FFI 最为有用，在 FFI 中，函数签名可以使用 *mut bool 而不是 &AtomicBool。

从共享引用返回 *mut 指针到此原子是安全的，因为原子类型可与内部可变性一起使用。 原子的所有修改都通过共享的 quot 更改值，并且只要它们使用原子操作就可以安全地进行更改。 对返回的裸指针的任何使用都需要一个 unsafe 块，并且仍然必须遵守相同的限制：对其进行的操作必须是原子的。

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

pub fn fetch_update<F>( &self, set_order: Ordering, fetch_order: Ordering, f: F ) -> Result<bool, bool>where F: FnMut(bool) -> Option<bool>,

获取该值，并对其应用一个函数，该函数返回一个可选的新值。如果函数返回 Some(_)，则返回 Ok(previous_value) 的 Result，否则返回 Err(previous_value)。

Note: 如果与此同时从其他线程更改了值，则只要函数返回 Some(_)，这可能会多次调用该函数，但是该函数仅对存储的值应用一次。

fetch_update 需要两个 Ordering 参数来描述这个操作的内存顺序。 第一个描述了操作最终成功时所需的顺序，第二个描述了负载所需的顺序。 这些分别对应于 AtomicBool::compare_exchange 的成功和失败顺序。

使用 Acquire 作为成功排序，使存储成为该操作 Relaxed 的一部分，而使用 Release，则使最终成功加载 Relaxed。 (failed) 加载顺序只能是 SeqCst、Acquire 或 Relaxed。

Note: 此方法仅在支持 u8 上原子操作的平台上可用。

Considerations

这种方法并不神奇; 它不是由硬件提供的。 它是根据 AtomicBool::compare_exchange_weak 实现的，并且具有相同的缺点。 特别是，这种方法不会绕过 ABA Problem。

Examples

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

let x = AtomicBool::new(false);
assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |_| None), Err(false));
assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(!x)), Ok(false));
assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(!x)), Ok(true));
assert_eq!(x.load(Ordering::SeqCst), false);

Trait Implementations

impl Debug for AtomicBool

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

使用给定的格式化程序格式化该值。

impl Default for AtomicBool

fn default() -> Self

创建一个初始化为 false 的 AtomicBool。

impl From<bool> for AtomicBool

fn from(b: bool) -> Self

将 bool 转换为 AtomicBool。

Examples

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

impl RefUnwindSafe for AtomicBool

impl Sync for AtomicBool