Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 1 addition & 122 deletions vortex-layout/src/scan/limit.rs
Original file line number Diff line number Diff line change
@@ -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<AtomicU64>);
pub(crate) use vortex_scan::limit::RowLimit;

/// The row limit of a scan.
#[derive(Clone)]
Expand All @@ -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());
}
}
40 changes: 2 additions & 38 deletions vortex-layout/src/scan/repeated_scan.rs
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,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;
Expand Down Expand Up @@ -384,43 +385,6 @@ fn map_split<A: 'static + Send>(
.boxed()
}

/// Trim arrays to the budget and drop upstream work as soon as it is exhausted.
fn limit_rows(
arrays: BoxStream<'static, VortexResult<ArrayRef>>,
limit: RowLimit,
) -> BoxStream<'static, VortexResult<ArrayRef>> {
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<T: Send + 'static>(
stream: BoxStream<'static, VortexResult<T>>,
Expand Down Expand Up @@ -505,9 +469,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;

Expand Down
1 change: 1 addition & 0 deletions vortex-scan/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@

pub mod arrays;
pub mod execution;
pub mod limit;
pub mod plan;
pub mod planning;
pub mod prepare;
Expand Down
173 changes: 173 additions & 0 deletions vortex-scan/src/limit.rs
Original file line number Diff line number Diff line change
@@ -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<AtomicU64>);

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<ArrayRef>>,
limit: RowLimit,
) -> BoxStream<'static, VortexResult<ArrayRef>> {
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());
}
}
Loading