Struct std::sync::atomic::AtomicPtr

#[repr(C, align(8))]
pub struct AtomicPtr<T> { /* fields omitted */ }

可以在线程之间安全共享的裸指针类型。

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

Note: 此类型仅在支持原子加载和指针存储的平台上可用。 它的大小取决于目标指针的大小。

Implementations

impl<T> AtomicPtr<T>

pub const fn new(p: *mut T) -> AtomicPtr<T>

创建一个新的 AtomicPtr。

Examples

use std::sync::atomic::AtomicPtr;

let ptr = &mut 5;
let atomic_ptr  = AtomicPtr::new(ptr);

pub fn get_mut(&mut self) -> &mut *mut T

返回基础指针的可变引用。

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

Examples

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

let mut data = 10;
let mut atomic_ptr = AtomicPtr::new(&mut data);
let mut other_data = 5;
*atomic_ptr.get_mut() = &mut other_data;
assert_eq!(unsafe { *atomic_ptr.load(Ordering::SeqCst) }, 5);

pub fn from_mut(v: &mut *mut T) -> &AtomicPtr<T>

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

获得对指针的原子访问。

Examples

#![feature(atomic_from_mut)]
use std::sync::atomic::{AtomicPtr, Ordering};

let mut data = 123;
let mut some_ptr = &mut data as *mut i32;
let a = AtomicPtr::from_mut(&mut some_ptr);
let mut other_data = 456;
a.store(&mut other_data, Ordering::Relaxed);
assert_eq!(unsafe { *some_ptr }, 456);

pub const fn into_inner(self) -> *mut T

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

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

Examples

use std::sync::atomic::AtomicPtr;

let mut data = 5;
let atomic_ptr = AtomicPtr::new(&mut data);
assert_eq!(unsafe { *atomic_ptr.into_inner() }, 5);

pub fn load(&self, order: Ordering) -> *mut T

从指针加载一个值。

load 采用 Ordering 参数，该参数描述此操作的内存顺序。 可能的值为 SeqCst，Acquire 和 Relaxed。

Panics

如果 order 是 Release 或 AcqRel，则为 Panics。

Examples

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

let ptr = &mut 5;
let some_ptr  = AtomicPtr::new(ptr);

let value = some_ptr.load(Ordering::Relaxed);

pub fn store(&self, ptr: *mut T, order: Ordering)

将值存储到指针中。

store 采用 Ordering 参数，该参数描述此操作的内存顺序。 可能的值为 SeqCst，Release 和 Relaxed。

Panics

如果 order 是 Acquire 或 AcqRel，则为 Panics。

Examples

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

let ptr = &mut 5;
let some_ptr  = AtomicPtr::new(ptr);

let other_ptr = &mut 10;

some_ptr.store(other_ptr, Ordering::Relaxed);

pub fn swap(&self, ptr: *mut T, order: Ordering) -> *mut T

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

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

Note: 此方法仅在支持对指针进行原子操作的平台上可用。

Examples

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

let ptr = &mut 5;
let some_ptr  = AtomicPtr::new(ptr);

let other_ptr = &mut 10;

let value = some_ptr.swap(other_ptr, Ordering::Relaxed);

pub fn compare_and_swap(
    &self,
    current: *mut T,
    new: *mut T,
    order: Ordering
) -> *mut T

👎 Deprecated since 1.50.0:

Use compare_exchange or compare_exchange_weak instead

如果当前值与 current 值相同，则将一个值存储到指针中。

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

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

Note: 此方法仅在支持对指针进行原子操作的平台上可用。

迁移到 compare_exchange 和 compare_exchange_weak

compare_and_swap 与 compare_exchange 等效，具有以下有关内存顺序的映射:

Original	Success	Failure
Relaxed	Relaxed	Relaxed Acquire

compare_exchange_weak 即使比较成功，也允许错误地失败，这允许在循环中使用 compare 和 swap 时编译器生成更好的汇编代码。

Examples

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

let ptr = &mut 5;
let some_ptr  = AtomicPtr::new(ptr);

let other_ptr   = &mut 10;

let value = some_ptr.compare_and_swap(ptr, other_ptr, Ordering::Relaxed);

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

如果当前值与 current 值相同，则将一个值存储到指针中。

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

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

失败排序只能是 SeqCst，Acquire 或 Relaxed，并且必须等于或弱于成功排序。

Note: 此方法仅在支持对指针进行原子操作的平台上可用。

Examples

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

let ptr = &mut 5;
let some_ptr  = AtomicPtr::new(ptr);

let other_ptr   = &mut 10;

let value = some_ptr.compare_exchange(ptr, other_ptr,
                                      Ordering::SeqCst, Ordering::Relaxed);

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

如果当前值与 current 值相同，则将一个值存储到指针中。

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

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

compare_exchange_weak 需要两个 Ordering 参数来描述此操作的内存顺序。 success 描述了如果与 current 的比较成功，则进行读 - 修改 - 写操作所需的顺序。 failure 描述比较失败时发生的加载操作所需的顺序。 使用 Acquire 作为成功排序，使存储成为操作 Relaxed 的一部分，而使用 Release，则使装载成功 Relaxed。 失败排序只能是 SeqCst，Acquire 或 Relaxed，并且必须等于或弱于成功排序。

Note: 此方法仅在支持对指针进行原子操作的平台上可用。

Examples

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

let some_ptr = AtomicPtr::new(&mut 5);

let new = &mut 10;
let mut old = some_ptr.load(Ordering::Relaxed);
loop {
    match some_ptr.compare_exchange_weak(old, new, Ordering::SeqCst, Ordering::Relaxed) {
        Ok(_) => break,
        Err(x) => old = x,
    }
}

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

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

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

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

使用 Acquire 作为成功排序，使存储成为该操作 Relaxed 的一部分，而使用 Release，则使最终成功加载 Relaxed。 (failed) 负载排序只能是 SeqCst，Acquire 或 Relaxed，并且必须等于或小于成功排序。

Note: 此方法仅在支持对指针进行原子操作的平台上可用。

Examples

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

let ptr: *mut _ = &mut 5;
let some_ptr = AtomicPtr::new(ptr);

let new: *mut _ = &mut 10;
assert_eq!(some_ptr.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |_| None), Err(ptr));
let result = some_ptr.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| {
    if x == ptr {
        Some(new)
    } else {
        None
    }
});
assert_eq!(result, Ok(ptr));
assert_eq!(some_ptr.load(Ordering::SeqCst), new);

Trait Implementations

impl<T> Debug for AtomicPtr<T>

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

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

impl<T> Default for AtomicPtr<T>

pub fn default() -> AtomicPtr<T>

创建一个空 AtomicPtr<T>。

impl<T> From<*mut T> for AtomicPtr<T>

pub fn from(p: *mut T) -> AtomicPtr<T>

执行转换。

impl<T> Pointer for AtomicPtr<T>

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

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

impl<T> RefUnwindSafe for AtomicPtr<T>

impl<T> Send for AtomicPtr<T>

impl<T> Sync for AtomicPtr<T>