[Feat] Add is_user_level property and cache_salt param to EvictionPolicy

royyhuang · royyhuang · commit 5a8a031233b3 · 2026-04-14T22:56:25.000Z
Add is_user_level property to EvictionPolicy base class (default False).
The eviction controller uses this to decide whether to check per-user
quotas or aggregate usage — no isinstance checks needed.

Add cache_salt optional parameter to get_eviction_actions(). When set,
user-level policies scope eviction to keys belonging to that user.
Non-user-level policies (LRU, NoOp) accept and ignore the parameter.

This is an interface extension only — no new policies or behavioral
changes. UserLRUEvictionPolicy (follow-up PR) will override
is_user_level to return True and use cache_salt for scoped eviction.

Signed-off-by: royyhuang &lt;royyhuang@gmail.com&gt;
Signed-off-by: royyhuang &lt;roy.y.huang@gmail.com&gt;
diff --git a/lmcache/v1/distributed/eviction.py b/lmcache/v1/distributed/eviction.py
@@ -27,6 +27,20 @@ class EvictionPolicy:
     L1EvictionPolicy and L2EvictionPolicy respectively.
     """
 
+    @property
+    def is_user_level(self) -> bool:
+        """Whether this policy supports per-user eviction.
+
+        When True, the eviction controller checks per-user usage and
+        passes ``cache_salt`` to ``get_eviction_actions()`` to scope
+        eviction to individual users. When False, the controller uses
+        aggregate usage only.
+
+        Default is False. Subclasses that support per-user eviction
+        (e.g., ``UserLRUEvictionPolicy``) should override to return True.
+        """
+        return False
+
     @abstractmethod
     def register_eviction_destination(self, destination: EvictionDestination):
         """
@@ -73,6 +87,7 @@ def get_eviction_actions(
         self,
         expected_ratio: float,
         key_eligible_filter: Callable[[ObjectKey], bool] | None = None,
+        cache_salt: str | None = None,
     ) -> list[EvictionAction]:
         """
         Get the eviction actions to evict objects from cache.
@@ -88,6 +103,11 @@ def get_eviction_actions(
                 provided, keys for which the filter returns False will be
                 skipped. This is useful for skipping locked keys that
                 cannot be deleted.
+            cache_salt: When set, scope eviction to keys belonging to this
+                salt only (identified by ``ObjectKey.cache_salt``). When
+                None, evict globally across all salts. Only meaningful for
+                policies where ``is_user_level`` is True; other policies
+                ignore this parameter.
 
         Returns:
             list[EvictionAction]: The eviction actions to perform. Each
diff --git a/lmcache/v1/distributed/eviction_policy/lru.py b/lmcache/v1/distributed/eviction_policy/lru.py
@@ -123,6 +123,7 @@ def get_eviction_actions(
         self,
         expected_ratio: float,
         key_eligible_filter: Callable[[ObjectKey], bool] | None = None,
+        cache_salt: str | None = None,
     ) -> list[EvictionAction]:
         """
         Get the eviction actions to evict objects from L1 cache.
@@ -137,6 +138,7 @@ def get_eviction_actions(
                 provided, keys for which the filter returns False will be
                 skipped. This is useful for skipping locked keys that
                 cannot be deleted.
+            cache_salt: Ignored by LRU policy (not user-level).
 
         Returns:
             list[EvictionAction]: The eviction actions to perform. Each
diff --git a/lmcache/v1/distributed/eviction_policy/noop.py b/lmcache/v1/distributed/eviction_policy/noop.py
@@ -45,5 +45,6 @@ def get_eviction_actions(
         self,
         expected_ratio: float,
         key_eligible_filter: Callable[[ObjectKey], bool] | None = None,
+        cache_salt: str | None = None,
     ) -> list[EvictionAction]:
         return []
