Trait Cached

pub trait Cached<K, V> {
    // Required methods
    fn cache_get<Q>(&mut self, k: &Q) -> Option<&V>
       where K: Borrow<Q>,
             Q: Hash + Eq + ?Sized;
    fn cache_get_mut<Q>(&mut self, k: &Q) -> Option<&mut V>
       where K: Borrow<Q>,
             Q: Hash + Eq + ?Sized;
    fn cache_set(&mut self, k: K, v: V) -> Option<V>;
    fn cache_get_or_set_with<F: FnOnce() -> V>(&mut self, k: K, f: F) -> &mut V;
    fn cache_try_get_or_set_with<F: FnOnce() -> Result<V, E>, E>(
        &mut self,
        k: K,
        f: F,
    ) -> Result<&mut V, E>;
    fn cache_remove<Q>(&mut self, k: &Q) -> Option<V>
       where K: Borrow<Q>,
             Q: Hash + Eq + ?Sized;
    fn cache_clear(&mut self);
    fn cache_reset(&mut self);
    fn cache_size(&self) -> usize;

    // Provided methods
    fn cache_reset_metrics(&mut self) { ... }
    fn cache_hits(&self) -> Option<u64> { ... }
    fn cache_misses(&self) -> Option<u64> { ... }
    fn cache_capacity(&self) -> Option<usize> { ... }
    fn cache_lifespan(&self) -> Option<u64> { ... }
    fn cache_set_lifespan(&mut self, _seconds: u64) -> Option<u64> { ... }
    fn cache_unset_lifespan(&mut self) -> Option<u64> { ... }
}

Cache operations

use cached::{Cached, UnboundCache};

let mut cache: UnboundCache<String, String> = UnboundCache::new();

// When writing, keys and values are owned:
cache.cache_set("key".to_string(), "owned value".to_string());

// When reading, keys are only borrowed for lookup:
let borrowed_cache_value = cache.cache_get("key");

assert_eq!(borrowed_cache_value, Some(&"owned value".to_string()))

Required Methods

fn cache_get<Q>(&mut self, k: &Q) -> Option<&V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Attempt to retrieve a cached value

// You can use borrowed data, or the data's borrowed type:
let borrow_lookup_1 = cache.cache_get("key")
    .map(String::clone);
let borrow_lookup_2 = cache.cache_get(&"key".to_string())
    .map(String::clone); // copy the values for test asserts

fn cache_get_mut<Q>(&mut self, k: &Q) -> Option<&mut V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Attempt to retrieve a cached value with mutable access

// You can use borrowed data, or the data's borrowed type:
let borrow_lookup_1 = cache.cache_get_mut("key")
    .map(|value| value.clone());
let borrow_lookup_2 = cache.cache_get_mut(&"key".to_string())
    .map(|value| value.clone()); // copy the values for test asserts

fn cache_set(&mut self, k: K, v: V) -> Option<V>

Insert a key, value pair and return the previous value

fn cache_get_or_set_with<F: FnOnce() -> V>(&mut self, k: K, f: F) -> &mut V

Get or insert a key, value pair

fn cache_try_get_or_set_with<F: FnOnce() -> Result<V, E>, E>( &mut self, k: K, f: F, ) -> Result<&mut V, E>

Get or insert a key, value pair with error handling

fn cache_remove<Q>(&mut self, k: &Q) -> Option<V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Remove a cached value

// You can use borrowed data, or the data's borrowed type:
let remove_1 = cache.cache_remove("key1");
let remove_2 = cache.cache_remove(&"key2".to_string());

fn cache_clear(&mut self)

Remove all cached values. Keeps the allocated memory for reuse.

fn cache_reset(&mut self)

Remove all cached values. Free memory and return to initial state

fn cache_size(&self) -> usize

Return the current cache size (number of elements)

Provided Methods

fn cache_reset_metrics(&mut self)

Reset misses/hits counters

fn cache_hits(&self) -> Option<u64>

Return the number of times a cached value was successfully retrieved

fn cache_misses(&self) -> Option<u64>

Return the number of times a cached value was unable to be retrieved

fn cache_capacity(&self) -> Option<usize>

Return the cache capacity

fn cache_lifespan(&self) -> Option<u64>

Return the lifespan of cached values (time to eviction)

fn cache_set_lifespan(&mut self, _seconds: u64) -> Option<u64>

Set the lifespan of cached values, returns the old value

fn cache_unset_lifespan(&mut self) -> Option<u64>

Remove the lifespan for cached values, returns the old value.

For cache implementations that don’t support retaining values indefinitely, this method is a no-op.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl<K, V, S> Cached<K, V> for HashMap<K, V, S>

where K: Hash + Eq, S: BuildHasher + Default,

fn cache_get<Q>(&mut self, k: &Q) -> Option<&V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

fn cache_get_mut<Q>(&mut self, k: &Q) -> Option<&mut V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

fn cache_set(&mut self, k: K, v: V) -> Option<V>

fn cache_get_or_set_with<F: FnOnce() -> V>(&mut self, key: K, f: F) -> &mut V

fn cache_try_get_or_set_with<F: FnOnce() -> Result<V, E>, E>( &mut self, k: K, f: F, ) -> Result<&mut V, E>

fn cache_remove<Q>(&mut self, k: &Q) -> Option<V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

fn cache_clear(&mut self)

fn cache_reset(&mut self)

fn cache_size(&self) -> usize

Implementors

impl<K: Hash + Eq + Clone, V> Cached<K, V> for SizedCache<K, V>

impl<K: Hash + Eq + Clone, V> Cached<K, V> for TimedSizedCache<K, V>

impl<K: Hash + Eq + Clone, V: CanExpire> Cached<K, V> for ExpiringValueCache<K, V>

impl<K: Hash + Eq, V> Cached<K, V> for TimedCache<K, V>

impl<K: Hash + Eq, V> Cached<K, V> for UnboundCache<K, V>