# tokio::sync::RwLock - Rust
API documentation for the Rust `RwLock` struct in crate `tokio`.
Keywords: rust, rustlang, rust-lang, RwLock

# Struct tokio::sync::RwLock [−] [src]

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

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

### `impl<T: ?Sized> RwLock<T>` [src]

#### `pub fn new(value: T) -> RwLock<T> where
T: Sized,` [src]

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

# Examples

    use tokio::sync::RwLock;

    let lock = RwLock::new(5);

#### `pub const fn const_new(value: T) -> RwLock<T> where
T: Sized,` [src]

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

# Examples

    use tokio::sync::RwLock;

    static LOCK: RwLock<i32> = RwLock::const_new(5);

#### `pub async fn read(&self) -> RwLockReadGuard<'_, T>` [src]

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.

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

#### `pub fn try_read(&self) -> Result<RwLockReadGuard<'_, T>, TryLockError>` [src]

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

#### `pub async fn write(&self) -> RwLockWriteGuard<'_, T>` [src]

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.

# Examples

    use tokio::sync::RwLock;

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

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

#### `pub fn try_write(&self) -> Result<RwLockWriteGuard<'_, T>, TryLockError>` [src]

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

#### `pub fn get_mut(&mut self) -> &mut Tⓘ

### Notable traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
` [src]

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

#### `pub fn into_inner(self) -> T where
T: Sized,` [src]

Consumes the lock, returning the underlying data.

## Trait Implementations

### `impl<T: Debug + ?Sized> Debug for RwLock<T>` [src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result` [src]

Formats the value using the given formatter. Read more

### `impl<T: ?Sized> Default for RwLock<T> where
T: Default,` [src]

#### `fn default() -> Self` [src]

Returns the "default value" for a type. Read more

### `impl<T> From<T> for RwLock<T>` [src]

#### `fn from(s: T) -> Self` [src]

Performs the conversion.

### `impl<T: ?Sized> Send for RwLock<T> where
T: Send,` [src]

### `impl<T: ?Sized> Sync for RwLock<T> where
T: Send + Sync,` [src]

## Auto Trait Implementations

### `impl<T> !RefUnwindSafe for RwLock<T>` [src]

### `impl<T: ?Sized> Unpin for RwLock<T> where
T: Unpin,` [src]

### `impl<T> !UnwindSafe for RwLock<T>` [src]

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &Tⓘ

### Notable traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut Tⓘ

### Notable traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<!> for T` [src]

#### `pub fn from(t: !) -> T` [src]

Performs the conversion.

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.