Skip to content

Commit bd24f4f

Browse files
authored
fix: keep FusedCodecPipeline compute off the event-loop thread (#4194)
* fix: byte-order handling for structured dtypes in the bytes codec (#220) * fix: byte-order handling for structured dtypes in the bytes codec The bytes codec neither byte-swapped structured-dtype fields to its configured endian on encode (numpy reports byteorder '|' for void dtypes, so the top-level byteorder comparison never detected a mismatch) nor honored its endian when decoding, silently corrupting any structured data whose field byte order differed from the stored one (e.g. virtual references to external big-endian data). Encode now detects byte-order mismatches by comparing full dtypes via newbyteorder, and decode reinterprets raw bytes in the stored byte order before converting to the data type's declared byte order, so the stored layout (codec state) and the in-memory layout (array data type) are independent. Closes #4141 Assisted-by: ClaudeCode:claude-fable-5 * test: fold structured byte-order cases into existing bytes codec tests Extend test_endian's parametrization with structured dtypes and test_bytes_codec_sync_roundtrip with endian/dtype parametrization plus stored-layout and decoded-dtype assertions, instead of adding parallel test functions for the same properties. Assisted-by: ClaudeCode:claude-fable-5 * refactor: rename stored_dtype to view_dtype in BytesCodec decode The variable is the dtype used to view the raw chunk bytes (byte order from the codec's endian configuration), not a property of the stored data or of the returned buffer, which always carries the array's declared dtype. Assisted-by: ClaudeCode:claude-fable-5 * docs: note that the decode-side byte-order conversion copies the chunk Assisted-by: ClaudeCode:claude-fable-5 * fix(codec_pipeline): keep FusedCodecPipeline compute off the event-loop thread FusedCodecPipeline.read/write ran their synchronous fast path inline on the coroutine servicing the request — i.e. on the global zarr_io event loop thread. Single-chunk batches decoded inline on the loop and multi-chunk batches blocked the loop in pool.map, so every sync-API call from every user thread serialized behind each other's codec compute. The blocked window scales with codec cost, which is why users reported the fused pipeline as "slower for zstd-compressed data" under multi-threaded (dask-style, one chunk per call) access: at 8 reader threads on 4 MiB zstd chunks it was 3.4x slower than BatchedCodecPipeline, and throughput did not scale with threads at all (336 -> 439 ms from 1 to 8 threads, versus 669 -> 121 ms for batched). Offload the synchronous batch to a worker thread with asyncio.to_thread: one hop per batch, not per chunk, preserving the fused pipeline's win over per-chunk async scheduling while keeping the loop free. After the fix the same workload scales 625 -> 109 ms from 1 to 8 threads, beating batched at every thread count; single-threaded performance is unchanged (the hop costs ~75 us per batch). The regression test asserts deterministically (no timing) that codec compute never runs on a thread with a running event loop, covering single- and multi-chunk reads and writes through the sync API. A new benchmark covers the many-threads/one-chunk-per-call access pattern. Assisted-by: ClaudeCode:claude-fable-5 * docs: rename change note to upstream PR number (4194) towncrier's issue_format links to zarr-developers/zarr-python issues, so 247 (the fork PR number) would render a link to an unrelated old issue. Assisted-by: ClaudeCode:claude-fable-5 * test: guard event-loop test against vacuity if the sync fast path stops triggering The test asserts a negative (compute never ran on the loop thread). If a refactor made the sync fast path stop triggering, the traced ChunkTransform methods would never be called (the async fallback uses AsyncChunkTransform) and the test would pass while guarding nothing. Assert the traced hooks actually ran. Assisted-by: ClaudeCode:claude-fable-5
1 parent 0c07bf5 commit bd24f4f

4 files changed

Lines changed: 133 additions & 2 deletions

File tree

‎changes/4194.bugfix.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
`FusedCodecPipeline` no longer runs chunk IO and codec compute on the thread
2+
driving zarr's internal event loop. Previously each read/write executed its
3+
synchronous fast path inline on that loop thread, and because every sync-API
4+
call from every user thread is serviced by the same loop, concurrent
5+
operations serialized behind each other's codec work — reported as the fused
6+
pipeline being slower than `BatchedCodecPipeline` for zstd-compressed data
7+
under multi-threaded (e.g. dask) access. The synchronous batch now runs on a
8+
worker thread (one hop per batch, not per chunk), keeping the loop free.
9+
Multi-threaded single-chunk reads of zstd data are ~4.5x faster than before
10+
and now scale with reader threads; single-threaded performance is unchanged.

‎src/zarr/core/codec_pipeline.py‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1182,7 +1182,15 @@ async def read(
11821182
(isinstance(first_bg, StorePath) and isinstance(first_bg.store, SupportsGetSync))
11831183
or (not isinstance(first_bg, StorePath) and isinstance(first_bg, SyncByteGetter))
11841184
):
1185-
return self.read_sync(batch, out, drop_axes, max_workers=_resolve_max_workers())
1185+
# One thread hop for the WHOLE batch — not per chunk, so the fused
1186+
# design's win over per-chunk async scheduling is preserved. Running
1187+
# read_sync inline here would block the event loop for the duration
1188+
# of the batch's IO+compute; every sync-API call from every user
1189+
# thread shares this one loop, so inline execution serializes
1190+
# concurrent callers behind each other's codec compute.
1191+
return await asyncio.to_thread(
1192+
self.read_sync, batch, out, drop_axes, max_workers=_resolve_max_workers()
1193+
)
11861194

11871195
# Non-sync store (e.g. ZipStore): can't use the sync fast path. But if the
11881196
# array-bytes codec supports partial decoding (sharding), still route
@@ -1235,7 +1243,11 @@ async def write(
12351243
(isinstance(first_bs, StorePath) and isinstance(first_bs.store, SupportsSetSync))
12361244
or (not isinstance(first_bs, StorePath) and isinstance(first_bs, SyncByteSetter))
12371245
):
1238-
self.write_sync(batch, value, drop_axes, max_workers=_resolve_max_workers())
1246+
# One thread hop for the whole batch; see the matching comment in
1247+
# `read` for why write_sync must not run inline on the event loop.
1248+
await asyncio.to_thread(
1249+
self.write_sync, batch, value, drop_axes, max_workers=_resolve_max_workers()
1250+
)
12391251
return
12401252

12411253
await _async_write_fallback(self, batch, value, drop_axes)

‎tests/benchmarks/test_e2e.py‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,3 +190,51 @@ def setup() -> tuple[tuple[zarr.Array, EllipsisType], dict]: # type: ignore[typ
190190
return (arr, Ellipsis), {}
191191

192192
benchmark.pedantic(getitem, setup=setup, rounds=3) # type: ignore[no-untyped-call]
193+
194+
195+
_CONCURRENT_READ_THREADS = 8
196+
_concurrent_layout = Layout(shape=(64_000_000,), chunks=(4_000_000,), shards=None)
197+
198+
199+
@pytest.mark.parametrize("pipeline", ["batched", "fused_full_threaded"], indirect=True)
200+
@pytest.mark.parametrize("compression_name", ["zstd", None])
201+
@pytest.mark.parametrize("store", ["local"], indirect=["store"])
202+
def test_read_array_concurrent(
203+
bench_store: Store,
204+
compression_name: CompressorName,
205+
pipeline: str,
206+
benchmark: BenchmarkFixture,
207+
) -> None:
208+
"""Dask-style access: several user threads each reading one chunk per call.
209+
210+
All sync-API calls are serviced by the one global event loop, so this
211+
measures how much of each read's IO+compute the pipeline runs while
212+
holding the loop: anything inline serializes the readers.
213+
"""
214+
from concurrent.futures import ThreadPoolExecutor
215+
216+
layout = _concurrent_layout
217+
arr = create_array(
218+
bench_store,
219+
dtype="uint8",
220+
shape=layout.shape,
221+
chunks=layout.chunks,
222+
shards=layout.shards,
223+
compressors=compressors[compression_name], # type: ignore[arg-type]
224+
fill_value=0,
225+
)
226+
arr[:] = _data(layout.shape)
227+
selections = [
228+
slice(start, start + layout.chunks[0])
229+
for start in range(0, layout.shape[0], layout.chunks[0])
230+
]
231+
232+
def read_all_chunks_concurrently() -> None:
233+
with ThreadPoolExecutor(max_workers=_CONCURRENT_READ_THREADS) as executor:
234+
list(executor.map(lambda sel: arr[sel], selections))
235+
236+
def setup() -> tuple[tuple[()], dict]: # type: ignore[type-arg]
237+
clear_cache()
238+
return (), {}
239+
240+
benchmark.pedantic(read_all_chunks_concurrently, setup=setup, rounds=3) # type: ignore[no-untyped-call]

‎tests/test_fused_pipeline.py‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,67 @@ def test_construction(codecs: tuple[Any, ...]) -> None:
3434
assert pipeline.codecs == codecs
3535

3636

37+
def test_sync_api_compute_off_event_loop(monkeypatch: pytest.MonkeyPatch) -> None:
38+
"""Codec compute must never run on the thread driving the event loop.
39+
40+
Every sync-API call, from every user thread, is serviced by the one global
41+
`zarr_io` event loop. Running decode/encode inline on that loop's thread
42+
turns it into a mutex around codec compute: concurrent readers serialize,
43+
and the penalty grows with codec cost (observed as "fused pipeline is
44+
slower for zstd data" under dask-style multi-threaded single-chunk reads).
45+
"""
46+
import asyncio
47+
48+
from zarr.core.chunk_utils import ChunkTransform
49+
50+
compute_on_loop = {"decode": False, "encode": False}
51+
calls = {"decode": 0, "encode": 0}
52+
real_decode = ChunkTransform.decode_chunk
53+
real_encode = ChunkTransform.encode_chunk
54+
55+
def _running_loop() -> bool:
56+
try:
57+
asyncio.get_running_loop()
58+
except RuntimeError:
59+
return False
60+
return True
61+
62+
def traced_decode(self: ChunkTransform, chunk_bytes: Any, chunk_spec: Any) -> Any:
63+
calls["decode"] += 1
64+
compute_on_loop["decode"] = compute_on_loop["decode"] or _running_loop()
65+
return real_decode(self, chunk_bytes, chunk_spec)
66+
67+
def traced_encode(self: ChunkTransform, chunk_array: Any, chunk_spec: Any) -> Any:
68+
calls["encode"] += 1
69+
compute_on_loop["encode"] = compute_on_loop["encode"] or _running_loop()
70+
return real_encode(self, chunk_array, chunk_spec)
71+
72+
monkeypatch.setattr(ChunkTransform, "decode_chunk", traced_decode)
73+
monkeypatch.setattr(ChunkTransform, "encode_chunk", traced_encode)
74+
75+
with zarr_config.set({"codec_pipeline.path": "zarr.core.codec_pipeline.FusedCodecPipeline"}):
76+
arr = zarr.create_array(
77+
MemoryStore(),
78+
shape=(8, 8),
79+
chunks=(4, 4),
80+
dtype="float64",
81+
compressors=ZstdCodec(level=1),
82+
)
83+
data = np.arange(64, dtype="float64").reshape(8, 8)
84+
arr[:4, :4] = data[:4, :4] # single-chunk write (batch of 1)
85+
arr[:] = data # multi-chunk write
86+
# Guard against vacuity: if the sync fast path stops triggering, the
87+
# traced ChunkTransform methods are never called (the async fallback
88+
# uses AsyncChunkTransform) and the on-loop flags stay trivially False.
89+
assert calls["encode"] > 0
90+
assert compute_on_loop["encode"] is False
91+
92+
np.testing.assert_array_equal(arr[:4, :4], data[:4, :4]) # single-chunk read
93+
np.testing.assert_array_equal(arr[:], data) # multi-chunk read
94+
assert calls["decode"] > 0
95+
assert compute_on_loop["decode"] is False
96+
97+
3798
def test_evolve_from_array_spec() -> None:
3899
"""evolve_from_array_spec creates a sync transform."""
39100
from zarr.core.array_spec import ArrayConfig, ArraySpec

0 commit comments

Comments
 (0)