feat(file): a coalescing IO service for planning-protocol scans

[joseph-isaacs]

Summary

1/5 of a stack that splits the V2 scan (#10464 and #10547) into smaller PRs on current develop. This is the content of #10463, rebased on develop, unchanged. It adds the IO layer the planner-driven scan reads through. Nothing drives it until the V2 scan PRs.

Stack:

1. IO service (this PR)
2. Planning driver (vortex-scan)
3. V2 scan in vortex-layout
4. Wiring into vortex-file, DataFusion and DuckDB
5. Split-boundary search perf

Changes

• FileIoService. Coalesces the ranges a batch of planning-protocol requests or announcements asks for. Each range is read once for every session interested in it, and a dropped session's interest is withdrawn.
• FileScanIo. Serves the same protocol through the file's segment source and read driver, sharing pending reads between live consumers.
• Local and object-store reads. Local files reuse their handles and admit native reads up to a bound; object-store reads stream completions as they land.
• Read driver. Keeps its coalescing scratch between passes and can leave optional requests out of coalescing (VORTEX_SCAN_IO_COALESCE_OPTIONAL).
• Segment caches. Can answer synchronously through SegmentCache::get_if_ready.
• Tracing. Request trace ids.

Unit tests for coalescing, shared reads, withdrawal and wake-ups are in segments::{io_service, scan_io}.

Checks run:

• cargo clippy -p vortex-io -p vortex-scan -p vortex-layout -p vortex-file --all-targets --all-features -- -D warnings

🤖 Generated with Claude Code

https://claude.ai/code/session_01Hai26WGsNERxRHXpA3JboE

---

Generated by Claude Code

[codspeed]

Merging this PR will regress 2 benchmarks

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️ 1 benchmark measured no execution time

Nothing ran under measurement, usually because the compiler removed the code under test. This result is not comparable, so it counts as unchanged.

Preventing compiler optimizations

• bench_compare_primitive[(10000, 2)]

⚠️ 34 benchmarks spent significant time in system calls

System calls cannot be consistently instrumented, so they are not included in the measure, which understates the real cost. Please switch to the Walltime instrument to accurately measure system calls.

Measurement and system calls

• density_sweep_dense_runs[0.001]
• test_repeated_scan_scalar_at[int]
• test_scan_filter[int_float]
• test_repeated_scan_filter[int]
• random_i128[0.01]
• density_sweep_dense_runs[0.9]
• chunked_dict_primitive_canonical_into[f64, (1000, 1000, 10)]
• test_scan[int_str]
• test_scan_filter_to_arrow_array[int]
• test_repeated_scan[int]
• …and 24 more

ℹ️ 40 benchmarks have no flame graph

The flamegraph could not be generated because we failed to resolve the symbols in the profiling trace. This happens when we fail to harvest information about language frames.

• test_scan_filter[int]
• test_repeated_scan_scalar_at[int]
• test_repeated_scan_scalar_at[int_str]
• test_repeated_scan_scalar_at[int_float]
• test_repeated_scan_scalar_at[int_str_float]
• test_scan_scalar_at[int_str_float]
• test_scan_scalar_at[int_str]
• test_scan_scalar_at[int_float]
• test_scan_filter[int_float]
• test_repeated_scan_to_arrow_array[int]
• …and 30 more

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 3 improved benchmarks
❌ 2 regressed benchmarks
✅ 2242 untouched benchmarks
⏩ 12 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌ ⚠️	Simulation	density_sweep_dense_runs[0.001]	29 µs	46.7 µs	-38.02%
❌ ℹ️	Simulation	test_scan_filter[int]	3 ms	3.4 ms	-10.44%
⚡	Simulation	take_map[(0.1, 1.0)]	352.2 µs	221.2 µs	+59.22%
⚡	Simulation	take_map[(0.1, 0.5)]	182.6 µs	146.4 µs	+24.72%
⚡	Simulation	take_map[(0.1, 0.05)]	87 µs	77.4 µs	+12.42%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing ji/scan-v2-1-io (7f2d936) with develop (6eae823)}

Footnotes

1. 12 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩