Implementation:LMCache LMCache Distributed Eviction

Knowledge Sources	LMCache
Domains	Distributed Storage, Cache Eviction
Last Updated	2026-02-09 00:00 GMT

Overview

Defines the abstract base class for cache eviction policies in the L1 distributed storage layer, bridging L1 manager lifecycle events to eviction decision-making.

Description

The EvictionPolicy abstract class serves as the base for all eviction strategies in the LMCache distributed storage system. It extends L1ManagerListener to receive lifecycle notifications about key operations (create, read, write, delete) and translates them into eviction-relevant callbacks. Subclasses must implement on_keys_created, on_keys_touched, on_keys_removed, and get_eviction_actions to define the specific eviction behavior. The register_eviction_destination method allows an eviction destination (such as an L2 tier or discard) to be attached. The class maps L1Manager events to simpler eviction-relevant events: write completions trigger on_keys_created, read completions trigger on_keys_touched, and manager-driven deletions trigger on_keys_removed.

Usage

Subclass EvictionPolicy to implement a concrete eviction strategy (e.g., LRU). Register it with the storage system so it receives L1Manager lifecycle events. When eviction is needed, the storage controller calls get_eviction_actions with an expected eviction ratio to obtain a list of EvictionAction objects specifying which keys to evict and their destination.

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/v1/distributed/eviction.py
• Lines: 1-110

Signature

class EvictionPolicy(L1ManagerListener):
    @abstractmethod
    def register_eviction_destination(self, destination: EvictionDestination) -> None: ...
    @abstractmethod
    def on_keys_created(self, keys: list[ObjectKey]) -> None: ...
    @abstractmethod
    def on_keys_touched(self, keys: list[ObjectKey]) -> None: ...
    @abstractmethod
    def on_keys_removed(self, keys: list[ObjectKey]) -> None: ...
    @abstractmethod
    def get_eviction_actions(self, expected_ratio: float) -> list[EvictionAction]: ...

    # L1ManagerListener implementations (inherited)
    def on_keys_reserved_read(self, keys: list[ObjectKey]) -> None: ...
    def on_keys_read_finished(self, keys: list[ObjectKey]) -> None: ...
    def on_keys_reserved_write(self, keys: list[ObjectKey]) -> None: ...
    def on_keys_write_finished(self, keys: list[ObjectKey]) -> None: ...
    def on_keys_deleted_by_manager(self, keys: list[ObjectKey]) -> None: ...

Import

from lmcache.v1.distributed.eviction import EvictionPolicy

I/O Contract

Inputs

Name	Type	Required	Description
keys	list[ObjectKey]	Yes	List of object keys involved in the lifecycle event
expected_ratio	float	Yes	Hint indicating approximate fraction of tracked keys to evict (0.0 to 1.0)
destination	EvictionDestination	Yes	The eviction destination to register for use by the policy

Outputs

Name	Type	Description
eviction_actions	list[EvictionAction]	List of eviction actions, each containing keys to evict and a destination

Usage Examples

from lmcache.v1.distributed.eviction import EvictionPolicy
from lmcache.v1.distributed.api import ObjectKey
from lmcache.v1.distributed.internal_api import EvictionAction, EvictionDestination

class LRUEvictionPolicy(EvictionPolicy):
    def __init__(self):
        self._access_order = []
        self._destination = None

    def register_eviction_destination(self, destination: EvictionDestination):
        self._destination = destination

    def on_keys_created(self, keys: list[ObjectKey]):
        self._access_order.extend(keys)

    def on_keys_touched(self, keys: list[ObjectKey]):
        # Move to end (most recently used)
        for key in keys:
            if key in self._access_order:
                self._access_order.remove(key)
            self._access_order.append(key)

    def on_keys_removed(self, keys: list[ObjectKey]):
        for key in keys:
            if key in self._access_order:
                self._access_order.remove(key)

    def get_eviction_actions(self, expected_ratio: float) -> list[EvictionAction]:
        count = int(len(self._access_order) * expected_ratio)
        victims = self._access_order[:count]
        return [EvictionAction(keys=victims, destination=self._destination)]