[PR #1284] [MERGED] [Store]: Add OffsetAllocator disk backend with lock-striped metadata + refcounted extents.

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

kvcache-ai/Mooncake#2133

bsakaguchi commented

2026-10-29 21:33:02 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/Mooncake/pull/1284
Author: @maheshrbapatu
Created: 12/26/2025
Status: ✅ Merged
Merged: 12/30/2025
Merged by: @ykwd

Base: main ← Head: offset_allocator_backend_1

📝 Commits (4)

7e9e889 [mooncake-store]: Add OffsetAllocator disk backend with lock-striped
f0bdda4 [mooncake-store]: Add OffsetAllocator disk backend with lock-striped
64ee3c0 fix initial gemini comments
a80022f fixed all the review comments

📊 Changes

4 files changed (+1687 additions, -15 deletions)

View changed files

📝 mooncake-store/include/storage_backend.h (+205 -1)
📝 mooncake-store/src/file_storage.cpp (+3 -1)
📝 mooncake-store/src/storage_backend.cpp (+540 -6)
📝 mooncake-store/tests/storage_backend_test.cpp (+939 -7)

📄 Description

Description

Introduce a new StorageBackendType::kOffsetAllocator backend that stores
all objects in a single data file (kv_cache.data) and manages free space
with OffsetAllocator.

Concurrency model (new backend only):

Metadata is sharded into 1024 stripes (SharedMutex + unordered_map)
using hash(key) & (N-1) to reduce contention.
Values are referenced via shared_ptr so
readers can drop locks before I/O while preventing reuse-after-free of
extents during in-flight reads.
Quota accounting uses atomics (total_size_, total_keys_) to avoid
global aggregation across shards.
Record format: [u32 key_len][u32 value_len][key_bytes][value_bytes].
Persistence v1: none (truncate on init; restart begins empty).

Tests:
Extend unit tests to cover new backend and fix cleanup to remove
leftover directories.

Type of Change

Types
- Bug fix
- New feature
  - Transfer Engine
  - Mooncake Store
  - Mooncake EP
  - Integration
  - P2P Store
  - Python Wheel
- Breaking change
- CI/CD
- Documentation update
- Other

How Has This Been Tested?

StorageBackendTest.*

Checklist

I have performed a self-review of my own code.
I have updated the documentation.
I have added tests to prove my changes are effective.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/Mooncake/pull/1284 **Author:** [@maheshrbapatu](https://github.com/maheshrbapatu) **Created:** 12/26/2025 **Status:** ✅ Merged **Merged:** 12/30/2025 **Merged by:** [@ykwd](https://github.com/ykwd) **Base:** `main` ← **Head:** `offset_allocator_backend_1` --- ### 📝 Commits (4) - [`7e9e889`](https://github.com/kvcache-ai/Mooncake/commit/7e9e8892a9fc8600f54767363b4629db4ac17a34) [mooncake-store]: Add OffsetAllocator disk backend with lock-striped - [`f0bdda4`](https://github.com/kvcache-ai/Mooncake/commit/f0bdda4d04adf19da4608b0a2c4812427696fc66) [mooncake-store]: Add OffsetAllocator disk backend with lock-striped - [`64ee3c0`](https://github.com/kvcache-ai/Mooncake/commit/64ee3c036b96f0b5551e966b615ee3ebe725ab5b) fix initial gemini comments - [`a80022f`](https://github.com/kvcache-ai/Mooncake/commit/a80022f3b8bf059b5f120e92b39d78ea614d00c2) fixed all the review comments ### 📊 Changes **4 files changed** (+1687 additions, -15 deletions) <details> <summary>View changed files</summary> 📝 `mooncake-store/include/storage_backend.h` (+205 -1) 📝 `mooncake-store/src/file_storage.cpp` (+3 -1) 📝 `mooncake-store/src/storage_backend.cpp` (+540 -6) 📝 `mooncake-store/tests/storage_backend_test.cpp` (+939 -7) </details> ### 📄 Description ## Description Introduce a new StorageBackendType::kOffsetAllocator backend that stores all objects in a single data file (kv_cache.data) and manages free space with OffsetAllocator. **Concurrency model (new backend only):** 1. Metadata is sharded into 1024 stripes (SharedMutex + unordered_map) using hash(key) & (N-1) to reduce contention. 2. Values are referenced via shared_ptr<RefCountedAllocationHandle> so readers can drop locks before I/O while preventing reuse-after-free of extents during in-flight reads. 3. Quota accounting uses atomics (total_size_, total_keys_) to avoid global aggregation across shards. 4. Record format: [u32 key_len][u32 value_len][key_bytes][value_bytes]. 5. Persistence v1: none (truncate on init; restart begins empty). **Tests:** Extend unit tests to cover new backend and fix cleanup to remove leftover directories. ## Type of Change * Types - [ ] Bug fix - [X] New feature - [ ] Transfer Engine - [X] Mooncake Store - [ ] Mooncake EP - [ ] Integration - [ ] P2P Store - [ ] Python Wheel - [ ] Breaking change - [ ] CI/CD - [ ] Documentation update - [ ] Other ## How Has This Been Tested? StorageBackendTest.* ## Checklist - [X] I have performed a self-review of my own code. - [ ] I have updated the documentation. - [X] I have added tests to prove my changes are effective. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

closed this issue
added the
pull-request
label

Rows
Columns

[PR #1284] [MERGED] [Store]: Add OffsetAllocator disk backend with lock-striped metadata + refcounted extents. #2133