Skip to content

[Store] Add parallel bucket writes for SSD offload - #3226

Open
NUABO wants to merge 1 commit into
kvcache-ai:mainfrom
NUABO:write-multi
Open

[Store] Add parallel bucket writes for SSD offload#3226
NUABO wants to merge 1 commit into
kvcache-ai:mainfrom
NUABO:write-multi

Conversation

@NUABO

@NUABO NUABO commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

Description

Add optional thread pool that dispatches per-bucket BatchOffload calls concurrently within a single heartbeat tick. Each bucket's D2H staging, eviction, WriteBucket (disk I/O), and master RPC run independently — buckets write to different files so the heavy disk writes are truly parallel.

  • MC_OFFLOAD_WRITE_THREADS (default 0, disabled)
    • 0: original sequential per-bucket loop, zero change.
    • >1: thread pool of that size; when multiple buckets are
    returned by AllocateOffloadingBuckets, each bucket is
    dispatched to a worker. The pool is created once in
    FileStorage::Init() and reused across heartbeat ticks.

  • Parallel-path error handling mirrors the sequential path:
    • KEYS_ULTRA_LIMIT or other non-INVALID_READ errors are
    captured and propagated after all futures complete.
    • INVALID_READ errors add the affected keys to failed_tasks
    (mutex-protected) so the master can release refcounts.
    • Keys skipped by GroupOffloadingKeysByBucket are also
    reported as failed.

Module

  • Transfer Engine (mooncake-transfer-engine)
  • Mooncake Store (mooncake-store)
  • Mooncake EP (mooncake-ep)
  • Mooncake PG (mooncake-pg)
  • Integration (mooncake-integration)
  • P2P Store (mooncake-p2p-store)
  • Python Wheel (mooncake-wheel)
  • Common (mooncake-common)
  • Mooncake RL (mooncake-rl)
  • CI/CD
  • Docs
  • Other

Type of Change

  • Bug fix
  • New feature
  • Refactor
  • Breaking change
  • Documentation update
  • Performance improvement
  • Other

How Has This Been Tested?

Test commands:

# Example: bash scripts/run_ci_test.sh

Test results:

  • Unit tests pass
  • Integration tests pass (if applicable)
  • Manual testing done (describe below)

Checklist

  • I have performed a self-review of my own code
  • I have formatted my code using ./scripts/code_format.sh
  • I have run pre-commit run --all-files and all hooks pass
  • I have updated the documentation (if applicable)
  • I have added tests to prove my changes are effective
  • For changes >500 LOC: I have filed an RFC issue

AI Assistance Disclosure

  • No AI tools were used
  • AI tools were used (specify below)

…HREADS

Add optional thread pool that dispatches per-bucket BatchOffload
calls concurrently within a single heartbeat tick.  Each bucket's
D2H staging, eviction, WriteBucket (disk I/O), and master RPC run
independently — buckets write to different files so the heavy disk
writes are truly parallel.

  MC_OFFLOAD_WRITE_THREADS (default 0, disabled)
    • 0:  original sequential per-bucket loop, zero change.
    • >1: thread pool of that size; when multiple buckets are
           returned by AllocateOffloadingBuckets, each bucket is
           dispatched to a worker.  The pool is created once in
           FileStorage::Init() and reused across heartbeat ticks.

  Parallel-path error handling mirrors the sequential path:
    • KEYS_ULTRA_LIMIT or other non-INVALID_READ errors are
      captured and propagated after all futures complete.
    • INVALID_READ errors add the affected keys to failed_tasks
      (mutex-protected) so the master can release refcounts.
    • Keys skipped by GroupOffloadingKeysByBucket are also
      reported as failed.

Signed-off-by: tan changzhi <544463199@qq.com>
@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 0% with 137 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
mooncake-store/src/file_storage.cpp 0.00% 137 Missing ⚠️

📢 Thoughts on this report? Let us know!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants