fix: roll back partial KV allocation on page miss

[shipiyouniao]

Summary

Fixes #364.

Fixes a lower-level allocation failure path in KVCacheManager.alloc() where PageAllocator.alloc_page() can raise after some block ids have already been reserved for the current allocation request.

Root Cause

available_size() and physical page allocation are not atomic across multiple instances sharing the same physical pool. A caller may pass the capacity check, consume reserved blocks or blocks from an existing page, and then fail when requesting a new physical page.

Before this change, that RuntimeError escaped without rolling back the partially allocated block ids.

What Changed

• Catch RuntimeError around page_allocator.alloc_page().
• Return None as an allocation miss instead of crashing the allocation path.
• Roll back any partially allocated block ids before returning None.
• Use an internal _free(..., release_empty_pages=False) rollback path so a partial-allocation rollback does not unmap/release physical pages that were not intentionally returned to the physical pool.
• Keep normal public free() behavior unchanged for real releases.
• Add unit coverage for:
  • reserved-block partial allocation rollback;
  • existing-page partial allocation rollback;
  • failure before any partial allocation.

Tests

python -m pytest tests/test_kvcache_manager_alloc_miss.py -q
python -m py_compile kvcached/kv_cache_manager.py tests/test_kvcache_manager_alloc_miss.py

[Copilot]

Pull request overview

Fixes a failure mode in KVCacheManager._alloc() where a PageAllocator.alloc_page() RuntimeError could escape after partially allocating block IDs, leaking those IDs instead of returning an allocation miss (None).

Changes:

• Catch RuntimeError from page_allocator.alloc_page() / page.init() and return None (allocation miss) instead of propagating the exception.
• Attempt to roll back any partially allocated block IDs via free() before returning None, and log rollback failures without masking the miss.
• Add regression tests covering partial allocation followed by a page-allocation failure.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
kvcached/kv_cache_manager.py	Adds exception handling + rollback for partial allocations when physical page allocation fails.
tests/test_kvcache_manager_alloc_miss.py	Adds regression tests for allocation-miss rollback scenarios.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.