Make CPU input buffer size a setting, default 256 chunks

[nclack]

CPU input buffers previously held one chunk per decode worker, limiting simultaneous file reads when each merged request contains several chunks. A new CPU executor setting, chunks_per_input_buffer (CpuLimits.chunks_per_input_buffer in Python, default 256), sets how many chunks each of the two input buffers holds. It must be at least decode_workers, so every worker can get a chunk, and at most 16384, the most chunks a batch can have. Values outside that range are rejected, with a message, when the executor is created. The worker pool and per-worker decoder workspaces stay the same.

This restores simultaneous reads. Each merged read still holds at most min(decode_workers, chunks_per_input_buffer) chunks, the rule used in the measurements below, so a buffer holds several reads at once. With 32 workers, reads are at most 32 chunks, so a full 256-chunk buffer splits into at least 8 reads. With one decode worker, reads do not merge. A separate read-size setting is left for a later PR.

This breaks existing budgets. The input reserve is 2 * chunks_per_input_buffer * max_encoded_chunk_bytes, plus per-chunk bookkeeping. With the defaults, 256 chunks and a 4 MiB encoded bound, that is 2 GiB before decoder workspaces and output buffers, so a 1 GiB CpuLimits budget that worked before now fails with BUDGET when the pipeline starts. Set max_encoded_chunk_bytes to the largest encoded chunk expected, lower chunks_per_input_buffer, or raise max_memory_bytes. When the budget is too small, starting now logs the bytes it tried to reserve for input buffers, decoder workspaces, output buffers, and the rest; a read plan that cannot fit logs its size too. Documentation shows the cost and raises the example budget to 3 GiB. The native pipeline fixture now uses a 1 KiB encoded bound appropriate for its small test chunks, retaining its 32 MiB budget. The throughput-cpu bench scenario no longer fit its 4 GiB budget with the 4 MiB bound; it now sets chunks_per_input_buffer to 256 and a 5 GiB budget. The bench reads the setting from a scenario's pipeline.chunks_per_input_buffer, default 256.

The motivating Turin experiment used 32 decode workers, 64 KiB chunks, 16 KiB Blosc blocks, and sixteen raw 1 GiB shards. In an isolated benchmark patch with persistent shard handles and default readahead, moving from 32 to 256 chunks improved cold translated 256×256 crop output by 47–55% and full-scan output by 71–97% across Blosc-LZ4 and Blosc-Zstd, adding 28.04 MiB of accounted memory at those 64 KiB chunk bounds, not the 2 GiB reserved with the default 4 MiB bound. These are benchmark-patch measurements; this PR does not include the persistent-handle or LZ4 additions and its final binary has not been benchmarked.

Regression coverage checks 513 chunks through three input groups of exactly 256, 256, and 1 chunks at 1, 2, and 32 workers; merged reads of at most decode_workers chunks, with exact read ranges, shard order, and reads per buffer at 1, 2, and 32 workers; complete output; exact memory-budget admission; oversized-allocation rejection; and rejection of chunks_per_input_buffer below decode_workers or above 16384, in C and in Python. Private read-plan tests check complete coverage at 256, 257, and 1024 workers without starting hundreds of threads. Formatting and whitespace checks pass, and the strict documentation build passes locally. At 18cee45, the CPU workflow built without CUDA and passed 24/24 CTest entries on Ubuntu and 25/25 on macOS (the native test executables plus the Python pytest suite), followed by the native dependency audit; the macOS job passed on a rerun after the known test_scheduler timing failure. The GPU-enabled regression workflow passed 36/36 CTest entries, the TSan-labeled check passed 1/1, and the build passed.

Stacked on #164; the base is fix/cpu-read-scheduling. #161 stacks on this branch.

[codecov]

Codecov Report

❌ Patch coverage is 77.77778% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.82%. Comparing base (0dafafd) to head (07d503d).

Files with missing lines	Patch %	Lines
bench/main.c	0.00%	6 Missing ⚠️
src/executor/cpu_executor.c	88.57%	1 Missing and 3 partials ⚠️

Additional details and impacted files

@@                     Coverage Diff                     @@
##           fix/cpu-read-scheduling     #168      +/-   ##
===========================================================
+ Coverage                    59.71%   59.82%   +0.11%     
===========================================================
  Files                           75       75              
  Lines                        11474    11493      +19     
  Branches                      1984     1987       +3     
===========================================================
+ Hits                          6852     6876      +24     
- Misses                        3806     3807       +1     
+ Partials                       816      810       -6     

Flag	Coverage Δ
unittests	59.82% <77.77%> (+0.11%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
python/damacy/__init__.py	96.04% <100.00%> (+0.02%)	⬆️
python/damacy/_components.c	0.00% <ø> (ø)
src/executor/cpu_executor.c	86.24% <88.57%> (+0.28%)	⬆️
bench/main.c	0.00% <0.00%> (ø)

... and 6 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.