Implementation:LMCache LMCache RWLock

Knowledge Sources	LMCache
Domains	Concurrency, Thread Safety
Last Updated	2026-02-09 00:00 GMT

Overview

Provides thread synchronization primitives including a read-write lock and a fast lock, both with timeout support, for thread-safe operations in the LMCache cache controller.

Description

This module implements two lock classes for thread-safe operations. RWLockWithTimeout is a classic readers-writer lock allowing multiple concurrent readers but exclusive writer access, with optional timeout on both acquire operations. It includes context managers (read_lock and write_lock) for safe usage. FastLockWithTimeout is an optimized mutex for high-frequency operations on small critical sections, using a non-blocking fast path to minimize context switch overhead. Both locks raise RWLockTimeoutError when acquisition fails within the specified timeout. Neither lock is reentrant.

Usage

Use RWLockWithTimeout when protecting shared data structures that are read frequently but written infrequently, such as the registry tree in the cache controller. Use FastLockWithTimeout for high-frequency, short critical sections such as per-worker node state updates where lock contention is expected to be minimal.

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/v1/cache_controller/locks.py
• Lines: 1-149

Signature

class RWLockTimeoutError(Exception): ...

class RWLockWithTimeout:
    def __init__(self) -> None: ...
    def acquire_read(self, timeout: Optional[float] = None) -> bool: ...
    def release_read(self) -> None: ...
    def acquire_write(self, timeout: Optional[float] = None) -> bool: ...
    def release_write(self) -> None: ...
    def read_lock(self, timeout: Optional[float] = None): ...   # context manager
    def write_lock(self, timeout: Optional[float] = None): ...  # context manager

class FastLockWithTimeout:
    def __init__(self) -> None: ...
    def acquire(self, timeout: Optional[float] = None) -> bool: ...
    def release(self) -> None: ...
    def __enter__(self) -> "FastLockWithTimeout": ...
    def __exit__(self, exc_type, exc_val, exc_tb) -> None: ...

Import

from lmcache.v1.cache_controller.locks import (
    RWLockWithTimeout,
    RWLockTimeoutError,
    FastLockWithTimeout,
)

I/O Contract

Inputs

Name	Type	Required	Description
timeout	Optional[float]	No	Timeout in seconds for lock acquisition; None means wait indefinitely

Outputs

Name	Type	Description
acquired	bool	Whether the lock was successfully acquired (for acquire_read/acquire_write/acquire methods)
RWLockTimeoutError	Exception	Raised by context managers when timeout expires before lock acquisition

Usage Examples

from lmcache.v1.cache_controller.locks import RWLockWithTimeout, FastLockWithTimeout

# Read-write lock with context manager
rw_lock = RWLockWithTimeout()

with rw_lock.read_lock(timeout=5.0):
    # Multiple threads can read concurrently
    data = shared_dict.get("key")

with rw_lock.write_lock(timeout=10.0):
    # Only one thread can write at a time
    shared_dict["key"] = new_value

# Fast lock for high-frequency operations
fast_lock = FastLockWithTimeout()

with fast_lock:
    # Short critical section with non-blocking fast path
    counter += 1