1use 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 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
98pub 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
111pub 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
137pub(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 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 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
188fn 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 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
258fn 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 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}