Implementation:LMCache LMCache Full Sync Sender

Knowledge Sources	LMCache
Domains	Distributed Caching, State Synchronization
Last Updated	2026-02-09 00:00 GMT

Overview

FullSyncSender manages the worker-side process of fully synchronizing all local hot_cache keys to the cache controller.

Description

The FullSyncSender class orchestrates a multi-step protocol for re-synchronizing a worker's local hot cache state with the central controller, typically triggered after a controller restart. The process involves: entering freeze mode (to prevent new allocations during sync), applying a random startup delay (to avoid thundering herd problems across workers), sending a start message with retry logic, transmitting all keys in configurable batches with rate limiting, sending an end-of-sync marker, and polling for completion status. If the controller reports missing batches, the sender retries sending those specific batches. The sender tracks its syncing state and guarantees cleanup (exiting freeze mode) regardless of success or failure.

Usage

This class is instantiated by the LMCache worker when a full sync is requested. It requires the engine config, the worker instance, the cache engine (for freeze/unfreeze), and the local CPU backend (to enumerate stored keys). It should not be imported by end-user code.

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/v1/cache_controller/full_sync_sender.py
• Lines: 1-475

Signature

@dataclass
class SyncInitResult:
    sync_id: str
    keys: List[int]
    total_keys: int
    batch_count: int

@dataclass
class BatchInfo:
    batch_id: int
    start_idx: int
    end_idx: int

class FullSyncSender:
    def __init__(
        self,
        config: LMCacheEngineConfig,
        worker: "LMCacheWorker",
        lmcache_engine: "LMCacheEngine",
        local_cpu_backend: "LocalCPUBackend",
    ) -> None: ...

    async def start_full_sync(self, reason: Optional[str] = None) -> bool: ...

    @property
    def is_syncing(self) -> bool: ...

Import

from lmcache.v1.cache_controller.full_sync_sender import FullSyncSender

I/O Contract

Inputs

Name	Type	Required	Description
config	LMCacheEngineConfig	Yes	Engine configuration providing batch size, delay, retry, and poll settings
worker	LMCacheWorker	Yes	The worker instance for sending messages to the controller
lmcache_engine	LMCacheEngine	Yes	The cache engine providing freeze/unfreeze capability
local_cpu_backend	LocalCPUBackend	Yes	The local CPU storage backend for enumerating cached keys
reason	Optional[str]	No	Reason for the full sync (e.g., "controller_restart")

Outputs

Name	Type	Description
success	bool	True if the full sync completed successfully, False otherwise
is_syncing	bool	Property indicating whether a sync is currently in progress

Usage Examples

from lmcache.v1.cache_controller.full_sync_sender import FullSyncSender

# Typically created inside the worker initialization
sender = FullSyncSender(
    config=engine_config,
    worker=lmcache_worker,
    lmcache_engine=cache_engine,
    local_cpu_backend=cpu_backend,
)

# Start a full sync (runs asynchronously)
success = await sender.start_full_sync(reason="controller_restart")
if success:
    print("Full sync completed successfully")
else:
    print("Full sync failed or timed out")

# Check sync status
if sender.is_syncing:
    print("Sync still in progress")