Implementation:LMCache LMCache Pin Monitor

Knowledge Sources	LMCache
Domains	Memory Management, Monitoring
Last Updated	2026-02-09 00:00 GMT

Overview

PinMonitor is a singleton background thread that periodically checks for pinned memory objects that have exceeded their timeout and forcibly unpins them.

Description

PinMonitor extends PeriodicThread and operates as a global singleton per process, shared across all cache engines. It maintains a dictionary of pinned MemoryObj instances keyed by their Python id(), along with their registration timestamps. Each execution cycle checks all registered objects for timeout (configurable via pin_timeout_sec) and force-unpins any that have exceeded the threshold by repeatedly calling unpin() until the pin count reaches zero. The monitor registers itself with a PeriodicThreadRegistry, exports Prometheus metrics for the count of monitored objects, and tracks forced unpin statistics via LMCStatsMonitor. Thread safety is ensured with separate locks for the singleton pattern and the pinned objects dictionary.

Usage

Use PinMonitor.GetOrCreate(config) to obtain the singleton instance on the first call; subsequent calls do not require the config argument. Register objects with on_pin() and unregister with on_unpin(). The monitor auto-starts on creation and can be stopped with stop_monitoring() or destroyed entirely with DestroyInstance().

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/v1/pin_monitor.py
• Lines: 1-246

Signature

class PinMonitor(PeriodicThread):
    def __init__(self, config: "LMCacheEngineConfig"): ...

    @staticmethod
    def GetOrCreate(config: Optional["LMCacheEngineConfig"] = None) -> "PinMonitor": ...

    def on_pin(self, memory_obj: "MemoryObj"): ...
    def on_unpin(self, memory_obj: "MemoryObj"): ...
    def start_monitoring(self): ...
    def stop_monitoring(self): ...
    def get_monitored_count(self) -> int: ...

    @staticmethod
    def DestroyInstance(): ...

Import

from lmcache.v1.pin_monitor import PinMonitor

I/O Contract

Inputs

Name	Type	Required	Description
config	LMCacheEngineConfig	Yes (first call)	Configuration providing pin_check_interval_sec and pin_timeout_sec
memory_obj	MemoryObj	Yes	The pinned memory object to register or unregister for timeout monitoring

Outputs

Name	Type	Description
GetOrCreate	PinMonitor	The singleton PinMonitor instance
get_monitored_count	int	Number of currently monitored pinned objects
_check_timeouts	tuple[int, int, int]	(pinned_count, timeout_count, force_unpin_success_count) from each check cycle

Usage Examples

from lmcache.v1.pin_monitor import PinMonitor

# Get or create the singleton instance
monitor = PinMonitor.GetOrCreate(config)

# Register a pinned object
monitor.on_pin(memory_obj)

# Check how many objects are being monitored
count = monitor.get_monitored_count()

# Unregister when object is unpinned normally
monitor.on_unpin(memory_obj)

# Stop monitoring and destroy the singleton (e.g., in tests)
PinMonitor.DestroyInstance()