Struct std::sync::RwLock

pub struct RwLock<T: ?Sized> { /* private fields */ }

reader-writer 锁

这种类型的锁定在任何时间点都允许多个 readers 或最多一个 writer。 此锁的写入部分通常允许修改底层数据 (独占访问)，而此锁的读取部分通常允许进行只读访问 (共享访问)。

相比之下，Mutex 不会区分获取锁定的 readers 或 writers，因此会阻塞等待锁定变为可用的所有线程。 RwLock 将允许任意数量的 readers 获取锁，只要 writer 不持有该锁即可。

锁定的优先级策略取决于底层操作系统的实现，并且这种类型不能保证将使用任何特定的策略。 特别是，等待获取 write 中的锁的 writer 可能会也可能不会阻止对 read 的并发调用，例如：

潜在的死锁示例

// Thread 1             |  // Thread 2
let _rg = lock.read();  |
                        |  // 会阻塞
                        |  let _wg = lock.write();
// 可能会陷入僵局         |
let _rg = lock.read();  |

类型参数 T 表示此锁保护的数据。 要求 T 满足 Send 在线程之间共享，并且 Sync 允许通过 readers 进行并发访问。 从锁定方法返回的 RAII 防护实现 Deref (对于 write 方法为 DerefMut) 以允许访问锁的内容。

Poisoning

RwLock 和 Mutex 一样，将在 panic 上中毒。 但是请注意，仅当 0panic 处于独占锁定状态 (写模式) 时，RwLock 才可能中毒。如果在任何 reader 中出现 panic，则锁不会中毒。

Examples

use std::sync::RwLock;

let lock = RwLock::new(5);

// 可以一次持有许多 reader 锁
{
    let r1 = lock.read().unwrap();
    let r2 = lock.read().unwrap();
    assert_eq!(*r1, 5);
    assert_eq!(*r2, 5);
} // 此时将丢弃读锁

// 只能持有一个写锁，但是
{
    let mut w = lock.write().unwrap();
    *w += 1;
    assert_eq!(*w, 6);
} // 写锁在这里被丢弃

Implementations

impl<T> RwLock<T>

pub const fn new(t: T) -> RwLock<T>

创建一个已解锁的 RwLock<T> 的新实例。

Examples

use std::sync::RwLock;

let lock = RwLock::new(5);

impl<T: ?Sized> RwLock<T>

pub fn read(&self) -> LockResult<RwLockReadGuard<'_, T>>

用共享读访问锁定这个 RwLock，阻塞当前线程直到它可以被获取。

调用线程将被阻塞，直到没有其他持有该锁的 writers 为止。 当此方法返回时，锁中可能当前存在其他 readers。 对于有争议的 readers 或 writers 将首先获取锁的顺序，此方法不提供任何保证。

返回 RAII 保护，一旦该线程被丢弃，它将释放该线程的共享访问。

Errors

如果 RwLock 中毒，此函数将返回错误。 每当 writer 在持有排他锁时发生 panic 时，RwLock 就会中毒。 获取锁定后，将立即发生故障。

Panics

如果当前线程已锁定，则调用此函数时可能为 panic。

Examples

use std::sync::{Arc, RwLock};
use std::thread;

let lock = Arc::new(RwLock::new(1));
let c_lock = Arc::clone(&lock);

let n = lock.read().unwrap();
assert_eq!(*n, 1);

thread::spawn(move || {
    let r = c_lock.read();
    assert!(r.is_ok());
}).join().unwrap();

pub fn try_read(&self) -> TryLockResult<RwLockReadGuard<'_, T>>

尝试使用共享读取访问权限获取此 RwLock。

如果此时不能授予访问权限，则返回 Err。 否则，将返回 RAII 保护，当该保护被丢弃时，该保护将释放共享访问。

该函数不会阻止。

对于有争议的 readers 或 writers 将首先获取锁的顺序，此函数不提供任何保证。

Errors

如果 RwLock 中毒，此函数将返回 Poisoned 错误。 每当 writer 在持有排他锁时发生 panic 时，RwLock 就会中毒。 Poisoned 只有在可以获取锁的情况下才会返回。

如果由于 RwLock 已被独占锁定而无法获取，此函数将返回 WouldBlock 错误。

Examples

use std::sync::RwLock;

let lock = RwLock::new(1);

match lock.try_read() {
    Ok(n) => assert_eq!(*n, 1),
    Err(_) => unreachable!(),
};

pub fn write(&self) -> LockResult<RwLockWriteGuard<'_, T>>

用独占写访问锁定这个 RwLock，阻塞当前线程，直到它可以被获取。

当前其他 writers 或其他 readers 可以访问该锁时，此函数将不会返回。

返回 RAII 守卫，它会在丢弃时丢弃此 RwLock 的写访问。

Errors

如果 RwLock 中毒，此函数将返回错误。 每当 writer 在持有排他锁时发生 panic 时，RwLock 就会中毒。 获取锁时将返回错误。

Panics

如果当前线程已锁定，则调用此函数时可能为 panic。

Examples

use std::sync::RwLock;

let lock = RwLock::new(1);

let mut n = lock.write().unwrap();
*n = 2;

assert!(lock.try_read().is_err());

pub fn try_write(&self) -> TryLockResult<RwLockWriteGuard<'_, T>>

尝试使用独占写入访问锁定此 RwLock。

如果此时无法获取锁，则返回 Err。 否则，将返回 RAII 守卫，它将在锁被丢弃时释放锁。

该函数不会阻止。

对于有争议的 readers 或 writers 将首先获取锁的顺序，此函数不提供任何保证。

Errors

如果 RwLock 中毒，此函数将返回 Poisoned 错误。 每当 writer 在持有排他锁时发生 panic 时，RwLock 就会中毒。 Poisoned 只有在可以获取锁的情况下才会返回。

如果由于 RwLock 已被独占锁定而无法获取，此函数将返回 WouldBlock 错误。

Examples

use std::sync::RwLock;

let lock = RwLock::new(1);

let n = lock.read().unwrap();
assert_eq!(*n, 1);

assert!(lock.try_write().is_err());

pub fn is_poisoned(&self) -> bool

确定锁是否中毒。

如果另一个线程处于活动状态，则锁定仍可能随时中毒。 如果没有其他同步，则不应信任 false 值来确保程序正确性。

Examples

use std::sync::{Arc, RwLock};
use std::thread;

let lock = Arc::new(RwLock::new(0));
let c_lock = Arc::clone(&lock);

let _ = thread::spawn(move || {
    let _lock = c_lock.write().unwrap();
    panic!(); // 锁被毒死了
}).join();
assert_eq!(lock.is_poisoned(), true);

pub fn clear_poison(&self)

🔬This is a nightly-only experimental API. (mutex_unpoison #96469)

从锁中清除中毒状态

如果锁中毒了，它将保持中毒状态，直到这个函数被调用为止。 这允许从中毒状态中恢复并标记它已经恢复。 例如，如果该值被已知良好的值覆盖，则互斥锁可以被标记为未中毒。 或者可能，可以检查该值，以确定它是否处于一致状态，如果是，则会清除中毒状态。

Examples

#![feature(mutex_unpoison)]

use std::sync::{Arc, RwLock};
use std::thread;

let lock = Arc::new(RwLock::new(0));
let c_lock = Arc::clone(&lock);

let _ = thread::spawn(move || {
    let _lock = c_lock.write().unwrap();
    panic!(); // 互斥锁中毒
}).join();

assert_eq!(lock.is_poisoned(), true);
let guard = lock.write().unwrap_or_else(|mut e| {
    **e.get_mut() = 1;
    lock.clear_poison();
    e.into_inner()
});
assert_eq!(lock.is_poisoned(), false);
assert_eq!(*guard, 1);

pub fn into_inner(self) -> LockResult<T>where T: Sized,

消耗这个 RwLock，返回底层数据。

Errors

如果 RwLock 中毒，此函数将返回错误。 每当 writer 在持有排他锁时发生 panic 时，RwLock 就会中毒。

仅当以其他方式获取锁时，才会返回错误。

Examples

use std::sync::RwLock;

let lock = RwLock::new(String::new());
{
    let mut s = lock.write().unwrap();
    *s = "modified".to_owned();
}
assert_eq!(lock.into_inner().unwrap(), "modified");

pub fn get_mut(&mut self) -> LockResult<&mut T>

返回对底层数据的可变引用。

由于此调用借用 RwLock 是可变的，因此不需要进行实际的锁定 - 可变借用可以静态地保证不存在任何锁定。

Errors

如果 RwLock 中毒，此函数将返回错误。 每当 writer 在持有排他锁时发生 panic 时，RwLock 就会中毒。 仅当以其他方式获取锁时，才会返回错误。

Examples

use std::sync::RwLock;

let mut lock = RwLock::new(0);
*lock.get_mut().unwrap() = 10;
assert_eq!(*lock.read().unwrap(), 10);

Trait Implementations

impl<T: ?Sized + Debug> Debug for RwLock<T>

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

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

impl<T: Default> Default for RwLock<T>

fn default() -> RwLock<T>

用 T 的 Default 值创建一个新的 RwLock<T>。

impl<T> From<T> for RwLock<T>

fn from(t: T) -> Self

创建一个已解锁的 RwLock<T> 的新实例。 这等效于 RwLock::new。

impl<T: ?Sized> RefUnwindSafe for RwLock<T>

impl<T: ?Sized + Send> Send for RwLock<T>

impl<T: ?Sized + Send + Sync> Sync for RwLock<T>

impl<T: ?Sized> UnwindSafe for RwLock<T>