Struct moka::future::OwnedKeyEntrySelector

pub struct OwnedKeyEntrySelector<'a, K, V, S> { /* private fields */ }

Available on crate feature future only.

Provides advanced methods to select or insert an entry of the cache.

Many methods here return an Entry, a snapshot of a single key-value pair in the cache, carrying additional information like is_fresh.

OwnedKeyEntrySelector is constructed from the entry method on the cache.

Implementations

impl<'a, K, V, S> OwnedKeyEntrySelector<'a, K, V, S>where K: Hash + Eq + Send + Sync + 'static, V: Clone + Send + Sync + 'static, S: BuildHasher + Clone + Send + Sync + 'static,

pub async fn or_default(self) -> Entry<K, V>where V: Default,

Returns the corresponding Entry for the key given when this entry selector was constructed. If the entry does not exist, inserts one by calling the default function of the value type V.

Example

// Cargo.toml
//
// [dependencies]
// moka = { version = "0.10", features = ["future"] }
// tokio = { version = "1", features = ["rt-multi-thread", "macros" ] }

use moka::future::Cache;

#[tokio::main]
async fn main() {
    let cache: Cache<String, Option<u32>> = Cache::new(100);
    let key = "key1".to_string();

    let entry = cache.entry(key.clone()).or_default().await;
    assert!(entry.is_fresh());
    assert_eq!(entry.key(), &key);
    assert_eq!(entry.into_value(), None);

    let entry = cache.entry(key).or_default().await;
    // Not fresh because the value was already in the cache.
    assert!(!entry.is_fresh());
}

pub async fn or_insert(self, default: V) -> Entry<K, V>

Returns the corresponding Entry for the key given when this entry selector was constructed. If the entry does not exist, inserts one by using the the given default value for V.

Example

// Cargo.toml
//
// [dependencies]
// moka = { version = "0.10", features = ["future"] }
// tokio = { version = "1", features = ["rt-multi-thread", "macros" ] }

use moka::future::Cache;

#[tokio::main]
async fn main() {
    let cache: Cache<String, u32> = Cache::new(100);
    let key = "key1".to_string();

    let entry = cache.entry(key.clone()).or_insert(3).await;
    assert!(entry.is_fresh());
    assert_eq!(entry.key(), &key);
    assert_eq!(entry.into_value(), 3);

    let entry = cache.entry(key).or_insert(6).await;
    // Not fresh because the value was already in the cache.
    assert!(!entry.is_fresh());
    assert_eq!(entry.into_value(), 3);
}

pub async fn or_insert_with(self, init: impl Future<Output = V>) -> Entry<K, V>

Returns the corresponding Entry for the key given when this entry selector was constructed. If the entry does not exist, resolves the init future and inserts the output.

Example

// Cargo.toml
//
// [dependencies]
// moka = { version = "0.10", features = ["future"] }
// tokio = { version = "1", features = ["rt-multi-thread", "macros" ] }

use moka::future::Cache;

#[tokio::main]
async fn main() {
    let cache: Cache<String, String> = Cache::new(100);
    let key = "key1".to_string();

    let entry = cache
        .entry(key.clone())
        .or_insert_with(async { "value1".to_string() })
        .await;
    assert!(entry.is_fresh());
    assert_eq!(entry.key(), &key);
    assert_eq!(entry.into_value(), "value1");

    let entry = cache
        .entry(key)
        .or_insert_with(async { "value2".to_string() })
        .await;
    // Not fresh because the value was already in the cache.
    assert!(!entry.is_fresh());
    assert_eq!(entry.into_value(), "value1");
}

Concurrent calls on the same key

This method guarantees that concurrent calls on the same not-existing entry are coalesced into one evaluation of the init future. Only one of the calls evaluates its future (thus returned entry’s is_fresh method returns true), and other calls wait for that future to resolve (and their is_fresh return false).

For more detail about the coalescing behavior, see Cache::get_with.

pub async fn or_insert_with_if( self, init: impl Future<Output = V>, replace_if: impl FnMut(&V) -> bool ) -> Entry<K, V>

Works like or_insert_with, but takes an additional replace_if closure.

This method will resolve the init future and insert the output to the cache when:

• The key does not exist.
• Or, replace_if closure returns true.

pub async fn or_optionally_insert_with( self, init: impl Future<Output = Option<V>> ) -> Option<Entry<K, V>>

Returns the corresponding Entry for the key given when this entry selector was constructed. If the entry does not exist, resolves the init future, and inserts an entry if Some(value) was returned. If None was returned from the future, this method does not insert an entry and returns None.

Example

// Cargo.toml
//
// [dependencies]
// moka = { version = "0.10", features = ["future"] }
// tokio = { version = "1", features = ["rt-multi-thread", "macros" ] }

use moka::future::Cache;

#[tokio::main]
async fn main() {
    let cache: Cache<String, u32> = Cache::new(100);
    let key = "key1".to_string();

    let none_entry = cache
        .entry(key.clone())
        .or_optionally_insert_with(async { None })
        .await;
    assert!(none_entry.is_none());

    let some_entry = cache
        .entry(key.clone())
        .or_optionally_insert_with(async { Some(3) })
        .await;
    assert!(some_entry.is_some());
    let entry = some_entry.unwrap();
    assert!(entry.is_fresh());
    assert_eq!(entry.key(), &key);
    assert_eq!(entry.into_value(), 3);

    let some_entry = cache
        .entry(key)
        .or_optionally_insert_with(async { Some(6) })
        .await;
    let entry = some_entry.unwrap();
    // Not fresh because the value was already in the cache.
    assert!(!entry.is_fresh());
    assert_eq!(entry.into_value(), 3);
}

Concurrent calls on the same key

This method guarantees that concurrent calls on the same not-existing entry are coalesced into one evaluation of the init future. Only one of the calls evaluates its future (thus returned entry’s is_fresh method returns true), and other calls wait for that future to resolve (and their is_fresh return false).

For more detail about the coalescing behavior, see Cache::optionally_get_with.

pub async fn or_try_insert_with<F, E>( self, init: F ) -> Result<Entry<K, V>, Arc<E>>where F: Future<Output = Result<V, E>>, E: Send + Sync + 'static,

Returns the corresponding Entry for the key given when this entry selector was constructed. If the entry does not exist, resolves the init future, and inserts an entry if Ok(value) was returned. If Err(_) was returned from the future, this method does not insert an entry and returns the Err wrapped by std::sync::Arc.

Example

// Cargo.toml
//
// [dependencies]
// moka = { version = "0.10", features = ["future"] }
// tokio = { version = "1", features = ["rt-multi-thread", "macros" ] }

use moka::future::Cache;

#[tokio::main]
async fn main() {
    let cache: Cache<String, u32> = Cache::new(100);
    let key = "key1".to_string();

    let error_entry = cache
        .entry(key.clone())
        .or_try_insert_with(async { Err("error") })
        .await;
    assert!(error_entry.is_err());

    let ok_entry = cache
        .entry(key.clone())
        .or_try_insert_with(async { Ok::<u32, &str>(3) })
        .await;
    assert!(ok_entry.is_ok());
    let entry = ok_entry.unwrap();
    assert!(entry.is_fresh());
    assert_eq!(entry.key(), &key);
    assert_eq!(entry.into_value(), 3);

    let ok_entry = cache
        .entry(key)
        .or_try_insert_with(async { Ok::<u32, &str>(6) })
        .await;
    let entry = ok_entry.unwrap();
    // Not fresh because the value was already in the cache.
    assert!(!entry.is_fresh());
    assert_eq!(entry.into_value(), 3);
}

Concurrent calls on the same key

This method guarantees that concurrent calls on the same not-existing entry are coalesced into one evaluation of the init future (as long as these futures return the same error type). Only one of the calls evaluates its future (thus returned entry’s is_fresh method returns true), and other calls wait for that future to resolve (and their is_fresh return false).

For more detail about the coalescing behavior, see Cache::try_get_with.