Struct moka::future::RefKeyEntrySelector
source · pub struct RefKeyEntrySelector<'a, K, Q, V, S>where
Q: ?Sized,{ /* private fields */ }
future
only.Expand description
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
.
RefKeyEntrySelector
is constructed from the
entry_by_ref
method on the cache.
Implementations§
source§impl<'a, K, Q, V, S> RefKeyEntrySelector<'a, K, Q, V, S>where
K: Borrow<Q> + Hash + Eq + Send + Sync + 'static,
Q: ToOwned<Owned = K> + Hash + Eq + ?Sized,
V: Clone + Send + Sync + 'static,
S: BuildHasher + Clone + Send + Sync + 'static,
impl<'a, K, Q, V, S> RefKeyEntrySelector<'a, K, Q, V, S>where K: Borrow<Q> + Hash + Eq + Send + Sync + 'static, Q: ToOwned<Owned = K> + Hash + Eq + ?Sized, V: Clone + Send + Sync + 'static, S: BuildHasher + Clone + Send + Sync + 'static,
sourcepub async fn or_default(self) -> Entry<K, V>where
V: Default,
pub async fn or_default(self) -> Entry<K, V>where V: Default,
Returns the corresponding Entry
for the reference of the key given when
this entry selector was constructed. If the entry does not exist, inserts one
by cloning the key and 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_by_ref(&key).or_default().await;
assert!(entry.is_fresh());
assert_eq!(entry.key(), &key);
assert_eq!(entry.into_value(), None);
let entry = cache.entry_by_ref(&key).or_default().await;
// Not fresh because the value was already in the cache.
assert!(!entry.is_fresh());
}
sourcepub async fn or_insert(self, default: V) -> Entry<K, V>
pub async fn or_insert(self, default: V) -> Entry<K, V>
Returns the corresponding Entry
for the reference of the key given when
this entry selector was constructed. If the entry does not exist, inserts one
by cloning the key and using 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_by_ref(&key).or_insert(3).await;
assert!(entry.is_fresh());
assert_eq!(entry.key(), &key);
assert_eq!(entry.into_value(), 3);
let entry = cache.entry_by_ref(&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);
}
sourcepub async fn or_insert_with(self, init: impl Future<Output = V>) -> Entry<K, V>
pub async fn or_insert_with(self, init: impl Future<Output = V>) -> Entry<K, V>
Returns the corresponding Entry
for the reference of the key given when
this entry selector was constructed. If the entry does not exist, inserts one
by cloning the key and resolving the init
future for the value.
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_by_ref(&key)
.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_by_ref(&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
.
sourcepub async fn or_insert_with_if(
self,
init: impl Future<Output = V>,
replace_if: impl FnMut(&V) -> bool
) -> Entry<K, V>
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 returnstrue
.
sourcepub async fn or_optionally_insert_with(
self,
init: impl Future<Output = Option<V>>
) -> Option<Entry<K, V>>
pub async fn or_optionally_insert_with( self, init: impl Future<Output = Option<V>> ) -> Option<Entry<K, V>>
Returns the corresponding Entry
for the reference of the key given when
this entry selector was constructed. If the entry does not exist, clones the
key and resolves the init
future. If Some(value)
was returned by the
future, inserts an entry with the value . If None
was returned, 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_by_ref(&key)
.or_optionally_insert_with(async { None })
.await;
assert!(none_entry.is_none());
let some_entry = cache
.entry_by_ref(&key)
.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_by_ref(&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
.
sourcepub 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,
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 reference of the key given when
this entry selector was constructed. If the entry does not exist, clones the
key and resolves the init
future. If Ok(value)
was returned from the
future, inserts an entry with the value. If Err(_)
was returned, 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_by_ref(&key)
.or_try_insert_with(async { Err("error") })
.await;
assert!(error_entry.is_err());
let ok_entry = cache
.entry_by_ref(&key)
.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_by_ref(&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
.