Skip to content

Invert layout writers to push API - #9423

Open
gatesn wants to merge 4 commits into
developfrom
ngates/push-layout-writer
Open

Invert layout writers to push API#9423
gatesn wants to merge 4 commits into
developfrom
ngates/push-layout-writer

Conversation

@gatesn

@gatesn gatesn commented Aug 15, 2026

Copy link
Copy Markdown
Contributor

Summary

  • invert the file/layout writer tree to a stateful push API with write, finish, and close
  • drive independent struct and list children concurrently through capacity-one mailboxes
  • retain the existing hierarchical SequenceId protocol so ordered byte sinks remain deterministic while key/value sinks may ignore ordering
  • account for arrays retained by actor mailboxes, buffering/repartition strategies, and spawned compression in buffered_bytes()
  • update the TPC-H writer and CUDA layout strategy to use the push API

Motivation

The previous public push writer fed a SendableArrayStream into a background stream-based strategy tree. This made incremental writing indirect and made strategy composition and buffered-byte ownership harder to follow.

The push inversion keeps one independently driven child per structural field and restores the old sequence identifiers to preserve deterministic on-disk segment ordering. Structural fan-out and finish poll sibling children concurrently, so ordered segment output does not depend on a sibling driver that is not being advanced.

Backpressure matches the previous writer's memory model: the public/root input, every structural child edge, and the segment-buffer sink each have capacity one. A slow VortexWrite fills the segment sink first, then leaf and structural mailboxes, and ultimately makes public Writer::write await. Compression retains its separate, explicitly bounded CPU-concurrency window. Queued and in-flight arrays remain byte-accounted until the receiving writer has processed them.

The stream compatibility adapter also explicitly drops its unused sequence pointer before finishing, preventing it from holding an ordering predecessor indefinitely.

Behavior

  • Writer::bytes_written() reports bytes passed to the underlying VortexWrite.
  • Writer::buffered_bytes() reports logical bytes retained by layout strategies and asynchronous work; it excludes output-sink buffering and allocator/statistics overhead.
  • The writer does not add a separate sink flush layer; custom VortexWrite implementations retain control over sink flushing.

Performance

Release in-memory fixture: 16 numeric columns, 8 chunks, 16K rows/chunk, 16 MiB logical input. Each run used two warmups and ten measured iterations against the latest merged develop; each value below is the median of its ten measured iterations.

Workers develop run medians Push run medians Mean: develop → push Change
1 25.109, 25.258 ms 24.925, 25.018 ms 25.184 → 24.971 ms -0.8%
8 9.009, 7.228 ms 6.877, 6.791 ms 8.118 → 6.834 ms -15.8%

Mean 1-to-8-worker scaling was 3.10x on develop and 3.65x with the push writer.

Validation

  • cargo test -p vortex-layout -p vortex-file
  • cargo check -p vortex-layout -p vortex-file -p vortex-cuda -p vortex-bench
  • cargo clippy --all-targets --all-features
  • cargo +nightly fmt --all
  • git diff --check

The layout tests include mailbox saturation/backpressure, cross-field compression overlap with deterministic segment IDs, buffered-byte accounting for queued and spawned work, nested structural ordering, dictionary codes-before-values, and zone maps after data.

gatesn added 3 commits August 14, 2026 21:31
Signed-off-by: Nicholas Gates <nick@nickgates.com>
Signed-off-by: Nicholas Gates <nick@nickgates.com>
Signed-off-by: Nicholas Gates <nick@nickgates.com>
@gatesn gatesn added the changelog/chore A trivial change label Aug 15, 2026
@codspeed-hq

codspeed-hq Bot commented Aug 15, 2026

Copy link
Copy Markdown

Merging this PR will degrade performance by 6.91%

⚠️ 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 improved benchmark
❌ 2 regressed benchmarks
✅ 2040 untouched benchmarks
⏩ 46 skipped benchmarks1

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Mode Benchmark BASE HEAD Efficiency
Simulation cold_misaligned[(64, 256)] 4.4 ms 5.5 ms -19.86%
Simulation take[small_m/shuffled/primitive/nonnull/chunks=16384/indices=16] 1.1 ms 1.2 ms -11.12%
WallTime words_gather_scalar[65536] 9.4 µs 8.3 µs +13.27%

Tip

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


Comparing ngates/push-layout-writer (2b83616) with develop (b363fb7)

Open in CodSpeed

Footnotes

  1. 46 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.

Signed-off-by: Nicholas Gates <nick@nickgates.com>
@gatesn gatesn added the action/bench-compress Run only the compression benchmark on this PR label Aug 15, 2026
@github-actions github-actions Bot removed the action/bench-compress Run only the compression benchmark on this PR label Aug 15, 2026
@gatesn
gatesn marked this pull request as ready for review August 15, 2026 02:18
@gatesn
gatesn enabled auto-merge (squash) August 15, 2026 02:18
@github-actions

github-actions Bot commented Aug 15, 2026

Copy link
Copy Markdown
Contributor

Polar Signals Profiling Results

Latest Run

Status Commit Job Attempt Link
🟢 Done 2b83616 compress-bench 1 Explore Profiling Data

Powered by Polar Signals Cloud

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

changelog/chore A trivial change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant