From fae6e759e134135d59a675d60b33510fde170a95 Mon Sep 17 00:00:00 2001 From: Marcello Lamonaca Date: Sun, 14 Apr 2024 18:09:23 +0200 Subject: [PATCH] rust: add `RwLock` notes --- docs/languages/rust/concurrency.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/languages/rust/concurrency.md b/docs/languages/rust/concurrency.md index b9b3bc5..673498c 100644 --- a/docs/languages/rust/concurrency.md +++ b/docs/languages/rust/concurrency.md @@ -119,3 +119,13 @@ std::thread::scope(|scope| { The `lock()` method returns a `Result` since the mutex can become **poisoned**. A mutex get marked as poisoned when a thread panics while holding the lock. Calling `lock()` on a poisoned mutex will return an `Err`. This poisoning mechanism protects against accessing data that may be in an inconsistent state. > **Note**: The lock is still acquired and the `Err` variant contains the guard, allowing to correct the data inconsistency. + +### Reader-Writer Lock + +A **reader-writer lock** understands the difference between _exclusive_ and _shared_ access, and can provide either. It has three states: unlocked, locked by a single writer (for exclusive access), and locked by any number of readers (for shared access). + +The Rust standard library provides this lock through the `std::sync::RwLock` type. It has a `read()` and `write()` method for locking as either a reader or a writer and it has two guard types: `RwLockReadGuard` and `RwLockWriteGuard`. + +The first only implements `Deref` to behave like a shared reference to the protected data, while the second also implements `DerefMut` to behave like an exclusive reference. + +Most implementations will block new readers when there is a writer waiting, even when the lock is already read-locked. This is done to prevent _writer starvation_, a situation where many readers collectively keep the lock from ever unlocking, never allowing any writer to update the data.