Struct lockable::Guard

source ·

pub struct Guard<M, V, H, P>where
    M: ArcMutexMapLike,
    H: Hooks<M::V>,
    M::V: Borrow<V> + BorrowMut<V> + FromInto<V, H>,
    P: Borrow<LockableMapImpl<M, V, H>>,
{ /* private fields */ }

Expand description

A RAII implementation of a scoped lock for locks from a LockableHashMap or LockableLruCache. When this instance is dropped (falls out of scope), the lock will be unlocked.

Implementations§

source §

impl<M, V, H, P> Guard<M, V, H, P>
where M: ArcMutexMapLike, H: Hooks<M::V>, M::V: Borrow<V> + BorrowMut<V> + FromInto<V, H>, P: Borrow<LockableMapImpl<M, V, H>>,

source

pub fn key(&self) -> &M::K

Returns the key of the entry that was locked with this guard.

§Examples

use lockable::{AsyncLimit, LockableHashMap};

let lockable_map = LockableHashMap::<i64, String>::new();
let guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

assert_eq!(4, *guard.key());

source

pub fn value(&self) -> Option<&V>

Returns the value of the entry that was locked with this guard.

If the locked entry didn’t exist, then this returns None, but the guard still represents a lock on this key and no other thread or task can lock the same key.

§Examples

use lockable::{AsyncLimit, LockableHashMap};

let lockable_map = LockableHashMap::<i64, String>::new();
{
    let mut guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Entry doesn't exist yet
    assert_eq!(None, guard.value());

    // Insert the entry
    guard.insert(String::from("Hello World"));
}
{
    let guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Now this entry exists
    assert_eq!(Some(&String::from("Hello World")), guard.value());
}

source

pub fn value_mut(&mut self) -> Option<&mut V>

Returns the value of the entry that was locked with this guard.

If the locked entry didn’t exist, then this returns None, but the guard still represents a lock on this key and no other thread or task can lock the same key.

§Examples

use lockable::{AsyncLimit, LockableHashMap};

let lockable_map = LockableHashMap::<i64, String>::new();
{
    let mut guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Entry doesn't exist yet
    assert_eq!(None, guard.value_mut());

    // Insert the entry
    guard.insert(String::from("Hello World"));
}
{
    let mut guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Modify the value
    *guard.value_mut().unwrap() = String::from("New Value");
}
{
    let guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Now it has the new value
    assert_eq!(Some(&String::from("New Value")), guard.value());
}

source

pub fn remove(&mut self) -> Option<V>

Removes the entry this guard has locked from the map.

If the entry existed, its value is returned. If the entry didn’t exist, None is returned.

§Examples

use lockable::{AsyncLimit, LockableHashMap};

let lockable_map = LockableHashMap::<i64, String>::new();
{
    let mut guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Insert the entry
    guard.insert(String::from("Hello World"));
}
{
    let mut guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // The value exists
    assert_eq!(Some(&String::from("Hello World")), guard.value());

    // Remove the value
    guard.remove();
}
{
    let guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Now the value doesn't exist anymore
    assert_eq!(None, guard.value());
}

source

pub fn insert(&mut self, value: V) -> Option<V>

Inserts a value for the entry this guard has locked to the map.

If the entry existed already, its old value is returned. If the entry didn’t exist yet, None is returned. In both cases, the map will contain the new value after the call.

§Examples

use lockable::{AsyncLimit, LockableHashMap};

let lockable_map = LockableHashMap::<i64, String>::new();
{
    let mut guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Insert the entry
    let prev_entry = guard.insert(String::from("Hello World"));

    // The value didn't exist previously
    assert_eq!(None, prev_entry);
}
{
    let guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Now the value exists
    assert_eq!(Some(&String::from("Hello World")), guard.value());
}

source

pub fn try_insert(&mut self, value: V) -> Result<&mut V, TryInsertError<V>>

Inserts a value for the entry this guard has locked to the map if it didn’t exist yet. If it already existed, this call returns TryInsertError::AlreadyExists instead.

This function also returns a mutable reference to the new entry, which can be used to further modify it.

§Examples

use lockable::{AsyncLimit, LockableHashMap};

let lockable_map = LockableHashMap::<i64, String>::new();
{
    let mut guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Insert the entry
    let insert_result = guard.try_insert(String::from("Hello World"));
    assert!(insert_result.is_ok());
}
{
    let mut guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // We cannot insert it again because it already exists
    let insert_result = guard.try_insert(String::from("Hello World"));
    assert!(insert_result.is_err());
}

source

pub fn value_or_insert_with(&mut self, value_fn: impl FnOnce() -> V) -> &mut V

Returns a mutable reference to the value of the entry this guard has locked.

If the entry doesn’t exist, then value_fn is invoked to create it, the value is added to the map, and then a mutable reference to it is returned.

§Examples

use lockable::{AsyncLimit, LockableHashMap};

let lockable_map = LockableHashMap::<i64, String>::new();
{
    let mut guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Entry doesn't exist yet, `value_or_insert_with` will create it
    let value = guard.value_or_insert_with(|| String::from("Old Value"));
    assert_eq!(&String::from("Old Value"), value);
}
{
    let mut guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Since the entry already exists, `value_or_insert_with` will not create it
    // but return the existing value instead.
    let value = guard.value_or_insert_with(|| String::from("New Value"));
    assert_eq!(&String::from("Old Value"), value);
}

source

pub fn value_or_insert(&mut self, value: V) -> &mut V

Returns a mutable reference to the value of the entry this guard has locked.

If the entry doesn’t exist, then value is inserted into the map for this entry, and then a mutable reference to it is returned.

§Examples

use lockable::{AsyncLimit, LockableHashMap};

let lockable_map = LockableHashMap::<i64, String>::new();
{
    let mut guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Entry doesn't exist yet, `value_or_insert_with` will create it
    let value = guard.value_or_insert(String::from("Old Value"));
    assert_eq!(&String::from("Old Value"), value);
}
{
    let mut guard = lockable_map.async_lock(4, AsyncLimit::no_limit()).await?;

    // Since the entry already exists, `value_or_insert_with` will not create it
    // but return the existing value instead.
    let value = guard.value_or_insert(String::from("New Value"));
    assert_eq!(&String::from("Old Value"), value);
}