Struct kvarn::prelude::RwLock

pub struct RwLock<T>where
    T: ?Sized,
{ /* private fields */ }
Expand description

An asynchronous reader-writer lock.

This type of lock allows a number of readers or at most one writer at any point in time. The write portion of this lock typically allows modification of the underlying data (exclusive access) and the read portion of this lock typically allows for read-only access (shared access).

In comparison, a Mutex does not distinguish between readers or writers that acquire the lock, therefore causing any tasks waiting for the lock to become available to yield. An RwLock will allow any number of readers to acquire the lock as long as a writer is not holding the lock.

The priority policy of Tokio’s read-write lock is fair (or write-preferring), in order to ensure that readers cannot starve writers. Fairness is ensured using a first-in, first-out queue for the tasks awaiting the lock; if a task that wishes to acquire the write lock is at the head of the queue, read locks will not be given out until the write lock has been released. This is in contrast to the Rust standard library’s std::sync::RwLock, where the priority policy is dependent on the operating system’s implementation.

The type parameter T represents the data that this lock protects. It is required that T satisfies Send to be shared across threads. The RAII guards returned from the locking methods implement Deref (and DerefMut for the write methods) to allow access to the content of the lock.

Examples

use tokio::sync::RwLock;

#[tokio::main]
async fn main() {
    let lock = RwLock::new(5);

    // many reader locks can be held at once
    {
        let r1 = lock.read().await;
        let r2 = lock.read().await;
        assert_eq!(*r1, 5);
        assert_eq!(*r2, 5);
    } // read locks are dropped at this point

    // only one write lock may be held, however
    {
        let mut w = lock.write().await;
        *w += 1;
        assert_eq!(*w, 6);
    } // write lock is dropped here
}

Implementations§

Creates a new instance of an RwLock<T> which is unlocked.

Examples
use tokio::sync::RwLock;

let lock = RwLock::new(5);

Creates a new instance of an RwLock<T> which is unlocked and allows a maximum of max_reads concurrent readers.

Examples
use tokio::sync::RwLock;

let lock = RwLock::with_max_readers(5, 1024);
Panics

Panics if max_reads is more than u32::MAX >> 3.

Available on crate feature parking_lot and non-loom only.

Creates a new instance of an RwLock<T> which is unlocked.

Examples
use tokio::sync::RwLock;

static LOCK: RwLock<i32> = RwLock::const_new(5);
Available on crate feature parking_lot and non-loom only.

Creates a new instance of an RwLock<T> which is unlocked and allows a maximum of max_reads concurrent readers.

Examples
use tokio::sync::RwLock;

static LOCK: RwLock<i32> = RwLock::const_with_max_readers(5, 1024);

Locks this RwLock with shared read access, causing the current task to yield until the lock has been acquired.

The calling task will yield until there are no writers which hold the lock. There may be other readers inside the lock when the task resumes.

Note that under the priority policy of RwLock, read locks are not granted until prior write locks, to prevent starvation. Therefore deadlock may occur if a read lock is held by the current task, a write lock attempt is made, and then a subsequent read lock attempt is made by the current task.

Returns an RAII guard which will drop this read access of the RwLock when dropped.

Cancel safety

This method uses a queue to fairly distribute locks in the order they were requested. Cancelling a call to read makes you lose your place in the queue.

Examples
use std::sync::Arc;
use tokio::sync::RwLock;

#[tokio::main]
async fn main() {
    let lock = Arc::new(RwLock::new(1));
    let c_lock = lock.clone();

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

    tokio::spawn(async move {
        // While main has an active read lock, we acquire one too.
        let r = c_lock.read().await;
        assert_eq!(*r, 1);
    }).await.expect("The spawned task has panicked");

    // Drop the guard after the spawned task finishes.
    drop(n);
}
Available on crate feature sync only.

Blockingly locks this RwLock with shared read access.

This method is intended for use cases where you need to use this rwlock in asynchronous code as well as in synchronous code.

Returns an RAII guard which will drop the read access of this RwLock when dropped.

Panics

This function panics if called within an asynchronous execution context.

  • If you find yourself in an asynchronous execution context and needing to call some (synchronous) function which performs one of these blocking_ operations, then consider wrapping that call inside [spawn_blocking()][crate::runtime::Handle::spawn_blocking] (or [block_in_place()][crate::task::block_in_place]).
Examples
use std::sync::Arc;
use tokio::sync::RwLock;

#[tokio::main]
async fn main() {
    let rwlock = Arc::new(RwLock::new(1));
    let mut write_lock = rwlock.write().await;

    let blocking_task = tokio::task::spawn_blocking({
        let rwlock = Arc::clone(&rwlock);
        move || {
            // This shall block until the `write_lock` is released.
            let read_lock = rwlock.blocking_read();
            assert_eq!(*read_lock, 0);
        }
    });

    *write_lock -= 1;
    drop(write_lock); // release the lock.

    // Await the completion of the blocking task.
    blocking_task.await.unwrap();

    // Assert uncontended.
    assert!(rwlock.try_write().is_ok());
}

Locks this RwLock with shared read access, causing the current task to yield until the lock has been acquired.

The calling task will yield until there are no writers which hold the lock. There may be other readers inside the lock when the task resumes.

This method is identical to RwLock::read, except that the returned guard references the RwLock with an Arc rather than by borrowing it. Therefore, the RwLock must be wrapped in an Arc to call this method, and the guard will live for the 'static lifetime, as it keeps the RwLock alive by holding an Arc.

Note that under the priority policy of RwLock, read locks are not granted until prior write locks, to prevent starvation. Therefore deadlock may occur if a read lock is held by the current task, a write lock attempt is made, and then a subsequent read lock attempt is made by the current task.

Returns an RAII guard which will drop this read access of the RwLock when dropped.

Cancel safety

This method uses a queue to fairly distribute locks in the order they were requested. Cancelling a call to read_owned makes you lose your place in the queue.

Examples
use std::sync::Arc;
use tokio::sync::RwLock;

#[tokio::main]
async fn main() {
    let lock = Arc::new(RwLock::new(1));
    let c_lock = lock.clone();

    let n = lock.read_owned().await;
    assert_eq!(*n, 1);

    tokio::spawn(async move {
        // While main has an active read lock, we acquire one too.
        let r = c_lock.read_owned().await;
        assert_eq!(*r, 1);
    }).await.expect("The spawned task has panicked");

    // Drop the guard after the spawned task finishes.
    drop(n);
}

Attempts to acquire this RwLock with shared read access.

If the access couldn’t be acquired immediately, returns TryLockError. Otherwise, an RAII guard is returned which will release read access when dropped.

Examples
use std::sync::Arc;
use tokio::sync::RwLock;

#[tokio::main]
async fn main() {
    let lock = Arc::new(RwLock::new(1));
    let c_lock = lock.clone();

    let v = lock.try_read().unwrap();
    assert_eq!(*v, 1);

    tokio::spawn(async move {
        // While main has an active read lock, we acquire one too.
        let n = c_lock.read().await;
        assert_eq!(*n, 1);
    }).await.expect("The spawned task has panicked");

    // Drop the guard when spawned task finishes.
    drop(v);
}

Attempts to acquire this RwLock with shared read access.

If the access couldn’t be acquired immediately, returns TryLockError. Otherwise, an RAII guard is returned which will release read access when dropped.

This method is identical to RwLock::try_read, except that the returned guard references the RwLock with an Arc rather than by borrowing it. Therefore, the RwLock must be wrapped in an Arc to call this method, and the guard will live for the 'static lifetime, as it keeps the RwLock alive by holding an Arc.

Examples
use std::sync::Arc;
use tokio::sync::RwLock;

#[tokio::main]
async fn main() {
    let lock = Arc::new(RwLock::new(1));
    let c_lock = lock.clone();

    let v = lock.try_read_owned().unwrap();
    assert_eq!(*v, 1);

    tokio::spawn(async move {
        // While main has an active read lock, we acquire one too.
        let n = c_lock.read_owned().await;
        assert_eq!(*n, 1);
    }).await.expect("The spawned task has panicked");

    // Drop the guard when spawned task finishes.
    drop(v);
}

Locks this RwLock with exclusive write access, causing the current task to yield until the lock has been acquired.

The calling task will yield while other writers or readers currently have access to the lock.

Returns an RAII guard which will drop the write access of this RwLock when dropped.

Cancel safety

This method uses a queue to fairly distribute locks in the order they were requested. Cancelling a call to write makes you lose your place in the queue.

Examples
use tokio::sync::RwLock;

#[tokio::main]
async fn main() {
  let lock = RwLock::new(1);

  let mut n = lock.write().await;
  *n = 2;
}
Available on crate feature sync only.

Blockingly locks this RwLock with exclusive write access.

This method is intended for use cases where you need to use this rwlock in asynchronous code as well as in synchronous code.

Returns an RAII guard which will drop the write access of this RwLock when dropped.

Panics

This function panics if called within an asynchronous execution context.

  • If you find yourself in an asynchronous execution context and needing to call some (synchronous) function which performs one of these blocking_ operations, then consider wrapping that call inside [spawn_blocking()][crate::runtime::Handle::spawn_blocking] (or [block_in_place()][crate::task::block_in_place]).
Examples
use std::sync::Arc;
use tokio::{sync::RwLock};

#[tokio::main]
async fn main() {
    let rwlock =  Arc::new(RwLock::new(1));
    let read_lock = rwlock.read().await;

    let blocking_task = tokio::task::spawn_blocking({
        let rwlock = Arc::clone(&rwlock);
        move || {
            // This shall block until the `read_lock` is released.
            let mut write_lock = rwlock.blocking_write();
            *write_lock = 2;
        }
    });

    assert_eq!(*read_lock, 1);
    // Release the last outstanding read lock.
    drop(read_lock);

    // Await the completion of the blocking task.
    blocking_task.await.unwrap();

    // Assert uncontended.
    let read_lock = rwlock.try_read().unwrap();
    assert_eq!(*read_lock, 2);
}

Locks this RwLock with exclusive write access, causing the current task to yield until the lock has been acquired.

The calling task will yield while other writers or readers currently have access to the lock.

This method is identical to RwLock::write, except that the returned guard references the RwLock with an Arc rather than by borrowing it. Therefore, the RwLock must be wrapped in an Arc to call this method, and the guard will live for the 'static lifetime, as it keeps the RwLock alive by holding an Arc.

Returns an RAII guard which will drop the write access of this RwLock when dropped.

Cancel safety

This method uses a queue to fairly distribute locks in the order they were requested. Cancelling a call to write_owned makes you lose your place in the queue.

Examples
use std::sync::Arc;
use tokio::sync::RwLock;

#[tokio::main]
async fn main() {
  let lock = Arc::new(RwLock::new(1));

  let mut n = lock.write_owned().await;
  *n = 2;
}

Attempts to acquire this RwLock with exclusive write access.

If the access couldn’t be acquired immediately, returns TryLockError. Otherwise, an RAII guard is returned which will release write access when dropped.

Examples
use tokio::sync::RwLock;

#[tokio::main]
async fn main() {
    let rw = RwLock::new(1);

    let v = rw.read().await;
    assert_eq!(*v, 1);

    assert!(rw.try_write().is_err());
}

Attempts to acquire this RwLock with exclusive write access.

If the access couldn’t be acquired immediately, returns TryLockError. Otherwise, an RAII guard is returned which will release write access when dropped.

This method is identical to RwLock::try_write, except that the returned guard references the RwLock with an Arc rather than by borrowing it. Therefore, the RwLock must be wrapped in an Arc to call this method, and the guard will live for the 'static lifetime, as it keeps the RwLock alive by holding an Arc.

Examples
use std::sync::Arc;
use tokio::sync::RwLock;

#[tokio::main]
async fn main() {
    let rw = Arc::new(RwLock::new(1));

    let v = Arc::clone(&rw).read_owned().await;
    assert_eq!(*v, 1);

    assert!(rw.try_write_owned().is_err());
}

Returns a mutable reference to the underlying data.

Since this call borrows the RwLock mutably, no actual locking needs to take place – the mutable borrow statically guarantees no locks exist.

Examples
use tokio::sync::RwLock;

fn main() {
    let mut lock = RwLock::new(1);

    let n = lock.get_mut();
    *n = 2;
}

Consumes the lock, returning the underlying data.

Trait Implementations§

Formats the value using the given formatter. Read more
Returns the “default value” for a type. Read more
Converts to this type from the input type.

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
Converts to this type from the input type.

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

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

Should always be Self
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.
Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more