[Refactor] Rename per_cache_salt → by_cache_salt for clarity

royyhuang · royyhuang · commit c59f18b10864 · 2026-04-21T05:20:49.000Z
The `per_*` prefix chained with a multi-word identifier produces long,
awkward names (`per_cache_salt_bytes`, `_per_cache_salt_size_bytes`).
Switch to `by_cache_salt` as the grouping-dimension qualifier:

- AdapterUsage.per_cache_salt_bytes → AdapterUsage.bytes_by_cache_salt
- L2AdapterInterface._per_cache_salt_size_bytes → _bytes_by_cache_salt
- _EMPTY_PER_CACHE_SALT → _EMPTY_BY_CACHE_SALT

No behavior change. Tests and the design doc are updated in lockstep.

Signed-off-by: royyhuang &lt;roy.y.huang@gmail.com&gt;
diff --git a/docs/design/v1/distributed/l2_adapters/l2_per_user_quota.md b/docs/design/v1/distributed/l2_adapters/l2_per_user_quota.md
@@ -37,7 +37,7 @@ L1 Manager → StoreController → L2 Adapter
   │                                │
   │                    _notify_keys_stored(keys, sizes)
   │                      → base class updates _total_bytes_used
-  │                        and _per_cache_salt_size_bytes
+  │                        and _bytes_by_cache_salt
   ▼
 Listeners:  L2EvictionPolicy bridge → UserLRUEvictionPolicy
             ┌──────────────────────┐
@@ -49,7 +49,7 @@ L2EvictionController (every 1s):
   for each adapter state:
     usage = adapter.get_usage()  → AdapterUsage dataclass
     if policy.is_user_level:
-      for cache_salt, bytes in usage.per_cache_salt_bytes:
+      for cache_salt, bytes in usage.bytes_by_cache_salt:
         if bytes > watermark * quota(cache_salt):
           policy.get_eviction_actions(ratio, cache_salt=cache_salt)
     else:
@@ -399,7 +399,7 @@ class AdapterUsage:
     total_capacity_bytes: int
     """Adapter's maximum capacity. 0 means unknown/unlimited."""
 
-    per_cache_salt_bytes: dict[str, int]
+    bytes_by_cache_salt: dict[str, int]
     """Bytes used per cache_salt. Only entries with positive usage."""
 
     @property
@@ -418,7 +418,7 @@ class L2AdapterInterface(ABC):
         self._listeners: list[L2AdapterListener] = []
         self._max_capacity_bytes = max_capacity_bytes
         self._total_bytes_used: int = 0
-        self._per_cache_salt_size_bytes: dict[str, int] = {}
+        self._bytes_by_cache_salt: dict[str, int] = {}
         self._usage_lock = threading.Lock()
 
     @property
@@ -437,8 +437,8 @@ class L2AdapterInterface(ABC):
         with self._usage_lock:
             for key, size in zip(keys, sizes, strict=True):
                 self._total_bytes_used += size
-                self._per_cache_salt_size_bytes[key.cache_salt] = (
-                    self._per_cache_salt_size_bytes.get(key.cache_salt, 0) + size
+                self._bytes_by_cache_salt[key.cache_salt] = (
+                    self._bytes_by_cache_salt.get(key.cache_salt, 0) + size
                 )
         for listener in self._listeners:
             listener.on_l2_keys_stored(keys)
@@ -449,8 +449,8 @@ class L2AdapterInterface(ABC):
         with self._usage_lock:
             for key, size in zip(keys, sizes, strict=True):
                 self._total_bytes_used -= size
-                self._per_cache_salt_size_bytes[key.cache_salt] = (
-                    self._per_cache_salt_size_bytes.get(key.cache_salt, 0) - size
+                self._bytes_by_cache_salt[key.cache_salt] = (
+                    self._bytes_by_cache_salt.get(key.cache_salt, 0) - size
                 )
         for listener in self._listeners:
             listener.on_l2_keys_deleted(keys)
@@ -460,8 +460,8 @@ class L2AdapterInterface(ABC):
             return AdapterUsage(
                 total_bytes_used=self._total_bytes_used,
                 total_capacity_bytes=self._max_capacity_bytes,
-                per_cache_salt_bytes={
-                    k: v for k, v in self._per_cache_salt_size_bytes.items()
+                bytes_by_cache_salt={
+                    k: v for k, v in self._bytes_by_cache_salt.items()
                     if v > 0
                 },
             )
@@ -653,7 +653,7 @@ class L2EvictionController(StorageControllerInterface):
 
         if policy.is_user_level and self._quota_manager:
             # Per-user watermark check
-            for cache_salt, user_bytes in usage.per_cache_salt_bytes.items():
+            for cache_salt, user_bytes in usage.bytes_by_cache_salt.items():
                 limit = self._quota_manager.get_limit_bytes(cache_salt)
                 if user_bytes <= watermark * limit:
                     continue
@@ -673,7 +673,7 @@ class L2EvictionController(StorageControllerInterface):
 ```
 
 The controller uses `policy.is_user_level` (not `isinstance`) to branch:
-- **`is_user_level=True`**: reads `usage.per_cache_salt_bytes`, checks each user
+- **`is_user_level=True`**: reads `usage.bytes_by_cache_salt`, checks each user
   against `watermark * quota`. Unregistered users (quota=0) get ratio=1.0.
 - **`is_user_level=False`**: reads `usage.usage_fraction` for global check.
 
@@ -841,7 +841,7 @@ The feature PR. Depends on PR1a + PR1b + PR2 + PR3 + PR4.
 | `lmcache/v1/distributed/eviction_policy/__init__.py` | Export `UserLRUEvictionPolicy` |
 | `lmcache/v1/distributed/config.py` | Add `"UserLRU"` to literal |
 | `lmcache/v1/distributed/l2_adapters/config.py` | Add `"UserLRU"` to allowed values |
-| `lmcache/v1/distributed/storage_controllers/eviction_controller.py` | `QuotaManager`; per-user branch using `is_user_level` + `per_cache_salt_bytes` |
+| `lmcache/v1/distributed/storage_controllers/eviction_controller.py` | `QuotaManager`; per-user branch using `is_user_level` + `bytes_by_cache_salt` |
 | `lmcache/v1/distributed/storage_manager.py` | Create `QuotaManager`; wire to controller + HTTP |
 | `lmcache/v1/multiprocess/http_server.py` | Quota CRUD endpoints |
 | `tests/v1/distributed/test_user_lru_eviction_policy.py` (new) | Unit tests |
diff --git a/lmcache/v1/distributed/l2_adapters/base.py b/lmcache/v1/distributed/l2_adapters/base.py
@@ -28,21 +28,21 @@
 L2TaskId = int
 
 
-_EMPTY_PER_CACHE_SALT: Mapping[str, int] = MappingProxyType({})
+_EMPTY_BY_CACHE_SALT: Mapping[str, int] = MappingProxyType({})
 
 
 @dataclass(frozen=True)
 class AdapterUsage:
     """Unified usage report for an L2 adapter.
 
     Replaces the old ``tuple[float, float]`` return shape with a structured
-    record that exposes both aggregate and per-cache_salt byte counts.
+    record that exposes both aggregate and per cache_salt byte counts.
     Buckets are keyed by ``ObjectKey.cache_salt`` directly — the salt may
     represent a user, a vLLM deployment, or any other isolation
     granularity the caller chooses; the adapter stays agnostic.
 
     Instances are returned as immutable snapshots:
-    ``per_cache_salt_bytes`` is a read-only ``Mapping``
+    ``bytes_by_cache_salt`` is a read-only ``Mapping``
     (``MappingProxyType``) so callers cannot mutate the snapshot after
     the fact. Each ``get_usage()`` call returns a fresh snapshot so a
     held reference will never reflect later state.
@@ -55,8 +55,8 @@ class AdapterUsage:
     """Adapter's maximum capacity. ``0`` means unknown / unlimited; the
     adapter does not support aggregate (global) usage-based eviction."""
 
-    per_cache_salt_bytes: Mapping[str, int] = field(
-        default_factory=lambda: _EMPTY_PER_CACHE_SALT
+    bytes_by_cache_salt: Mapping[str, int] = field(
+        default_factory=lambda: _EMPTY_BY_CACHE_SALT
     )
     """Bytes used per ``cache_salt``. Only entries with positive usage
     appear; an empty mapping means no traffic has been tracked yet.
@@ -131,11 +131,11 @@ def __init__(self, max_capacity_bytes: int = 0) -> None:
 
         # Centralized byte accounting. Subclasses pass ``sizes`` to
         # ``_notify_keys_stored`` / ``_notify_keys_deleted`` and the base
-        # class maintains both aggregate and per-cache_salt totals so
+        # class maintains both aggregate and per cache_salt totals so
         # every adapter exposes the same shape via ``get_usage()``.
         self._max_capacity_bytes: int = max_capacity_bytes
         self._total_bytes_used: int = 0
-        self._per_cache_salt_size_bytes: dict[str, int] = {}
+        self._bytes_by_cache_salt: dict[str, int] = {}
         self._usage_lock = threading.Lock()
 
     #####################
@@ -358,7 +358,7 @@ def _notify_keys_stored(self, keys: list[ObjectKey], sizes: list[int]) -> None:
         outside the lock so a slow listener cannot stall further notifies.
         """
         # Aggregate per-salt deltas before touching
-        # ``_per_cache_salt_size_bytes`` — one dict read/write per unique
+        # ``_bytes_by_cache_salt`` — one dict read/write per unique
         # salt instead of one per key. This matters when the registry is
         # large (10k+ salts) and keys/sizes are bulky.
         delta: dict[str, int] = {}
@@ -370,8 +370,8 @@ def _notify_keys_stored(self, keys: list[ObjectKey], sizes: list[int]) -> None:
         with self._usage_lock:
             self._total_bytes_used += total_delta
             for salt, d in delta.items():
-                self._per_cache_salt_size_bytes[salt] = (
-                    self._per_cache_salt_size_bytes.get(salt, 0) + d
+                self._bytes_by_cache_salt[salt] = (
+                    self._bytes_by_cache_salt.get(salt, 0) + d
                 )
         for listener in self._listeners:
             listener.on_l2_keys_stored(keys)
@@ -388,7 +388,7 @@ def _notify_keys_deleted(self, keys: list[ObjectKey], sizes: list[int]) -> None:
         the same value the adapter passed to ``_notify_keys_stored``).
 
         Per-cache_salt buckets that drop to zero are removed so the
-        ``per_cache_salt_bytes`` snapshot in ``AdapterUsage`` stays compact.
+        ``bytes_by_cache_salt`` snapshot in ``AdapterUsage`` stays compact.
 
         Counters are clamped at zero — a delete that would drive
         ``_total_bytes_used`` negative indicates an accounting bug in the
@@ -420,11 +420,11 @@ def _notify_keys_deleted(self, keys: list[ObjectKey], sizes: list[int]) -> None:
                 )
                 self._total_bytes_used = 0
             for salt, d in delta.items():
-                new_total = self._per_cache_salt_size_bytes.get(salt, 0) - d
+                new_total = self._bytes_by_cache_salt.get(salt, 0) - d
                 if new_total <= 0:
-                    self._per_cache_salt_size_bytes.pop(salt, None)
+                    self._bytes_by_cache_salt.pop(salt, None)
                 else:
-                    self._per_cache_salt_size_bytes[salt] = new_total
+                    self._bytes_by_cache_salt[salt] = new_total
         for listener in self._listeners:
             listener.on_l2_keys_deleted(keys)
 
@@ -484,15 +484,15 @@ def get_usage(self) -> AdapterUsage:
         """
         with self._usage_lock:
             per_salt_snapshot = {
-                k: v for k, v in self._per_cache_salt_size_bytes.items() if v > 0
+                k: v for k, v in self._bytes_by_cache_salt.items() if v > 0
             }
             return AdapterUsage(
                 total_bytes_used=self._total_bytes_used,
                 total_capacity_bytes=self._max_capacity_bytes,
                 # Wrap in a read-only view so callers can't mutate the
                 # snapshot. The underlying dict is a fresh copy so the
                 # view is fully detached from the adapter's live state.
-                per_cache_salt_bytes=MappingProxyType(per_salt_snapshot),
+                bytes_by_cache_salt=MappingProxyType(per_salt_snapshot),
             )
 
     #####################
diff --git a/lmcache/v1/distributed/storage_controllers/eviction_controller.py b/lmcache/v1/distributed/storage_controllers/eviction_controller.py
@@ -183,7 +183,7 @@ def stop(self):
         self._thread.join()
 
     def report_status(self) -> dict:
-        # NOTE: ``usage.per_cache_salt_bytes`` is intentionally NOT
+        # NOTE: ``usage.bytes_by_cache_salt`` is intentionally NOT
         # surfaced here. A deployment can have 10k+ salts, so embedding
         # the full bucket map in the status response would blow up the
         # payload. A separate paginated / queried endpoint is the right
@@ -199,7 +199,7 @@ def report_status(self) -> dict:
                     "current_usage": usage.usage_fraction,
                     "total_bytes_used": usage.total_bytes_used,
                     "total_capacity_bytes": usage.total_capacity_bytes,
-                    "num_cache_salt_buckets": len(usage.per_cache_salt_bytes),
+                    "num_cache_salt_buckets": len(usage.bytes_by_cache_salt),
                 }
             )
         return {
diff --git a/tests/v1/distributed/test_l2_adapter_base.py b/tests/v1/distributed/test_l2_adapter_base.py
@@ -2,7 +2,7 @@
 """
 Unit tests for the L2 adapter base class accounting + AdapterUsage.
 
-The base class owns ``_total_bytes_used`` / ``_per_cache_salt_size_bytes`` and
+The base class owns ``_total_bytes_used`` / ``_bytes_by_cache_salt`` and
 exposes them through ``get_usage()``. Adapters drive accounting by passing
 ``sizes`` to ``_notify_keys_stored`` / ``_notify_keys_deleted``.
 """
@@ -89,9 +89,9 @@ def test_usage_fraction_negative_capacity_returns_minus_one(self):
         u = AdapterUsage(total_bytes_used=10, total_capacity_bytes=-1)
         assert u.usage_fraction == -1.0
 
-    def test_per_cache_salt_bytes_default_empty(self):
+    def test_bytes_by_cache_salt_default_empty(self):
         u = AdapterUsage(total_bytes_used=0, total_capacity_bytes=100)
-        assert u.per_cache_salt_bytes == {}
+        assert u.bytes_by_cache_salt == {}
 
     def test_frozen(self):
         # Standard
@@ -136,7 +136,7 @@ def test_store_increments_aggregate_and_per_user(self):
         a._notify_keys_stored([k_alice, k_bob, k_alice2], [100, 200, 50])
         u = a.get_usage()
         assert u.total_bytes_used == 350
-        assert u.per_cache_salt_bytes == {"alice": 150, "bob": 200}
+        assert u.bytes_by_cache_salt == {"alice": 150, "bob": 200}
 
     def test_delete_decrements_aggregate_and_per_user(self):
         a = _StubAdapter(max_capacity_bytes=10_000)
@@ -146,7 +146,7 @@ def test_delete_decrements_aggregate_and_per_user(self):
         a._notify_keys_deleted([k_alice], [100])
         u = a.get_usage()
         assert u.total_bytes_used == 200
-        assert u.per_cache_salt_bytes == {"bob": 200}
+        assert u.bytes_by_cache_salt == {"bob": 200}
 
     def test_per_user_bucket_dropped_when_zero(self):
         """Per-user bookkeeping should not retain stale ``0`` entries — it
@@ -158,29 +158,29 @@ def test_per_user_bucket_dropped_when_zero(self):
         a._notify_keys_deleted([k], [100])
         u = a.get_usage()
         assert u.total_bytes_used == 0
-        assert "alice" not in u.per_cache_salt_bytes
-        assert u.per_cache_salt_bytes == {}
+        assert "alice" not in u.bytes_by_cache_salt
+        assert u.bytes_by_cache_salt == {}
 
     def test_empty_salt_is_a_real_bucket(self):
         """Un-salted traffic accumulates under the empty-string key.
-        ``per_cache_salt_bytes`` must reflect that so legacy/unisolated traffic
+        ``bytes_by_cache_salt`` must reflect that so legacy/unisolated traffic
         is observable too."""
         a = _StubAdapter(max_capacity_bytes=10_000)
         k = _make_key(1, salt="")
         a._notify_keys_stored([k], [100])
         u = a.get_usage()
-        assert u.per_cache_salt_bytes == {"": 100}
+        assert u.bytes_by_cache_salt == {"": 100}
 
     def test_get_usage_filters_zero_buckets(self):
         """Snapshot only includes positive-byte buckets."""
         a = _StubAdapter(max_capacity_bytes=10_000)
         # Manually inject a ``0`` entry as if accounting drift left one
         # behind.
-        a._per_cache_salt_size_bytes["ghost"] = 0
-        a._per_cache_salt_size_bytes["alice"] = 100
+        a._bytes_by_cache_salt["ghost"] = 0
+        a._bytes_by_cache_salt["alice"] = 100
         a._total_bytes_used = 100
         u = a.get_usage()
-        assert u.per_cache_salt_bytes == {"alice": 100}
+        assert u.bytes_by_cache_salt == {"alice": 100}
 
     def test_size_list_length_mismatch_raises(self):
         """``zip(strict=True)`` catches caller bugs where keys/sizes drift
@@ -204,17 +204,17 @@ def test_underflow_clamps_to_zero(self):
         assert u.usage_fraction == 0.0  # not the -1 sentinel
 
     def test_get_usage_returns_immutable_per_user_view(self):
-        """``per_cache_salt_bytes`` is a read-only ``Mapping`` so a caller
+        """``bytes_by_cache_salt`` is a read-only ``Mapping`` so a caller
         cannot mutate the snapshot or the adapter's live state."""
         a = _StubAdapter(max_capacity_bytes=10_000)
         k = _make_key(1, salt="alice")
         a._notify_keys_stored([k], [100])
         u = a.get_usage()
         # MappingProxyType raises TypeError on mutation attempts.
         with pytest.raises(TypeError):
-            u.per_cache_salt_bytes["bob"] = 999  # type: ignore[index]
+            u.bytes_by_cache_salt["bob"] = 999  # type: ignore[index]
         # Original snapshot still intact.
-        assert dict(u.per_cache_salt_bytes) == {"alice": 100}
+        assert dict(u.bytes_by_cache_salt) == {"alice": 100}
 
     def test_get_usage_snapshot_is_detached(self):
         """A held ``AdapterUsage`` reference does not see later
@@ -226,11 +226,11 @@ def test_get_usage_snapshot_is_detached(self):
         a._notify_keys_stored([_make_key(2, salt="bob")], [200])
         # u1 is the snapshot at the earlier moment.
         assert u1.total_bytes_used == 100
-        assert dict(u1.per_cache_salt_bytes) == {"alice": 100}
+        assert dict(u1.bytes_by_cache_salt) == {"alice": 100}
         # Live state is now 300 / {alice, bob}.
         u2 = a.get_usage()
         assert u2.total_bytes_used == 300
-        assert dict(u2.per_cache_salt_bytes) == {"alice": 100, "bob": 200}
+        assert dict(u2.bytes_by_cache_salt) == {"alice": 100, "bob": 200}
 
     def test_zero_size_notify_is_listener_only(self):
         """Calling ``_notify_keys_stored`` with size=0 fires the listener
@@ -245,7 +245,7 @@ def test_zero_size_notify_is_listener_only(self):
         a._notify_keys_stored([k], [0])
         u = a.get_usage()
         assert u.total_bytes_used == 100
-        assert dict(u.per_cache_salt_bytes) == {"alice": 100}
+        assert dict(u.bytes_by_cache_salt) == {"alice": 100}
         # Listener fired twice (LRU policy can move_to_end on second).
         assert lst.stored == [[k], [k]]
 
diff --git a/tests/v1/distributed/test_mock_l2_adapter.py b/tests/v1/distributed/test_mock_l2_adapter.py
@@ -708,7 +708,7 @@ def test_get_usage_empty_adapter_is_zero(self, adapter):
         usage = adapter.get_usage()
         assert usage.total_bytes_used == 0
         assert usage.usage_fraction == 0.0
-        assert usage.per_cache_salt_bytes == {}
+        assert usage.bytes_by_cache_salt == {}
 
     def test_get_usage_increases_after_store(self, adapter):
         """get_usage() should report positive bytes after a store."""
@@ -734,7 +734,7 @@ def test_get_usage_decreases_after_delete(self, adapter):
         assert usage.total_bytes_used == 0
         assert usage.usage_fraction == 0.0
 
-    def test_per_cache_salt_bytes_populated_from_cache_salt(self, adapter):
+    def test_bytes_by_cache_salt_populated_from_cache_salt(self, adapter):
         """End-to-end: storing keys with different ``cache_salt`` values
         should drive the per-user byte buckets in ``AdapterUsage`` —
         proves the salt actually flows through the real adapter into the
@@ -761,22 +761,22 @@ def test_per_cache_salt_bytes_populated_from_cache_salt(self, adapter):
             _store_and_wait(adapter, k, obj)
 
         usage = adapter.get_usage()
-        assert usage.per_cache_salt_bytes == {"alice": 1024, "bob": 512}
+        assert usage.bytes_by_cache_salt == {"alice": 1024, "bob": 512}
         assert usage.total_bytes_used == 1536
 
         # Deleting one of alice's keys should shrink alice's bucket but
         # leave bob's untouched.
         adapter.delete([alice_keys[0]])
         usage = adapter.get_usage()
-        assert usage.per_cache_salt_bytes == {"alice": 512, "bob": 512}
+        assert usage.bytes_by_cache_salt == {"alice": 512, "bob": 512}
         assert usage.total_bytes_used == 1024
 
         # Deleting alice's last key should drop the bucket entirely so
         # the snapshot stays compact.
         adapter.delete([alice_keys[1]])
         usage = adapter.get_usage()
-        assert "alice" not in usage.per_cache_salt_bytes
-        assert usage.per_cache_salt_bytes == {"bob": 512}
+        assert "alice" not in usage.bytes_by_cache_salt
+        assert usage.bytes_by_cache_salt == {"bob": 512}
 
     def test_listener_notified_on_store(self, adapter):
         """Listener.on_l2_keys_stored should be called after a store completes."""
