Struct RwLock

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

A Futures-aware RwLock.

std::sync::RwLock cannot be used in an asynchronous environment like Tokio, because an acquisition can block an entire reactor. This class can be used instead. It functions much like std::sync::RwLock. Unlike that class, it also has a builtin Arc, making it accessible from multiple threads. It’s also safe to clone. Also unlike std::sync::RwLock, this class does not detect lock poisoning.

Implementations§

Source§

impl<T> RwLock<T>

Source

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

Create a new RwLock in the unlocked state.

Source

pub fn try_unwrap(self) -> Result<T, RwLock<T>>

Consumes the RwLock and returns the wrapped data. If the RwLock still has multiple references (not necessarily locked), returns a copy of self instead.

Source§

impl<T: ?Sized> RwLock<T>

Source

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

Returns a reference to the underlying data, if there are no other clones of the RwLock.

Since this call borrows the RwLock mutably, no actual locking takes place – the mutable borrow statically guarantees no locks exist. However, if the RwLock has already been cloned, then None will be returned instead.

§Examples
let mut lock = RwLock::<u32>::new(0);
*lock.get_mut().unwrap() += 5;
assert_eq!(lock.try_unwrap().unwrap(), 5);
Source

pub fn read(&self) -> RwLockReadFut<T>

Acquire the RwLock nonexclusively, read-only, blocking the task in the meantime.

When the returned Future is ready, then this task will have read-only access to the protected data.

§Examples
let rwlock = RwLock::<u32>::new(42);
let fut = rwlock.read().map(|mut guard| { *guard });
assert_eq!(block_on(fut), 42);
Source

pub fn write(&self) -> RwLockWriteFut<T>

Acquire the RwLock exclusively, read-write, blocking the task in the meantime.

When the returned Future is ready, then this task will have read-write access to the protected data.

§Examples
let rwlock = RwLock::<u32>::new(42);
let fut = rwlock.write().map(|mut guard| { *guard = 5;});
block_on(fut);
assert_eq!(rwlock.try_unwrap().unwrap(), 5);
Source

pub fn try_read(&self) -> Result<RwLockReadGuard<T>, TryLockError>

Attempts to acquire the RwLock nonexclusively.

If the operation would block, returns Err instead. Otherwise, returns a guard (not a Future).

§Examples
let mut lock = RwLock::<u32>::new(5);
let r = match lock.try_read() {
    Ok(guard) => *guard,
    Err(_) => panic!("Better luck next time!")
};
assert_eq!(5, r);
Source

pub fn try_write(&self) -> Result<RwLockWriteGuard<T>, TryLockError>

Attempts to acquire the RwLock exclusively.

If the operation would block, returns Err instead. Otherwise, returns a guard (not a Future).

§Examples
let mut lock = RwLock::<u32>::new(5);
match lock.try_write() {
    Ok(mut guard) => *guard += 5,
    Err(_) => panic!("Better luck next time!")
}
assert_eq!(10, lock.try_unwrap().unwrap());
Source§

impl<T: 'static + ?Sized> RwLock<T>

Source

pub fn with_read<B, F, R>(&self, f: F) -> impl Future<Output = R>
where F: FnOnce(RwLockReadGuard<T>) -> B + Send + 'static, B: Future<Output = R> + Send + 'static, R: Send + 'static, T: Send,

Available on crate feature tokio only.

Acquires a RwLock nonexclusively and performs a computation on its guarded value in a separate task. Returns a Future containing the result of the computation.

When using Tokio, this method will often hold the RwLock for less time than chaining a computation to read. The reason is that Tokio polls all tasks promptly upon notification. However, Tokio does not guarantee that it will poll all futures promptly when their owning task gets notified. So it’s best to hold RwLocks within their own tasks, lest their continuations get blocked by slow stacked combinators.

§Examples
let rwlock = RwLock::<u32>::new(5);
let mut rt = Runtime::new().unwrap();
let r = rt.block_on(async {
    rwlock.with_read(|mut guard| {
        ready(*guard)
    }).await
});
assert_eq!(r, 5);
Source

pub fn with_read_local<B, F, R>(&self, f: F) -> impl Future<Output = R>
where F: FnOnce(RwLockReadGuard<T>) -> B + 'static + Unpin, B: Future<Output = R> + 'static, R: 'static,

Available on crate feature tokio only.

Like with_read but for Futures that aren’t Send. Spawns a new task on a single-threaded Runtime to complete the Future.

§Examples
// Note: Rc is not `Send`
let rwlock = RwLock::<Rc<u32>>::new(Rc::new(5));
let mut rt = Runtime::new().unwrap();
let r = rt.block_on(async {
    rwlock.with_read_local(|mut guard| {
        ready(**guard)
    }).await
});
assert_eq!(r, 5);
Source

pub fn with_write<B, F, R>(&self, f: F) -> impl Future<Output = R>
where F: FnOnce(RwLockWriteGuard<T>) -> B + Send + 'static, B: Future<Output = R> + Send + 'static, R: Send + 'static, T: Send,

Available on crate feature tokio only.

Acquires a RwLock exclusively and performs a computation on its guarded value in a separate task. Returns a Future containing the result of the computation.

When using Tokio, this method will often hold the RwLock for less time than chaining a computation to write. The reason is that Tokio polls all tasks promptly upon notification. However, Tokio does not guarantee that it will poll all futures promptly when their owning task gets notified. So it’s best to hold RwLocks within their own tasks, lest their continuations get blocked by slow stacked combinators.

§Examples
let rwlock = RwLock::<u32>::new(0);
let mut rt = Runtime::new().unwrap();
let r = rt.block_on(async {
    rwlock.with_write(|mut guard| {
        *guard += 5;
        ready(())
    }).await
});
assert_eq!(rwlock.try_unwrap().unwrap(), 5);
Source

pub fn with_write_local<B, F, R>(&self, f: F) -> impl Future<Output = R>
where F: FnOnce(RwLockWriteGuard<T>) -> B + 'static + Unpin, B: Future<Output = R> + 'static, R: 'static,

Available on crate feature tokio only.

Like with_write but for Futures that aren’t Send. Spawns a new task on a single-threaded Runtime to complete the Future.

§Examples
// Note: Rc is not `Send`
let rwlock = RwLock::<Rc<u32>>::new(Rc::new(0));
let mut rt = Runtime::new().unwrap();
let r = rt.block_on(async {
    rwlock.with_write_local(|mut guard| {
        *Rc::get_mut(&mut *guard).unwrap() += 5;
        ready(())
    }).await
});
assert_eq!(*rwlock.try_unwrap().unwrap(), 5);

Trait Implementations§

Source§

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

Source§

fn clone(&self) -> RwLock<T>

Returns a duplicate of the value. Read more
1.0.0 · Source§

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

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

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

fn default() -> RwLock<T>

Returns the “default value” for a type. Read more
Source§

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

Source§

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

Auto Trait Implementations§

§

impl<T> Freeze for RwLock<T>
where T: ?Sized,

§

impl<T> !RefUnwindSafe for RwLock<T>

§

impl<T> Unpin for RwLock<T>
where T: ?Sized,

§

impl<T> !UnwindSafe for RwLock<T>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

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

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

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

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.