Skip to main content

vortex_array/scalar_fn/unstable/row/
vtable.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Adapts [`RowFn`] implementations to the scalar-function interface.
5//!
6//! The blanket [`ScalarFnVTable`] implementation supplies common arity, validity, fallibility, and
7//! execution behavior. The visitor layer validates and executes the concrete signature selected by
8//! dispatch. [`row_fn_return_dtype`] and [`execute_rows`] expose the same paths to public vtables
9//! that delegate to a private row kernel.
10
11use smallvec::SmallVec;
12use vortex_error::VortexResult;
13use vortex_error::vortex_ensure_eq;
14use vortex_mask::MaskValuesRef;
15use vortex_session::VortexSession;
16
17use super::batch::ArrayInputs;
18use super::batch::BatchProbe;
19use super::batch::BorrowedRowFnArgs;
20use super::batch::RowInputs;
21use super::batch::finalize_kernel_output;
22use super::row_fn::RowFn;
23use super::visitor::BatchPlanner;
24use super::visitor::ExecuteDenseWithRetry;
25use super::visitor::ExecuteFilteredRows;
26use super::visitor::ExecuteFused;
27use super::visitor::ExecuteRows;
28use super::visitor::ExecuteValidRows;
29use super::visitor::Fused;
30use crate::ArrayRef;
31use crate::ExecutionCtx;
32use crate::dtype::DType;
33use crate::scalar_fn::Arity;
34use crate::scalar_fn::ChildName;
35use crate::scalar_fn::ExecutionArgs;
36use crate::scalar_fn::ReduceNode;
37use crate::scalar_fn::ReduceNodeValidity;
38use crate::scalar_fn::ScalarFnId;
39use crate::scalar_fn::ScalarFnVTable;
40use crate::scalar_fn::union_child_validities;
41use crate::scalar_fn::unstable::row::execute::DenseAttempt;
42
43impl<F: RowFn> ScalarFnVTable for F {
44    type Options = F::Options;
45
46    fn id(&self) -> ScalarFnId {
47        RowFn::id(self)
48    }
49
50    fn serialize(&self, options: &Self::Options) -> VortexResult<Option<Vec<u8>>> {
51        RowFn::serialize(self, options)
52    }
53
54    fn deserialize(&self, metadata: &[u8], session: &VortexSession) -> VortexResult<Self::Options> {
55        RowFn::deserialize(self, metadata, session)
56    }
57
58    fn arity(&self, _options: &Self::Options) -> Arity {
59        Arity::Exact(F::ARG_NAMES.len())
60    }
61
62    fn child_name(&self, _options: &Self::Options, child_index: usize) -> ChildName {
63        ChildName::from(F::ARG_NAMES[child_index])
64    }
65
66    fn return_dtype(&self, options: &Self::Options, args: &[DType]) -> VortexResult<DType> {
67        row_fn_return_dtype(self, options, args)
68    }
69
70    fn execute(
71        &self,
72        options: &Self::Options,
73        args: &dyn ExecutionArgs,
74        ctx: &mut ExecutionCtx,
75    ) -> VortexResult<ArrayRef> {
76        execute_rows(self, options, args, ctx)
77    }
78
79    fn validity<T: ReduceNode>(
80        &self,
81        _options: &Self::Options,
82        node: &T,
83    ) -> VortexResult<ReduceNodeValidity<T>> {
84        Ok(ReduceNodeValidity::Reduced(union_child_validities(node)?))
85    }
86
87    // `RowFn` is stricter than `ScalarFnVTable::is_strict`: its kernel cannot produce null from
88    // valid inputs, so batch execution derives output validity only from input validity.
89    fn is_strict(&self, _options: &Self::Options) -> bool {
90        true
91    }
92
93    fn is_infallible(&self, _options: &Self::Options) -> bool {
94        F::INFALLIBLE
95    }
96}
97
98/// Compute the return dtype of a [`RowFn`] kernel without invoking its blanket vtable.
99pub fn row_fn_return_dtype<F: RowFn>(
100    function: &F,
101    options: &F::Options,
102    args: &[DType],
103) -> VortexResult<DType> {
104    ensure_arity(function, args.len())?;
105
106    let plan = function.dispatch(options, args, BatchPlanner::<F>::new(args))?;
107
108    Ok(plan.result_dtype(args))
109}
110
111/// Execute a [`RowFn`] without using its blanket [`ScalarFnVTable`] implementation.
112///
113/// A type cannot implement both [`RowFn`] and [`ScalarFnVTable`] because every `RowFn` receives the
114/// standard vtable automatically. Existing vtables can keep their custom hooks on one type and
115/// delegate row execution to a private `RowFn` kernel through this function.
116///
117/// Nullary functions execute for `args.row_count()` rows without batch validity handling because
118/// they have no input validity to propagate.
119pub fn execute_rows<F: RowFn>(
120    function: &F,
121    options: &F::Options,
122    args: &dyn ExecutionArgs,
123    ctx: &mut ExecutionCtx,
124) -> VortexResult<ArrayRef> {
125    let arrays = (0..args.num_inputs())
126        .map(|index| args.get(index))
127        .collect::<VortexResult<SmallVec<[ArrayRef; 4]>>>()?;
128
129    execute_row_inputs(
130        function,
131        options,
132        &ArrayInputs::new(&arrays, args.row_count()),
133        ctx,
134    )
135}
136
137/// Execute a row function over borrowed input columns.
138///
139/// Callers that already hold their operands avoid collecting another owned argument list.
140/// Batch inspection validates the lengths before planning or decoding the inputs.
141pub(crate) fn execute_row_inputs<F: RowFn, I: RowInputs + ?Sized>(
142    function: &F,
143    options: &F::Options,
144    inputs: &I,
145    ctx: &mut ExecutionCtx,
146) -> VortexResult<ArrayRef> {
147    ensure_arity(function, inputs.num_inputs())?;
148
149    if inputs.num_inputs() == 0 {
150        return execute_nullary_rows(function, options, inputs.row_count(), ctx);
151    }
152
153    // Classify every input before decoding any, so a null literal in any position skips all
154    // decoding, including an earlier input whose decode could fail or copy from a device.
155    let probe = BatchProbe::new(|| RowFn::id(function), inputs)?;
156    let collected: SmallVec<[DType; 4]>;
157    let arg_dtypes = match inputs.dtypes() {
158        Some(dtypes) => dtypes,
159        None => {
160            collected = (0..inputs.num_inputs())
161                .map(|index| inputs.input(index).dtype().clone())
162                .collect();
163            &collected
164        }
165    };
166
167    // Plan and execute in one dispatch, which `visitor::fused` explains. Only a batch that needs a
168    // dense retry or valid-row execution dispatches again.
169    let batch = match function.dispatch(
170        options,
171        arg_dtypes,
172        ExecuteFused::<F, I>::new(function, inputs, probe, arg_dtypes, ctx),
173    )? {
174        Fused::Done(values) => return Ok(values),
175        Fused::Partial(batch) => batch,
176    };
177
178    batch.execute(
179        arg_dtypes,
180        |args, ctx| execute_row_kernel(function, options, args, ctx),
181        |args, ctx| execute_dense_attempt(function, options, args, ctx),
182        |args, valid, ctx| try_execute_valid_rows(function, options, args, valid, ctx),
183        |args, valid, ctx| execute_filtered_rows(function, options, args, valid, ctx),
184        ctx,
185    )
186}
187
188/// Execute a nullary kernel without batch validity or constant handling.
189fn execute_nullary_rows<F: RowFn>(
190    function: &F,
191    options: &F::Options,
192    row_count: usize,
193    ctx: &mut ExecutionCtx,
194) -> VortexResult<ArrayRef> {
195    let plan = function.dispatch(options, &[], BatchPlanner::<F>::new(&[]))?;
196    let result_dtype = plan.result_dtype(&[]);
197    let args = BorrowedRowFnArgs::new(&[], row_count, &[], &plan);
198
199    // A nullary function has no input validity to propagate, so its kernel output is the finished
200    // column and this path labels it directly.
201    let values = plan.relabel_output(execute_row_kernel(function, options, args, ctx)?)?;
202
203    finalize_kernel_output(RowFn::id(function), &result_dtype, row_count, values, ctx)
204}
205
206fn ensure_arity<F: RowFn>(function: &F, actual: usize) -> VortexResult<()> {
207    let expected = F::ARG_NAMES.len();
208    vortex_ensure_eq!(
209        actual,
210        expected,
211        "row function {} has the wrong arity",
212        RowFn::id(function),
213    );
214
215    Ok(())
216}
217
218fn execute_row_kernel<F: RowFn>(
219    function: &F,
220    options: &F::Options,
221    args: BorrowedRowFnArgs<'_>,
222    ctx: &mut ExecutionCtx,
223) -> VortexResult<ArrayRef> {
224    function.dispatch(
225        options,
226        args.dtypes(),
227        ExecuteRows::<F>::new(&args, args.dtypes(), args.plan(), ctx),
228    )
229}
230
231fn execute_dense_attempt<F: RowFn>(
232    function: &F,
233    options: &F::Options,
234    args: BorrowedRowFnArgs<'_>,
235    ctx: &mut ExecutionCtx,
236) -> VortexResult<DenseAttempt> {
237    function.dispatch(
238        options,
239        args.dtypes(),
240        ExecuteDenseWithRetry::<F>::new(&args, ctx),
241    )
242}
243
244fn try_execute_valid_rows<F: RowFn>(
245    function: &F,
246    options: &F::Options,
247    args: BorrowedRowFnArgs<'_>,
248    valid: MaskValuesRef,
249    ctx: &mut ExecutionCtx,
250) -> VortexResult<Option<ArrayRef>> {
251    function.dispatch(
252        options,
253        args.dtypes(),
254        ExecuteValidRows::<F>::new(&args, args.dtypes(), args.plan(), valid, ctx),
255    )
256}
257
258/// Execute valid rows over `args` filtered to the valid row domain of `valid`.
259fn execute_filtered_rows<F: RowFn>(
260    function: &F,
261    options: &F::Options,
262    args: BorrowedRowFnArgs<'_>,
263    valid: MaskValuesRef,
264    ctx: &mut ExecutionCtx,
265) -> VortexResult<ArrayRef> {
266    function.dispatch(
267        options,
268        args.dtypes(),
269        ExecuteFilteredRows::<F>::new(&args, args.dtypes(), args.plan(), valid, ctx),
270    )
271}
272
273#[cfg(test)]
274mod tests {
275    use std::sync::Arc;
276    use std::sync::LazyLock;
277    use std::sync::atomic::AtomicUsize;
278    use std::sync::atomic::Ordering;
279
280    use rstest::rstest;
281    use vortex_error::VortexError;
282    use vortex_error::VortexResult;
283    use vortex_session::VortexSession;
284    use vortex_session::registry::CachedId;
285
286    use super::execute_rows;
287    use super::row_fn_return_dtype;
288    use crate::IntoArray;
289    use crate::VortexSessionExecute;
290    use crate::arrays::PrimitiveArray;
291    use crate::assert_arrays_eq;
292    use crate::dtype::DType;
293    use crate::scalar_fn::EmptyOptions;
294    use crate::scalar_fn::ScalarFnId;
295    use crate::scalar_fn::VecExecutionArgs;
296    use crate::scalar_fn::unstable::row::RowFn;
297    use crate::scalar_fn::unstable::row::RowVisitor;
298    use crate::validity::Validity;
299
300    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
301
302    #[derive(Clone)]
303    struct IndexingRowFn;
304
305    #[derive(Clone)]
306    struct NullarySeven;
307
308    #[derive(Clone)]
309    struct ChangingDispatchRowFn {
310        dispatches: Arc<AtomicUsize>,
311        change: DispatchChange,
312    }
313
314    #[derive(Clone, Copy)]
315    enum DispatchChange {
316        Policy,
317        Element,
318    }
319
320    impl RowFn for NullarySeven {
321        type Options = EmptyOptions;
322
323        const ARG_NAMES: &'static [&'static str] = &[];
324        const INFALLIBLE: bool = true;
325
326        fn id(&self) -> ScalarFnId {
327            static ID: CachedId = CachedId::new("test.nullary_seven");
328            *ID
329        }
330
331        fn dispatch<V: RowVisitor>(
332            &self,
333            _options: &Self::Options,
334            _args: &[DType],
335            visitor: V,
336        ) -> VortexResult<V::VisitResult> {
337            visitor.visit::<(), i64>(|()| 7)
338        }
339    }
340
341    impl RowFn for IndexingRowFn {
342        type Options = EmptyOptions;
343
344        const ARG_NAMES: &'static [&'static str] = &["value"];
345
346        const INFALLIBLE: bool = true;
347
348        fn id(&self) -> ScalarFnId {
349            static ID: CachedId = CachedId::new("test.indexing_row_fn");
350            *ID
351        }
352
353        fn dispatch<V: RowVisitor>(
354            &self,
355            _options: &Self::Options,
356            args: &[DType],
357            visitor: V,
358        ) -> VortexResult<V::VisitResult> {
359            _ = &args[0];
360
361            visitor.visit::<(i64,), i64>(|(value,)| value)
362        }
363    }
364
365    impl RowFn for ChangingDispatchRowFn {
366        type Options = EmptyOptions;
367
368        const ARG_NAMES: &'static [&'static str] = &["value"];
369        const INFALLIBLE: bool = false;
370
371        fn id(&self) -> ScalarFnId {
372            static ID: CachedId = CachedId::new("test.changing_dispatch_row_fn");
373            *ID
374        }
375
376        fn dispatch<V: RowVisitor>(
377            &self,
378            _options: &Self::Options,
379            _args: &[DType],
380            visitor: V,
381        ) -> VortexResult<V::VisitResult> {
382            // Select `DenseWithRetry` first, so a partially valid batch dispatches again for its
383            // dense attempt, and then change the policy or element type on that second dispatch.
384            if self.dispatches.fetch_add(1, Ordering::Relaxed) == 0 {
385                visitor.visit_deferred::<(i64,), i64, bool>(|(value,)| (value, false), |_| Ok(()))
386            } else {
387                match self.change {
388                    DispatchChange::Policy => visitor.visit::<(i64,), i64>(|(value,)| value),
389                    DispatchChange::Element => visitor
390                        .visit_deferred::<(u64,), u64, bool>(|(value,)| (value, false), |_| Ok(())),
391                }
392            }
393        }
394    }
395
396    #[test]
397    fn test_return_dtype_rejects_wrong_arity_before_dispatch() {
398        let error = row_fn_return_dtype(&IndexingRowFn, &EmptyOptions, &[])
399            .expect_err("wrong arity must fail before dispatch");
400
401        assert_arity_error(error);
402    }
403
404    #[test]
405    fn test_execute_rejects_wrong_arity_before_dispatch() {
406        let args = VecExecutionArgs::new(vec![], 0);
407        let mut ctx = SESSION.create_execution_ctx();
408        let error = execute_rows(&IndexingRowFn, &EmptyOptions, &args, &mut ctx)
409            .expect_err("wrong arity must fail before dispatch");
410
411        assert_arity_error(error);
412    }
413
414    #[rstest]
415    #[case::empty(0)]
416    #[case::nonempty(3)]
417    fn test_execute_nullary_rows(#[case] row_count: usize) -> VortexResult<()> {
418        let args = VecExecutionArgs::new(vec![], row_count);
419        let mut ctx = SESSION.create_execution_ctx();
420
421        let actual = execute_rows(&NullarySeven, &EmptyOptions, &args, &mut ctx)?;
422        let expected = PrimitiveArray::from_iter(vec![7_i64; row_count]).into_array();
423
424        assert_arrays_eq!(&actual, &expected, &mut ctx);
425        Ok(())
426    }
427
428    #[test]
429    fn test_execute_dispatches_once_without_retry() -> VortexResult<()> {
430        let dispatches = Arc::new(AtomicUsize::new(0));
431        let function = ChangingDispatchRowFn {
432            dispatches: Arc::clone(&dispatches),
433            change: DispatchChange::Policy,
434        };
435        let input = PrimitiveArray::new(vec![1_i64, 2], Validity::NonNullable).into_array();
436        let args = VecExecutionArgs::new(vec![input.clone()], 2);
437        let mut ctx = SESSION.create_execution_ctx();
438
439        let actual = execute_rows(&function, &EmptyOptions, &args, &mut ctx)?;
440
441        assert_eq!(dispatches.load(Ordering::Relaxed), 1);
442        assert_arrays_eq!(&actual, &input, &mut ctx);
443        Ok(())
444    }
445
446    #[test]
447    fn test_execute_rejects_dispatch_that_changes_after_planning() -> VortexResult<()> {
448        let function = ChangingDispatchRowFn {
449            dispatches: Arc::new(AtomicUsize::new(0)),
450            change: DispatchChange::Policy,
451        };
452        let validity = Validity::from_iter([true, false]);
453        let input = PrimitiveArray::new(vec![1_i64, 2], validity).into_array();
454        let args = VecExecutionArgs::new(vec![input], 2);
455        let mut ctx = SESSION.create_execution_ctx();
456
457        let error = match execute_rows(&function, &EmptyOptions, &args, &mut ctx) {
458            Err(error) => error,
459            Ok(_) => {
460                vortex_error::vortex_bail!("dispatch must not change after planning")
461            }
462        };
463        let message = error.to_string();
464
465        assert!(
466            message.contains("row dispatch must select the planned nullable execution policy"),
467            "unexpected error: {error}",
468        );
469        assert!(
470            message.contains("planned DenseWithRetry, got Dense"),
471            "unexpected error: {error}",
472        );
473        Ok(())
474    }
475
476    #[test]
477    fn test_execute_revalidates_element_types_after_planning() -> VortexResult<()> {
478        let function = ChangingDispatchRowFn {
479            dispatches: Arc::new(AtomicUsize::new(0)),
480            change: DispatchChange::Element,
481        };
482        let validity = Validity::from_iter([true, false]);
483        let input = PrimitiveArray::new(vec![1_i64, 2], validity).into_array();
484        let args = VecExecutionArgs::new(vec![input], 2);
485        let mut ctx = SESSION.create_execution_ctx();
486
487        let error = match execute_rows(&function, &EmptyOptions, &args, &mut ctx) {
488            Err(error) => error,
489            Ok(_) => {
490                vortex_error::vortex_bail!("dispatch must preserve its planned element types")
491            }
492        };
493
494        assert!(
495            error
496                .to_string()
497                .contains("row input column has the wrong ptype"),
498            "unexpected error: {error}",
499        );
500        Ok(())
501    }
502
503    #[track_caller]
504    fn assert_arity_error(error: VortexError) {
505        assert!(
506            error.to_string().contains("has the wrong arity"),
507            "unexpected error: {error}",
508        );
509    }
510}