Skip to content

Commit 45b918d

Browse files
committed
Apply the RowFn review: trim the API, sharpen the contracts
A review pass over the row scalar-function framework in three parts. Every surviving change is codegen-neutral: the emitted IR of every `visit_prepared_into` monomorph, profiled by vector width, reduction count, overflow-intrinsic survival and bounds checks, is identical to the parent commit. API: - Delete `decode_null_tolerant` overrides that only restated the default, from the primitive, bool and `TensorRow` elements. `GeometryRow`'s is the only real one. The doc now says a dense-safe element should not override. - Delete the nullary path (`ElementTuple for ()` and the `num_inputs() == 0` branch). With no inputs there is no validity to propagate, which is the whole of what the lifting does, so such a function belongs on `ScalarFnVTable`. - Replace `OutputSink::row_count_matches(rows, n) -> bool` with `rows_len(rows) -> usize`. The executor compares it against the batch row count, which gives the optimizer the same bound and lets the error report the length it actually found. `SpreadSink`'s width invariant, the one use of the extra expressiveness, moves to `rows()` where it belongs. - Give `reduce_encoded` an explicit `row_count`. The required length is the filtered count under filter-and-scatter, which was prose discoverable only on a mixed validity mask, and is now in the signature. - Record on `ElementTuple` why it carries arities past the widest function in tree: it is sealed, so a downstream crate cannot add the one it needs, and an uninstantiated arity costs only its own macro expansion. Execution: - Share `resolve_validity` between `execute_filtered` and the forced-strategy test seam so the mask shortcuts cannot drift apart between them. - Correct the dense-retry comment. It filters unconditionally because `execute_dense` is not handed the `branch` closure, not because a deferred sink cannot skip rows: `ERRORS_ARE_DEFERRED` and `SUPPORTS_SKIPPED_ROWS` are independent consts. - Pin the two `reduce_encoded` probes and their row counts with a test. The first sees the original arrays at full length and is the only one that does; the second sees filtered copies at the surviving count. Implementations: - Keep one `l2_norm_row`. Cosine's prepared and per-row arms must agree bit for bit, which holds only while both accumulate in the same order, so a second copy was an invitation to break the property its comments defend. - Zip the cosine `reduce_encoded` loops instead of indexing three slices per row, and record why it materializes where `InnerProduct` stays lazy. - Collapse the checked-arithmetic macros so each predicate is written once: `impl_checked_integer!` owns the shape, and the unsigned and signed wrappers own their add/sub/div. Only `mul_failure` varies per width, and only signed 64-bit needs to spell its own. Delete `CheckedArithmetic::mul_error`, which had no caller left once `CheckedMul` reported through `mul_failure`. - Cover every container variant of geo's `contains_route` against plain `a.contains(b)` in all four constant arrangements. The existing agreement grid goes through real arrays but only covers four of the ten container types, so a geo release that moved a row would leave it green. - Correct `scalar_fn`'s trait-choice doc, which listed `vortex.byte_length` as a `RowFn` when it is a `ScalarFnVTable`, and add it as the worked example of row-determined being necessary but not sufficient. Two changes were made, reviewed and reverted; `SCALAR_FN_HANDOFF.md` records both so they are not retried. Making `CheckedSink` safe with `BufferMut::zeroed` measured 1.65 to 1.71x slower than the `MaybeUninit` storage it replaced, because `alloc_zeroed` does not avoid the write pass the row loop then duplicates. Hoisting `SUPPORTS_SKIPPED_ROWS` into the plan, which #9130 records as a follow-up, is not sound: the branch path probes `reduce_encoded` against the original arrays before it consults the sink, and that is the only probe that sees them still encoded. Verification: 3318 vortex-array, 179 vortex-tensor and 241 vortex-geo tests, 72 doctests, clippy over the three crates with `--all-targets --all-features`, nightly fmt, and `git diff --check`. Signed-off-by: "Connor Tsui" <[email protected]> Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_014mwiAahcxc5xBfTrhDK11L
1 parent f430847 commit 45b918d

25 files changed

Lines changed: 595 additions & 425 deletions

File tree

‎Cargo.toml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,10 @@ flatbuffers = "25.2.10"
160160
fsst-rs = "0.6.0"
161161
futures = { version = "0.3.31", default-features = false }
162162
fuzzy-matcher = "0.3"
163+
# `vortex-geo`'s `contains_route` transcribes geo's `impl_contains_from_relate!` dispatch table, so
164+
# any bump that moves a row silently changes containment verdicts. This requirement admits 0.31.x,
165+
# which `cargo update` takes without a diff here, so the lockfile is as load-bearing as this line;
166+
# see `vortex-geo/src/scalar_fn/contains.rs`.
163167
geo = "0.31.0"
164168
geo-traits = "0.3.0"
165169
geo-types = "0.7.19"

‎SCALAR_FN_HANDOFF.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -278,6 +278,125 @@ The checks recorded for the final API state are:
278278
The generated-code comparison and native timing evidence are described above and in the final
279279
section of `STRICT_SCALAR_FN_RESEARCH.md`.
280280

281+
## Review pass: what changed and what was deliberately left
282+
283+
A review of the three parts (API, execution, implementations) produced the following changes. They
284+
are simplifications and sharp-edge fixes, not a redesign; no execution semantics changed.
285+
286+
API:
287+
288+
- `InputElement::decode_null_tolerant` overrides that only restated the default were deleted from
289+
the primitive, bool and `TensorRow` elements. `GeometryRow`'s override is the only real one. The
290+
doc now says a dense-safe element should *not* override.
291+
- The nullary path is gone: `ElementTuple for ()` and the `num_inputs() == 0` branch in the blanket
292+
`execute`. A function with no inputs has no validity to propagate, which is the whole of what the
293+
lifting does, so it belongs on `ScalarFnVTable`. A `RowFn` declaring no arguments now fails the
294+
dispatch arity assertion at compile time.
295+
- `ElementTuple` keeps its arities through twelve, and now says why. Trimming to four (the widest
296+
in tree) was tried and reverted: the trait is sealed, so a downstream crate cannot add the arity
297+
it needs, and an uninstantiated arity costs only its own macro expansion. That is capability
298+
removed for no saving.
299+
- `OutputSink::row_count_matches(rows, n) -> bool` became `rows_len(rows) -> usize`. The executor
300+
compares it against the batch row count, which gives the optimizer the same bound and lets the
301+
error report the actual length. The one sink that used the extra expressiveness (`SpreadSink`'s
302+
width invariant) asserts it in `rows()`, where it belongs.
303+
- `RowFn::reduce_encoded` takes `row_count` explicitly. It was the most dangerous prose in the API:
304+
the required length is the *filtered* count under filter-and-scatter, discoverable only on a mixed
305+
mask. It is now in the signature.
306+
307+
Execution:
308+
309+
- `execute_filtered` and the forced-strategy test seam now share `resolve_validity`, so the mask
310+
materialization and the all-true/all-false shortcuts cannot drift apart between them.
311+
- The dense-retry path documents why it filters unconditionally instead of consulting
312+
`branch_beats_filter`: only a deferred-error dispatch reaches it, and such a sink declines skipped
313+
rows, so branch-and-skip is unavailable whatever the mask says.
314+
315+
Implementations:
316+
317+
- `l2_norm_row` had two copies, in `l2_norm.rs` and `cosine_similarity.rs`. Cosine's prepared and
318+
per-row arms must agree bit for bit, which only holds while both accumulate in the same order, so
319+
the duplicate was an invitation to break exactly the property the comments defend. One copy now
320+
lives in `scalar_fns/row.rs`.
321+
- `CosineSimilarity::reduce_encoded` zips its three slices instead of indexing `0..len` three times
322+
per row, and documents why it materializes where `InnerProduct::reduce_encoded` stays lazy (the
323+
zero-norm guard is a conditional, not an arithmetic factor).
324+
- The checked-arithmetic macros collapsed from four near-identical bodies into one
325+
`impl_checked_integer!` parameterized by the error tests and the `mul_failure` form, which is the
326+
only thing that genuinely varies. `CheckedArithmetic::mul_error` was deleted: `CheckedMul` reports
327+
through `mul_failure`, and after the collapse nothing called the boolean form.
328+
- `contains_route` and the workspace `geo` dependency both record that the table transcribes geo's
329+
`impl_contains_from_relate!` and must be re-verified on a version bump. `geo = "0.31.0"` admits
330+
patches but not `0.32`, so the coupling can only break deliberately.
331+
332+
Deliberately **not** done:
333+
334+
- **No `DeferredElementSink`.** `CheckedSink` exists largely because `ElementSink` cannot name an
335+
error at `finish`. A framework sink combining an element output with a type-level message would
336+
remove ~100 lines per function, but there is exactly one deferred-error function. Build it when a
337+
second appears, rather than copying `CheckedSink`.
338+
- **No change to `reduce_encoded`'s probe semantics.** Hoisting the probe out of the strategy paths
339+
and masking a full-length result looks like a simplification and is not one:
340+
`normalized_readthrough_survives_null_rows` pins that a filtered input is no longer `Normalized`,
341+
so which arrays reach `reduce_encoded` is load-bearing and differs per strategy.
342+
- **No PR split.** Recommended landing order, each step individually revertible and separately
343+
benchmarkable: (1) API + lifting with dense/filter only; (2) branch-and-skip + adaptive selection
344+
+ its benchmarks; (3) `NumericBinary`; (4) tensor; (5) geo. The seam already supports this split
345+
and no API changes between steps.
346+
347+
### Two changes this pass made and then reverted
348+
349+
Both were proposed, implemented, reviewed, and backed out on evidence. They are recorded because
350+
each is an attractive idea that a later reader will have again.
351+
352+
**Making `CheckedSink` safe with `BufferMut::zeroed` costs 1.65 to 1.71x.** Replacing the
353+
`MaybeUninit` storage removes an `unsafe set_len` and reads as a clear win, and `ElementSink`'s own
354+
comment appears to bless it by routing a zeroable placeholder to `alloc_zeroed`. Measured, it is
355+
not: allocate-zeroed-then-fill against allocate-then-fill, interleaved in one process over `u64`
356+
outputs, ran **1.221x** slower at 8 KiB, **1.71x** at 64 KiB, **1.66x** at 512 KiB and **1.71x** at
357+
2 MiB, stable to within 2% across two runs. `alloc_zeroed` does not avoid the write: below glibc's
358+
mmap threshold `calloc` recycles a dirty chunk and memsets it, and above it every fresh page faults
359+
on first touch. The row loop overwrites every slot regardless, so this is a duplicated pass over
360+
the output of the hottest kernel in the system.
361+
362+
Note the corollary, which is a real optimization nobody has taken: `ElementSink::with_capacity`
363+
pays exactly this on every batch, and only branch-and-skip ever reads a placeholder back. A sink
364+
that allocated uninitialized on the dense and filter paths would recover it.
365+
366+
**Hoisting `OutputSink::SUPPORTS_SKIPPED_ROWS` into the plan is not sound as an optimization.**
367+
#9130 records "avoid probing `reduce_encoded` twice when branch execution is unsupported" as a
368+
follow-up. It reads as free, and is not, because the branch path probes `reduce_encoded` against
369+
the _original_ arrays before it consults the sink, and that is the only probe that ever sees them
370+
still encoded. Skipping the path early leaves such a function with only the filtered probe, whose
371+
canonical arrays match no encoding fast path. For a function whose reduction is _defined_ to answer
372+
differently from its row loop, which is exactly what `L2Norm` over `Normalized` is, that is a wrong
373+
answer rather than a slow one. Nothing in tree is reachable today only because every `ValidOnly`
374+
dispatch happens to use `ElementSink`. **#9130's follow-up should be struck, not implemented.**
375+
`reduce_encoded_row_count_follows_the_arrays_it_is_given` now pins the two probes and their row
376+
counts.
377+
378+
### On measurement, and what the IR gate does and does not cover
379+
380+
Wall-clock benchmarking of the row loops was attempted first and abandoned on evidence. Two runs of
381+
the *same* baseline binary, pinned with `taskset -c 2`, 100 samples, disagreed by up to 4x
382+
(`row_wrapping_add_nullable`: 198.8 us then 52.9 us median; `specialized_checked_add`: 185.5 us then
383+
34.4 us). The 4-vCPU shared VM drifts more within a session than any effect being measured, which is
384+
the same conclusion this branch already reached on a dedicated 7950X.
385+
386+
The gate used instead is the emitted optimized IR of every `visit_prepared_into` monomorph in
387+
`vortex-array`, profiled by vector width, reduction count, overflow-intrinsic survival and bounds
388+
checks, then compared as a multiset before and after. Reproduce with:
389+
390+
```bash
391+
RUSTFLAGS="--emit=llvm-ir -C codegen-units=1" cargo rustc -p vortex-array --release --lib
392+
```
393+
394+
**Its blind spot is worth stating, because it nearly landed a regression.** The IR of a row loop
395+
cannot show an allocator call outside it, so the `BufferMut::zeroed` substitution above passed this
396+
gate cleanly while costing 1.7x. An allocation-strategy change needs its own targeted A/B, which is
397+
cheap to write and immune to the host drift above because both arms run interleaved in one process.
398+
Use the IR gate for loop shape and a focused microbenchmark for anything the loop does not contain.
399+
281400
## Remaining boundaries
282401

283402
- Complete the required x86 production and forced-null-strategy benchmark run above before treating

‎vortex-array/benches/row_fn_executor.rs‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -120,8 +120,8 @@ impl OutputSink for CheckedAddSink {
120120
}
121121
}
122122

123-
fn row_count_matches(rows: &Self::Rows<'_>, row_count: usize) -> bool {
124-
rows.values.len() == row_count
123+
fn rows_len(rows: &Self::Rows<'_>) -> usize {
124+
rows.values.len()
125125
}
126126

127127
fn row<'a>(rows: &'a mut Self::Rows<'_>, index: usize) -> Self::Row<'a> {
@@ -184,8 +184,8 @@ impl OutputSink for I64Sink {
184184
self.0.as_mut_slice()
185185
}
186186

187-
fn row_count_matches(rows: &Self::Rows<'_>, row_count: usize) -> bool {
188-
rows.len() == row_count
187+
fn rows_len(rows: &Self::Rows<'_>) -> usize {
188+
rows.len()
189189
}
190190

191191
fn row<'a>(rows: &'a mut Self::Rows<'_>, index: usize) -> Self::Row<'a> {

‎vortex-array/benches/strict_validity.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,7 @@ impl RowFn for LazyDouble {
102102
&self,
103103
_options: &Self::Options,
104104
args: &[ArrayRef],
105+
_row_count: usize,
105106
ctx: &mut ExecutionCtx,
106107
) -> VortexResult<Option<ArrayRef>> {
107108
doubled(&args[0], ctx).map(Some)

0 commit comments

Comments
 (0)