Struct RwLockUpgradableReadGuard 

pub struct RwLockUpgradableReadGuard<'a, R: RawRwLockUpgrade, T: ?Sized> { /* private fields */ }

An RAII guard which releases upgradable read access when dropped.

This structure is created by the upgradable_read and try_upgradable_read methods on RwLock.

Implementations

impl<'a, R: RawRwLockUpgrade + 'a, T: ?Sized + 'a> RwLockUpgradableReadGuard<'a, R, T>

pub fn rwlock(s: &Self) -> &'a RwLock<R, T>

Returns a reference to the original reader-writer lock object.

pub fn unlocked<F, U>(s: &mut Self, f: F) -> U

where F: FnOnce() -> U,

Temporarily unlocks the RwLock to execute the given function.

The mutable reference ensures that no references derived from this guard are live while the lock is temporarily released.

Aborts

Aborts if re-locking the RwLock panics.

pub fn upgrade(s: Self) -> RwLockWriteGuard<'a, R, T>

Atomically upgrades an upgradable read lock into an exclusive write lock, blocking the current thread until it can be acquired.

This cannot complete while any other read guards remain. Calling it while the current thread holds another read guard may therefore deadlock.

pub fn try_upgrade(s: Self) -> Result<RwLockWriteGuard<'a, R, T>, Self>

Tries to atomically upgrade an upgradable read lock into an exclusive write lock.

If the access could not be granted at this time, then the current guard is returned.

impl<'a, R: RawRwLockUpgradeFair + 'a, T: ?Sized + 'a> RwLockUpgradableReadGuard<'a, R, T>

pub fn unlock_fair(s: Self)

Unlocks the RwLock using a fair unlock protocol.

A fair unlock gives waiting threads priority over new acquisition attempts. This can prevent starvation, but may reduce throughput by forcing a context switch.

pub fn unlocked_fair<F, U>(s: &mut Self, f: F) -> U

where F: FnOnce() -> U,

Temporarily unlocks the RwLock to execute the given function.

The RwLock is unlocked using a fair unlock protocol.

The mutable reference ensures that no references derived from this guard are live while the lock is temporarily released.

Aborts

Aborts if re-locking the RwLock panics.

pub fn bump(s: &mut Self)

Temporarily yields the RwLock to a waiting thread if there is one.

This method is functionally equivalent to calling unlock_fair followed by upgradable_read, however it can be much more efficient in the case where there are no waiting threads.

impl<'a, R: RawRwLockUpgradeDowngrade + 'a, T: ?Sized + 'a> RwLockUpgradableReadGuard<'a, R, T>

pub fn downgrade(s: Self) -> RwLockReadGuard<'a, R, T>

Atomically downgrades an upgradable read lock into a shared read lock without allowing any writers to take exclusive access of the lock in the meantime.

Note that if there are any writers currently waiting to take the lock then other readers may not be able to acquire the lock even if it was downgraded.

pub fn with_upgraded<Ret, F: FnOnce(&mut T) -> Ret>(&mut self, f: F) -> Ret

First, atomically upgrades an upgradable read lock into an exclusive write lock, blocking the current thread until it can be acquired. This cannot complete while any other read guards remain.

Then, calls the provided closure with an exclusive reference to the lock’s data.

Finally, atomically downgrades the lock back to an upgradable read lock. The closure’s return value is returned.

This function only requires a mutable reference to the guard, unlike upgrade which takes the guard by value.

Aborts

Aborts if upgrading or downgrading back to an upgradable read lock panics, since releasing and re-acquiring would break continuous lock ownership.

pub fn try_with_upgraded<Ret, F: FnOnce(&mut T) -> Ret>( &mut self, f: F, ) -> Option<Ret>

First, tries to atomically upgrade an upgradable read lock into an exclusive write lock.

If the access could not be granted at this time, then None is returned.

Otherwise, calls the provided closure with an exclusive reference to the lock’s data, and finally downgrades the lock back to an upgradable read lock. The closure’s return value is wrapped in Some and returned.

This function only requires a mutable reference to the guard, unlike try_upgrade which takes the guard by value.

Aborts

Aborts if upgrading or downgrading back to an upgradable read lock panics, since releasing and re-acquiring would break continuous lock ownership.

impl<'a, R: RawRwLockUpgradeTimed + 'a, T: ?Sized + 'a> RwLockUpgradableReadGuard<'a, R, T>

pub fn try_upgrade_for( s: Self, timeout: R::Duration, ) -> Result<RwLockWriteGuard<'a, R, T>, Self>

Tries to atomically upgrade an upgradable read lock into an exclusive write lock, until a timeout is reached.

If the access could not be granted before the timeout expires, then the current guard is returned.

See RawRwLockUpgradeTimed::try_upgrade_for for timeout behavior.

pub fn try_upgrade_until( s: Self, timeout: R::Instant, ) -> Result<RwLockWriteGuard<'a, R, T>, Self>

Tries to atomically upgrade an upgradable read lock into an exclusive write lock, until a timeout is reached.

If the access could not be granted before the timeout expires, then the current guard is returned.

See RawRwLockUpgradeTimed::try_upgrade_until for timeout behavior.

impl<'a, R: RawRwLockUpgradeTimed + RawRwLockUpgradeDowngrade + 'a, T: ?Sized + 'a> RwLockUpgradableReadGuard<'a, R, T>

pub fn try_with_upgraded_for<Ret, F: FnOnce(&mut T) -> Ret>( &mut self, timeout: R::Duration, f: F, ) -> Option<Ret>

Tries to atomically upgrade an upgradable read lock into an exclusive write lock, until a timeout is reached.

If the access could not be granted before the timeout expires, then None is returned.

See RawRwLockUpgradeTimed::try_upgrade_for for timeout behavior.

Otherwise, calls the provided closure with an exclusive reference to the lock’s data, and finally downgrades the lock back to an upgradable read lock. The closure’s return value is wrapped in Some and returned.

This function only requires a mutable reference to the guard, unlike try_upgrade_for which takes the guard by value.

Aborts

Aborts if upgrading or downgrading back to an upgradable read lock panics, since releasing and re-acquiring would break continuous lock ownership.

pub fn try_with_upgraded_until<Ret, F: FnOnce(&mut T) -> Ret>( &mut self, timeout: R::Instant, f: F, ) -> Option<Ret>

Tries to atomically upgrade an upgradable read lock into an exclusive write lock, until a timeout is reached.

If the access could not be granted before the timeout expires, then None is returned.

See RawRwLockUpgradeTimed::try_upgrade_until for timeout behavior.

Otherwise, calls the provided closure with an exclusive reference to the lock’s data, and finally downgrades the lock back to an upgradable read lock. The closure’s return value is wrapped in Some and returned.

This function only requires a mutable reference to the guard, unlike try_upgrade_until which takes the guard by value.

Aborts

Aborts if upgrading or downgrading back to an upgradable read lock panics, since releasing and re-acquiring would break continuous lock ownership.

Trait Implementations

impl<'a, R: RawRwLockUpgrade + 'a, T: Debug + ?Sized + 'a> Debug for RwLockUpgradableReadGuard<'a, R, T>

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

Formats the value using the given formatter.

impl<'a, R: RawRwLockUpgrade + 'a, T: ?Sized + 'a> Deref for RwLockUpgradableReadGuard<'a, R, T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<'a, R: RawRwLockUpgrade + 'a, T: Display + ?Sized + 'a> Display for RwLockUpgradableReadGuard<'a, R, T>

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

Formats the value using the given formatter.

impl<'a, R: RawRwLockUpgrade + 'a, T: ?Sized + 'a> Drop for RwLockUpgradableReadGuard<'a, R, T>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.