docs

Signed-off-by: Adam Gutglick <adam@spiraldb.com>

Author: AdamGS

vortex-layout/src/scan/layout.rs

@@ -335,6 +335,8 @@ impl Partition for LayoutReaderSplit {
         // Use into_stream() which creates a LazyScanStream that spawns individual I/O
         // tasks onto the runtime, enabling parallel execution across executor threads.
         let stream = builder.into_stream()?.boxed();
+        // Caps total rows across all partitions; only correct for unordered consumption
+        // (see `SharedRowLimit`).
         let stream = match shared_limit {
             Some(limit) => LimitedStream::new(stream, RowBudget::Shared(limit)).boxed(),
             None => stream,

vortex-layout/src/scan/limit.rs

@@ -16,12 +16,12 @@ use vortex_array::ArrayRef;
 use vortex_error::VortexExpect;
 use vortex_error::VortexResult;
 
-/// A row limit shared by streams that execute independent scan partitions.
+/// A row limit shared by the streams executing one scan's independent partitions.
 ///
-/// The shared budget gives "at most `limit` rows in total" semantics without any ordering
-/// guarantee across the streams that share it: whichever stream produces a chunk first claims
-/// the budget first. It is therefore only correct for consumers that treat the combined output
-/// as unordered (e.g. a bare `LIMIT n`), not for order-preserving cross-partition consumption.
+/// The single budget is claimed in completion order, not row order, so the combined output is
+/// "any `limit` rows", not "the first `limit` in scan order": under concurrency a later partition
+/// can drain the budget and starve an earlier one. Only sound for unordered consumers (a bare
+/// `LIMIT n`); order-preserving consumers must use a per-partition `ScanBuilder::with_limit`.
 #[derive(Clone)]
 pub(crate) struct SharedRowLimit(Arc<AtomicU64>);
 

vortex-layout/src/scan/multi.rs

@@ -542,6 +542,8 @@ impl Partition for MultiLayoutPartition {
 
         let dtype = builder.dtype()?;
         let stream = builder.into_stream()?.boxed();
+        // Caps total rows across all partitions; only correct for unordered consumption
+        // (see `SharedRowLimit`).
         let stream = match shared_limit {
             Some(limit) => LimitedStream::new(stream, RowBudget::Shared(limit)).boxed(),
             None => stream,

vortex-layout/src/scan/repeated_scan.rs

@@ -183,10 +183,7 @@ impl RepeatedScan {
         })
     }
 
-    pub(crate) fn execute(
-        &self,
-        row_range: Option<Range<u64>>,
-    ) -> VortexResult<Vec<TaskFuture>> {
+    pub(crate) fn execute(&self, row_range: Option<Range<u64>>) -> VortexResult<Vec<TaskFuture>> {
         let ctx = self.task_context();
 
         let mut limit = self.limit;