Struct Guard

Source
pub struct Guard<'a> { /* private fields */ }
Expand description

An acquired lock guard.

This object is created by calling Lock::lock or one of the other locking functions.

A Guard can be used to access Locked data by calling Locked::get.

Each Guard represents a ticket of the Lock it was created from. A thread can have any number of tickets and while a thread holds at least 1 ticket of a Lock, no other thread can acquire a ticket from that Lock.

A Guard can temporarily give up its ticket by calling Guard::unlocked or Guard::unlocked_fair. The ticket will be restored before those functions return. The Guard is inaccessible while the function is running.

Dropping the Guard or calling Guard::unlock_fair consumes the ticket.

The Guard can be passed to mem::forget to leak the ticket without leaking any memory.

§Example

use shared_lock::Lock;

let lock = Lock::default();
let _guard = lock.lock();

Implementations§

Source§

impl Guard<'_>

Source

pub fn unlock_fair(self)

Unlocks this guard.

If this causes the number of tickets to drop to 0, the underlying mutex is unlocked using a fair protocol.

§Example
use shared_lock::Lock;

let lock = Lock::default();
let guard = lock.lock();
guard.unlock_fair();
Source

pub fn unlocked<T>(&mut self, f: impl FnOnce() -> T) -> T

Unlocks this guard, runs a function, and then re-acquires the guard.

If another guard exists, then other threads will not be able to acquire the lock even while the function is running.

§Example
use shared_lock::Lock;

let lock = Lock::default();
let locked = lock.wrap(1);
let mut guard = lock.lock();
assert_eq!(*locked.get(&guard), 1);
guard.unlocked(|| {
    assert!(!lock.is_locked());
});
assert_eq!(*locked.get(&guard), 1);
Source

pub fn unlocked_fair<T>(&mut self, f: impl FnOnce() -> T) -> T

Unlocks this guard fairly, runs a function, and then re-acquires the guard.

If another guard exists, then other threads will not be able to acquire the lock even while the function is running.

§Example
use shared_lock::Lock;

let lock = Lock::default();
let locked = lock.wrap(1);
let mut guard = lock.lock();
assert_eq!(*locked.get(&guard), 1);
guard.unlocked_fair(|| {
    assert!(!lock.is_locked());
});
assert_eq!(*locked.get(&guard), 1);

Trait Implementations§

Source§

impl Debug for Guard<'_>

Source§

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

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

impl Drop for Guard<'_>

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

§

impl<'a> Freeze for Guard<'a>

§

impl<'a> !RefUnwindSafe for Guard<'a>

§

impl<'a> !Send for Guard<'a>

§

impl<'a> !Sync for Guard<'a>

§

impl<'a> Unpin for Guard<'a>

§

impl<'a> !UnwindSafe for Guard<'a>

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> 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, 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.