mirror of
https://github.com/kvcache-ai/Mooncake.git
synced 2026-11-05 01:17:55 +00:00
[GH-ISSUE #3360] [RFC]: Refactor Mooncake Store segment management around SegmentPool #852
Labels
No labels
ascend
auto-closed
bug
bug
CI/Build
Common
documentation
enhancement
feature request
good first issue
help wanted
high priority
MetaX
nightly-failure
pull-request
PyTorch Backend
question
RFC
Roadmap
stale
Store
Tests
Transfer Engine
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
kvcache-ai/Mooncake#852
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @Aionw on GitHub (Aug 10, 2026).
Original GitHub issue: https://github.com/kvcache-ai/Mooncake/issues/3360
Changes proposed
Summary
Mooncake Store currently splits mounted-region ownership between
SegmentManagerandNoFSegmentManager, while client-local SSD state is embedded inSegmentManagereven though it is not an addressable allocation region.This RFC proposes a behavior-preserving refactor:
SegmentPoolowns client-mounted, addressable regions that the Master can allocate from: Memory, CXL, and NoF.LocalSsdManagerowns per-client local SSD registration, capacity, usage, and existing local tier state.SegmentPool.Motivation
The current layout duplicates mounted-segment catalogs, indexes, allocators, locking, and lifecycle code across Memory/CXL and NoF. It also couples LocalSSD registration and task state to the memory segment manager.
A resource should belong to
SegmentPoolbecause it is an addressable allocation region, not because of its physical medium. This keeps NoF in the pool while separating LocalSSD, whose data is object/file based and identified by client.Target architecture
For addressable Memory/CXL regions, the conceptual dependency remains
object catalog / request orchestration -> SegmentPool -> RegionDriver. Replica placement is a stateless execution seam between the object layer and the pool: it borrows a lock-scoped placement view but owns no catalog, target, allocator, or physical resource.The runtime paths use those ownership boundaries as follows:
Key invariants:
SegmentPoolis the only owner of the Memory/CXL mounted catalog, indexes, placement index, and driver registry.SegmentPool.RegionDriverowns physical resources;PlacementIndexcontains only stable non-owning target pointers.ReplicaAllocatorowns policy configuration and scratch state, not resources; adding a policy does not expandSegmentPool.LocalSsdManagerremains independent. NoF uses the same placement executor but retains its own catalog/resources until #3364.Proposed boundaries
SegmentPoolLocalSsdManagerMasterServiceThe external Memory, CXL, NoF, and LocalSSD RPC contracts remain unchanged. Type-specific RPC requests are converted at the Master boundary.
Compatibility and invariants
This is a refactor, not a traffic migration or placement-policy change.
ldfield and legacy LocalSSD decoding.Implementation and tracking
This RFC is tracked through its native GitHub sub-issues. They should land in dependency order so each merged revision has one state owner and remains independently testable.
Active Memory/CXL implementation stack (#3363)
The implementation is split so reusable mechanisms can be reviewed and merged before the final one-time
MasterServicecutover. The first four PRs do not switchMasterService; the last PR switches callers and deletes the obsolete paths in the same revision.mainReview and merge in table order. #3364 remains responsible for moving NoF catalog/resource ownership into
SegmentPool; #3365 remains responsible for cleanup that depends on that NoF move.Alternatives considered
SegmentPool: rejected because LocalSSD is a client-local object store rather than a Master-allocatable address region.Risks
Each tracking issue will carry explicit compatibility constraints and targeted tests.
Related work
SsdMetricsProvidernaming. This RFC focuses on resource ownership and lifecycle. Any LocalSSD usage-view changes should coordinate with #3158 rather than duplicate its metrics work.Call for contributors
Contributions are welcome. Please comment on an unassigned tracking issue before starting and include a short implementation outline. The issues are dependency ordered; parallel work is welcome only where the issue says it is safe.
Contributors should:
[Store]PR title and link both this RFC and the tracking issue;The first snapshot/model extraction issue is the best entry point for contributors unfamiliar with the allocation path. The NoF integration issue is better suited to contributors familiar with allocator and unmount semantics.
Before submitting a new issue...
@github-actions[bot] commented on GitHub (Aug 10, 2026):
Thanks for opening this issue, @Aionw!
41376987A maintainer will triage this when possible. To help us respond faster, please include:
Useful links: Documentation · Contributing guide