Implementation:LMCache LMCache Event Manager

Knowledge Sources	LMCache
Domains	Event Management, Concurrency
Last Updated	2026-02-09 00:00 GMT

Overview

Provides a thread-safe event manager for tracking asynchronous events by type and status within the LMCache system.

Description

The EventManager class manages asynchronous events identified by an EventType enum (currently LOADING) and an EventStatus enum (ONGOING, DONE, NOT_FOUND). Events are stored in a nested dictionary structure organized by type and status, with each event holding an asyncio.Future. The manager provides thread-safe operations (guarded by threading.Lock) to add events (initially as ONGOING), update event status (moving events between status dictionaries), query event status, pop completed events, and count events by status. Status counting is an O(1) operation using dictionary length.

Usage

Use EventManager to track the lifecycle of asynchronous operations like KV cache loading tasks. Add an event when an async operation begins, update its status when it completes, and pop it to retrieve the associated future. Use get_events_count_by_status for lightweight monitoring of in-flight vs. completed events.

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/v1/event_manager.py
• Lines: 1-126

Signature

class EventType(Enum):
    LOADING = auto()

class EventStatus(Enum):
    ONGOING = auto()
    DONE = auto()
    NOT_FOUND = auto()

class EventManager:
    def __init__(self) -> None: ...
    def add_event(self, event_type: EventType, event_id: str, future: asyncio.Future) -> None: ...
    def pop_event(self, event_type: EventType, event_id: str) -> asyncio.Future: ...
    def update_event_status(self, event_type: EventType, event_id: str, status: EventStatus) -> None: ...
    def get_event_status(self, event_type: EventType, event_id: str) -> EventStatus: ...
    def get_events_count_by_status(self, event_type: EventType, status: EventStatus) -> int: ...

Import

from lmcache.v1.event_manager import EventManager, EventType, EventStatus

I/O Contract

Inputs

Name	Type	Required	Description
event_type	EventType	Yes	The type of event (e.g., LOADING)
event_id	str	Yes	Unique string identifier for the event
future	asyncio.Future	Yes	The asyncio Future associated with the event (for add_event)
status	EventStatus	Yes	The target status to move the event to (for update_event_status)

Outputs

Name	Type	Description
future	asyncio.Future	The Future associated with a popped DONE event
status	EventStatus	The current status of the queried event (ONGOING, DONE, or NOT_FOUND)
count	int	Number of events matching the given type and status

Usage Examples

import asyncio
from lmcache.v1.event_manager import EventManager, EventType, EventStatus

manager = EventManager()

# Add an event
future = asyncio.get_event_loop().create_future()
manager.add_event(EventType.LOADING, "req-001", future)

# Check status
status = manager.get_event_status(EventType.LOADING, "req-001")
assert status == EventStatus.ONGOING

# Count ongoing events
ongoing_count = manager.get_events_count_by_status(EventType.LOADING, EventStatus.ONGOING)

# Mark as done
manager.update_event_status(EventType.LOADING, "req-001", EventStatus.DONE)

# Pop the completed event
completed_future = manager.pop_event(EventType.LOADING, "req-001")