Add pydocstyle to the ruff rules (#52136)

Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
Signed-off-by: Harry Mellor <hej.mellor@gmail.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Harry Mellor
2026-09-16 16:44:29 +00:00
committed by GitHub
co-authored by Claude Opus 5
parent 804e5377aa
commit 8c1557a79c
2002 changed files with 15024 additions and 14269 deletions
@@ -15,7 +15,8 @@ from vllm.v1.kv_offload.cpu.policies.lru import LRUCachePolicy
class _DummyCachePolicy(CachePolicy):
"""Minimal CachePolicy for CachePolicyFactory registration tests. Loaded
by module path, so it must be importable at module scope (mirrors
tests/v1/kv_offload/test_factory.py's SingleArgExternalOffloadingSpec)."""
tests/v1/kv_offload/test_factory.py's SingleArgExternalOffloadingSpec).
"""
def __init__(self, cache_capacity: int) -> None:
self.cache_capacity = cache_capacity
@@ -54,7 +55,8 @@ class TestCachePolicyFactory:
def test_pre_registered_policies_can_be_imported(self):
"""If someone moves a policy module but forgets to update
factory.py, CI fails."""
factory.py, CI fails.
"""
for name in CachePolicyFactory._registry:
cls = CachePolicyFactory._registry[name]()
assert issubclass(cls, CachePolicy)
@@ -88,7 +90,8 @@ class TestCachePolicyFactory:
register_cache_policy() call -- this is how external projects
integrate a custom CachePolicy without forking/patching vLLM.
Mirrors tests/v1/kv_offload/test_factory.py's
test_dynamic_load_via_spec_module_path."""
test_dynamic_load_via_spec_module_path.
"""
policy_cls = CachePolicyFactory.get_cache_policy_cls(
"_DummyCachePolicy", "tests.v1.kv_offload.cpu.policies.test_factory"
)
@@ -96,7 +99,8 @@ class TestCachePolicyFactory:
def test_manager_resolves_policy_via_module_path(self):
"""End-to-end: CPUOffloadingManager resolves an unregistered policy
purely from cache_policy_module_path."""
purely from cache_policy_module_path.
"""
manager = CPUOffloadingManager(
num_chunks=4,
cache_policy="_DummyCachePolicy",
@@ -106,6 +110,7 @@ class TestCachePolicyFactory:
def test_unregistered_policy_without_module_path_raises(self):
"""eviction_policy not in registry + no cache_policy_module_path ->
ValueError, same shape as the OffloadingSpecFactory error path."""
ValueError, same shape as the OffloadingSpecFactory error path.
"""
with pytest.raises(ValueError, match="Unknown cache policy"):
CachePolicyFactory.get_cache_policy_cls("nonexistent", None)
@@ -126,7 +126,8 @@ def _canonical_handler(gpu_tensor, cpu_tensor, mapping, gpu_to_cpu):
def test_gpu_roundtrip_assembles_canonical_page_across_ranks():
"""Two TP2-style rank handlers must scatter into one shared canonical
CPU page such that each rank reloads bit-exact and a whole-page (TP1)
reader sees both shards — the cross-topology contract."""
reader sees both shards — the cross-topology contract.
"""
torch.manual_seed(0)
num_blocks = 4
gpu_rank = [
@@ -203,7 +204,8 @@ def _nhd_shard_mapping(tp: int, rank: int) -> CanonicalPageMapping:
def _head_shard(full_kv: torch.Tensor, tp: int, rank: int) -> torch.Tensor:
"""This rank's local page rows out of the (blocks, 2, tokens, heads,
head_bytes) ground truth."""
head_bytes) ground truth.
"""
local_heads = _TOTAL_HEADS // tp
shard = full_kv[:, :, :, rank * local_heads : (rank + 1) * local_heads, :]
return shard.reshape(full_kv.shape[0], -1).contiguous()
@@ -214,7 +216,8 @@ def _head_shard(full_kv: torch.Tensor, tp: int, rank: int) -> torch.Tensor:
def test_cross_topology_roundtrip(writer_tp: int, reader_tp: int):
"""KV written at one tp must be readable at another: writer ranks scatter
head shards into a shared canonical region, reader ranks gather their own
shards, and every reader must see the writers' ground-truth bytes."""
shards, and every reader must see the writers' ground-truth bytes.
"""
torch.manual_seed(0)
num_blocks = 3
full_kv = torch.randint(
+13 -28
View File
@@ -166,8 +166,7 @@ def test_cpu_eviction_removed_precedes_stored():
@pytest.mark.parametrize("eviction_policy", ["lru", "arc"])
def test_already_stored_chunk_not_evicted_during_prepare_store(eviction_policy):
"""
Regression test: a chunk that is already stored must not be evicted
"""Regression test: a chunk that is already stored must not be evicted
by prepare_store() when it needs to make room for new chunks.
Applies to both lru and arc policies.
@@ -367,9 +366,7 @@ def test_cpu_manager_clears_write_usage_after_failed_store():
def test_cpu_manager():
"""
Tests CPUOffloadingManager with lru policy.
"""
"""Tests CPUOffloadingManager with lru policy."""
# initialize a CPU manager with a capacity of 4 chunks
cpu_manager = make_cpu_manager(num_chunks=4, cache_policy="lru", enable_events=True)
@@ -597,8 +594,7 @@ class TestARCPolicy:
return manager, policy
def test_basic(self):
"""
Tests CPUOffloadingManager with arc policy.
"""Tests CPUOffloadingManager with arc policy.
Verifies that ARC handles store, load, and lookup operations correctly.
"""
cpu_manager, arc_policy = self._make_manager()
@@ -637,8 +633,7 @@ class TestARCPolicy:
assert len(arc_policy.t2) == 0
def test_t1_to_t2_promotion(self):
"""
Tests that accessing a chunk in T1 promotes it to T2 (frequent).
"""Tests that accessing a chunk in T1 promotes it to T2 (frequent).
This is a key feature of ARC's adaptive behavior.
"""
cpu_manager, arc_policy = self._make_manager(enable_events=False)
@@ -659,8 +654,7 @@ class TestARCPolicy:
assert to_keys([1])[0] in arc_policy.t2
def test_eviction_with_load(self):
"""
Tests ARC eviction behavior similar to LRU test.
"""Tests ARC eviction behavior similar to LRU test.
Verifies that chunks being loaded (ref_cnt > 0) cannot be evicted.
"""
cpu_manager, _ = self._make_manager()
@@ -700,8 +694,7 @@ class TestARCPolicy:
assert len(prepare_store_output.evicted_keys) >= 1
def test_adaptive_target(self):
"""
Tests ARC's adaptive target adjustment via ghost lists.
"""Tests ARC's adaptive target adjustment via ghost lists.
When a chunk in B1 (ghost list) is accessed, target_t1_size increases.
When a chunk in B2 is accessed, target_t1_size decreases.
"""
@@ -728,8 +721,7 @@ class TestARCPolicy:
assert arc_policy.target_t1_size > initial_target
def test_t1_t2_eviction_policy(self):
"""
Tests that ARC evicts from T1 or T2 based on target_t1_size.
"""Tests that ARC evicts from T1 or T2 based on target_t1_size.
If |T1| >= target_t1_size, evict from T1, otherwise from T2.
"""
cpu_manager, arc_policy = self._make_manager(enable_events=False)
@@ -917,8 +909,7 @@ class TestARCPolicy:
assert not arc_policy.b2
def test_ghost_list_bounds(self):
"""
Tests that ghost lists (B1, B2) don't grow unbounded.
"""Tests that ghost lists (B1, B2) don't grow unbounded.
They should be capped at cache_capacity.
"""
cpu_manager, arc_policy = self._make_manager(num_chunks=2, enable_events=False)
@@ -937,8 +928,7 @@ class TestARCPolicy:
assert len(arc_policy.b2) <= arc_policy.cache_capacity
def test_touch_ordering(self):
"""
Tests that touch() correctly updates access patterns.
"""Tests that touch() correctly updates access patterns.
Similar to LRU test but verifies T1/T2 ordering.
"""
cpu_manager, arc_policy = self._make_manager()
@@ -970,8 +960,7 @@ class TestARCPolicy:
)
def test_failed_store(self):
"""
Tests that failed store operations clean up correctly.
"""Tests that failed store operations clean up correctly.
Similar to LRU test but for ARC.
"""
cpu_manager, arc_policy = self._make_manager()
@@ -999,8 +988,7 @@ class TestARCPolicy:
assert evicted_hash in arc_policy.b1
def test_full_scenario(self):
"""
Comprehensive test covering multiple ARC operations in sequence.
"""Comprehensive test covering multiple ARC operations in sequence.
Similar to the full LRU test but adapted for ARC behavior.
"""
cpu_manager, arc_policy = self._make_manager()
@@ -1039,9 +1027,7 @@ class TestARCPolicy:
def test_filter_reused_manager():
"""
Tests CPUOffloadingManager reuse filtering (store_threshold=2).
"""
"""Tests CPUOffloadingManager reuse filtering (store_threshold=2)."""
manager = make_cpu_manager(
num_chunks=4,
cache_policy="lru",
@@ -1148,8 +1134,7 @@ def test_store_threshold_does_not_hide_ready_reuse():
def test_evictable_cache_chunk_count():
"""
Verifies _num_evictable_cache_chunks is maintained correctly through the
"""Verifies _num_evictable_cache_chunks is maintained correctly through the
full store/load lifecycle, eviction, failed stores, concurrent loads,
reset_cache, and the early-exit fast path in prepare_store.
"""
@@ -167,7 +167,8 @@ def _mp_race_construct_and_write(
) -> None:
"""Race to construct a SharedOffloadRegion, write fill_value, then wait
for the parent's cleanup signal before tearing down. The wait gives the
parent a window to read the raw mmap before the creator removes the file."""
parent a window to read the raw mmap before the creator removes the file.
"""
try:
region = SharedOffloadRegion(
engine_id=engine_id,
@@ -196,7 +197,8 @@ def _mp_barrier_construct_and_hold(
replicated: bool = False,
) -> None:
"""Construct with a real cross-process barrier, write, then hold the
mapping (no cleanup) until the parent SIGKILLs this process."""
mapping (no cleanup) until the parent SIGKILLs this process.
"""
try:
populate_calls = 0
get_populate_write_fn = region_module._get_populate_write_fn
@@ -250,7 +252,8 @@ def iid():
def test_create_next_worker_view_shape_and_stride(iid):
"""Returned tensor must have shape (num_chunks, tensor_page_size) and
stride (row_stride, 1) where row_stride = cpu_page_size * num_workers."""
stride (row_stride, 1) where row_stride = cpu_page_size * num_workers.
"""
with _region(iid, num_chunks=4, cpu_page_size=2 * PAGE_SIZE) as r:
t = r.create_next_worker_view(PAGE_SIZE)
assert t.shape == (4, PAGE_SIZE)
@@ -290,7 +293,8 @@ def test_create_next_worker_view_row_stride_with_multiple_workers(iid):
def test_create_next_worker_view_cursor_advances(iid):
"""Each create_next_worker_view call must advance _worker_offset by
tensor_page_size."""
tensor_page_size.
"""
with _region(iid, cpu_page_size=3 * PAGE_SIZE) as r:
assert r._worker_offset == 0
r.create_next_worker_view(PAGE_SIZE)
@@ -347,7 +351,8 @@ def test_create_next_worker_view_overflow_does_not_mutate_cursor(iid):
def test_create_next_worker_view_write_visible_in_raw_mmap(iid):
"""Writes into a create_next_worker_view view must appear at the correct
raw mmap offset"""
raw mmap offset
"""
with _region(iid, num_chunks=4) as r:
t = r.create_next_worker_view(PAGE_SIZE)
t[2, :] = 42 # write to chunk row 2
@@ -380,7 +385,8 @@ def test_create_next_worker_view_multi_tensor_layout(iid):
def test_create_next_worker_view_multiprocess_slots(iid):
"""Each worker process calls create_next_worker_view and writes distinct data;
the parent verifies each slot lands at the correct interleaved offset."""
the parent verifies each slot lands at the correct interleaved offset.
"""
num_workers = 2
num_chunks = 4
@@ -665,7 +671,8 @@ def test_multi_worker_race_shared_memory_visible(iid):
def test_multiprocess_race_construct_and_write(iid):
"""N processes race to construct the same SharedOffloadRegion, each writes
fill_value = rank+1 into their slot; parent verifies interleaved layout."""
fill_value = rank+1 into their slot; parent verifies interleaved layout.
"""
num_workers = 4
num_chunks = 3
@@ -791,7 +798,8 @@ def test_cleanup_unregisters_every_pinned_chunk(iid, monkeypatch):
def test_cleanup_after_create_next_worker_view_releases_mmap(iid):
"""cleanup() must close the mmap even after create_next_worker_view was called.
create_next_worker_view returns a view that shares storage with _base; both must be
released before mmap.close() can succeed."""
released before mmap.close() can succeed.
"""
r = _make_region(iid)
mmap_obj = r.mmap_obj
@@ -970,7 +978,8 @@ def test_ftruncate_failure_cleans_up_creator(monkeypatch):
def test_backing_file_unlinked_after_barrier(iid):
"""The file must exist until the barrier releases (late joiners need the
name) and be gone right after, so no exit path can leak it."""
name) and be gone right after, so no exit path can leak it.
"""
path = f"/dev/shm/vllm_offload_{iid}.mmap"
seen_at_barrier = []
@@ -992,7 +1001,8 @@ def test_backing_file_unlinked_after_barrier(iid):
def test_barrier_failure_unlinks_creator_and_raises(iid):
"""A failed rendezvous must remove the creator's file and re-raise, not
leave a stub that wedges the next start in _wait_for_file_size."""
leave a stub that wedges the next start in _wait_for_file_size.
"""
path = f"/dev/shm/vllm_offload_{iid}.mmap"
with pytest.raises(RuntimeError, match="peer died"):
_make_region(iid, barrier=MagicMock(side_effect=RuntimeError("peer died")))
@@ -1002,7 +1012,8 @@ def test_barrier_failure_unlinks_creator_and_raises(iid):
@pytest.mark.parametrize("replicated", [False, True])
def test_mp_barrier_unlinks_file_and_survives_sigkill(iid, replicated):
"""With a real cross-process barrier every worker maps one shared inode,
the name is gone while they run, and SIGKILL leaks nothing."""
the name is gone while they run, and SIGKILL leaks nothing.
"""
num_workers = 2
path = f"/dev/shm/vllm_offload_{iid}.mmap"
ctx = get_mp_context()
@@ -1041,7 +1052,8 @@ def test_mp_barrier_unlinks_file_and_survives_sigkill(iid, replicated):
@pytest.mark.parametrize("failure_phase", ["shm", "memory", "population"])
def test_setup_failure_before_barrier_releases_peers(iid, monkeypatch, failure_phase):
"""A worker that dies before the rendezvous must still arrive at the
barrier, or its peers block in the collective until it times out."""
barrier, or its peers block in the collective until it times out.
"""
failure = MagicMock(side_effect=ValueError("Insufficient space"))
memory_check = failure if failure_phase == "memory" else None
if failure_phase == "shm":
@@ -1072,7 +1084,8 @@ def test_setup_failure_before_barrier_releases_peers(iid, monkeypatch, failure_p
def test_mmap_failure_unlinks_creator_before_releasing_peers(iid, monkeypatch):
"""A creator that fails after sizing the file must drop it before arriving
at the barrier, so the next start does not land on a stale file."""
at the barrier, so the next start does not land on a stale file.
"""
path = f"/dev/shm/vllm_offload_{iid}.mmap"
monkeypatch.setattr("mmap.mmap", MagicMock(side_effect=OSError("mmap")))
seen_at_barrier = []
@@ -1085,7 +1098,8 @@ def test_mmap_failure_unlinks_creator_before_releasing_peers(iid, monkeypatch):
def test_barrier_release_failure_keeps_original_error(iid, monkeypatch):
"""When releasing the peers fails too, the setup error that explains the
failure must be the one that propagates."""
failure must be the one that propagates.
"""
import vllm.v1.kv_offload.cpu.shared_offload_region as region
monkeypatch.setattr(
+1 -2
View File
@@ -76,8 +76,7 @@ def make_mapper_from_offloading_spec(**kwargs) -> FileMapper:
def test_get_file_name_full_structure():
"""
Path must match: <base_path>_r<rank>/<hhh>/<hh>_g<group_idx>/<hash_hex>.bin
"""Path must match: <base_path>_r<rank>/<hhh>/<hh>_g<group_idx>/<hash_hex>.bin.
Concretely:
- The segment immediately after base_path must end with `_r3`
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
"""
P2PConnector proxy server for OffloadingConnector + TieringOffloadingSpec.
"""P2PConnector proxy server for OffloadingConnector + TieringOffloadingSpec.
Unlike NixlConnector (which returns remote_host/remote_port in the prefill
response), OffloadingConnector does not embed connector coordinates in its
@@ -132,7 +132,7 @@ class TestNixlTransportWithMockedAgent:
assert tid1 != tid2
def test_poll_empty_when_no_inflight(self):
"""poll returns empty when nothing is inflight."""
"""Poll returns empty when nothing is inflight."""
transport = self._make_transport()
result = transport.poll()
assert result == PollResult(done=(), failed=())
@@ -213,7 +213,7 @@ class TestNixlTransportWithMockedAgent:
assert tid2 not in transport._inflight
def test_cancel_removes_inflight(self):
"""cancel removes transfers and releases handles."""
"""Cancel removes transfers and releases handles."""
transport = self._make_transport()
transport.add_remote_peer("peer:1", b"meta", 0x1000, 8, 1024)
@@ -226,7 +226,7 @@ class TestNixlTransportWithMockedAgent:
transport._agent.release_xfer_handle.assert_called()
def test_cancel_ignores_unknown_ids(self):
"""cancel with unknown IDs doesn't crash."""
"""Cancel with unknown IDs doesn't crash."""
transport = self._make_transport()
assert transport.cancel([999, 1000]) == []
assert transport.cancel([999, 1000], mode="wait") == []
@@ -286,7 +286,7 @@ class TestNixlTransportWithMockedAgent:
transport._agent.remove_remote_agent.assert_called()
def test_close_releases_everything(self):
"""close releases all handles and clears state."""
"""Close releases all handles and clears state."""
transport = self._make_transport()
transport.add_remote_peer("peer:1", b"meta", 0x1000, 8, 1024)
transport.write_blocks("peer:1", [0], [1])
+62 -31
View File
@@ -48,7 +48,8 @@ def _remote_prefiller_kv_params(
kv_request_id: str = "req-1",
) -> dict:
"""Decoder-side kv_transfer_params: ``remote_prefiller`` sub-dict carries
kv_request_id + remote_host + remote_port."""
kv_request_id + remote_host + remote_port.
"""
return {
"remote_prefiller": {
"kv_request_id": kv_request_id,
@@ -64,7 +65,8 @@ def _remote_kv_source_kv_params(
kv_request_id: str = "req-1",
) -> dict:
"""Symmetric-P2P consumer kv_transfer_params: ``remote_kv_source`` sub-dict has
the same shape as ``remote_prefiller`` (kv_request_id + remote_host + port)."""
the same shape as ``remote_prefiller`` (kv_request_id + remote_host + port).
"""
return {
"remote_kv_source": {
"kv_request_id": kv_request_id,
@@ -76,7 +78,8 @@ def _remote_kv_source_kv_params(
def _remote_decoder_kv_params(kv_request_id: str = "req-1") -> dict:
"""Prefiller-side kv_transfer_params: ``remote_decoder`` sub-dict carries
kv_request_id only."""
kv_request_id only.
"""
return {"remote_decoder": {"kv_request_id": kv_request_id}}
@@ -241,7 +244,8 @@ class TestLookup:
def test_lookup_returns_miss_without_prefill_key(self):
"""No ``remote_prefiller`` sub-dict means the request was not routed for
remote prefill — local prefill should run instead, so lookup()
returns MISS even when a stale ``remote_decoder`` block is present."""
returns MISS even when a stale ``remote_decoder`` block is present.
"""
mgr = _make_manager()
ctx = _req_context(kv_params=_remote_decoder_kv_params())
assert mgr.lookup(b"key", ctx) is LookupResult.MISS
@@ -309,7 +313,8 @@ class TestServeExternalRequests:
def test_flushes_failed_serve_ctxs_then_serves_each_session(self):
"""serve_external_requests releases the failed serves left by
reaped sessions via parent.on_request_finished (clearing the
queue), then delegates to every live session with the same parent."""
queue), then delegates to every live session with the same parent.
"""
mgr = _make_manager()
ctx = ReqContext(req_id="p2p:peer:req-1:lu1")
mgr._failed_serve_ctxs = [ctx]
@@ -363,7 +368,8 @@ class TestSubmitStore:
def test_no_binding_yet_parks_in_unbound_stores(self):
"""submit_store without a bound session buffers the batch keyed
by kv_request_id; no session is pre-created (peer_id is unknown
to the producer at store time)."""
to the producer at store time).
"""
mgr = _make_manager()
job = _job_metadata(
job_id=1,
@@ -390,7 +396,8 @@ class TestSubmitStore:
def test_routes_to_bound_session(self):
"""If a session has already received FetchMsg for this
kv_request_id (so _kv_to_session is populated), submit_store
forwards directly to that session rather than re-buffering."""
forwards directly to that session rather than re-buffering.
"""
mgr = _make_manager()
bound = _FakeSession(peer_id="10.0.0.1:8000", connected=True)
mgr._kv_to_session["req-1"] = bound # type: ignore[assignment]
@@ -413,7 +420,8 @@ class TestSubmitStore:
def test_extra_top_level_keys_are_ignored(self):
"""Producer-side kv_transfer_params should not pre-create a
session even when a stale caller still passes a top-level
``remote_host``/``remote_port`` next to ``remote_decoder``."""
``remote_host``/``remote_port`` next to ``remote_decoder``.
"""
mgr = _make_manager()
params = _remote_decoder_kv_params()
params["remote_host"] = "stale"
@@ -457,7 +465,8 @@ class TestSubmitLoad:
def test_happy_path_with_active_session(self):
"""When the peer's session exists, submit_load forwards to
session.request_blocks and does NOT add a finished result yet."""
session.request_blocks and does NOT add a finished result yet.
"""
mgr = _make_manager()
peer_id = "10.0.0.1:8000"
existing = _FakeSession(peer_id=peer_id, connected=True)
@@ -477,7 +486,8 @@ class TestSubmitLoad:
def test_missing_consumer_flag_fails(self):
"""Peer fields present but neither do_remote_prefill nor
do_p2p_fetch is set — submit_load fails the job rather than
emit a stray FetchMsg."""
emit a stray FetchMsg.
"""
mgr = _make_manager()
params = {
"remote_host": "10.0.0.1",
@@ -521,7 +531,8 @@ class TestOnRequestFinished:
def test_decoder_side_calls_session_finish_request(self):
"""Decoder-side finish (``remote_prefiller`` set) still routes via peer_id
because the consumer addresses the producer it loaded from. The
session's finish_request cancels the client-role load."""
session's finish_request cancels the client-role load.
"""
mgr = _make_manager()
peer_id = "10.0.0.1:8000"
session = _FakeSession(peer_id=peer_id)
@@ -533,7 +544,8 @@ class TestOnRequestFinished:
def test_p2p_consumer_side_calls_session_finish_request(self):
"""Symmetric-P2P consumer finish (``remote_kv_source`` set) routes via peer_id
so the session drops any pending lookups (cancel_lookups) and
cancels any inbound load."""
cancels any inbound load.
"""
mgr = _make_manager()
peer_id = "10.0.0.1:8000"
session = _FakeSession(peer_id=peer_id)
@@ -544,7 +556,8 @@ class TestOnRequestFinished:
def test_prefiller_bound_id_routes_via_kv_to_session(self):
"""Prefiller-side finish for an id whose session is already bound
(FetchMsg received) routes via _kv_to_session and pops the entry."""
(FetchMsg received) routes via _kv_to_session and pops the entry.
"""
mgr = _make_manager()
bound = _FakeSession(peer_id="some-peer:1", connected=True)
mgr._kv_to_session["req-1"] = bound # type: ignore[assignment]
@@ -558,7 +571,8 @@ class TestOnRequestFinished:
and no session binding is a no-op on `_unbound_stores`. The
parked batches survive until a peer fetches them or the
`_reap_unbound_stores` timeout fires — `on_request_finished`
must not evict them."""
must not evict them.
"""
from vllm.v1.kv_offload.tiering.p2p.manager import _UnboundStoreBatch
mgr = _make_manager()
@@ -728,7 +742,8 @@ class TestGetFinished:
def test_reap_fails_probes(self):
"""A reaped session's in-flight lookups land in _failed_req_ids so
the consumer's lookup() returns MISS instead of RETRY forever."""
the consumer's lookup() returns MISS instead of RETRY forever.
"""
class FakeData:
def remove_remote_peer(self, pid):
@@ -763,7 +778,8 @@ class TestGetFinished:
def test_unbound_store_reaped_after_timeout(self):
"""Unbound stores past the reap deadline surface as failed and their
kv_request_id lands in _reaped_stores so a late FetchMsg is rejected
instead of parking demand nothing can satisfy."""
instead of parking demand nothing can satisfy.
"""
from vllm.v1.kv_offload.tiering.p2p.manager import _UnboundStoreBatch
mgr = self._make()
@@ -785,7 +801,8 @@ class TestGetFinished:
def test_submit_store_parks_unbound_batch(self):
"""submit_store on an unbound id appends a batch with a fresh
submitted_at stamp so the unbound-store sweep can age it out."""
submitted_at stamp so the unbound-store sweep can age it out.
"""
mgr = _make_manager()
job = _job_metadata(
job_id=1, kv_params=_remote_decoder_kv_params(kv_request_id="req-1")
@@ -807,18 +824,21 @@ class TestHasPendingWork:
"""has_pending_work() must always return True so the engine keeps
ticking the offload pipeline — that's the only thread driving
_control.poll() (incoming peer connects) and session.poll()
(incoming fetch messages on existing sessions)."""
(incoming fetch messages on existing sessions).
"""
def test_returns_true_unconditionally_to_keep_engine_ticking(self):
"""Even with no sessions and no jobs, has_pending_work() returns
True so the engine keeps calling get_finished_jobs(), which is
what drives _control.poll() for inbound peer connects."""
what drives _control.poll() for inbound peer connects.
"""
mgr = _make_manager()
assert mgr.has_pending_work() is True
def test_returns_true_even_when_sessions_present(self):
"""The result is the same regardless of session state — there is
no 'idle' branch."""
no 'idle' branch.
"""
mgr = _make_manager()
mgr._sessions["peer:1"] = _FakeSession(peer_id="peer:1") # type: ignore[assignment]
assert mgr.has_pending_work() is True
@@ -831,7 +851,8 @@ class TestHasPendingWork:
class _ShutdownFakeData:
"""Fake DataTransport that records cancel/poll/close calls and
drives the wait-cancel loop with a scriptable `still` queue."""
drives the wait-cancel loop with a scriptable `still` queue.
"""
def __init__(self, still_queue: list[list[int]] | None = None) -> None:
# Each list in still_queue is the set of ids the next
@@ -875,7 +896,8 @@ class _ShutdownFakeControl:
class TestShutdownDrain:
"""shutdown() drains inflight transfers via cancel(mode='wait')
before calling _data.close(), with a 3s deadline fallback to
cancel(mode='immediate')."""
cancel(mode='immediate').
"""
def _prep(
self,
@@ -1294,7 +1316,8 @@ class _RecordingConn:
class TestAcceptNewPeers:
"""A second inbound from an already-connected peer is rejected and the
new conn is closed; the existing session is left untouched."""
new conn is closed; the existing session is left untouched.
"""
def test_duplicate_connection_is_closed_and_existing_session_untouched(self):
mgr = _make_manager()
@@ -1316,7 +1339,8 @@ class TestAcceptNewPeers:
"""An inbound conn from a peer with no existing session creates
a fresh connected session and registers it under conn.peer_id.
The prefiller has no pre-created pending session anymore — the
first signal of a peer's existence is its inbound connection."""
first signal of a peer's existence is its inbound connection.
"""
class FakeData:
block_len = 4096
@@ -1363,7 +1387,8 @@ class TestAcceptNewPeers:
class TestPollOnce:
"""_poll_once must drain control, accept new peers, poll every session,
surface results, and reap dead sessions — in that order."""
surface results, and reap dead sessions — in that order.
"""
def test_orchestrates_accept_poll_and_reap(self):
mgr = _make_manager()
@@ -1419,7 +1444,8 @@ class TestPollOnce:
def test_new_fetch_id_binds_and_replays_unbound_batches(self):
"""When session.poll() reports a kv_request_id whose FetchMsg
arrived this tick, the manager binds it to that session and
replays every parked submit_store batch via add_stored_blocks."""
replays every parked submit_store batch via add_stored_blocks.
"""
from vllm.v1.kv_offload.tiering.p2p.manager import _UnboundStoreBatch
mgr = _make_manager()
@@ -1453,7 +1479,8 @@ class TestPollOnce:
def test_new_fetch_id_with_no_unbound_still_binds(self):
"""A FetchMsg for a kv_request_id with no parked batches still
records the binding so subsequent submit_stores route fast."""
records the binding so subsequent submit_stores route fast.
"""
mgr = _make_manager()
peer = "10.0.0.1:8000"
sess = _FakeSession(
@@ -1476,7 +1503,8 @@ class TestPollOnce:
def test_failed_load_records_kv_request_id(self):
"""A LoadResult(success=False) from session.poll() must add its
kv_request_id to _failed_req_ids so future lookups return MISS."""
kv_request_id to _failed_req_ids so future lookups return MISS.
"""
mgr = _make_manager()
peer = "10.0.0.1:8000"
sess = _FakeSession(
@@ -1540,7 +1568,8 @@ class TestDrainJobs:
def test_logs_warning_after_5s_then_completes(self, monkeypatch):
"""A session that stays inflight past 5s triggers the warning, and
once it clears the loop returns."""
once it clears the loop returns.
"""
mgr = _make_manager()
mgr._control = _DrainCtrl() # type: ignore[assignment]
sess = _FakeSession(peer_id="peer:1")
@@ -1598,7 +1627,8 @@ class TestDrainJobs:
class TestOnScheduleEnd:
def test_is_noop(self):
"""on_schedule_end is a documented no-op; just confirm it doesn't
raise and doesn't mutate state."""
raise and doesn't mutate state.
"""
mgr = _make_manager()
before_sessions = dict(mgr._sessions)
before_jobs = list(mgr._finished_jobs)
@@ -1624,7 +1654,8 @@ class TestConnectionDeathMidTransfer:
prefiller-side store no longer travels through the session at store
time (it's parked in _unbound_stores keyed by kv_request_id), so its
cleanup on connection death is via on_request_finished or the
unbound-store timeout — covered separately below."""
unbound-store timeout — covered separately below.
"""
def test_dead_connection_with_pending_work_surfaces_failures(self):
mgr_a, mgr_b = _build_paired_managers()
@@ -626,7 +626,8 @@ class TestClientFlows:
"""collect_results / has_active_loads use the _active_loads work-list,
armed when a fetch is issued and discarded exactly when its load
clears — a probe-only request never enters it, and completion empties
it while the entry may briefly linger for GC."""
it while the entry may briefly linger for GC.
"""
session, conn, _ = _make_session()
_activate(session, conn)
client = session._client
@@ -703,7 +704,8 @@ class TestClientFlows:
def test_load_abort_ack_clears_request(self):
"""After load timeout sends AbortFetch, an arriving AbortAckMsg from
the peer surfaces the failure cleanly and removes the request from
_requests — covers the on_abort_ack arrival path."""
_requests — covers the on_abort_ack arrival path.
"""
session, conn, _ = _make_session()
_activate(session, conn)
session.request_blocks(
@@ -740,7 +742,8 @@ class TestLookupFlow:
def test_aggregate_flush_resolve_round_trip(self):
"""register_lookup → flush sends one LookupMsg → response
resolves entries → register_lookup returns the cached bool on
every call, and repeat probes never re-issue a LookupMsg."""
every call, and repeat probes never re-issue a LookupMsg.
"""
session, conn, _ = _make_session()
_activate(session, conn)
@@ -793,7 +796,8 @@ class TestLookupFlow:
def test_request_blocks_clears_probe_cache(self):
"""A resolved HIT probe is popped when its fetch is issued, so a
re-scheduled request re-probes instead of trusting the stale True
(the served block is unpinned and may have been evicted)."""
(the served block is unpinned and may have been evicted).
"""
session, conn, _ = _make_session()
_activate(session, conn)
@@ -827,7 +831,7 @@ class TestLookupFlow:
assert fresh[0][LookupMsg.KEYS] == [b"hA"]
def test_flush_uses_work_list_not_full_scan(self):
"""flush drains a work-list rather than scanning every live request.
"""Flush drains a work-list rather than scanning every live request.
A request with no newly-registered keys is not revisited: after a
flush the work-list is empty, an idle re-flush sends nothing, and a
@@ -879,7 +883,8 @@ class TestLookupFlow:
def test_multiple_lookup_msgs_across_steps(self):
"""A request's block set may be discovered across scheduler steps:
each step that registers new keys flushes its own LookupMsg for
the same kv_request_id, carrying only the newly-probed keys."""
the same kv_request_id, carrying only the newly-probed keys.
"""
session, conn, _ = _make_session()
_activate(session, conn)
@@ -907,7 +912,8 @@ class TestLookupFlow:
def test_split_response_resolves_across_messages(self):
"""Producer may answer one LookupMsg's keys across multiple
LookupRespMsgs — pairs are self-describing so each lands."""
LookupRespMsgs — pairs are self-describing so each lands.
"""
session, conn, _ = _make_session()
_activate(session, conn)
@@ -954,7 +960,8 @@ class TestLookupFlow:
def test_finish_after_flushed_lookup_sends_empty_fetch(self):
"""LookupMsg flushed but no FetchMsg sent (all-miss case) →
finish_request emits an empty FetchMsg so the peer can drop its
lookup state and call parent.on_request_finished."""
lookup state and call parent.on_request_finished.
"""
session, conn, _ = _make_session()
_activate(session, conn)
@@ -972,7 +979,8 @@ class TestLookupFlow:
def test_finish_without_flushed_lookup_sends_no_fetch(self):
"""No LookupMsg was ever sent → finish_request must not emit an
empty FetchMsg (the peer has no state to release)."""
empty FetchMsg (the peer has no state to release).
"""
session, conn, _ = _make_session()
_activate(session, conn)
@@ -987,7 +995,8 @@ class TestLookupFlow:
def test_finish_after_real_fetch_sends_no_second_fetch(self):
"""A real FetchMsg was already sent for the id → finish_request
must not emit a second (empty) FetchMsg."""
must not emit a second (empty) FetchMsg.
"""
session, conn, _ = _make_session()
_activate(session, conn)
@@ -1018,7 +1027,8 @@ class TestLookupFlow:
"""``poll()`` only enqueues an inbound LookupMsg — no response is
sent until ``serve_external_requests``. With an all-miss parent
the aggregated LookupRespMsg carries the same keys and
``hits=[False, ...]``."""
``hits=[False, ...]``.
"""
session, conn, _ = _make_session()
_activate(session, conn)
@@ -1078,7 +1088,8 @@ class TestServerLookupHandling:
def test_immediate_hits_create_one_store_job(self):
"""All-HIT batch: one create_store_job call with all keys, one
LookupRespMsg with hits=[True]*N, on_request_finished fires at the
end of serve, and `available` is populated for the eventual fetch."""
end of serve, and `available` is populated for the eventual fetch.
"""
cb = FakeParent(stored={b"hA": 1, b"hB": 2, b"hC": 3})
session, conn, _ = _make_session()
_activate(session, conn)
@@ -1108,7 +1119,8 @@ class TestServerLookupHandling:
def test_all_misses_no_store_job_finish_fires(self):
"""All-MISS batch: no create_store_job call; one LookupRespMsg
with hits=[False]*N; on_request_finished fires at end of serve."""
with hits=[False]*N; on_request_finished fires at end of serve.
"""
cb = FakeParent()
session, conn, _ = _make_session()
_activate(session, conn)
@@ -1128,7 +1140,8 @@ class TestServerLookupHandling:
"""HIT/MISS resolutions do not go out on first sight when any
key is still HIT_PENDING / RETRY. The lookup parks until every
key has settled (or the deadline fires), then one
LookupRespMsg carries all keys in wire order."""
LookupRespMsg carries all keys in wire order.
"""
cb = FakeParent(
stored={b"hA": 1},
pending={b"hB"},
@@ -1157,7 +1170,8 @@ class TestServerLookupHandling:
the deferred aggregate response: one LookupRespMsg carrying
both keys in wire order, and one create_store_job call per
HIT (the second HIT is pinned when it resolves, not when the
response goes out)."""
response goes out).
"""
cb = FakeParent(stored={b"hA": 1}, pending={b"hB"})
session, conn, _ = _make_session()
_activate(session, conn)
@@ -1193,7 +1207,8 @@ class TestServerLookupHandling:
def test_pending_timeout_replies_miss_no_store_job(self):
"""A HIT_PENDING key that stays pending past the batch
``deadline`` is force-MISS and never pinned; the deferred
aggregate response fires with hits=[False]."""
aggregate response fires with hits=[False].
"""
cb = FakeParent(pending={b"hA"})
session, conn, _ = _make_session()
_activate(session, conn)
@@ -1220,7 +1235,8 @@ class TestServerLookupHandling:
def test_finish_request_called_per_lookup_msg_not_per_kv_request_id(self):
"""Two LookupMsgs for the same kv_request_id get distinct ctxs
and two on_request_finished calls (one per batch)."""
and two on_request_finished calls (one per batch).
"""
cb = FakeParent(stored={b"hA": 1, b"hB": 2})
session, conn, _ = _make_session()
_activate(session, conn)
@@ -1244,7 +1260,8 @@ class TestServerLookupHandling:
"""Tearing the session down with a parked batch returns the
synthetic ctx as a failed serve (no parent handle at teardown) so
the manager can release the TieringManager's state on its next
serve."""
serve.
"""
cb = FakeParent(pending={b"hA"})
session, conn, _ = _make_session()
_activate(session, conn)
@@ -1265,7 +1282,8 @@ class TestServerLookupHandling:
def test_wire_finish_drops_pending_batches_for_kv_request_id(self):
"""``ServerRole.finish(kv_request_id)`` drops every parked batch
whose kv_request_id matches and queues its ctx for the next
serve's on_request_finished."""
serve's on_request_finished.
"""
cb = FakeParent(pending={b"hA", b"hB"})
session, conn, _ = _make_session()
_activate(session, conn)
@@ -1296,7 +1314,8 @@ class TestServerLookupHandling:
def test_incoming_fetch_drops_pending_lookups_for_kv_request_id(self):
"""A peer FetchMsg terminates the lookup phase for its id: parked
lookups with matching kv_request_id are dropped and their
ctx queued for on_request_finished; other kv_request_ids untouched."""
ctx queued for on_request_finished; other kv_request_ids untouched.
"""
cb = FakeParent(pending={b"hA", b"hB"})
session, conn, _ = _make_session()
_activate(session, conn)
@@ -1338,7 +1357,8 @@ class TestServerLookupHandling:
def test_lookup_then_fetch_round_trip_emits_store_result(self):
"""End-to-end: lookup pins primary slots → fetch matches them →
NIXL transfer completes → StoreResult surfaces with the
create_store_job's job_id (the engine releases the pin)."""
create_store_job's job_id (the engine releases the pin).
"""
cb = FakeParent(stored={b"hA": 7, b"hB": 8})
session, conn, transport = _make_session()
_activate(session, conn)
@@ -1460,7 +1480,8 @@ class TestServerFlows:
def test_abort_fetch_defers_ack_when_cancel_pending(self):
"""If cancel(mode='wait') reports still-inflight tids, the ack is
deferred and the abort is parked (abort_started_at set)."""
deferred and the abort is parked (abort_started_at set).
"""
session, conn, transport = _make_session()
_activate(session, conn)
# Seed an inflight transfer for req-1 that the transport pretends
@@ -1495,7 +1516,8 @@ class TestServerFlows:
def test_abort_fetch_acks_after_drain(self):
"""Once the transport reports the tid as DONE the parked abort
completes and AbortAckMsg is sent."""
completes and AbortAckMsg is sent.
"""
session, conn, transport = _make_session()
_activate(session, conn)
tid = 42
@@ -1534,7 +1556,8 @@ class TestServerFlows:
def test_abort_fetch_force_cancels_after_timeout(self):
"""If wait-mode never drains, the deadline forces immediate
cancel and an ack is still sent."""
cancel and an ack is still sent.
"""
session, conn, transport = _make_session()
_activate(session, conn)
tid = 42
@@ -1576,7 +1599,8 @@ class TestServerFlows:
def test_abort_fetch_idempotent_while_draining(self):
"""Receiving AbortFetchMsg twice for the same kv_request_id
keeps a single pending entry and produces a single ack."""
keeps a single pending entry and produces a single ack.
"""
session, conn, transport = _make_session()
_activate(session, conn)
tid = 42
@@ -1634,7 +1658,8 @@ class TestServerFlows:
def test_store_timeout_then_late_completion_no_duplicate(self):
"""A job timed out by _timeout_pending_store_jobs must not also
emit a contradictory StoreResult(success=True) when the transport
later reports the same transfer as done."""
later reports the same transfer as done.
"""
session, conn, transport = _make_session()
_activate(session, conn)
session.add_stored_blocks("req-1", [b"k1"], [0], job_id=1)
@@ -1667,7 +1692,8 @@ class TestServerFlows:
def test_store_timeout_then_late_failure_no_duplicate(self):
"""Symmetric guard: a timed-out job must not also emit a second
StoreResult(success=False) when the transport later reports the
same transfer as failed."""
same transfer as failed.
"""
session, conn, transport = _make_session()
_activate(session, conn)
session.add_stored_blocks("req-1", [b"k1"], [0], job_id=1)
@@ -1710,7 +1736,8 @@ class TestFinishRequestServerSide:
def test_no_inflight_unmatched_demand_sends_failure(self):
"""finish_request with unmatched demand and no inflight ->
immediate TransferDoneMsg(success=False); _outbound cleared."""
immediate TransferDoneMsg(success=False); _outbound cleared.
"""
session, conn, _ = _make_session()
_activate(session, conn)
# Decoder demanded a block we never stored.
@@ -1736,7 +1763,8 @@ class TestFinishRequestServerSide:
def test_with_inflight_defers_then_fires_on_last_transfer(self):
"""finish_request with inflight defers; last transfer fires the
early-fail message and clears _outbound."""
early-fail message and clears _outbound.
"""
session, conn, transport = _make_session()
_activate(session, conn)
# Demand 2 blocks; we store 1 (kicks one inflight transfer).
@@ -1773,7 +1801,8 @@ class TestFinishRequestServerSide:
def test_full_demand_satisfied_still_sends_success(self):
"""finish_request must not override a fully-satisfied transfer:
when remaining hits 0, success=True still fires."""
when remaining hits 0, success=True still fires.
"""
session, conn, transport = _make_session()
_activate(session, conn)
conn.enqueue(
@@ -1802,7 +1831,8 @@ class TestFinishRequestServerSide:
"""Prefiller-first: finish_request runs before the decoder's
fetch arrives. State is held until fetch, then
finalized — success=True if all demand was matched against
available blocks, else success=False."""
available blocks, else success=False.
"""
# Case A: all demand satisfied by available blocks.
session, conn, transport = _make_session()
_activate(session, conn)
@@ -1863,7 +1893,8 @@ class TestFinishRequestServerSide:
"""finish_request with a stored-but-unmatched job and no inflight ->
TransferDoneMsg(success=False) AND deferred
StoreResult(success=False) for the submit_store'd job, instead of
the 30s _STORE_TIMEOUT_S path."""
the 30s _STORE_TIMEOUT_S path.
"""
session, conn, _ = _make_session()
_activate(session, conn)
# Decoder demanded b"demand"; we never stored it.
@@ -1899,7 +1930,8 @@ class TestFinishRequestServerSide:
def test_finish_request_remaining_zero_emits_success_via_inflight(self):
"""Deferred-via-inflight path: finish_request with inflight, last
transfer drains remaining to 0 -> TransferDoneMsg(success=True)
AND StoreResult(success=True)."""
AND StoreResult(success=True).
"""
session, conn, transport = _make_session()
_activate(session, conn)
conn.enqueue(
@@ -2247,7 +2279,8 @@ class TestDisconnect:
def test_send_failure_marks_connection_dead(self):
"""A raising send must mark the connection dead, not silently drop
the message — otherwise the session lingers alive, is never reaped,
and in-flight lookups/loads toward the dead peer hang forever."""
and in-flight lookups/loads toward the dead peer hang forever.
"""
session, conn, _ = _make_session()
_activate(session, conn)
assert session.alive
@@ -2260,7 +2293,8 @@ class TestDisconnect:
def test_close_surfaces_inflight_lookups(self):
"""close() reports kv_request_ids whose symmetric-P2P probe is still
unresolved; resolved probes are not reported (their answer is in)."""
unresolved; resolved probes are not reported (their answer is in).
"""
session, conn, _ = _make_session()
_activate(session, conn)
@@ -2368,7 +2402,8 @@ class TestDispatchErrorHandling:
def test_value_error_disconnects_on_first_occurrence(self):
"""A FetchMsg that fails validate() raises ValueError and must
terminate the session immediately, with a DisconnectMsg sent."""
terminate the session immediately, with a DisconnectMsg sent.
"""
session, conn, _ = _make_session()
_activate(session, conn)
# length mismatch → FetchMsg.validate raises ValueError
@@ -2395,7 +2430,8 @@ class TestDispatchErrorHandling:
def test_internal_error_does_not_disconnect_once(self):
"""A non-ValueError raised by a handler is treated as an internal
bug: counter increments, session stays alive on a single hit."""
bug: counter increments, session stays alive on a single hit.
"""
session, conn, _ = _make_session()
_activate(session, conn)
@@ -2418,7 +2454,8 @@ class TestDispatchErrorHandling:
def test_internal_error_threshold_disconnects(self):
"""Once consecutive non-protocol errors hit the threshold, the
session tears down via _protocol_error."""
session tears down via _protocol_error.
"""
session, conn, _ = _make_session()
_activate(session, conn)
@@ -2442,7 +2479,8 @@ class TestDispatchErrorHandling:
def test_internal_error_counter_resets_on_success(self):
"""A successful dispatch between errors prevents the threshold
from being reached."""
from being reached.
"""
session, conn, _ = _make_session()
_activate(session, conn)
@@ -2485,7 +2523,8 @@ class TestInflightPerReqInvariant:
def test_invariant_holds_through_lifecycle(self):
"""Run a full submit→complete sequence for two concurrent
kv_request_ids and assert the counter matches `_inflight` at
every observable step, including the empty-after-finish case."""
every observable step, including the empty-after-finish case.
"""
session, conn, transport = _make_session()
_activate(session, conn)
@@ -2550,7 +2589,8 @@ class TestInflightPerReqInvariant:
"""Populate many inflight xfers across many ids; lookup must
match the actual presence in `_inflight` for both hits and
misses. The whole point of the counter is that this lookup is
constant-time, but we assert correctness, not timing."""
constant-time, but we assert correctness, not timing.
"""
session, _, _ = _make_session()
for kv_id_idx in range(100):
kv_id = f"req-{kv_id_idx}"
@@ -264,7 +264,8 @@ class TestAsyncLookupManager:
subsequent lookup then returns False (MISS) directly, WITHOUT enqueuing
a fresh batch_lookup — that is what makes the request unable to loop.
The entry is retained (as False) not dropped, so cleanup()'s reverse
index stays consistent; an unknown key is a no-op."""
index stays consistent; an unknown key is a no-op.
"""
mgr = InMemoryLookupManager(existing_keys={_key(1), _key(2)})
ctx = _ctx("reqA")
assert mgr.lookup(_key(1), ctx) is None
@@ -304,7 +305,8 @@ class TestAsyncLookupManager:
receive at most one result per key. Normal operation resolves a key a
single time; a second result for an already-decided key trips the assert
that guards the invariant (a silent overwrite could flip a corrected
miss back to True and reopen the failed-load livelock)."""
miss back to True and reopen the failed-load livelock).
"""
mgr = InMemoryLookupManager(existing_keys={_key(1)})
ctx = _ctx("reqA")
+1 -2
View File
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
"""
Unit tests for SecondaryTierFactory.
"""Unit tests for SecondaryTierFactory.
These tests verify:
1. Pre-registration integrity — registered tier module paths can import
+17 -10
View File
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
"""
Unit tests for FileSystemTierManager.
"""Unit tests for FileSystemTierManager.
These tests use real disk I/O to verify the filesystem tier implementation.
The tier manager writes KV cache blocks to disk and reads them back, verifying
@@ -370,7 +369,8 @@ def test_shutdown_discards_pending_tasks(fs_tier):
@pytest.mark.parametrize("use_c_ext", [True, False])
def test_store_load_data_integrity(fs_tier, monkeypatch, use_c_ext, batch_size):
"""Data written by store must be exactly recovered by load, for batches
of any size -- including the empty batch."""
of any size -- including the empty batch.
"""
import vllm.v1.kv_offload.tiering.fs.io as io_mod
if use_c_ext and not io_mod._HAS_FSIO_C:
@@ -467,7 +467,8 @@ def test_wait_idle_blocks_until_tasks_complete():
def test_batch_lookup_c_extension(tmp_path):
"""Validates batch_lookup_C: empty, single, all-existing, all-missing,
mixed ordering, and input type validation."""
mixed ordering, and input type validation.
"""
try:
from vllm.fs_io_C import batch_lookup as batch_lookup_C
except ImportError:
@@ -531,7 +532,8 @@ def test_batch_lookup_dispatch(fs_tier, monkeypatch, use_c_ext):
@pytest.mark.parametrize("use_c_ext", [True, False])
def test_out_of_bounds_block_id_smoke(fs_tier, monkeypatch, use_c_ext):
"""Smoke test: a block id beyond the primary tensor's block count must
fail the job, for both the C extension and the Python fallback."""
fail the job, for both the C extension and the Python fallback.
"""
import vllm.v1.kv_offload.tiering.fs.io as io_mod
if use_c_ext and not io_mod._HAS_FSIO_C:
@@ -613,7 +615,8 @@ def test_batched_partial_load_failure_keeps_loaded_blocks(
loaded before it (#50321). Corrupt the LAST block: the earlier blocks load
fine, so the job reports successful_keys for them and marks only the failed
tail a miss. The earlier keys stay HIT — including for the same request —
while the corrupt block stays a MISS (its file was removed)."""
while the corrupt block stays a MISS (its file was removed).
"""
import vllm.v1.kv_offload.tiering.fs.io as io_mod
if use_c_ext and not io_mod._HAS_FSIO_C:
@@ -665,7 +668,8 @@ def test_batched_load_first_block_fails_marks_whole_batch(
):
"""When the FIRST block fails, nothing loaded before it: the job reports no
successful_keys (None) and the whole batch is marked a miss for the
request."""
request.
"""
import vllm.v1.kv_offload.tiering.fs.io as io_mod
if use_c_ext and not io_mod._HAS_FSIO_C:
@@ -696,7 +700,8 @@ def test_transient_load_failure_leaves_file(fs_tier, monkeypatch, use_c_ext):
"""A transient host error (here ELOOP on open) is NOT a short read: the job
fails but the block file must survive untouched, on both the C and Python
paths. Deleting on a transient error would turn a passing hiccup into
permanent data loss."""
permanent data loss.
"""
import vllm.v1.kv_offload.tiering.fs.io as io_mod
if use_c_ext and not io_mod._HAS_FSIO_C:
@@ -800,7 +805,8 @@ def test_mixed_job_results_emit_event_only_for_successful_job(
fs_tier_with_events, monkeypatch
):
"""With a failed and a successful store job in flight, exactly one event
is emitted and its keys belong to the successful job."""
is emitted and its keys belong to the successful job.
"""
import vllm.v1.kv_offload.tiering.fs.manager as mgr_mod
tier = fs_tier_with_events
@@ -885,7 +891,8 @@ def test_events_require_global_kv_events_flag(tmp_path):
def test_cascade_store_emits_fs_event_through_tiering_manager(tmp_path):
"""A GPU->CPU->fs cascade surfaces the tier-owned FS stored event via the
TieringOffloadingManager's aggregated take_events()."""
TieringOffloadingManager's aggregated take_events().
"""
from vllm.v1.kv_offload.tiering.manager import (
CPUPrimaryTierOffloadingManager,
TieringOffloadingManager,
+5 -4
View File
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
"""
Mock-based unit tests for ObjectStoreSecondaryTierManager.
"""Mock-based unit tests for ObjectStoreSecondaryTierManager.
These tests replace the NIXL backend with an in-memory mock so they run
without S3 credentials or a live object store. They verify the manager's
@@ -347,7 +346,8 @@ class TestMockObjTierBasic:
the scheduler would re-issue the same doomed promotion every step for
the life of the request. The mark is served from cache with no
re-probe, so even though the mock object is still 'present' the SAME
request now resolves to MISS."""
request now resolves to MISS.
"""
ctx = ReqContext(req_id="obj-livelock")
self.tier.submit_store(make_job(1, [key(1)], [0]))
assert all(r.success for r in drain(self.tier))
@@ -651,7 +651,8 @@ class TestObjTierKVEvents:
def test_mixed_job_results_emit_event_only_for_successful_job(self):
"""With a failed and a successful store job resolving in the same
poll, exactly one event is emitted and its keys belong to the
successful job."""
successful job.
"""
original = self.agent.check_xfer_state
self.agent.check_xfer_state = lambda h: "ERR" if h._id == 0 else original(h)
self.tier.submit_store(make_job(1, [key(1)], [0])) # handle 0: fails
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
"""
Unit tests for TieringOffloadingManager and ExampleSecondaryTierManager.
"""Unit tests for TieringOffloadingManager and ExampleSecondaryTierManager.
These tests verify:
1. Basic tiered offloading operations (store, load, lookup)
@@ -274,7 +273,8 @@ _CASCADE_SUPPLY_BEHAVIOR = {
def test_every_lookup_result_has_a_declared_cascade_behavior():
"""A new LookupResult must state what the cascade does with it, rather
than falling into whichever branch happens to catch it."""
than falling into whichever branch happens to catch it.
"""
assert set(_CASCADE_SUPPLY_BEHAVIOR) == set(LookupResult)
@@ -321,7 +321,8 @@ class TestTieringOffloadingManager:
def test_failed_promotion_finalizes_primary_with_failure(self, manager_setup):
"""A failed promotion still finalizes the primary slots with
success=False; the tier corrects its own verdict."""
success=False; the tier corrects its own verdict.
"""
from unittest.mock import patch
from vllm.v1.kv_offload.tiering.base import JobResult
@@ -1092,7 +1093,8 @@ class TestTieringOffloadingManager:
def test_on_new_request_lifecycle(self, manager_setup):
"""Policy defaults to CHUNK_LEVEL, escalates when a tier requests it,
and is cleaned up on on_request_finished."""
and is cleaned up on on_request_finished.
"""
# Default: all tiers return CHUNK_LEVEL
ctx = ReqContext(req_id="req_policy_lifecycle")
result = self.manager.on_new_request(ctx)
@@ -1169,7 +1171,8 @@ class TestTieringOffloadingManager:
def _make_request_level_request(self, req_id: str) -> ReqContext:
"""Start a request for which tier1 asks for request-level offloading,
with tier1's submit_store wrapped so the cascade can be observed."""
with tier1's submit_store wrapped so the cascade can be observed.
"""
self.secondary_tier1.on_new_request = lambda req_context: (
RequestOffloadingContext(policy=OffloadPolicy.REQUEST_LEVEL)
)
@@ -1191,7 +1194,8 @@ class TestTieringOffloadingManager:
def test_cascade_rejects_retry_from_primary(self, manager_setup):
"""RETRY would be parked with no guarantee of ever draining, so the
cascade refuses it. No real primary tier returns it, so this is the one
disposition that has to be forced."""
disposition that has to be forced.
"""
keys = to_keys(range(3))
self._start_request()
assert self.manager.prepare_store(keys, _CTX) is not None
@@ -1206,7 +1210,8 @@ class TestTieringOffloadingManager:
def _start_in_flight_primary_write(self, keys: list[OffloadKey]) -> ReqContext:
"""Leave a GPU->primary write for `keys` open, so they look present to
prepare_store but are not yet readable."""
prepare_store but are not yet readable.
"""
writer_ctx = ReqContext(req_id="req_writer")
self._start_request(writer_ctx)
assert self.manager.prepare_store(keys, writer_ctx) is not None
@@ -1215,7 +1220,8 @@ class TestTieringOffloadingManager:
def test_cascade_defers_keys_whose_primary_write_is_in_flight(self, manager_setup):
"""A key another request is still writing must reach the peer once the
write lands, not be dropped: prepare_store already counts it as stored
and the scheduler advances past its chunk, so nothing re-offers it."""
and the scheduler advances past its chunk, so nothing re-offers it.
"""
keys = to_keys(range(3))
writer_ctx = self._start_in_flight_primary_write(keys)
@@ -1232,7 +1238,8 @@ class TestTieringOffloadingManager:
def test_deferred_cascade_holds_request_from_finalization(self, manager_setup):
"""A request that finishes with keys still deferred must stay alive, or
its tiers are torn down before the peer is ever served."""
its tiers are torn down before the peer is ever served.
"""
keys = to_keys(range(3))
writer_ctx = self._start_in_flight_primary_write(keys)
@@ -1255,7 +1262,8 @@ class TestTieringOffloadingManager:
self, manager_setup
):
"""A failed write frees the chunk, so the deferred key resolves to MISS
and the request finalizes instead of parking forever."""
and the request finalizes instead of parking forever.
"""
keys = to_keys(range(3))
writer_ctx = self._start_in_flight_primary_write(keys)
@@ -1275,7 +1283,8 @@ class TestTieringOffloadingManager:
def test_reset_cache_clears_orchestrator_state(self, manager_setup):
"""reset_cache wipes every kind of orchestrator state and resets
primary tier; pending submissions are dropped without being sent
to the secondary tier. Active request state is retained."""
to the secondary tier. Active request state is retained.
"""
# Cascade — populates primary chunks and leaves cascade jobs
# in _jobs (the synchronous example tier has already
# queued completions); reset_cache's drain loop will pick them up.
@@ -1367,7 +1376,8 @@ class TestTieringOffloadingManager:
self, manager_setup, load_tier_filter
):
"""Filter excluding secondary medium returns MISS from secondaries
even when they hold the chunk; primary is unaffected."""
even when they hold the chunk; primary is unaffected.
"""
chunks = to_keys(range(2))
# Put one chunk in primary, one only in secondary
self._start_request()