What Eviction Policy Does Moka Use? TinyLFU and LRU Configuration

Moka uses the TinyLFU (Tiny Least Frequently Used) eviction policy by default, which combines an LRU eviction strategy with a Count-Min Sketch admission filter to optimize cache hit rates, while also supporting traditional LRU through explicit builder configuration.

The moka-rs/moka crate provides a high-performance concurrent cache for Rust applications. Its eviction policy determines which entries are removed when the cache reaches capacity, directly impacting hit rates and memory efficiency in production workloads.

Default TinyLFU Eviction Policy

By default, Moka caches employ the TinyLFU admission and eviction policy. TinyLFU enhances standard LRU by using a Count-Min Sketch probabilistic data structure to estimate the historical frequency of keys. This allows the cache to admit new entries only if they are more popular than the items they would replace, significantly improving hit rates for workloads with frequency-based access patterns.

The default is established in the cache builder via EvictionPolicy::default(), which resolves to TinyLfu as defined in src/policy.rs. When you create a cache using Cache::new(), the builder automatically applies this default without requiring explicit configuration.

use moka::sync::Cache;

// Creates a cache with default TinyLFU policy
let cache = Cache::new(100);
cache.insert("key", "value");

Configuring the LRU Eviction Policy

While TinyLFU optimizes for general workloads, you can explicitly select pure LRU (Least Recently Used) eviction when recency rather than frequency determines your access patterns. Configure this through the eviction_policy method on the cache builder, which accepts an EvictionPolicy enum value.

The builder API in src/sync/builder.rs provides the eviction_policy setter (around lines 78‑79). Set this to EvictionPolicy::lru() to bypass the TinyLFU admission filter and use standard LRU eviction instead.

use moka::sync::Cache;
use moka::policy::EvictionPolicy;

let cache = Cache::builder()
    .max_capacity(200)
    .eviction_policy(EvictionPolicy::lru()) // Explicitly select LRU
    .build();

cache.insert("item", 42);

Monitoring Eviction Events

Regardless of whether you use TinyLFU or LRU, you can monitor eviction events using the eviction_listener method. This functionality operates independently of the selected eviction policy, allowing you to log or react to removals caused by capacity constraints.

use moka::sync::Cache;
use std::sync::Arc;

let cache = Cache::builder()
    .max_capacity(50)
    .eviction_listener(Arc::new(|key, value| {
        println!("Evicted: {} => {}", key, value);
    }))
    .build();

// Insert enough items to trigger evictions
for i in 0..100 {
    cache.insert(i, i * 10);
}

Source Code Implementation

The eviction policy implementation spans two primary files in the moka-rs/moka repository:

• src/policy.rs — Defines the EvictionPolicy enum with variants TinyLfu and Lru, and implements Default to return TinyLfu.
• src/sync/builder.rs — Contains the eviction_policy method that sets the policy, defaulting to EvictionPolicy::tiny_lfu() when not explicitly overridden.

These components ensure that TinyLFU remains the zero-config default while providing the flexibility to switch to LRU for specialized use cases.

Summary

• Moka defaults to TinyLFU, a hybrid policy combining LRU eviction with Count-Min Sketch frequency filtering for optimal hit rates.
• Pure LRU is available via EvictionPolicy::lru() configured through the cache builder in src/sync/builder.rs.
• Policy configuration occurs at cache construction time and cannot be changed dynamically.
• Eviction listeners work uniformly across both TinyLFU and LRU policies for monitoring cache removals.

Frequently Asked Questions

What is TinyLFU and how does it differ from standard LRU?

TinyLFU (Tiny Least Frequently Used) is an admission policy that uses a Count-Min Sketch to estimate key popularity before admitting new entries into the cache. Unlike standard LRU, which only considers recency, TinyLFU filters out one-hit wonders and infrequently accessed items, generally providing higher hit rates for real-world workloads while maintaining low memory overhead.

How do I switch from TinyLFU to LRU in Moka?

Import moka::policy::EvictionPolicy and call .eviction_policy(EvictionPolicy::lru()) on the cache builder before invoking .build(). This overrides the default EvictionPolicy::tiny_lfu() setting established in src/policy.rs.

Does the eviction policy affect the eviction listener API?

No, the eviction listener API functions identically regardless of whether TinyLFU or LRU is active. The listener callback receives the key and value whenever an entry is evicted due to capacity constraints, independent of the underlying eviction policy logic defined in the source code.

Where is the eviction policy defined in the Moka source code?

The EvictionPolicy enum is defined in src/policy.rs, which specifies the TinyLfu and Lru variants. The default selection and builder configuration logic reside in src/sync/builder.rs, where the builder initializes new caches with EvictionPolicy::default() (TinyLFU) unless explicitly configured otherwise.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}