Moka

https://docs.rs/moka/latest
Admin
Moka is a fast, concurrent in-memory cache library for Rust inspired by Caffeine, featuring...
Tokens:540,313
Snippets:3,612
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Try Compute With Setup

Source: https://docs.rs/moka/latest/src/moka/future/cache.rs.html?search=std%3A%3Avec

Initializes a cache and defines the structure for testing `and_try_compute_with` operations.

```rust
    #[tokio::test]
    async fn try_compute_with() {
        use crate::ops::compute;
        use tokio::sync::RwLock;

        let cache: Cache<u32, Arc<RwLock<Vec<i32>>>> = Cache::new(100);
        const KEY: u32 = 0;

        // Spawn four async tasks to call `and_try_compute_with` for the same key.
        // Ensure the key-level lock is working by verifying the value after all
        // tasks finish.
        //
        // |         |   task 1   |    task 2     |   task 3   |  task 4    |
        // |---------|------------|---------------|------------|------------|
        // |    0 ms | get none   |               |            |            |
        // |  100 ms |            | blocked       |            |            |
        // |  200 ms | insert [1] |               |            |            |
        // |         |            | get [1]       |            |            |
        // |  300 ms |            |               | blocked    |            |
        // |  400 ms |            | insert [1, 2] |            |            |
        // |         |            |               | get [1, 2] |            |
```

--------------------------------

### Build Cache Example

Source: https://docs.rs/moka/latest/src/moka/sync/builder.rs.html

Demonstrates building a cache with default settings and with custom expiration policies.

```rust
#[test]
fn build_cache() {
    // Cache<char, String>
    let cache = CacheBuilder::new(100).build();
    let policy = cache.policy();

    assert_eq!(policy.max_capacity(), Some(100));
    assert_eq!(policy.time_to_live(), None);
    assert_eq!(policy.time_to_idle(), None);
    assert_eq!(policy.num_segments(), 1);

    cache.insert('a', "Alice");
    assert_eq!(cache.get(&'a'), Some("Alice"));

    let cache = CacheBuilder::new(100)
        .time_to_live(Duration::from_secs(45 * 60))
        .time_to_idle(Duration::from_secs(15 * 60))
        .build();
    let config = cache.policy();

    assert_eq!(config.max_capacity(), Some(100));
    assert_eq!(config.time_to_live(), Some(Duration::from_secs(45 * 60)));
    assert_eq!(config.time_to_idle(), Some(Duration::from_secs(15 * 60)));
    assert_eq!(config.num_segments(), 1);

    cache.insert('a', "Alice");
    assert_eq!(cache.get(&'a'), Some("Alice"));
}
```

--------------------------------

### Try Compute With Setup

Source: https://docs.rs/moka/latest/src/moka/future/cache.rs.html?search=

Initializes a cache and defines the structure for testing concurrent try_compute_with operations.

```rust
    #[tokio::test]
    async fn try_compute_with() {
        use crate::ops::compute;
        use tokio::sync::RwLock;

        let cache: Cache<u32, Arc<RwLock<Vec<i32>>>> = Cache::new(100);
        const KEY: u32 = 0;
```

--------------------------------

### Try Compute With Initialization

Source: https://docs.rs/moka/latest/src/moka/sync/cache.rs.html

Setup for testing `and_try_compute_with` with multiple threads.

```rust
    #[test]
    fn try_compute_with() {
        use crate::ops::compute;
        use std::{
            sync::RwLock,
            thread::{sleep, spawn},
        };

        let cache: Cache<u32, Arc<RwLock<Vec<i32>>>> = Cache::new(100);
        const KEY: u32 = 0;

        // Spawn four threads to call `and_try_compute_with` for the same key. Ensure
        // the key-level lock is working by verifying the value after all threads
        // finish.
        //
        // |         |  thread 1  |   thread 2    |  thread 3  | thread 4   |
        // |---------|------------|---------------|------------|------------|
```

--------------------------------

### Cache Size Estimation Example

Source: https://docs.rs/moka/latest/src/moka/future/cache.rs.html

Demonstrates how to insert items into a cache and retrieve an approximate count.

```rust
/// // Cargo.toml
/// //
/// // [dependencies]
/// // moka = { version = "0.12", features = ["future"] }
/// // tokio = { version = "1", features = ["rt-multi-thread", "macros" ] }
/// use moka::future::Cache;
///
/// #[tokio::main]
/// async fn main() {
///     let cache = Cache::new(10);
///     cache.insert('n', "Netherland Dwarf").await;
///     cache.insert('l', "Lop Eared").await;
```

--------------------------------

### CacheBuilder Configuration Example

Source: https://docs.rs/moka/latest/moka/sync/struct.CacheBuilder.html?search=

Demonstrates how to use CacheBuilder to configure cache capacity and expiration policies.

```APIDOC
## CacheBuilder Configuration

### Description
Configures and builds a cache instance with specific capacity and expiration settings.

### Methods
- **max_capacity(u64)**: Sets the maximum number of entries the cache can hold.
- **time_to_live(Duration)**: Sets the time-to-live (TTL) for entries.
- **time_to_idle(Duration)**: Sets the time-to-idle (TTI) for entries.
- **build()**: Constructs the cache instance.

### Example
```rust
use moka::sync::Cache;
use std::time::Duration;

let cache = Cache::builder()
    .max_capacity(10_000)
    .time_to_live(Duration::from_secs(30 * 60))
    .time_to_idle(Duration::from_secs(5 * 60))
    .build();
```
```

--------------------------------

### Example of Cache Entry Eviction

Source: https://docs.rs/moka/latest/src/moka/future/cache.rs.html

Demonstrates how to use an eviction listener and run pending tasks after a delay.

```rust
            .read_data_file(path.as_path())
            .await
            .with_context(|| format!("Failed to read data from {path:?}"))?;
        println!("contents: {contents}");
    }

    // Sleep for five seconds. While sleeping, the cache entry for key "user1"
    // will be expired and evicted, so the eviction listener will be called to
    // remove the file.
    tokio::time::sleep(Duration::from_secs(5)).await;

    cache.run_pending_tasks();

    Ok(())
}
```

--------------------------------

### Console output for optionally_get_with example

Source: https://docs.rs/moka/latest/src/moka/sync/cache.rs.html?search=std%3A%3Avec

Shows the expected output when multiple threads compete to initialize a cache entry.

```console
Thread 0 started.
Thread 1 started.
Thread 2 started.
get_file_size() called by thread 0.
Thread 3 started.
Thread 2 got the value. (len: 1466)
Thread 0 got the value. (len: 1466)
Thread 1 got the value. (len: 1466)
Thread 3 got the value. (len: 1466)
```

--------------------------------

### Concurrent Cache Initialization Example

Source: https://docs.rs/moka/latest/src/moka/sync/cache.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how concurrent calls to the same key are coalesced into a single initialization closure execution.

```rust
use moka::sync::Cache;
    use std::{path::Path, thread};

    /// This function tries to get the file size in bytes.
    fn get_file_size(thread_id: u8, path: impl AsRef<Path>) -> Option<u64> {
        println!("get_file_size() called by thread {thread_id}.");
        std::fs::metadata(path).ok().map(|m| m.len())
    }

    let cache = Cache::new(100);

    // Spawn four threads.
    let threads: Vec<_> = (0..4_u8)
        .map(|thread_id| {
            let my_cache = cache.clone();
            thread::spawn(move || {
```

--------------------------------

### Concurrent Cache Initialization Example

Source: https://docs.rs/moka/latest/src/moka/sync/cache.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates using optionally_get_with to ensure a value is computed only once across multiple threads.

```rust
println!("Thread {thread_id} started.");

// Try to insert and get the value for key1. Although all four
// threads will call `optionally_get_with` at the same time,
// get_file_size() must be called only once.
let value = my_cache.optionally_get_with(
    "key1",
    || get_file_size(thread_id, "./Cargo.toml"),
);

// Ensure the value exists now.
assert!(value.is_some());
assert!(my_cache.get(&"key1").is_some());

println!(
    "Thread {thread_id} got the value. (len: {})",
    value.unwrap()
);
})
})
.collect();

// Wait all threads to complete.
threads
    .into_iter()
    .for_each(|t| t.join().expect("Thread failed"));
```

```console
Thread 0 started.
Thread 1 started.
Thread 2 started.
get_file_size() called by thread 0.
Thread 3 started.
Thread 2 got the value. (len: 1466)
Thread 0 got the value. (len: 1466)
Thread 1 got the value. (len: 1466)
Thread 3 got the value. (len: 1466)
```

--------------------------------

### Cache Test Setup with try_get_with_by_ref

Source: https://docs.rs/moka/latest/src/moka/future/cache.rs.html

Initializes a cache and defines a task for testing try_get_with_by_ref with custom error types.

```rust
#[tokio::test]
    async fn try_get_with_by_ref() {
        use std::sync::Arc;

        // Note that MyError does not implement std::error::Error trait
        // like anyhow::Error.
        #[derive(Debug)]
        pub struct MyError(#[allow(dead_code)] String);

        type MyResult<T> = Result<T, Arc<MyError>>;

        let cache = Cache::new(100);
        const KEY: &u32 = &0;

        // This test will run eight async tasks:
        //
        // Task1 will be the first task to call `try_get_with_by_ref` for a key, so
        // its async block will be evaluated and then an error will be returned.
        // Nothing will be inserted to the cache.
        let task1 = {
            let cache1 = cache.clone();
            async move {
```

--------------------------------

### Example Usage of and_compute_with

Source: https://docs.rs/moka/latest/src/moka/future/entry_selector.rs.html?search=u32+-%3E+bool

Demonstrates how to use and_compute_with to perform insert, update, and remove operations on a cache entry.

```rust
///                       Op::Put(1) // Insert
    ///                 };
    ///                 // Return a Future that is resolved to `op` immediately.
    ///                 std::future::ready(op)
    ///             })
    ///             .await
    ///     }
    ///
    ///     // This should insert a new counter value 1 to the cache, and return the
    ///     // value with the kind of the operation performed.
    ///     let result = inclement_or_remove_counter(&cache, &key).await;
    ///     let CompResult::Inserted(entry) = result else {
    ///         panic!("`Inserted` should be returned: {result:?}");
    ///     };
    ///     assert_eq!(entry.into_value(), 1);
    ///
    ///     // This should increment the cached counter value by 1.
    ///     let result = inclement_or_remove_counter(&cache, &key).await;
    ///     let CompResult::ReplacedWith(entry) = result else {
    ///         panic!("`ReplacedWith` should be returned: {result:?}");
    ///     };
    ///     assert_eq!(entry.into_value(), 2);
    ///
    ///     // This should remove the cached counter from the cache, and returns the
    ///     // _removed_ value.
    ///     let result = inclement_or_remove_counter(&cache, &key).await;
    ///     let CompResult::Removed(entry) = result else {
    ///         panic!("`Removed` should be returned: {result:?}");
    ///     };
    ///     assert_eq!(entry.into_value(), 2);
    ///
    ///     // The key should not exist.
    ///     assert!(!cache.contains_key(&key));
    ///
    ///     // This should start over; insert a new counter value 1 to the cache.
    ///     let result = inclement_or_remove_counter(&cache, &key).await;
    ///     let CompResult::Inserted(entry) = result else {
    ///         panic!("`Inserted` should be returned: {result:?}");
    ///     };
    ///     assert_eq!(entry.into_value(), 1);
    /// }
```

--------------------------------

### Handling Panics in Cache Get Operations

Source: https://docs.rs/moka/latest/src/moka/sync/cache.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Setup for testing panic handling within cache operations.

```rust
    #[test]
    // https://github.com/moka-rs/moka/issues/43
    fn handle_panic_in_get_with() {
        use std::{sync::Barrier, thread};

        let cache = Cache::new(16);
        let barrier = Arc::new(Barrier::new(2));
        {

```

--------------------------------

### Concurrent cache get operations

Source: https://docs.rs/moka/latest/src/moka/future/cache.rs.html?search=

Shows how standard get operations behave when called during or after the execution of concurrent try_get_with tasks.

```rust
let task6 = {
            let cache6 = cache.clone();
            async move {
                // Wait for 200 ms before calling `get`.
                sleep(Duration::from_millis(200)).await;
                let maybe_v = cache6.get(&KEY).await;
                assert!(maybe_v.is_none());
            }
        };
```

```rust
let task7 = {
            let cache7 = cache.clone();
            async move {
                // Wait for 400 ms before calling `get`.
                sleep(Duration::from_millis(400)).await;
                let maybe_v = cache7.get(&KEY).await;
                assert!(maybe_v.is_none());
            }
        };
```

```rust
let task8 = {
            let cache8 = cache.clone();
            async move {
                // Wait for 800 ms before calling `get`.
                sleep(Duration::from_millis(800)).await;
                let maybe_v = cache8.get(&KEY).await;
                assert_eq!(maybe_v, Some("task3"));
            }
        };
```

--------------------------------

### Concurrent optionally_get_with and get operations

Source: https://docs.rs/moka/latest/src/moka/sync/segment.rs.html

Demonstrates how multiple threads interact with a shared cache using optionally_get_with and get, including timing-based synchronization.

```rust
let thread3 = {
            let cache3 = cache.clone();
            spawn(move || {
                // Wait for 400 ms before calling `optionally_get_with`.
                sleep(Duration::from_millis(400));
                let v = cache3.optionally_get_with(KEY, || {
                    // Wait for 300 ms and return an Ok(&str) value.
                    sleep(Duration::from_millis(300));
                    Some("thread3")
                });
                assert_eq!(v.unwrap(), "thread3");
            })
        };

        // thread4 will be the fourth thread to call `optionally_get_with` for the same
        // key. So its init closure will not be evaluated. Once thread3's init
        // closure finishes, it will get the same okay &str value.
        let thread4 = {
            let cache4 = cache.clone();
            spawn(move || {
                // Wait for 500 ms before calling `optionally_get_with`.
                sleep(Duration::from_millis(500));
                let v = cache4.optionally_get_with(KEY, || unreachable!());
                assert_eq!(v.unwrap(), "thread3");
            })
        };

        // Thread5 will be the fifth thread to call `optionally_get_with` for the same
        // key. So its init closure will not be evaluated. By the time it calls,
        // thread3's init closure should have finished already, so its init closure
        // will not be evaluated and will get the value insert by thread3's init
        // closure immediately.
        let thread5 = {
            let cache5 = cache.clone();
            spawn(move || {
                // Wait for 800 ms before calling `optionally_get_with`.
                sleep(Duration::from_millis(800));
                let v = cache5.optionally_get_with(KEY, || unreachable!());
                assert_eq!(v.unwrap(), "thread3");
            })
        };

        // Thread6 will call `get` for the same key. It will call when thread1's init
        // closure is still running, so it will get none for the key.
        let thread6 = {
            let cache6 = cache.clone();
            spawn(move || {
                // Wait for 200 ms before calling `get`.
                sleep(Duration::from_millis(200));
                let maybe_v = cache6.get(&KEY);
                assert!(maybe_v.is_none());
            })
        };

        // Thread7 will call `get` for the same key. It will call after thread1's init
        // closure finished with an error. So it will get none for the key.
        let thread7 = {
            let cache7 = cache.clone();
            spawn(move || {
                // Wait for 400 ms before calling `get`.
                sleep(Duration::from_millis(400));
                let maybe_v = cache7.get(&KEY);
                assert!(maybe_v.is_none());
            })
        };

        // Thread8 will call `get` for the same key. It will call after thread3's init
        // closure finished, so it will get the value insert by thread3's init closure.
        let thread8 = {
            let cache8 = cache.clone();
            spawn(move || {
                // Wait for 800 ms before calling `get`.
                sleep(Duration::from_millis(800));
                let maybe_v = cache8.get(&KEY);
                assert_eq!(maybe_v, Some("thread3"));
            })
        };
```

--------------------------------

### Configure Cache with Eviction Listener

Source: https://docs.rs/moka/latest/src/moka/sync/cache.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example demonstrating how to build a cache with a time-to-live duration and an eviction listener to handle file cleanup.

```rust
    // Create the cache. Set time to live for two seconds and set the
    // eviction listener.
    let cache = Cache::builder()
        .max_capacity(100)
        .time_to_live(Duration::from_secs(2))
        .eviction_listener(eviction_listener)
        .build();
```

--------------------------------

### Conditional Retrieval and Internal Get Logic

Source: https://docs.rs/moka/latest/src/moka/sync/base_cache.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Advanced retrieval methods supporting conditional ignore logic and internal core get implementation.

```rust
    pub(crate) fn get_with_hash_and_ignore_if<Q, I>(
        &self,
        key: &Q,
        hash: u64,
        ignore_if: Option<&mut I>,
        need_key: bool,
    ) -> Option<Entry<K, V>>
    where
        Q: Equivalent<K> + Hash + ?Sized,
        I: FnMut(&V) -> bool,
    {
        // Define a closure to record a read op.
        let record = |op, now| {
            self.record_read_op(op, now)
                .expect("Failed to record a get op");
        };
        self.do_get_with_hash(key, hash, record, ignore_if, need_key)
    }

    pub(crate) fn get_with_hash_without_recording<Q, I>(
        &self,
        key: &Q,
        hash: u64,
        ignore_if: Option<&mut I>,
    ) -> Option<V>
    where
        Q: Equivalent<K> + Hash + ?Sized,
        I: FnMut(&V) -> bool,
    {
        // Define a closure that skips to record a read op.
        let record = |_op, _now| {};
        self.do_get_with_hash(key, hash, record, ignore_if, false)
            .map(Entry::into_value)
    }

    fn do_get_with_hash<Q, R, I>(
        &self,
        key: &Q,
        hash: u64,
        read_recorder: R,
        mut ignore_if: Option<&mut I>,
        need_key: bool,
    ) -> Option<Entry<K, V>>
    where
        Q: Equivalent<K> + Hash + ?Sized,
        R: Fn(ReadOp<K, V>, Instant),
        I: FnMut(&V) -> bool,
    {
        if self.is_map_disabled() {
            return None;
        }

        let mut now = self.current_time();

        let maybe_entry = self
            .inner
            .get_key_value_and_then(key, hash, move |k, entry| {
                if let Some(ignore_if) = &mut ignore_if {
                    if ignore_if(&entry.value) {
                        // Ignore the entry.
                        return None;
                    }
                }

                let i = &self.inner;
                let (ttl, tti, va) = (&i.time_to_live(), &i.time_to_idle(), &i.valid_after());

                if is_expired_by_per_entry_ttl(entry.entry_info(), now)
                    || is_expired_entry_wo(ttl, va, entry, now)
                    || is_expired_entry_ao(tti, va, entry, now)
```

--------------------------------

### get

Source: https://docs.rs/moka/latest/src/moka/sync/segment.rs.html

Retrieves a clone of the value corresponding to the key.

```APIDOC
## fn get<Q>(&self, key: &Q) -> Option<V>

### Description
Returns a clone of the value corresponding to the key. If the value is expensive to clone, it is recommended to store it wrapped in an `Arc`.
```

--------------------------------

### Configuring Cache with Eviction Listener

Source: https://docs.rs/moka/latest/src/moka/sync/cache.rs.html?search=std%3A%3Avec

Demonstrates setting up a cache with an eviction listener and using try_get_with to manage data files.

```rust
        match file_mgr1.write() {
            Err(_e) => {
                eprintln!("The lock has been poisoned");
            }
            Ok(mut mgr) => {
                if let Err(_e) = mgr.remove_data_file(v.as_path()) {
                    eprintln!("Failed to remove a data file at {v:?}");
                }
            }
        }
    };

    let cache = Cache::builder()
        .max_capacity(100)
        .time_to_live(Duration::from_secs(2))
        .eviction_listener(eviction_listener)
        .build();

    println!("== try_get_with()");
    let key = "user1";
    let path = cache
        .try_get_with(key, || -> anyhow::Result<_> {
            let mut mgr = file_mgr
                .write()
                .map_err(|_e| anyhow::anyhow!("The lock has been poisoned"))?;
            let path = mgr
                .write_data_file(key, "user data".into())
                .with_context(|| format!("Failed to create a data file"))?;
            Ok(path)
        })
        .map_err(|e| anyhow!("{e}"))?;

    println!("\n== read_data_file()");
    {
        let mgr = file_mgr
            .read()
            .map_err(|_e| anyhow::anyhow!("The lock has been poisoned"))?;
        let contents = mgr
            .read_data_file(path.as_path())
            .with_context(|| format!("Failed to read data from {path:?}"))?;
        println!("contents: {contents}");
    }

    std::thread::sleep(Duration::from_secs(5));

    cache.run_pending_tasks();

    Ok(())
```

--------------------------------

### Get Number of Segments

Source: https://docs.rs/moka/latest/src/moka/cht/segment.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the count of segments currently in the map.

```rust
#[cfg(test)]
    /// Returns the number of segments in the map.
    pub(crate) fn num_segments(&self) -> usize {
        self.segments.len()
    }
```

--------------------------------

### try_get_with_by_ref implementation

Source: https://docs.rs/moka/latest/src/moka/future/cache.rs.html?search=std%3A%3Avec

Example of using try_get_with_by_ref with a custom error type.

```rust
#[tokio::test]
    async fn try_get_with_by_ref() {
        use std::sync::Arc;

        // Note that MyError does not implement std::error::Error trait
        // like anyhow::Error.
        #[derive(Debug)]
        pub struct MyError(#[allow(dead_code)] String);

        type MyResult<T> = Result<T, Arc<MyError>>;

        let cache = Cache::new(100);
        const KEY: &u32 = &0;

        // This test will run eight async tasks:
        //
        // Task1 will be the first task to call `try_get_with_by_ref` for a key, so
        // its async block will be evaluated and then an error will be returned.
        // Nothing will be inserted to the cache.
        let task1 = {
            let cache1 = cache.clone();
            async move {
                // Call `try_get_with_by_ref` immediately.
                let v = cache1
                    .try_get_with_by_ref(KEY, async {
```

--------------------------------

### Configure Cache with Expiry and Listener

Source: https://docs.rs/moka/latest/src/moka/future/cache.rs.html?search=

Demonstrates setting up a cache with max capacity and expiry, followed by manual task execution.

```rust
let mut cache = Cache::builder()
    .max_capacity(100)
    .expire_after(expiry)
    .build();
cache.reconfigure_for_testing().await;

// Make the cache exterior immutable.
let cache = cache;

// The key is not present.
cache.get_with("a", async { "alice" }).await;
expiry_counters.incl_expected_creations();
cache.run_pending_tasks().await;

// The key is present.
cache.get_with("a", async { "alex" }).await;
expiry_counters.incl_expected_reads();
cache.run_pending_tasks().await;

// The key is not present.
cache.invalidate("a").await;
cache.get_with("a", async { "amanda" }).await;
expiry_counters.incl_expected_creations();
cache.run_pending_tasks().await;

expiry_counters.verify();
```

--------------------------------

### Keys Iteration Setup

Source: https://docs.rs/moka/latest/src/moka/cht/map/bucket_array_ref.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes the guard for iterating over keys in the bucket array.

```rust
pub(crate) fn keys<T>(&self, mut with_key: impl FnMut(&K) -> T) -> Vec<T> {
        let guard = &crossbeam_epoch::pin();
```

--------------------------------

### Try Get with Reference

Source: https://docs.rs/moka/latest/src/moka/sync/segment.rs.html?search=u32+-%3E+bool

Similar to try_get_with but accepts a reference to the key, cloning it if necessary.

```rust
pub fn try_get_with_by_ref<F, E, Q>(&self, key: &Q, init: F) -> Result<V, Arc<E>>
    where
        F: FnOnce() -> Result<V, E>,
        E: Send + Sync + 'static,
        Q: Equivalent<K> + ToOwned<Owned = K> + Hash + ?Sized,
    {
        let hash = self.inner.hash(key);
        self.inner
            .select(hash)
            .get_or_try_insert_with_hash_by_ref_and_fun(key, hash, init, false)
            .map(Entry::into_value)
    }
```

--------------------------------

### Configure Housekeeper for Eviction

Source: https://docs.rs/moka/latest/src/moka/future/cache.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates setting up a cache with specific HousekeeperConfig and verifying eviction behavior without an eviction listener.

```rust
#[tokio::test]
    async fn no_batch_size_limit_on_eviction() {
        const MAX_CAPACITY: u64 = 20;

        const EVICTION_TIMEOUT: Duration = Duration::from_nanos(0);
        const MAX_LOG_SYNC_REPEATS: u32 = 1;
        const EVICTION_BATCH_SIZE: u32 = 1;

        let hk_conf = HousekeeperConfig::new(
            // Timeout should be ignored when the eviction listener is not provided.
            Some(EVICTION_TIMEOUT),
            Some(MAX_LOG_SYNC_REPEATS),
            Some(EVICTION_BATCH_SIZE),
        );

        // Create a cache with the LRU policy.
        let mut cache = Cache::builder()
            .max_capacity(MAX_CAPACITY)
            .eviction_policy(EvictionPolicy::lru())
            .housekeeper_config(hk_conf)
            .build();
        cache.reconfigure_for_testing().await;

        // Make the cache exterior immutable.
        let cache = cache;

        // Fill the cache.
        for i in 0..MAX_CAPACITY {
            let v = format!("v{i}");
            cache.insert(i, v).await
        }
        // The max capacity should not change because we have not called
        // `run_pending_tasks` yet.
        assert_eq!(cache.entry_count(), 0);

        cache.run_pending_tasks().await;
        assert_eq!(cache.entry_count(), MAX_CAPACITY);

        // Insert more items to the cache.
        for i in MAX_CAPACITY..(MAX_CAPACITY * 2) {
            let v = format!("v{i}");
            cache.insert(i, v).await
        }
        // The max capacity should not change because we have not called
        // `run_pending_tasks` yet.
        assert_eq!(cache.entry_count(), MAX_CAPACITY);
        // Both old and new keys should exist.
        assert!(cache.contains_key(&0)); // old
        assert!(cache.contains_key(&(MAX_CAPACITY - 1))); // old
        assert!(cache.contains_key(&(MAX_CAPACITY * 2 - 1))); // new

        // Process the remaining write op logs (there should be MAX_CAPACITY logs),
        // and evict the LRU entries.
        cache.run_pending_tasks().await;
        assert_eq!(cache.entry_count(), MAX_CAPACITY);

        // Now all the old keys should be gone.
        assert!(!cache.contains_key(&0));
        assert!(!cache.contains_key(&(MAX_CAPACITY - 1)));
        // And the new keys should exist.
        assert!(cache.contains_key(&(MAX_CAPACITY * 2 - 1)));
    }
```

--------------------------------

### Get Number of Segments

Source: https://docs.rs/moka/latest/src/moka/cht/segment.rs.html

Returns the total count of segments in the map, available only during tests.

```rust
#[cfg(test)]
/// Returns the number of segments in the map.
pub(crate) fn num_segments(&self) -> usize {
    self.segments.len()
}
```

--------------------------------

### Configure Cache with Expiry and Eviction Listener

Source: https://docs.rs/moka/latest/src/moka/future/cache.rs.html

Demonstrates initializing a cache with a custom expiry policy and an eviction listener to track entry lifecycle events.

```rust
#[tokio::main]
async fn main() {
    // Create a `Cache<u32, (Expiration, String)>` with an expiry `MyExpiry` and
    // eviction listener.
    let expiry = MyExpiry;

    let eviction_listener = |key, _value, cause| {
        println!("Evicted key {key}. Cause: {cause:?}");
    };

    let cache = Cache::builder()
        .max_capacity(100)
        .expire_after(expiry)
        .eviction_listener(eviction_listener)
        .build();

    // Insert some entries into the cache with different expirations.
    cache
        .get_with(0, async { (Expiration::AfterShortTime, "a".to_string()) })
        .await;

    cache
        .get_with(1, async { (Expiration::AfterLongTime, "b".to_string()) })
        .await;

    cache
        .get_with(2, async { (Expiration::Never, "c".to_string()) })
        .await;

    // Verify that all the inserted entries exist.
    assert!(cache.contains_key(&0));
    assert!(cache.contains_key(&1));
    assert!(cache.contains_key(&2));

    // Sleep for 6 seconds. Key 0 should expire.
    println!("\nSleeping for 6 seconds...\n");
    tokio::time::sleep(Duration::from_secs(6)).await;
    cache.run_pending_tasks().await;
    println!("Entry count: {}", cache.entry_count());

    // Verify that key 0 has been evicted.
    assert!(!cache.contains_key(&0));
    assert!(cache.contains_key(&1));
    assert!(cache.contains_key(&2));

    // Sleep for 10 more seconds. Key 1 should expire.
    println!("\nSleeping for 10 seconds...\n");
    tokio::time::sleep(Duration::from_secs(10)).await;
    cache.run_pending_tasks().await;
    println!("Entry count: {}", cache.entry_count());

    // Verify that key 1 has been evicted.
    assert!(!cache.contains_key(&1));
    assert!(cache.contains_key(&2));

    // Manually invalidate key 2.
    cache.invalidate(&2).await;
    assert!(!cache.contains_key(&2));

    println!("\nSleeping for a second...\n");
    tokio::time::sleep(Duration::from_secs(1)).await;
    cache.run_pending_tasks().await;
    println!("Entry count: {}", cache.entry_count());

    println!("\nDone!");
}
```

--------------------------------

### Concurrent Execution Output

Source: https://docs.rs/moka/latest/moka/sync/struct.Cache.html?search=std%3A%3Avec

The expected console output when running the concurrent initialization example.

```text
Thread 1 started.
Thread 2 started.
get_file_size() called by thread 1.
Thread 3 started.
Thread 0 started.
Thread 2 got the value. (len: 1466)
Thread 0 got the value. (len: 1466)
Thread 1 got the value. (len: 1466)
Thread 3 got the value. (len: 1466)
```

--------------------------------

### Cache Entry Count Estimation

Source: https://docs.rs/moka/latest/src/moka/future/cache.rs.html?search=std%3A%3Avec

Demonstrates how to initialize a cache and insert entries before checking the approximate count.

```rust
use moka::future::Cache;

#[tokio::main]
async fn main() {
    let cache = Cache::new(10);
    cache.insert('n', "Netherland Dwarf").await;
    cache.insert('l', "Lop Eared").await;
    cache.insert('d', "Dutch").await;

    // Ensure an entry exists.
```

--------------------------------

### Get or Insert with Hash

Source: https://docs.rs/moka/latest/src/moka/future/cache.rs.html?search=std%3A%3Avec

Retrieves an entry by hash or inserts a new value if the entry does not exist.

```rust
pub(crate) async fn get_or_insert_with_hash(
        &self,
        key: Arc<K>,
        hash: u64,
        init: impl FnOnce() -> V,
    ) -> Entry<K, V> {
        match self
            .base
            .get_with_hash(&*key, hash, never_ignore(), true, true)
            .await
        {
            Some(entry) => entry,
            None => {
                let value = init();
                self.insert_with_hash(Arc::clone(&key), hash, value.clone())
                    .await;
                Entry::new(Some(key), value, true, false)
            }
        }
    }
```

```rust
pub(crate) async fn get_or_insert_with_hash_by_ref<Q>(
        &self,
        key: &Q,
        hash: u64,
        init: impl FnOnce() -> V,
    ) -> Entry<K, V>
    where
        Q: Equivalent<K> + ToOwned<Owned = K> + Hash + ?Sized,
    {
        match self
            .base
            .get_with_hash(key, hash, never_ignore(), true, true)
            .await
        {
            Some(entry) => entry,
            None => {
                let key = Arc::new(key.to_owned());
                let value = init();
                self.insert_with_hash(Arc::clone(&key), hash, value.clone())
                    .await;
                Entry::new(Some(key), value, true, false)
            }
        }
    }
```

--------------------------------

### Cache Initialization

Source: https://docs.rs/moka/latest/src/moka/future/base_cache.rs.html

Constructor for the internal cache structure, handling segment allocation and policy setup.

```rust
    #[allow(clippy::too_many_arguments)]
    fn new(
        name: Option<String>,
        max_capacity: Option<u64>,
        initial_capacity: Option<usize>,
        build_hasher: S,
        weigher: Option<Weigher<K, V>>,
        eviction_policy: EvictionPolicy,
        eviction_listener: Option<AsyncEvictionListener<K, V>>,
        read_op_ch: Receiver<ReadOp<K, V>>,
        write_op_ch: Receiver<WriteOp<K, V>>,
        expiration_policy: ExpirationPolicy<K, V>,
        invalidator_enabled: bool,
        clock: Clock,
    ) -> Self {
        // TODO: Calculate the number of segments based on the max capacity and
        // the number of CPUs.
        let (num_segments, initial_capacity) = if max_capacity == Some(0) {
            (1, 0)
        } else {
            let ic = initial_capacity
                .map(|cap| cap + WRITE_LOG_CH_SIZE)
                .unwrap_or_default();
            (64, ic)
        };
        let cache = crate::cht::SegmentedHashMap::with_num_segments_capacity_and_hasher(
            num_segments,
            initial_capacity,
            build_hasher.clone(),
        );

        let now = clock.now();
        let timer_wheel = Mutex::new(TimerWheel::new(now));

        let (removal_notifier, key_locks) = if let Some(listener) = eviction_listener {
            let rn = Arc::new(RemovalNotifier::new(listener, name.clone()));
            let kl = KeyLockMap::with_hasher(build_hasher.clone());
            (Some(rn), Some(kl))
        } else {
            (None, None)
        };
        let invalidator = if invalidator_enabled {
            Some(Invalidator::new(build_hasher.clone()))
        } else {
            None
        };

        Self {
            name,
            max_capacity,
            entry_count: AtomicCell::default(),
            weighted_size: AtomicCell::default(),
            cache,
            build_hasher,
            deques: Mutex::default(),
            timer_wheel,
            frequency_sketch: RwLock::new(FrequencySketch::default()),
            frequency_sketch_enabled: AtomicBool::default(),
            read_op_ch,

```

--------------------------------

### Configure CacheBuilder with segments and eviction listeners

Source: https://docs.rs/moka/latest/src/moka/sync/builder.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates initializing a cache with specific segment counts and configuring advanced options like TTL, TTI, and eviction listeners.

```rust
let cache = CacheBuilder::new(100).segments(15).build();
let policy = cache.policy();

assert_eq!(policy.max_capacity(), Some(100));
assert!(policy.time_to_live().is_none());
assert!(policy.time_to_idle().is_none());
assert_eq!(policy.num_segments(), 16_usize.next_power_of_two());

cache.insert('b', "Bob");
assert_eq!(cache.get(&'b'), Some("Bob"));

let listener = move |_key, _value, _cause| ();

let builder = CacheBuilder::new(400)
    .time_to_live(Duration::from_secs(45 * 60))
    .time_to_idle(Duration::from_secs(15 * 60))
    .eviction_listener(listener)
    .name("tracked_sessions")
    .segments(24);

assert!(builder.eviction_listener.is_some());

let cache = builder.build();
let policy = cache.policy();

assert_eq!(policy.max_capacity(), Some(400));
assert_eq!(policy.time_to_live(), Some(Duration::from_secs(45 * 60)));
assert_eq!(policy.time_to_idle(), Some(Duration::from_secs(15 * 60)));
assert_eq!(policy.num_segments(), 24_usize.next_power_of_two());
assert_eq!(cache.name(), Some("tracked_sessions"));

cache.insert('b', "Bob");
assert_eq!(cache.get(&'b'), Some("Bob"));
```

--------------------------------

### Configure Housekeeper for Eviction

Source: https://docs.rs/moka/latest/src/moka/future/cache.rs.html

Shows how to configure the housekeeper with specific batch sizes and timeouts, and how to verify cache capacity behavior.

```rust
#[tokio::test]
async fn no_batch_size_limit_on_eviction() {
    const MAX_CAPACITY: u64 = 20;

    const EVICTION_TIMEOUT: Duration = Duration::from_nanos(0);
    const MAX_LOG_SYNC_REPEATS: u32 = 1;
    const EVICTION_BATCH_SIZE: u32 = 1;

    let hk_conf = HousekeeperConfig::new(
        // Timeout should be ignored when the eviction listener is not provided.
        Some(EVICTION_TIMEOUT),
        Some(MAX_LOG_SYNC_REPEATS),
        Some(EVICTION_BATCH_SIZE),
    );

    // Create a cache with the LRU policy.
    let mut cache = Cache::builder()
        .max_capacity(MAX_CAPACITY)
        .eviction_policy(EvictionPolicy::lru())
        .housekeeper_config(hk_conf)
        .build();
    cache.reconfigure_for_testing().await;

    // Make the cache exterior immutable.
    let cache = cache;

    // Fill the cache.
    for i in 0..MAX_CAPACITY {
        let v = format!("v{i}");
        cache.insert(i, v).await
    }
    // The max capacity should not change because we have not called
    // `run_pending_tasks` yet.
    assert_eq!(cache.entry_count(), 0);

    cache.run_pending_tasks().await;
    assert_eq!(cache.entry_count(), MAX_CAPACITY);

    // Insert more items to the cache.
    for i in MAX_CAPACITY..(MAX_CAPACITY * 2) {
        let v = format!("v{i}");
        cache.insert(i, v).await
    }
    // The max capacity should not change because we have not called
    // `run_pending_tasks` yet.
    assert_eq!(cache.entry_count(), MAX_CAPACITY);
    // Both old and new keys should exist.
    assert!(cache.contains_key(&0)); // old
    assert!(cache.contains_key(&(MAX_CAPACITY - 1))); // old
    assert!(cache.contains_key(&(MAX_CAPACITY * 2 - 1))); // new

    // Process the remaining write op logs (there should be MAX_CAPACITY logs),
    // and evict the LRU entries.
    cache.run_pending_tasks().await;
    assert_eq!(cache.entry_count(), MAX_CAPACITY);

    // Now all the old keys should be gone.
    assert!(!cache.contains_key(&0));
    assert!(!cache.contains_key(&(MAX_CAPACITY - 1)));
    // And the new keys should exist.
    assert!(cache.contains_key(&(MAX_CAPACITY * 2 - 1)));
}
```

--------------------------------

### Configure Cache with Segments and Policies

Source: https://docs.rs/moka/latest/src/moka/sync/builder.rs.html?search=

Demonstrates initializing a cache with custom segment counts and configuring TTL, TTI, and eviction listeners via the builder pattern.

```rust
// SegmentCache<char, String>
let cache = CacheBuilder::new(100).segments(15).build();
let policy = cache.policy();

assert_eq!(policy.max_capacity(), Some(100));
assert!(policy.time_to_live().is_none());
assert!(policy.time_to_idle().is_none());
assert_eq!(policy.num_segments(), 16_usize.next_power_of_two());

cache.insert('b', "Bob");
assert_eq!(cache.get(&'b'), Some("Bob"));

let listener = move |_key, _value, _cause| ();

let builder = CacheBuilder::new(400)
    .time_to_live(Duration::from_secs(45 * 60))
    .time_to_idle(Duration::from_secs(15 * 60))
    .eviction_listener(listener)
    .name("tracked_sessions")
    // Call segments() at the end to check all field values in the current
    // builder struct are copied to the new builder:
    // https://github.com/moka-rs/moka/issues/207
    .segments(24);

assert!(builder.eviction_listener.is_some());

let cache = builder.build();
let policy = cache.policy();

assert_eq!(policy.max_capacity(), Some(400));
assert_eq!(policy.time_to_live(), Some(Duration::from_secs(45 * 60)));
assert_eq!(policy.time_to_idle(), Some(Duration::from_secs(15 * 60)));
assert_eq!(policy.num_segments(), 24_usize.next_power_of_two());
assert_eq!(cache.name(), Some("tracked_sessions"));

cache.insert('b', "Bob");
assert_eq!(cache.get(&'b'), Some("Bob"));
```

--------------------------------

### build()

Source: https://docs.rs/moka/latest/moka/future/struct.CacheBuilder.html

Finalizes the configuration and builds the Cache instance.

```APIDOC
### pub fn build(self) -> Cache<K, V, RandomState>

Builds a `Cache<K, V>`. Panics if configured with either `time_to_live` or `time_to_idle` higher than 1000 years.
```

--------------------------------

### Configure Size-based Eviction with CacheBuilder

Source: https://docs.rs/moka/latest/moka/future/struct.Cache.html?search=

Demonstrates creating caches with either a fixed entry count limit or a custom weight-based capacity limit using a weigher closure.

```rust
// Cargo.toml
//
// [dependencies]
// moka = { version = "0.12", features = ["future"] }
// tokio = { version = "1", features = ["rt-multi-thread", "macros" ] }
// futures-util = "0.3"

use moka::future::Cache;

#[tokio::main]
async fn main() {
    // Evict based on the number of entries in the cache.
    let cache = Cache::builder()
        // Up to 10,000 entries.
        .max_capacity(10_000)
        // Create the cache.
        .build();
    cache.insert(1, "one".to_string()).await;

    // Evict based on the byte length of strings in the cache.
    let cache = Cache::builder()
        // A weigher closure takes &K and &V and returns a u32
        // representing the relative size of the entry.
        .weigher(|_key, value: &String| -> u32 {
            value.len().try_into().unwrap_or(u32::MAX)
        })
        // This cache will hold up to 32MiB of values.
        .max_capacity(32 * 1024 * 1024)
        .build();
    cache.insert(2, "two".to_string()).await;
}
```

--------------------------------

### Concatenate Strings

Source: https://docs.rs/moka/latest/moka/future/type.PredicateId.html?search=

Examples of string concatenation using the + operator, including moving and cloning behavior.

```rust
let a = String::from("hello");
let b = String::from(" world");
let c = a + &b;
// `a` is moved and can no longer be used here.
```

```rust
let a = String::from("hello");
let b = String::from(" world");
let c = a.clone() + &b;
// `a` is still valid here.
```

```rust
let a = "hello";
let b = " world";
let c = a.to_string() + b;
```

--------------------------------

### Cache Initialization Methods

Source: https://docs.rs/moka/latest/src/moka/sync/cache.rs.html?search=

Core implementation of atomic cache retrieval and insertion methods.

```rust
    pub fn optionally_get_with<F>(&self, key: K, init: F) -> Option<V>
    where
        F: FnOnce() -> Option<V>,
    {
        let hash = self.base.hash(&key);
        let key = Arc::new(key);

        self.get_or_optionally_insert_with_hash_and_fun(key, hash, init, false)
            .map(Entry::into_value)
    }

    /// Similar to [`optionally_get_with`](#method.optionally_get_with), but instead
    /// of passing an owned key, you can pass a reference to the key. If the key does
    /// not exist in the cache, the key will be cloned to create new entry in the
    /// cache.
    pub fn optionally_get_with_by_ref<F, Q>(&self, key: &Q, init: F) -> Option<V>
    where
        F: FnOnce() -> Option<V>,
        Q: Equivalent<K> + ToOwned<Owned = K> + Hash + ?Sized,
    {
        let hash = self.base.hash(key);
        self.get_or_optionally_insert_with_hash_by_ref_and_fun(key, hash, init, false)
            .map(Entry::into_value)
    }
```

--------------------------------

### Initialize Probe Sequence

Source: https://docs.rs/moka/latest/src/moka/cht/map/bucket.rs.html

Creates a new probe iterator starting from the calculated hash offset.

```rust
fn probe(&self, guard: &'g Guard, hash: u64) -> Probe<'_, 'g, K, V> {
        let buckets = &self.buckets;
        let offset = hash as usize & (buckets.len() - 1);
        // SAFETY: `len()` is never be 0 so this index access will never panic.
        // This invariant is ensured by the `assert!()` at the beginning of
        // `with_length()` because 0 is not a power of two.
        let this_bucket = (offset, &buckets[offset]);
        Probe {
            buckets,
            guard,
            this_bucket,
            offset,

            i: 0,
            reload: true,
        }
    }
```
Tokens:
Raw