From 2322eea54874c9a70e92546157564dca6000db54 Mon Sep 17 00:00:00 2001 From: Nicholas Gates Date: Fri, 20 Nov 2026 16:46:29 -0500 Subject: [PATCH 1/2] Move RowLimit and limit_rows into vortex-scan Scans in vortex-scan need the row budget that layout scans share, so the budget and the stream adapter that trims to it move down a crate and vortex-layout uses them from there. Signed-off-by: Nicholas Gates Co-Authored-By: Claude Fable 5.2 --- vortex-layout/src/scan/limit.rs | 123 +---------------- vortex-layout/src/scan/repeated_scan.rs | 41 +----- vortex-scan/src/lib.rs | 1 + vortex-scan/src/limit.rs | 173 ++++++++++++++++++++++++ 4 files changed, 177 insertions(+), 161 deletions(-) create mode 100644 vortex-scan/src/limit.rs diff --git a/vortex-layout/src/scan/limit.rs b/vortex-layout/src/scan/limit.rs index e7791e5961f..42e69a54a56 100644 --- a/vortex-layout/src/scan/limit.rs +++ b/vortex-layout/src/scan/limit.rs @@ -1,22 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 // SPDX-FileCopyrightText: Copyright the Vortex contributors -use std::sync::Arc; -use std::sync::atomic::AtomicU64; -use std::sync::atomic::Ordering; - -use vortex_error::VortexExpect; -use vortex_mask::Mask; - -/// A cloneable row budget shared by all work that can contribute rows to one scan. -/// -/// Filterless scans reserve each split's selected rows before constructing its projection, so -/// rows past the limit are never decoded. Filtered scans cannot know a split's row count up front, -/// so they take rows from the budget as arrays are emitted and discard the excess. Either way, -/// the order in which rows are taken decides which rows are returned: an ordered scan takes them -/// in split order, an unordered one in completion order. -#[derive(Clone)] -pub(crate) struct RowLimit(Arc); +pub(crate) use vortex_scan::limit::RowLimit; /// The row limit of a scan. #[derive(Clone)] @@ -36,109 +21,3 @@ impl ScanLimit { } } } - -impl RowLimit { - pub(crate) fn new(limit: u64) -> Self { - Self(Arc::new(AtomicU64::new(limit))) - } - - /// Reserve rows selected by `mask` and retain only the earliest granted rows in that mask. - pub(crate) fn limit(&self, mask: Mask) -> Mask { - let granted = self.take(mask.true_count()); - mask.limit(granted) - } - - /// Reserve up to `rows` rows, returning how many the remaining budget granted. - pub(crate) fn take(&self, rows: usize) -> usize { - let requested = u64::try_from(rows).unwrap_or(u64::MAX); - usize::try_from(self.reserve(requested)).unwrap_or(usize::MAX) - } - - pub(crate) fn is_exhausted(&self) -> bool { - self.0.load(Ordering::Relaxed) == 0 - } - - fn reserve(&self, requested: u64) -> u64 { - let remaining = self - .0 - .try_update(Ordering::Relaxed, Ordering::Relaxed, |remaining| { - Some(remaining.saturating_sub(requested)) - }) - .ok() - .vortex_expect("row reservation always updates the budget"); - remaining.min(requested) - } -} - -#[cfg(test)] -mod tests { - use std::sync::Arc; - use std::sync::Barrier; - use std::sync::atomic::AtomicU64; - use std::sync::atomic::Ordering; - use std::thread; - - use vortex_mask::Mask; - - use super::RowLimit; - - #[test] - fn reserve_grants_up_to_the_remaining_budget() { - let limit = RowLimit::new(5); - assert_eq!(limit.reserve(3), 3); - assert!(!limit.is_exhausted()); - // Only two rows remain, so a larger request saturates at what is left. - assert_eq!(limit.reserve(10), 2); - assert!(limit.is_exhausted()); - // Once exhausted, further requests grant nothing. - assert_eq!(limit.reserve(1), 0); - } - - #[test] - fn limit_keeps_the_earliest_granted_rows() { - let limit = RowLimit::new(2); - // Rows 0, 2, 3, 5 are selected; only the first two survive the budget of 2. - let mask = Mask::from_iter([true, false, true, true, false, true]); - let limited = limit.limit(mask); - - assert_eq!(limited.true_count(), 2); - assert!(limited.value(0)); - assert!(limited.value(2)); - assert!(!limited.value(3)); - assert!(!limited.value(5)); - assert!(limit.is_exhausted()); - } - - #[test] - fn concurrent_reservations_never_exceed_the_budget() { - const THREADS: usize = 8; - const PER_THREAD: u64 = 10_000; - const LIMIT: u64 = 25_000; - - let limit = RowLimit::new(LIMIT); - let granted_total = Arc::new(AtomicU64::new(0)); - let barrier = Arc::new(Barrier::new(THREADS)); - - thread::scope(|scope| { - for _ in 0..THREADS { - let limit = limit.clone(); - let granted_total = Arc::clone(&granted_total); - let barrier = Arc::clone(&barrier); - scope.spawn(move || { - // Start all threads together to maximize contention on the atomic. - barrier.wait(); - let mut local = 0; - for _ in 0..PER_THREAD { - local += limit.reserve(1); - } - granted_total.fetch_add(local, Ordering::Relaxed); - }); - } - }); - - // Total requested (THREADS * PER_THREAD = 80_000) exceeds the budget, so exactly the - // budget is granted across all threads — no double-grant, over-grant, or lost reservation. - assert_eq!(granted_total.load(Ordering::Relaxed), LIMIT); - assert!(limit.is_exhausted()); - } -} diff --git a/vortex-layout/src/scan/repeated_scan.rs b/vortex-layout/src/scan/repeated_scan.rs index 1a950fec418..2d82f283dc4 100644 --- a/vortex-layout/src/scan/repeated_scan.rs +++ b/vortex-layout/src/scan/repeated_scan.rs @@ -14,7 +14,6 @@ use futures::Stream; use futures::StreamExt; use futures::future; use futures::future::BoxFuture; -use futures::ready; use futures::stream; use futures::stream::BoxStream; use itertools::Either; @@ -32,6 +31,7 @@ use vortex_error::VortexResult; use vortex_error::vortex_bail; use vortex_io::runtime::BlockingRuntime; use vortex_io::session::RuntimeSessionExt; +use vortex_scan::limit::limit_rows; use vortex_scan::row_mask::RowMask; use vortex_scan::selection::Selection; use vortex_session::VortexSession; @@ -384,43 +384,6 @@ fn map_split( .boxed() } -/// Trim arrays to the budget and drop upstream work as soon as it is exhausted. -fn limit_rows( - arrays: BoxStream<'static, VortexResult>, - limit: RowLimit, -) -> BoxStream<'static, VortexResult> { - let mut arrays = Some(arrays); - stream::poll_fn(move |cx| { - loop { - if limit.is_exhausted() { - arrays = None; - } - let Some(stream) = arrays.as_mut() else { - return Poll::Ready(None); - }; - let array = match ready!(stream.poll_next_unpin(cx)) { - Some(Ok(array)) => array, - end => { - arrays = None; - return Poll::Ready(end); - } - }; - let granted = limit.take(array.len()); - if limit.is_exhausted() { - arrays = None; - } - if granted != 0 { - return Poll::Ready(Some(if granted < array.len() { - array.slice(0..granted) - } else { - Ok(array) - })); - } - } - }) - .boxed() -} - /// Yield the first error and drop upstream without polling it again. fn stop_on_error( stream: BoxStream<'static, VortexResult>, @@ -505,9 +468,9 @@ mod tests { use vortex_array::arrays::PrimitiveArray; use vortex_error::VortexResult; use vortex_error::vortex_err; + use vortex_scan::limit::limit_rows; use super::SplitConcurrency; - use super::limit_rows; use super::stop_on_error; use crate::scan::limit::RowLimit; diff --git a/vortex-scan/src/lib.rs b/vortex-scan/src/lib.rs index 0c355a1a428..d693b1d3bb8 100644 --- a/vortex-scan/src/lib.rs +++ b/vortex-scan/src/lib.rs @@ -24,6 +24,7 @@ pub mod arrays; pub mod execution; +pub mod limit; pub mod plan; pub mod planning; pub mod prepare; diff --git a/vortex-scan/src/limit.rs b/vortex-scan/src/limit.rs new file mode 100644 index 00000000000..845a7525d89 --- /dev/null +++ b/vortex-scan/src/limit.rs @@ -0,0 +1,173 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: Copyright the Vortex contributors + +//! Row limits that the work of one scan shares. + +use std::sync::Arc; +use std::sync::atomic::AtomicU64; +use std::sync::atomic::Ordering; +use std::task::Poll; + +use futures::StreamExt; +use futures::ready; +use futures::stream; +use futures::stream::BoxStream; +use vortex_array::ArrayRef; +use vortex_error::VortexExpect; +use vortex_error::VortexResult; +use vortex_mask::Mask; + +/// A cloneable row budget shared by all work that can contribute rows to one scan. +/// +/// Filterless scans reserve each split's selected rows before constructing its projection, so +/// rows past the limit are never decoded. Filtered scans cannot know a split's row count up front, +/// so they take rows from the budget as arrays are emitted and discard the excess. Either way, +/// the order in which rows are taken decides which rows are returned: an ordered scan takes them +/// in split order, an unordered one in completion order. +#[derive(Clone)] +pub struct RowLimit(Arc); + +impl RowLimit { + /// A budget of `limit` rows. + pub fn new(limit: u64) -> Self { + Self(Arc::new(AtomicU64::new(limit))) + } + + /// Reserve rows selected by `mask` and retain only the earliest granted rows in that mask. + pub fn limit(&self, mask: Mask) -> Mask { + let granted = self.take(mask.true_count()); + mask.limit(granted) + } + + /// Reserve up to `rows` rows, returning how many the remaining budget granted. + pub fn take(&self, rows: usize) -> usize { + let requested = u64::try_from(rows).unwrap_or(u64::MAX); + usize::try_from(self.reserve(requested)).unwrap_or(usize::MAX) + } + + /// Whether the budget is spent. + pub fn is_exhausted(&self) -> bool { + self.0.load(Ordering::Relaxed) == 0 + } + + fn reserve(&self, requested: u64) -> u64 { + let remaining = self + .0 + .try_update(Ordering::Relaxed, Ordering::Relaxed, |remaining| { + Some(remaining.saturating_sub(requested)) + }) + .ok() + .vortex_expect("row reservation always updates the budget"); + remaining.min(requested) + } +} + +/// Trim arrays to the budget and drop upstream work as soon as it is exhausted. +pub fn limit_rows( + arrays: BoxStream<'static, VortexResult>, + limit: RowLimit, +) -> BoxStream<'static, VortexResult> { + let mut arrays = Some(arrays); + stream::poll_fn(move |cx| { + loop { + if limit.is_exhausted() { + arrays = None; + } + let Some(stream) = arrays.as_mut() else { + return Poll::Ready(None); + }; + let array = match ready!(stream.poll_next_unpin(cx)) { + Some(Ok(array)) => array, + end => { + arrays = None; + return Poll::Ready(end); + } + }; + let granted = limit.take(array.len()); + if limit.is_exhausted() { + arrays = None; + } + if granted != 0 { + return Poll::Ready(Some(if granted < array.len() { + array.slice(0..granted) + } else { + Ok(array) + })); + } + } + }) + .boxed() +} + +#[cfg(test)] +mod tests { + use std::sync::Arc; + use std::sync::Barrier; + use std::sync::atomic::AtomicU64; + use std::sync::atomic::Ordering; + use std::thread; + + use vortex_mask::Mask; + + use super::RowLimit; + + #[test] + fn reserve_grants_up_to_the_remaining_budget() { + let limit = RowLimit::new(5); + assert_eq!(limit.reserve(3), 3); + assert!(!limit.is_exhausted()); + // Only two rows remain, so a larger request saturates at what is left. + assert_eq!(limit.reserve(10), 2); + assert!(limit.is_exhausted()); + // Once exhausted, further requests grant nothing. + assert_eq!(limit.reserve(1), 0); + } + + #[test] + fn limit_keeps_the_earliest_granted_rows() { + let limit = RowLimit::new(2); + // Rows 0, 2, 3, 5 are selected; only the first two survive the budget of 2. + let mask = Mask::from_iter([true, false, true, true, false, true]); + let limited = limit.limit(mask); + + assert_eq!(limited.true_count(), 2); + assert!(limited.value(0)); + assert!(limited.value(2)); + assert!(!limited.value(3)); + assert!(!limited.value(5)); + assert!(limit.is_exhausted()); + } + + #[test] + fn concurrent_reservations_never_exceed_the_budget() { + const THREADS: usize = 8; + const PER_THREAD: u64 = 10_000; + const LIMIT: u64 = 25_000; + + let limit = RowLimit::new(LIMIT); + let granted_total = Arc::new(AtomicU64::new(0)); + let barrier = Arc::new(Barrier::new(THREADS)); + + thread::scope(|scope| { + for _ in 0..THREADS { + let limit = limit.clone(); + let granted_total = Arc::clone(&granted_total); + let barrier = Arc::clone(&barrier); + scope.spawn(move || { + // Start all threads together to maximize contention on the atomic. + barrier.wait(); + let mut local = 0; + for _ in 0..PER_THREAD { + local += limit.reserve(1); + } + granted_total.fetch_add(local, Ordering::Relaxed); + }); + } + }); + + // Total requested (THREADS * PER_THREAD = 80_000) exceeds the budget, so exactly the + // budget is granted across all threads — no double-grant, over-grant, or lost reservation. + assert_eq!(granted_total.load(Ordering::Relaxed), LIMIT); + assert!(limit.is_exhausted()); + } +} From 08ef4677ac185cb661fa6dd1f8a2a524b0acd533 Mon Sep 17 00:00:00 2001 From: Nicholas Gates Date: Fri, 20 Nov 2026 17:20:44 -0500 Subject: [PATCH 2/2] Keep the futures::ready import that repeated_scan still uses Signed-off-by: Nicholas Gates Co-Authored-By: Claude Opus 5.5 --- vortex-layout/src/scan/repeated_scan.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/vortex-layout/src/scan/repeated_scan.rs b/vortex-layout/src/scan/repeated_scan.rs index 2d82f283dc4..be849306f4a 100644 --- a/vortex-layout/src/scan/repeated_scan.rs +++ b/vortex-layout/src/scan/repeated_scan.rs @@ -14,6 +14,7 @@ use futures::Stream; use futures::StreamExt; use futures::future; use futures::future::BoxFuture; +use futures::ready; use futures::stream; use futures::stream::BoxStream; use itertools::Either;