From 4b2a1769c442a25813287ea8400edabde828b22f Mon Sep 17 00:00:00 2001 From: Joe Isaacs Date: Wed, 4 Nov 2026 11:25:31 +0000 Subject: [PATCH 1/4] feat(scan): add RowClaim-bounded file read sharing to the planner driver Extract the row-claim read lifetime from the closed #10857 on its own, without its layout, DuckDB, or DataFusion changes. `FileReads` shares pending and completed reads across all workers of one file execution. Work owns a `RowClaim` over the file-local rows it may still read, and moves, splits (`split_to`), narrows (`restrict_to`), or shares that claim as it is handed between planners. A read whose `ReadLifetime` bounds its consumers to a row range is evicted once no live claim covers that range; reads with unknown lifetimes live until the last claim drops. Nothing constructs these types yet; wiring them into the V2 scan planners is left to a follow-up. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UeniBBmU6aRNmSqEsMdKGW Signed-off-by: Joe Isaacs --- vortex-scan/Cargo.toml | 2 +- vortex-scan/src/planning/driver/mod.rs | 6 + vortex-scan/src/planning/driver/reads/mod.rs | 342 ++++++++ .../src/planning/driver/reads/progress.rs | 252 ++++++ .../src/planning/driver/reads/tests.rs | 762 ++++++++++++++++++ 5 files changed, 1363 insertions(+), 1 deletion(-) create mode 100644 vortex-scan/src/planning/driver/reads/mod.rs create mode 100644 vortex-scan/src/planning/driver/reads/progress.rs create mode 100644 vortex-scan/src/planning/driver/reads/tests.rs diff --git a/vortex-scan/Cargo.toml b/vortex-scan/Cargo.toml index d12c207b049..a54e2ad63a9 100644 --- a/vortex-scan/Cargo.toml +++ b/vortex-scan/Cargo.toml @@ -25,11 +25,11 @@ vortex-utils = { workspace = true } async-trait = { workspace = true } futures = { workspace = true } +parking_lot = { workspace = true } roaring = { workspace = true } tracing = { workspace = true } [dev-dependencies] -parking_lot = { workspace = true } rstest = { workspace = true } vortex-array = { workspace = true, features = ["_test-harness"] } diff --git a/vortex-scan/src/planning/driver/mod.rs b/vortex-scan/src/planning/driver/mod.rs index e9cf27da3c2..db5baec3f2e 100644 --- a/vortex-scan/src/planning/driver/mod.rs +++ b/vortex-scan/src/planning/driver/mod.rs @@ -16,12 +16,18 @@ //! a completion it took from a source to [`Run::complete`]. [`Driver::run`] is the blocking //! convenience for one root. +mod reads; + use std::collections::BTreeMap; use std::collections::VecDeque; use std::sync::Arc; use std::task::Context; use std::task::Poll; +pub use reads::FileReads; +pub use reads::ReadLifetime; +pub use reads::ReadLifetimes; +pub use reads::RowClaim; use vortex_array::ArrayRef; use vortex_error::VortexResult; use vortex_error::vortex_bail; diff --git a/vortex-scan/src/planning/driver/reads/mod.rs b/vortex-scan/src/planning/driver/reads/mod.rs new file mode 100644 index 00000000000..098c58b1265 --- /dev/null +++ b/vortex-scan/src/planning/driver/reads/mod.rs @@ -0,0 +1,342 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: Copyright the Vortex contributors + +//! File-execution read sharing, bounded by unfinished consumer row ranges. + +mod progress; +#[cfg(test)] +mod tests; + +use std::collections::BTreeMap; +use std::collections::VecDeque; +use std::future::poll_fn; +use std::ops::Range; +use std::sync::Arc; +use std::task::Context; +use std::task::Poll; +use std::task::Wake; +use std::task::Waker; +use std::thread; + +use futures::FutureExt; +use futures::StreamExt; +use futures::future::AbortHandle; +use futures::future::Abortable; +use futures::future::BoxFuture; +use futures::future::Shared; +use futures::stream::FuturesUnordered; +use parking_lot::Mutex; +use vortex_error::SharedVortexResult; +use vortex_error::VortexError; +use vortex_error::VortexResult; +use vortex_error::vortex_ensure; +use vortex_error::vortex_err; +use vortex_io::request::Completion; +use vortex_io::request::IoBatch; +use vortex_io::request::IoIntent; +use vortex_io::request::IoOwnerId; +use vortex_io::request::IoRequest; +use vortex_io::request::IoRequestId; +use vortex_io::request::IoResult; +use vortex_io::request::IoService; +use vortex_io::request::IoSource; +use vortex_io::request::IoTarget; +use vortex_utils::aliases::hash_map::Entry; +use vortex_utils::aliases::hash_map::HashMap; + +pub use self::progress::RowClaim; + +/// The possible consumers of a read, expressed in the file's root row domain. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum ReadLifetime { + /// Only consumers overlapping this range can need the read. + Rows(Range), + /// No tighter bound is known; keep the read until the file execution ends. + File, +} + +/// Conservative read lifetimes derived by the layout planner. Missing targets live to file end. +pub type ReadLifetimes = Arc>; + +type SharedRead = Shared>>; + +/// Read sharing for one execution over one file, across all its workers and queued work. +/// +/// Reserve the scan's rows with [`claim`](Self::claim), then move and split that claim with +/// the work. Queued work retains its claim before any worker takes it. Completed reads and +/// unconsumed hints expire when no claim overlaps their consumer range. Dropping the last nonempty +/// claim clears even file-lifetime reads, independently of the service or prepared plan lifetime. +#[derive(Clone)] +pub struct FileReads { + transport: Arc, + lifetimes: ReadLifetimes, + state: Arc>, +} + +#[derive(Default)] +struct ReadState { + claims: progress::Claims, + entries: HashMap, + expiry: BTreeMap>, +} + +struct ReadEntry { + transport: Arc, + read: Option, + rows: Option>, + announced: bool, +} + +/// One target's transport scope. Clearing it also releases unused announcements on eviction. +struct ReadTransport(Arc); + +impl Drop for ReadTransport { + fn drop(&mut self) { + self.0.clear(); + } +} + +impl FileReads { + /// Creates fresh sharing state for one file execution. Lifetimes may be reused across + /// executions, but the service itself must not be shared with another execution or file. + pub fn new(transport: Arc, lifetimes: ReadLifetimes) -> Self { + Self { + transport, + lifetimes, + state: Arc::default(), + } + } + + /// Reserves the initial rows before any work runs. Descendants receive splits or shares + /// of this claim; they must not register fresh ranges after those rows have been released. + pub fn claim(&self, rows: Range) -> RowClaim { + RowClaim::new(self.clone(), rows) + } + + fn request(&self, request: IoRequest) -> VortexResult> { + let mut state = self.state.lock(); + vortex_ensure!( + !state.claims.is_empty(), + "file reads require a live row claim" + ); + let ReadState { + entries, expiry, .. + } = &mut *state; + let entry = match entries.entry(request.target) { + Entry::Occupied(entry) => entry.into_mut(), + Entry::Vacant(entry) => { + let lifetime = self + .lifetimes + .get(&request.target) + .cloned() + .unwrap_or(ReadLifetime::File); + let rows = match lifetime { + ReadLifetime::Rows(rows) => { + expiry.entry(rows.end).or_default().push(request.target); + Some(rows) + } + ReadLifetime::File => None, + }; + entry.insert(ReadEntry { + transport: Arc::new(ReadTransport(self.transport.session())), + read: None, + rows, + announced: false, + }) + } + }; + if request.intent == IoIntent::Announce { + if entry.read.is_none() && !entry.announced { + entry.transport.0.submit( + IoOwnerId(0), + vec![IoRequest { + request: IoRequestId(0), + ..request + }], + )?; + entry.announced = true; + } + return Ok(None); + } + if let Some(read) = &entry.read { + return Ok(Some(read.clone())); + } + // Prefetches become internal fetches: the coordinator owns their result, and only a + // subscribing fetch gets a completion under its original owner and request identity. + entry.transport.0.submit( + IoOwnerId(0), + vec![IoRequest { + intent: IoIntent::Fetch, + request: IoRequestId(0), + ..request + }], + )?; + let transport = Arc::clone(&entry.transport); + let read = async move { + let completion = poll_fn(|cx| transport.0.poll_completion(cx)).await?; + vortex_ensure!( + completion.owner == IoOwnerId(0) && completion.request == IoRequestId(0), + "transport completed an unknown read" + ); + let result = completion.result?; + if !result.matches(&request.target) { + return Err(vortex_err!( + "read of {:?} returned {}", + request.target, + result.kind() + )); + } + Ok(result) + } + .map(|result: VortexResult| result.map_err(Arc::new)) + .boxed() + .shared(); + entry.read = Some(read.clone()); + Ok(Some(read)) + } +} + +impl IoService for FileReads { + fn session(&self) -> Arc { + Arc::new(ReadSession { + file: self.clone(), + pending: Mutex::default(), + }) + } +} + +#[derive(Default)] +struct Pending { + reads: FuturesUnordered>>, + ready: VecDeque, + subscriptions: HashMap<(IoOwnerId, IoRequestId), AbortHandle>, +} + +struct ReadSession { + file: FileReads, + pending: Mutex, +} + +impl ReadSession { + fn next(&self, cx: &mut Context<'_>) -> Poll> { + let mut pending = self.pending.lock(); + if let Some(completion) = pending.ready.pop_front() { + return Poll::Ready(Some(completion)); + } + loop { + match pending.reads.poll_next_unpin(cx) { + Poll::Ready(Some(Some(completion))) => { + pending + .subscriptions + .remove(&(completion.owner, completion.request)); + return Poll::Ready(Some(completion)); + } + Poll::Ready(Some(None)) => continue, + Poll::Ready(None) => return Poll::Ready(None), + Poll::Pending => return Poll::Pending, + } + } + } +} + +impl IoSource for ReadSession { + fn submit(&self, owner: IoOwnerId, batch: IoBatch) -> VortexResult<()> { + let mut pending = self.pending.lock(); + let mut reads = Vec::with_capacity(batch.len()); + for request in batch { + if let Some(read) = self.file.request(request)? { + reads.push((request, read)); + } + } + for (request, mut read) in reads { + let ready = read.poll_unpin(&mut Context::from_waker(Waker::noop())); + if request.intent == IoIntent::Prefetch { + if let Poll::Ready(Err(error)) = ready { + return Err(VortexError::from(error)); + } + continue; + } + // Cached and in-memory reads need no asynchronous subscription allocation. + if let Poll::Ready(result) = ready { + pending.ready.push_back(Completion { + owner, + request: request.request, + result: result.map_err(VortexError::from), + }); + continue; + } + let (abort, registration) = AbortHandle::new_pair(); + pending + .subscriptions + .insert((owner, request.request), abort); + let completion = async move { + Completion { + owner, + request: request.request, + result: read.await.map_err(VortexError::from), + } + }; + pending.reads.push( + Abortable::new(completion, registration) + .map(Result::ok) + .boxed(), + ); + } + Ok(()) + } + + fn poll(&self) -> VortexResult> { + Ok(match self.next(&mut Context::from_waker(Waker::noop())) { + Poll::Ready(completion) => completion, + Poll::Pending => None, + }) + } + + fn poll_completion(&self, cx: &mut Context<'_>) -> Poll> { + match self.next(cx) { + Poll::Ready(Some(completion)) => Poll::Ready(Ok(completion)), + Poll::Ready(None) => Poll::Ready(Err(vortex_err!("waiting with no reads in flight"))), + Poll::Pending => Poll::Pending, + } + } + + fn wait(&self) -> VortexResult { + let waker = Waker::from(Arc::new(ThreadWake(thread::current()))); + let mut cx = Context::from_waker(&waker); + loop { + match self.poll_completion(&mut cx) { + Poll::Ready(completion) => return completion, + Poll::Pending => thread::park(), + } + } + } + + fn release(&self, owner: IoOwnerId) { + let mut pending = self.pending.lock(); + pending.ready.retain(|completion| completion.owner != owner); + pending.subscriptions.retain(|(subscriber, _), abort| { + if *subscriber == owner { + abort.abort(); + false + } else { + true + } + }); + } + + fn clear(&self) { + *self.pending.lock() = Pending::default(); + } +} + +struct ThreadWake(thread::Thread); + +impl Wake for ThreadWake { + fn wake(self: Arc) { + self.0.unpark(); + } + + fn wake_by_ref(self: &Arc) { + self.0.unpark(); + } +} diff --git a/vortex-scan/src/planning/driver/reads/progress.rs b/vortex-scan/src/planning/driver/reads/progress.rs new file mode 100644 index 00000000000..31e5b2e4b70 --- /dev/null +++ b/vortex-scan/src/planning/driver/reads/progress.rs @@ -0,0 +1,252 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: Copyright the Vortex contributors + +//! Owned row claims travel with queued and running work. + +use std::collections::BTreeMap; +use std::ops::Bound::Excluded; +use std::ops::Bound::Included; +use std::ops::Range; + +use vortex_error::VortexExpect; + +use super::FileReads; +use super::ReadEntry; +use super::ReadState; + +/// Disjoint spans with the number of owners covering each span. Splitting ownership does not +/// change coverage; only sharing and releasing rows touch this index. +#[derive(Default)] +pub(super) struct Claims(BTreeMap); + +#[derive(Clone, Copy)] +struct Span { + end: u64, + owners: usize, +} + +impl Claims { + pub(super) fn is_empty(&self) -> bool { + self.0.is_empty() + } + + fn split_at(&mut self, row: u64) { + if let Some((&start, &span)) = self.0.range(..row).next_back() + && row < span.end + { + self.0.get_mut(&start).vortex_expect("span exists").end = row; + self.0.insert(row, span); + } + } + + fn join_at(&mut self, row: u64) { + if let Some((&start, &left)) = self.0.range(..row).next_back() + && let Some(&right) = self.0.get(&row) + && left.end == row + && left.owners == right.owners + { + self.0.get_mut(&start).vortex_expect("span exists").end = right.end; + self.0.remove(&row); + } + } + + fn add(&mut self, rows: &Range) { + if rows.is_empty() { + return; + } + self.split_at(rows.start); + self.split_at(rows.end); + let starts: Vec<_> = self + .0 + .range(rows.clone()) + .map(|(&start, _)| start) + .collect(); + let mut cursor = rows.start; + for start in starts { + if cursor < start { + self.0.insert( + cursor, + Span { + end: start, + owners: 1, + }, + ); + } + let span = self.0.get_mut(&start).vortex_expect("span exists"); + span.owners += 1; + cursor = span.end; + } + if cursor < rows.end { + self.0.insert( + cursor, + Span { + end: rows.end, + owners: 1, + }, + ); + } + self.join_at(rows.start); + self.join_at(rows.end); + } + + /// Returns newly uncovered gaps, including adjacent rows already released by other parts. + fn release(&mut self, rows: &Range) -> Vec> { + if rows.is_empty() { + return Vec::new(); + } + self.split_at(rows.start); + self.split_at(rows.end); + let starts: Vec<_> = self + .0 + .range(rows.clone()) + .map(|(&start, _)| start) + .collect(); + let mut removed = Vec::new(); + for start in starts { + let span = self.0.get_mut(&start).vortex_expect("span exists"); + span.owners -= 1; + if span.owners == 0 { + self.0.remove(&start); + removed.push(start); + } + } + self.join_at(rows.start); + self.join_at(rows.end); + let mut gaps = Vec::new(); + for row in removed { + let start = self + .0 + .range(..row) + .next_back() + .map_or(0, |(_, span)| span.end); + let end = self + .0 + .range(row..) + .next() + .map_or(u64::MAX, |(&start, _)| start); + let gap = start..end; + if gaps.last() != Some(&gap) { + gaps.push(gap); + } + } + gaps + } +} + +impl ReadState { + /// Return evicted entries so transport cancellation runs outside the state lock. + fn release(&mut self, rows: &Range) -> Vec { + let gaps = self.claims.release(rows); + if self.claims.is_empty() { + self.expiry.clear(); + return self.entries.drain().map(|(_, entry)| entry).collect(); + } + let mut evicted = Vec::new(); + for gap in gaps { + let ends: Vec<_> = self + .expiry + .range((Excluded(gap.start), Included(gap.end))) + .map(|(&end, _)| end) + .collect(); + for end in ends { + let targets = self.expiry.get_mut(&end).vortex_expect("expiry exists"); + targets.retain(|target| { + let entry = self.entries.get(target).vortex_expect("read exists"); + if entry + .rows + .as_ref() + .is_some_and(|rows| rows.start >= gap.start) + { + evicted.push(self.entries.remove(target).vortex_expect("read exists")); + false + } else { + true + } + }); + if targets.is_empty() { + self.expiry.remove(&end); + } + } + } + evicted + } +} + +/// An owned reservation for rows that may still read from a file execution. +/// +/// Move the claim with work through queues and planner handoffs. Split it before handing off +/// disjoint children; dropping it marks its remaining rows finished or cancelled. Output batches +/// must not own claims, since retaining a batch does not imply any future file reads. +#[must_use = "dropping a row claim releases its rows"] +pub struct RowClaim { + file: FileReads, + rows: Range, +} + +impl RowClaim { + pub(super) fn new(file: FileReads, rows: Range) -> Self { + assert!(rows.start <= rows.end, "claim rows must be ordered"); + file.state.lock().claims.add(&rows); + Self { file, rows } + } + + /// The file-local rows this claim still reserves. + pub fn rows(&self) -> &Range { + &self.rows + } + + /// Transfers the prefix ending at `end` into a child claim, keeping the suffix in `self`. + /// Coverage is unchanged, so splitting requires no lock or registration updates. + /// Panics if `end` is outside this claim's range. + pub fn split_to(&mut self, end: u64) -> Self { + assert!( + self.rows.contains(&end) || end == self.rows.end, + "split must lie within the claim" + ); + let rows = self.rows.start..end; + self.rows.start = end; + Self { + file: self.file.clone(), + rows, + } + } + + /// Releases rows proven unnecessary, retaining only the given subrange. + /// Panics if the range is not ordered and contained in this claim. + pub fn restrict_to(&mut self, rows: Range) { + assert!( + self.rows.start <= rows.start && rows.start <= rows.end && rows.end <= self.rows.end, + "remaining rows must be contained in the claim" + ); + if self.rows == rows { + return; + } + let evicted = { + let mut state = self.file.state.lock(); + let mut evicted = state.release(&(self.rows.start..rows.start)); + evicted.extend(state.release(&(rows.end..self.rows.end))); + self.rows = rows; + evicted + }; + drop(evicted); + } + + /// Creates another owner for the same rows, for consumers that overlap rather than split. + /// Each owner's remaining rows stay registered until that owner releases them. + pub fn share(&self) -> Self { + Self::new(self.file.clone(), self.rows.clone()) + } +} + +impl Drop for RowClaim { + fn drop(&mut self) { + if self.rows.is_empty() { + return; + } + let evicted = { + let mut state = self.file.state.lock(); + state.release(&self.rows) + }; + drop(evicted); + } +} diff --git a/vortex-scan/src/planning/driver/reads/tests.rs b/vortex-scan/src/planning/driver/reads/tests.rs new file mode 100644 index 00000000000..1c4f5eddfa5 --- /dev/null +++ b/vortex-scan/src/planning/driver/reads/tests.rs @@ -0,0 +1,762 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: Copyright the Vortex contributors + +use std::collections::VecDeque; +use std::sync::Weak; +use std::sync::atomic::AtomicBool; +use std::sync::atomic::AtomicUsize; +use std::sync::atomic::Ordering; + +use futures::task::AtomicWaker; +use rstest::rstest; +use vortex_array::buffer::BufferHandle; +use vortex_buffer::ByteBuffer; +use vortex_io::request::IoConsumer; + +use super::*; +use crate::planning::driver::Progress; +use crate::planning::driver::Run; +use crate::planning::planner::Planner; +use crate::planning::planner::PlannerOutput; +use crate::planning::planner::State; +use crate::planning::planner::WorkScope; + +#[derive(Default)] +struct Control { + reads: AtomicUsize, + announcements: AtomicUsize, + clears: AtomicUsize, + ready: AtomicBool, + fail: AtomicBool, + sources: Mutex>>, +} + +impl Control { + fn complete(&self) { + self.ready.store(true, Ordering::SeqCst); + for source in self.sources.lock().iter().filter_map(Weak::upgrade) { + source.waker.wake(); + } + } +} + +struct TestService(Arc); + +impl IoService for TestService { + fn session(&self) -> Arc { + let source = Arc::new(TestSource { + control: Arc::clone(&self.0), + ready: Mutex::default(), + waker: AtomicWaker::new(), + }); + self.0.sources.lock().push(Arc::downgrade(&source)); + source + } +} + +struct TestSource { + control: Arc, + ready: Mutex>, + waker: AtomicWaker, +} + +impl IoSource for TestSource { + fn submit(&self, owner: IoOwnerId, batch: IoBatch) -> VortexResult<()> { + for request in batch { + if request.intent == IoIntent::Announce { + self.control.announcements.fetch_add(1, Ordering::SeqCst); + continue; + } + self.control.reads.fetch_add(1, Ordering::SeqCst); + self.ready.lock().push_back(Completion { + owner, + request: request.request, + result: if self.control.fail.load(Ordering::SeqCst) { + Err(vortex_err!("transport failure")) + } else { + Ok(IoResult::Bytes(BufferHandle::new_host(ByteBuffer::from( + vec![ + 7; + match request.target { + IoTarget::Range { len, .. } => len, + _ => 4, + } + ], + )))) + }, + }); + } + Ok(()) + } + + fn poll(&self) -> VortexResult> { + Ok(if self.control.ready.load(Ordering::SeqCst) { + self.ready.lock().pop_front() + } else { + None + }) + } + + fn poll_completion(&self, cx: &mut Context<'_>) -> Poll> { + self.waker.register(cx.waker()); + match self.poll()? { + Some(completion) => Poll::Ready(Ok(completion)), + None => Poll::Pending, + } + } + + fn wait(&self) -> VortexResult { + self.poll()? + .ok_or_else(|| vortex_err!("test source is not ready")) + } + + fn release(&self, owner: IoOwnerId) { + self.ready + .lock() + .retain(|completion| completion.owner != owner); + } + + fn clear(&self) { + self.control.clears.fetch_add(1, Ordering::SeqCst); + self.ready.lock().clear(); + } +} + +fn file(control: &Arc) -> FileReads { + FileReads::new( + Arc::new(TestService(Arc::clone(control))), + Arc::new( + [ + (IoTarget::range(0, 4), ReadLifetime::Rows(0..20)), + (IoTarget::range(4, 4), ReadLifetime::Rows(20..40)), + (IoTarget::range(8, 4), ReadLifetime::File), + ] + .into_iter() + .collect(), + ), + ) +} + +fn request(intent: IoIntent, id: u32, offset: u64) -> IoRequest { + IoRequest { + intent, + request: IoRequestId(id), + target: IoTarget::range(offset, 4), + } +} + +fn retained(file: &FileReads) -> (usize, usize) { + let state = file.state.lock(); + let bytes = state + .entries + .values() + .map( + |entry| match entry.read.as_ref().and_then(SharedRead::peek) { + Some(Ok(IoResult::Bytes(buffer))) => buffer.len(), + _ => 0, + }, + ) + .sum(); + (state.entries.len(), bytes) +} + +#[rstest] +#[case::flat(false)] +#[case::shared_dictionary(true)] +fn part_retention_compared_with_file_watermark( + #[case] dictionary: bool, + #[values(false, true)] bound_start: bool, +) -> VortexResult<()> { + const PARTS: u64 = 32; + const SEGMENT_BYTES: usize = 4096; + const DICTIONARY_BYTES: usize = 16384; + let control = Arc::new(Control::default()); + control.complete(); + let mut lifetimes: HashMap<_, _> = (0..PARTS) + .map(|part| { + ( + IoTarget::range(part * SEGMENT_BYTES as u64, SEGMENT_BYTES), + // Starting every region at zero reproduces the former file-wide watermark: + // a stalled first part keeps every later part's reads alive. + ReadLifetime::Rows(if bound_start { part * 20 } else { 0 }..(part + 1) * 20), + ) + }) + .collect(); + let values = IoTarget::range(PARTS * SEGMENT_BYTES as u64, DICTIONARY_BYTES); + // Values span two parts and must remain shared until both finish. The stalled first + // part and queued later parts cannot read these values. + lifetimes.insert( + values, + ReadLifetime::Rows(if bound_start { 20 } else { 0 }..60), + ); + let file = FileReads::new( + Arc::new(TestService(Arc::clone(&control))), + Arc::new(lifetimes), + ); + let mut remaining = file.claim(0..PARTS * 20); + let first = remaining.split_to(20); + let session = file.session(); + let mut peak = (0, 0); + for part in 0..PARTS { + let work = (part != 0).then(|| remaining.split_to((part + 1) * 20)); + session.submit( + IoOwnerId(0), + vec![IoRequest { + intent: IoIntent::Fetch, + request: IoRequestId(0), + target: IoTarget::range(part * SEGMENT_BYTES as u64, SEGMENT_BYTES), + }], + )?; + session.wait()?.result?; + if dictionary && (1..=2).contains(&part) { + session.submit( + IoOwnerId(0), + vec![IoRequest { + intent: IoIntent::Fetch, + request: IoRequestId(1), + target: values, + }], + )?; + session.wait()?.result?; + } + let current = retained(&file); + peak = (peak.0.max(current.0), peak.1.max(current.1)); + drop(work); + let keep_segments = if bound_start { + 1 + } else { + usize::try_from(part)? + 1 + }; + let keep_values = + usize::from(dictionary && if bound_start { part == 1 } else { part >= 1 }); + assert_eq!( + retained(&file), + ( + keep_segments + keep_values, + keep_segments * SEGMENT_BYTES + keep_values * DICTIONARY_BYTES + ) + ); + } + assert_eq!( + control.reads.load(Ordering::SeqCst), + usize::try_from(PARTS)? + usize::from(dictionary) + ); + let peak_segments = if bound_start { + 2 + } else { + usize::try_from(PARTS)? + }; + assert_eq!( + peak, + ( + peak_segments + usize::from(dictionary), + peak_segments * SEGMENT_BYTES + usize::from(dictionary) * DICTIONARY_BYTES + ) + ); + drop(first); + assert_eq!(retained(&file), (0, 0)); + Ok(()) +} + +#[test] +fn overlapping_claims_release_only_uncovered_segments() -> VortexResult<()> { + let control = Arc::new(Control::default()); + control.complete(); + let file = file(&control); + let mut original = file.claim(0..60); + let mut overlap = original.share(); + overlap.restrict_to(10..30); + let session = file.session(); + for offset in [0, 4] { + session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, offset)])?; + session.wait()?.result?; + } + original.restrict_to(40..60); + assert_eq!(retained(&file), (2, 8)); + overlap.restrict_to(20..30); + assert_eq!(retained(&file), (1, 4)); + drop(overlap); + assert_eq!(retained(&file), (0, 0)); + Ok(()) +} + +#[test] +fn trimming_a_claim_releases_segments_on_both_sides() -> VortexResult<()> { + let control = Arc::new(Control::default()); + control.complete(); + let file = file(&control); + let mut claim = file.claim(0..40); + let session = file.session(); + for offset in [0, 4] { + session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, offset)])?; + session.wait()?.result?; + } + claim.restrict_to(0..20); + assert_eq!(retained(&file), (1, 4)); + claim.restrict_to(10..10); + assert_eq!(retained(&file), (0, 0)); + Ok(()) +} + +#[rstest] +#[case::forward([0, 1, 2, 3])] +#[case::reverse([3, 2, 1, 0])] +#[case::outside_in([0, 3, 1, 2])] +#[case::inside_out([1, 2, 0, 3])] +fn eviction_matches_remaining_consumers(#[case] order: [usize; 4]) -> VortexResult<()> { + let control = Arc::new(Control::default()); + control.complete(); + let regions: Vec<_> = (0..80) + .step_by(10) + .flat_map(|start| (start + 10..=80).step_by(10).map(move |end| start..end)) + .collect(); + let lifetimes = regions + .iter() + .enumerate() + .map(|(index, rows)| { + ( + IoTarget::range(index as u64 * 4, 4), + ReadLifetime::Rows(rows.clone()), + ) + }) + .collect(); + let file = FileReads::new( + Arc::new(TestService(Arc::clone(&control))), + Arc::new(lifetimes), + ); + let mut root = file.claim(0..80); + let mut overlap = root.share(); + overlap.restrict_to(10..70); + let mut parts: Vec<_> = (1..=4).map(|part| Some(root.split_to(part * 20))).collect(); + let session = file.session(); + for index in 0..regions.len() { + session.submit( + IoOwnerId(0), + vec![request(IoIntent::Fetch, 0, index as u64 * 4)], + )?; + session.wait()?.result?; + } + for (step, index) in order.into_iter().enumerate() { + drop(parts[index].take()); + if step == 1 { + overlap.restrict_to(30..50); + } + let expected = regions + .iter() + .filter(|region| { + parts + .iter() + .flatten() + .chain(std::iter::once(&overlap)) + .any(|claim| claim.rows().start < region.end && region.start < claim.rows().end) + }) + .count(); + assert_eq!(retained(&file), (expected, expected * 4)); + } + drop(overlap); + assert_eq!(retained(&file), (0, 0)); + Ok(()) +} + +struct Hold { + _claim: RowClaim, +} + +impl IoConsumer for Hold { + fn set_io_result(&mut self, _request: IoRequestId, _result: IoResult) {} +} + +impl Planner for Hold { + fn state(&self) -> State { + State::NeedsCompute + } + + fn compute(&mut self) -> VortexResult { + Ok(PlannerOutput::Done) + } +} + +#[test] +fn completed_parts_release_reads_before_earlier_parts_finish() -> VortexResult<()> { + let control = Arc::new(Control::default()); + control.complete(); + let file = file(&control); + let mut third = file.claim(0..60); + let first = third.split_to(20); + let second = third.split_to(40); + let session = file.session(); + for (id, offset) in [0, 4, 8].into_iter().enumerate() { + session.submit( + IoOwnerId(0), + vec![request(IoIntent::Fetch, u32::try_from(id)?, offset)], + )?; + session.wait()?.result?; + } + drop(second); + assert_eq!(control.clears.load(Ordering::SeqCst), 1); + drop(first); + assert_eq!(control.clears.load(Ordering::SeqCst), 2); + drop(third); + assert_eq!(control.clears.load(Ordering::SeqCst), 3); + // The engine may still hold the service and session after all the file's work has ended. + assert!(file.state.lock().entries.is_empty()); + assert!(session.poll()?.is_none()); + Ok(()) +} + +#[test] +fn sequential_sessions_reuse_reads_until_the_region_finishes() -> VortexResult<()> { + let control = Arc::new(Control::default()); + control.complete(); + let file = file(&control); + let work = file.claim(0..20); + for id in 0..3 { + let session = file.session(); + session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, id, 0)])?; + assert_eq!(session.wait()?.request, IoRequestId(id)); + session.clear(); + } + assert_eq!(control.reads.load(Ordering::SeqCst), 1); + drop(work); + assert_eq!(control.clears.load(Ordering::SeqCst), 1); + Ok(()) +} + +#[rstest] +fn prefetch_and_fetch_share_one_read(#[values(false, true)] prefetch: bool) -> VortexResult<()> { + let control = Arc::new(Control::default()); + let file = file(&control); + let _work = file.claim(0..20); + let first = file.session(); + let second = file.session(); + let intent = if prefetch { + IoIntent::Prefetch + } else { + IoIntent::Fetch + }; + first.submit(IoOwnerId(0), vec![request(intent, 0, 0)])?; + second.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; + assert_eq!(control.reads.load(Ordering::SeqCst), 1); + assert!(first.poll()?.is_none()); + assert!(second.poll()?.is_none()); + // Cancelling the initiating session must not cancel the other session's shared read. + first.clear(); + control.complete(); + second.wait()?.result?; + assert!(first.poll()?.is_none()); + Ok(()) +} + +#[derive(Default)] +struct WakeCount(AtomicUsize); + +impl Wake for WakeCount { + fn wake(self: Arc) { + self.0.fetch_add(1, Ordering::SeqCst); + } +} + +#[test] +fn completion_wakes_every_worker_and_preserves_request_identity() -> VortexResult<()> { + let control = Arc::new(Control::default()); + let file = file(&control); + let _work = file.claim(0..20); + let workers: Vec<_> = (0..2) + .map(|_| (file.session(), Arc::new(WakeCount::default()))) + .collect(); + for (index, (session, wake)) in workers.iter().enumerate() { + session.submit( + IoOwnerId(9), + vec![request(IoIntent::Fetch, u32::try_from(index)?, 0)], + )?; + let waker = Waker::from(Arc::clone(wake)); + assert!( + session + .poll_completion(&mut Context::from_waker(&waker)) + .is_pending() + ); + wake.0.store(0, Ordering::SeqCst); + } + control.complete(); + for (index, (session, wake)) in workers.iter().enumerate() { + assert!(wake.0.load(Ordering::SeqCst) > 0); + let completion = session.wait()?; + assert_eq!(completion.owner, IoOwnerId(9)); + assert_eq!(completion.request, IoRequestId(u32::try_from(index)?)); + completion.result?; + } + assert_eq!(control.reads.load(Ordering::SeqCst), 1); + Ok(()) +} + +#[test] +fn read_errors_reach_every_subscriber() -> VortexResult<()> { + let control = Arc::new(Control::default()); + control.fail.store(true, Ordering::SeqCst); + control.complete(); + let file = file(&control); + let _work = file.claim(0..20); + for _ in 0..2 { + let session = file.session(); + session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; + let error = session.wait()?.result.expect_err("transport fails"); + assert!(error.to_string().contains("transport failure")); + } + assert_eq!(control.reads.load(Ordering::SeqCst), 1); + Ok(()) +} + +#[test] +fn duplicate_announcements_share_one_hint_and_expire_with_their_region() -> VortexResult<()> { + let control = Arc::new(Control::default()); + let file = file(&control); + let mut remaining = file.claim(0..40); + let first = remaining.split_to(20); + let session = file.session(); + session.submit( + IoOwnerId(0), + vec![ + request(IoIntent::Announce, 0, 0), + request(IoIntent::Announce, 1, 0), + ], + )?; + assert_eq!(control.announcements.load(Ordering::SeqCst), 1); + assert_eq!(control.reads.load(Ordering::SeqCst), 0); + drop(first); + assert_eq!(control.clears.load(Ordering::SeqCst), 1); + Ok(()) +} + +struct Producer(RowClaim); + +impl IoConsumer for Producer { + fn set_io_result(&mut self, _request: IoRequestId, _result: IoResult) {} +} + +impl Planner for Producer { + fn state(&self) -> State { + if self.0.rows().is_empty() { + State::Done + } else { + State::NeedsCompute + } + } + + fn compute(&mut self) -> VortexResult { + let end = self.0.rows().start + 20; + let claim = self.0.split_to(end); + let rows = claim.rows().clone(); + Ok(PlannerOutput::Spawn( + WorkScope { + file_ordinal: 0, + rows, + }, + Box::new(Hold { _claim: claim }), + )) + } +} + +#[test] +fn queued_children_keep_reads_live_across_run_handoffs() -> VortexResult<()> { + let control = Arc::new(Control::default()); + control.complete(); + let file = file(&control); + let root = Box::new(Producer(file.claim(0..40))); + let io = file.session(); + io.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; + io.wait()?.result?; + let mut producer = Run::new(); + producer.admit( + root, + WorkScope { + file_ordinal: 0, + rows: 0..40, + }, + io, + ); + let Progress::Spawn(first_scope, first) = producer.advance()? else { + panic!("first child") + }; + let Progress::Spawn(_, second) = producer.advance()? else { + panic!("second child") + }; + drop(producer); + assert_eq!(control.clears.load(Ordering::SeqCst), 0); + // The first child remains registered while in the engine's queue, then on another run. + let mut worker = Run::new(); + worker.admit(first, first_scope, file.session()); + assert!(matches!(worker.advance()?, Progress::RootDone(_))); + assert_eq!(control.clears.load(Ordering::SeqCst), 1); + drop(second); + assert!(file.state.lock().entries.is_empty()); + Ok(()) +} + +#[test] +fn executions_do_not_share_identical_byte_ranges() -> VortexResult<()> { + let control = Arc::new(Control::default()); + control.complete(); + for _ in 0..2 { + let file = file(&control); + let _work = file.claim(0..20); + let session = file.session(); + session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; + session.wait()?.result?; + } + assert_eq!(control.reads.load(Ordering::SeqCst), 2); + assert_eq!(control.clears.load(Ordering::SeqCst), 2); + Ok(()) +} + +#[rstest] +fn cancellation_releases_pending_reads(#[values(false, true)] cancel: bool) -> VortexResult<()> { + let control = Arc::new(Control::default()); + let file = file(&control); + let root = Box::new(Hold { + _claim: file.claim(0..20), + }); + let session = file.session(); + session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; + let mut run = Run::new(); + let root = run.admit( + root, + WorkScope { + file_ordinal: 0, + rows: 0..20, + }, + Arc::clone(&session), + ); + if cancel { + run.cancel(root); + } else { + drop(run); + } + assert_eq!(control.clears.load(Ordering::SeqCst), 1); + assert!(file.state.lock().entries.is_empty()); + assert!(session.poll()?.is_none()); + Ok(()) +} + +#[test] +fn releasing_one_owner_preserves_other_subscriptions() -> VortexResult<()> { + let control = Arc::new(Control::default()); + let file = file(&control); + let _work = file.claim(0..20); + let session = file.session(); + for owner in 0..2 { + session.submit(IoOwnerId(owner), vec![request(IoIntent::Fetch, 0, 0)])?; + } + session.release(IoOwnerId(0)); + control.complete(); + let completion = session.wait()?; + assert_eq!(completion.owner, IoOwnerId(1)); + completion.result?; + assert!(session.poll()?.is_none()); + assert_eq!(control.reads.load(Ordering::SeqCst), 1); + Ok(()) +} + +#[test] +fn unknown_lifetimes_are_bounded_by_file_completion() -> VortexResult<()> { + let control = Arc::new(Control::default()); + control.complete(); + let file = file(&control); + let mut second = file.claim(0..40); + let first = second.split_to(20); + let session = file.session(); + session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 12)])?; + session.wait()?.result?; + drop(first); + assert_eq!(control.clears.load(Ordering::SeqCst), 0); + drop(second); + assert_eq!(control.clears.load(Ordering::SeqCst), 1); + Ok(()) +} + +#[test] +fn splitting_transfers_rows_without_releasing_their_reads() -> VortexResult<()> { + let control = Arc::new(Control::default()); + control.complete(); + let file = file(&control); + let mut remaining = file.claim(0..40); + let session = file.session(); + session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; + session.wait()?.result?; + + let child = remaining.split_to(20); + assert_eq!(child.rows(), &(0..20)); + assert_eq!(remaining.rows(), &(20..40)); + assert_eq!(control.clears.load(Ordering::SeqCst), 0); + // Moving the claim between stages changes neither registration nor cached reads. + let next_stage = child; + drop(remaining); + assert_eq!(control.clears.load(Ordering::SeqCst), 0); + drop(next_stage); + assert_eq!(control.clears.load(Ordering::SeqCst), 1); + Ok(()) +} + +#[test] +fn restricting_a_claim_releases_skipped_rows() -> VortexResult<()> { + let control = Arc::new(Control::default()); + control.complete(); + let file = file(&control); + let mut claim = file.claim(0..40); + let session = file.session(); + for offset in [0, 8] { + session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, offset)])?; + session.wait()?.result?; + } + claim.restrict_to(20..35); + assert_eq!(control.clears.load(Ordering::SeqCst), 1); + claim.restrict_to(35..35); + assert_eq!(control.clears.load(Ordering::SeqCst), 2); + assert!(file.state.lock().claims.is_empty()); + drop(claim); + assert_eq!(control.clears.load(Ordering::SeqCst), 2); + Ok(()) +} + +#[test] +fn overlapping_consumers_keep_independent_claims() -> VortexResult<()> { + let control = Arc::new(Control::default()); + control.complete(); + let file = file(&control); + let mut first = file.claim(0..40); + let second = first.share(); + let session = file.session(); + session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; + session.wait()?.result?; + first.restrict_to(20..40); + assert_eq!(control.clears.load(Ordering::SeqCst), 0); + drop(second); + assert_eq!(control.clears.load(Ordering::SeqCst), 1); + assert_eq!(first.rows(), &(20..40)); + Ok(()) +} + +#[rstest] +#[case::empty_prefix(0)] +#[case::two_ranges(20)] +#[case::empty_suffix(40)] +fn split_boundaries_preserve_coverage(#[case] end: u64) { + let control = Arc::new(Control::default()); + let file = file(&control); + let mut remaining = file.claim(0..40); + let child = remaining.split_to(end); + assert_eq!(child.rows(), &(0..end)); + assert_eq!(remaining.rows(), &(end..40)); + drop(child); + drop(remaining); + assert!(file.state.lock().claims.is_empty()); +} + +#[rstest] +#[case::before_start(9)] +#[case::after_end(41)] +#[should_panic(expected = "split must lie within the claim")] +fn splits_outside_the_claim_are_rejected(#[case] end: u64) { + let file = file(&Arc::new(Control::default())); + let mut claim = file.claim(10..40); + let _child = claim.split_to(end); +} From 09ea597d695c61946fdbcdc8ab251dd3f942e065 Mon Sep 17 00:00:00 2001 From: Joe Isaacs Date: Wed, 4 Nov 2026 14:49:18 +0000 Subject: [PATCH 2/4] refactor(scan): move row claims from the IO layer into the driver Row claims are a timing system for when in-memory scan state can be dropped, not an IO concern, so they now live in the planner driver. A `Liveness` tracks which root rows of one file live work may still touch. `Run::admit_with_liveness` gives every planner and morsel descended from a root a `RowClaim` over its scope's rows: taken when the work is spawned, narrowed after each compute to the work's new optional `remaining_rows()`, and released when the work retires or is cancelled. Children claim their rows before their parent narrows, so handed-off rows are never uncovered in between. Planners no longer pass claims around themselves. Any value decoded for those rows (arrays, dictionary values, buffers) can be pinned to a `Lifetime` with `Liveness::pin` and is dropped once no claim covers its rows. Caches that want to find it again keep a weak reference. This removes the IO-layer `FileReads` coordinator and its read lifetimes. `Planner` and `Morsel` gain `remaining_rows()`, which defaults to keeping the whole scope, so existing implementations are unchanged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UeniBBmU6aRNmSqEsMdKGW Signed-off-by: Joe Isaacs --- .../src/planning/driver/liveness/coverage.rs | 138 ++++ .../src/planning/driver/liveness/mod.rs | 230 ++++++ .../src/planning/driver/liveness/tests.rs | 279 +++++++ vortex-scan/src/planning/driver/mod.rs | 95 ++- vortex-scan/src/planning/driver/reads/mod.rs | 342 -------- .../src/planning/driver/reads/progress.rs | 252 ------ .../src/planning/driver/reads/tests.rs | 762 ------------------ vortex-scan/src/planning/morsel.rs | 7 + vortex-scan/src/planning/planner.rs | 10 + 9 files changed, 752 insertions(+), 1363 deletions(-) create mode 100644 vortex-scan/src/planning/driver/liveness/coverage.rs create mode 100644 vortex-scan/src/planning/driver/liveness/mod.rs create mode 100644 vortex-scan/src/planning/driver/liveness/tests.rs delete mode 100644 vortex-scan/src/planning/driver/reads/mod.rs delete mode 100644 vortex-scan/src/planning/driver/reads/progress.rs delete mode 100644 vortex-scan/src/planning/driver/reads/tests.rs diff --git a/vortex-scan/src/planning/driver/liveness/coverage.rs b/vortex-scan/src/planning/driver/liveness/coverage.rs new file mode 100644 index 00000000000..7deb819df3c --- /dev/null +++ b/vortex-scan/src/planning/driver/liveness/coverage.rs @@ -0,0 +1,138 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: Copyright the Vortex contributors + +//! Reference-counted coverage of a file's root rows by live claims. + +use std::collections::BTreeMap; +use std::ops::Range; + +use vortex_error::VortexExpect; + +/// Disjoint spans with the number of claims covering each span. +#[derive(Default)] +pub(super) struct Coverage(BTreeMap); + +#[derive(Clone, Copy)] +struct Span { + end: u64, + owners: usize, +} + +impl Coverage { + pub(super) fn is_empty(&self) -> bool { + self.0.is_empty() + } + + /// Whether any claim covers part of `rows`. + pub(super) fn overlaps(&self, rows: &Range) -> bool { + !rows.is_empty() + && self + .0 + .range(..rows.end) + .next_back() + .is_some_and(|(_, span)| span.end > rows.start) + } + + fn split_at(&mut self, row: u64) { + if let Some((&start, &span)) = self.0.range(..row).next_back() + && row < span.end + { + self.0.get_mut(&start).vortex_expect("span exists").end = row; + self.0.insert(row, span); + } + } + + fn join_at(&mut self, row: u64) { + if let Some((&start, &left)) = self.0.range(..row).next_back() + && let Some(&right) = self.0.get(&row) + && left.end == row + && left.owners == right.owners + { + self.0.get_mut(&start).vortex_expect("span exists").end = right.end; + self.0.remove(&row); + } + } + + pub(super) fn add(&mut self, rows: &Range) { + if rows.is_empty() { + return; + } + self.split_at(rows.start); + self.split_at(rows.end); + let starts: Vec<_> = self + .0 + .range(rows.clone()) + .map(|(&start, _)| start) + .collect(); + let mut cursor = rows.start; + for start in starts { + if cursor < start { + self.0.insert( + cursor, + Span { + end: start, + owners: 1, + }, + ); + } + let span = self.0.get_mut(&start).vortex_expect("span exists"); + span.owners += 1; + cursor = span.end; + } + if cursor < rows.end { + self.0.insert( + cursor, + Span { + end: rows.end, + owners: 1, + }, + ); + } + self.join_at(rows.start); + self.join_at(rows.end); + } + + /// Releases one claim on `rows`, returning the maximal uncovered gaps around every span that + /// became uncovered, including adjacent rows other claims released earlier. + pub(super) fn release(&mut self, rows: &Range) -> Vec> { + if rows.is_empty() { + return Vec::new(); + } + self.split_at(rows.start); + self.split_at(rows.end); + let starts: Vec<_> = self + .0 + .range(rows.clone()) + .map(|(&start, _)| start) + .collect(); + let mut removed = Vec::new(); + for start in starts { + let span = self.0.get_mut(&start).vortex_expect("span exists"); + span.owners -= 1; + if span.owners == 0 { + self.0.remove(&start); + removed.push(start); + } + } + self.join_at(rows.start); + self.join_at(rows.end); + let mut gaps = Vec::new(); + for row in removed { + let start = self + .0 + .range(..row) + .next_back() + .map_or(0, |(_, span)| span.end); + let end = self + .0 + .range(row..) + .next() + .map_or(u64::MAX, |(&start, _)| start); + let gap = start..end; + if gaps.last() != Some(&gap) { + gaps.push(gap); + } + } + gaps + } +} diff --git a/vortex-scan/src/planning/driver/liveness/mod.rs b/vortex-scan/src/planning/driver/liveness/mod.rs new file mode 100644 index 00000000000..662f310d06d --- /dev/null +++ b/vortex-scan/src/planning/driver/liveness/mod.rs @@ -0,0 +1,230 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: Copyright the Vortex contributors + +//! When a file's in-memory scan state can be dropped, decided by the work still live in the +//! driver. +//! +//! A [`Liveness`] tracks which root rows of one file live work may still touch. A [`Run`] that +//! admits a root with [`admit_with_liveness`] gives every planner and morsel descended from it a +//! [`RowClaim`] over its scope's rows: the claim is taken when the work is spawned, narrowed to +//! the work's [`remaining_rows`], and released when the work retires or is cancelled. +//! +//! Anything decoded for those rows, such as arrays, dictionary values, or buffers, can be +//! [`pin`](Liveness::pin)ned to the rows it serves. The pin holds the value until no claim covers +//! any of its rows, and then drops it. A cache that wants to find such a value again keeps a weak +//! reference to it: the pin is the only strong reference that keeps it alive. +//! +//! [`Run`]: super::Run +//! [`admit_with_liveness`]: super::Run::admit_with_liveness +//! [`remaining_rows`]: crate::planning::planner::Planner::remaining_rows + +mod coverage; +#[cfg(test)] +mod tests; + +use std::any::Any; +use std::collections::BTreeMap; +use std::ops::Bound::Excluded; +use std::ops::Bound::Included; +use std::ops::Range; +use std::sync::Arc; + +use parking_lot::Mutex; +use vortex_error::VortexExpect; +use vortex_utils::aliases::hash_map::HashMap; + +use self::coverage::Coverage; + +/// The root rows whose work may still need a pinned value. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Lifetime { + /// Only work whose claim overlaps these rows can need the value. + Rows(Range), + /// No tighter bound is known: keep the value while any work on the file is live. + File, +} + +/// Which root rows of one file live work still claims, and the values pinned to them. +/// +/// Clones share state, so the runs of every thread that scans the file can report to one +/// liveness. Nothing is pinned while no claim is live: hold a [`claim`](Self::claim) over the +/// whole scan before admitting its roots when values must outlive the gap between one root +/// finishing and the next being admitted. +#[derive(Clone, Default)] +pub struct Liveness { + state: Arc>, +} + +#[derive(Default)] +struct State { + coverage: Coverage, + pins: HashMap, + next_pin: u64, + /// Pins with a row lifetime, by the end of their rows. + expiry: BTreeMap>, +} + +struct Pin { + rows: Option>, + /// Never read: dropping it is the point. + _value: Box, +} + +impl Liveness { + /// Creates liveness for one file with nothing claimed or pinned. + pub fn new() -> Self { + Self::default() + } + + /// Claims `rows` until the returned claim is dropped. + pub fn claim(&self, rows: Range) -> RowClaim { + RowClaim::new(self.clone(), rows) + } + + /// Whether live work claims any of `rows`. + pub fn is_claimed(&self, rows: &Range) -> bool { + self.state.lock().coverage.overlaps(rows) + } + + /// Holds `value` until no live claim covers any row of `lifetime`. + /// + /// Returns `false`, dropping `value` at once, when no claim covers those rows already. + pub fn pin(&self, lifetime: Lifetime, value: T) -> bool { + let mut state = self.state.lock(); + let rows = match lifetime { + Lifetime::Rows(rows) => { + if !state.coverage.overlaps(&rows) { + drop(state); + drop(value); + return false; + } + Some(rows) + } + Lifetime::File => { + if state.coverage.is_empty() { + drop(state); + drop(value); + return false; + } + None + } + }; + let id = state.next_pin; + state.next_pin += 1; + if let Some(rows) = &rows { + state.expiry.entry(rows.end).or_default().push(id); + } + state.pins.insert( + id, + Pin { + rows, + _value: Box::new(value), + }, + ); + true + } + + /// The number of values currently pinned. + pub fn pinned(&self) -> usize { + self.state.lock().pins.len() + } + + fn add(&self, rows: &Range) { + self.state.lock().coverage.add(rows); + } + + /// Releases one claim on `rows`. Evicted values are dropped after the lock is released, so + /// a value's destructor may use this liveness. + fn release(&self, rows: &Range) { + let evicted = self.state.lock().release(rows); + drop(evicted); + } +} + +impl State { + fn release(&mut self, rows: &Range) -> Vec { + let gaps = self.coverage.release(rows); + if self.coverage.is_empty() { + self.expiry.clear(); + return self.pins.drain().map(|(_, pin)| pin).collect(); + } + let mut evicted = Vec::new(); + for gap in gaps { + let ends: Vec<_> = self + .expiry + .range((Excluded(gap.start), Included(gap.end))) + .map(|(&end, _)| end) + .collect(); + for end in ends { + let ids = self.expiry.get_mut(&end).vortex_expect("expiry exists"); + ids.retain(|id| { + let pin = self.pins.get(id).vortex_expect("pin exists"); + if pin.rows.as_ref().is_some_and(|rows| rows.start >= gap.start) { + evicted.push(self.pins.remove(id).vortex_expect("pin exists")); + false + } else { + true + } + }); + if ids.is_empty() { + self.expiry.remove(&end); + } + } + } + evicted + } +} + +/// An owned claim on root rows that live work may still touch. +/// +/// The driver holds one for every planner and morsel of a root admitted with liveness, so +/// planners do not handle claims themselves. An engine can hold one over a whole scan so values +/// pinned by its first roots survive until its last root is admitted. Dropping the claim releases +/// its remaining rows. +#[must_use = "dropping a row claim releases its rows"] +pub struct RowClaim { + liveness: Liveness, + rows: Range, +} + +impl RowClaim { + fn new(liveness: Liveness, rows: Range) -> Self { + assert!(rows.start <= rows.end, "claim rows must be ordered"); + liveness.add(&rows); + Self { liveness, rows } + } + + /// The rows this claim still covers. + pub fn rows(&self) -> &Range { + &self.rows + } + + /// Releases every row outside `rows`, which must lie within the claim. + /// + /// # Panics + /// + /// Panics if `rows` is unordered or not contained in the claim. + pub fn restrict_to(&mut self, rows: Range) { + assert!( + self.rows.start <= rows.start && rows.start <= rows.end && rows.end <= self.rows.end, + "remaining rows must be contained in the claim" + ); + if self.rows == rows { + return; + } + let evicted = { + let mut state = self.liveness.state.lock(); + let mut evicted = state.release(&(self.rows.start..rows.start)); + evicted.extend(state.release(&(rows.end..self.rows.end))); + evicted + }; + self.rows = rows; + drop(evicted); + } +} + +impl Drop for RowClaim { + fn drop(&mut self) { + self.liveness.release(&self.rows); + } +} diff --git a/vortex-scan/src/planning/driver/liveness/tests.rs b/vortex-scan/src/planning/driver/liveness/tests.rs new file mode 100644 index 00000000000..58728821d0a --- /dev/null +++ b/vortex-scan/src/planning/driver/liveness/tests.rs @@ -0,0 +1,279 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: Copyright the Vortex contributors + +use std::collections::VecDeque; + +use vortex_error::VortexResult; +use vortex_io::request::IoConsumer; +use vortex_io::request::IoRequestId; +use vortex_io::request::IoResult; +use vortex_io::request::IoSource; + +use super::*; +use crate::planning::driver::Progress; +use crate::planning::driver::Run; +use crate::planning::morsel::MorselOutput; +use crate::planning::planner::Planner; +use crate::planning::planner::PlannerOutput; +use crate::planning::planner::State; +use crate::planning::tests::scripted; +use crate::planning::tests::scripted::MorselStep; +use crate::planning::tests::scripted::RecordingIoSource; +use crate::planning::tests::scripted::ScriptedMorsel; +use crate::planning::tests::scripted::array_of; +use crate::planning::tests::scripted::scope; + +/// Ordered record of batches and of pinned values being dropped. +#[derive(Clone, Default)] +struct Events(Arc>>); + +impl Events { + fn push(&self, event: impl Into) { + self.0.lock().push(event.into()); + } + + fn take(&self) -> Vec { + std::mem::take(&mut *self.0.lock()) + } +} + +/// A pinned value that records when it is dropped. +struct Tracked(&'static str, Events); + +impl Drop for Tracked { + fn drop(&mut self) { + self.1.push(format!("drop {}", self.0)); + } +} + +fn pin_rows(liveness: &Liveness, events: &Events, name: &'static str, rows: Range) -> bool { + liveness.pin(Lifetime::Rows(rows), Tracked(name, events.clone())) +} + +#[test] +fn pin_lives_until_its_rows_are_released() { + let (liveness, events) = (Liveness::new(), Events::default()); + let claim = liveness.claim(0..8); + assert!(pin_rows(&liveness, &events, "a", 0..8)); + assert!(events.take().is_empty()); + drop(claim); + assert_eq!(events.take(), ["drop a"]); + assert_eq!(liveness.pinned(), 0); +} + +#[test] +fn overlapping_claims_keep_a_pin_until_both_release() { + let (liveness, events) = (Liveness::new(), Events::default()); + let first = liveness.claim(0..8); + let second = liveness.claim(4..12); + pin_rows(&liveness, &events, "a", 4..8); + drop(first); + assert!(events.take().is_empty()); + drop(second); + assert_eq!(events.take(), ["drop a"]); +} + +#[test] +fn restricting_a_claim_drops_pins_only_outside_the_remaining_rows() { + let (liveness, events) = (Liveness::new(), Events::default()); + let mut claim = liveness.claim(0..12); + pin_rows(&liveness, &events, "head", 0..4); + pin_rows(&liveness, &events, "middle", 4..8); + pin_rows(&liveness, &events, "tail", 8..12); + claim.restrict_to(4..8); + let mut dropped = events.take(); + dropped.sort(); + assert_eq!(dropped, ["drop head", "drop tail"]); + assert_eq!(claim.rows(), &(4..8)); + drop(claim); + assert_eq!(events.take(), ["drop middle"]); +} + +#[test] +fn a_pin_spanning_live_rows_survives_a_partial_release() { + let (liveness, events) = (Liveness::new(), Events::default()); + let left = liveness.claim(0..4); + let right = liveness.claim(4..8); + pin_rows(&liveness, &events, "a", 2..6); + drop(left); + assert!(events.take().is_empty()); + assert!(liveness.is_claimed(&(2..6))); + drop(right); + assert_eq!(events.take(), ["drop a"]); +} + +#[test] +fn pinning_unclaimed_rows_drops_the_value_at_once() { + let (liveness, events) = (Liveness::new(), Events::default()); + let _claim = liveness.claim(0..4); + assert!(!pin_rows(&liveness, &events, "a", 4..8)); + assert_eq!(events.take(), ["drop a"]); + assert_eq!(liveness.pinned(), 0); +} + +#[test] +fn a_file_lifetime_lasts_until_no_claim_is_live() { + let (liveness, events) = (Liveness::new(), Events::default()); + assert!(!liveness.pin(Lifetime::File, Tracked("early", events.clone()))); + assert_eq!(events.take(), ["drop early"]); + + let first = liveness.claim(0..4); + let second = liveness.claim(100..104); + assert!(liveness.pin(Lifetime::File, Tracked("file", events.clone()))); + drop(first); + assert!(events.take().is_empty()); + drop(second); + assert_eq!(events.take(), ["drop file"]); +} + +/// Cuts its scope into chunks and emits one single-batch morsel per chunk, pinning a value to +/// each chunk first. Its remaining rows are the chunks it has not emitted. +struct Chunker { + chunks: VecDeque>, + end: u64, + liveness: Liveness, + events: Events, + names: VecDeque<&'static str>, + log: scripted::Log, +} + +impl IoConsumer for Chunker { + fn set_io_result(&mut self, _request: IoRequestId, _result: IoResult) { + unreachable!("the chunker publishes no IO") + } +} + +impl Planner for Chunker { + fn state(&self) -> State { + if self.chunks.is_empty() { + State::Done + } else { + State::NeedsCompute + } + } + + fn compute(&mut self) -> VortexResult { + let chunk = self.chunks.pop_front().vortex_expect("a chunk is left"); + let name = self.names.pop_front().vortex_expect("a name is left"); + assert!(pin_rows(&self.liveness, &self.events, name, chunk.clone())); + let morsel = ScriptedMorsel::new( + "morsel", + vec![MorselStep::Compute(MorselOutput::Batch(array_of( + chunk.end - chunk.start, + )))], + &self.log, + ); + Ok(PlannerOutput::Morsel(scope(chunk), Box::new(morsel))) + } + + fn remaining_rows(&self) -> Option> { + Some(self.chunks.front().map_or(self.end, |chunk| chunk.start)..self.end) + } +} + +fn chunker(liveness: &Liveness, events: &Events) -> Box { + Box::new(Chunker { + chunks: VecDeque::from([0..4, 4..8, 8..12]), + end: 12, + liveness: liveness.clone(), + events: events.clone(), + names: VecDeque::from(["0", "1", "2"]), + log: scripted::Log::default(), + }) +} + +fn io() -> Arc { + Arc::new(RecordingIoSource::default()) +} + +#[test] +fn the_driver_drops_each_chunks_values_once_its_morsel_retires() -> VortexResult<()> { + let (liveness, events) = (Liveness::new(), Events::default()); + let mut run = Run::new().with_step_limit(100); + run.admit_with_liveness(chunker(&liveness, &events), scope(0..12), io(), liveness.clone()); + loop { + match run.advance()? { + Progress::Batch(batch) => events.push(format!("batch {:?}", batch.scope.rows)), + Progress::RootDone(_) | Progress::Idle => break, + Progress::Waiting | Progress::Spawn(..) => unreachable!("no IO and no spawns"), + } + } + assert_eq!( + events.take(), + [ + "batch 0..4", + "drop 0", + "batch 4..8", + "drop 1", + "batch 8..12", + "drop 2" + ] + ); + assert_eq!(liveness.pinned(), 0); + assert!(!liveness.is_claimed(&(0..12))); + Ok(()) +} + +#[test] +fn cancelling_a_root_drops_the_values_its_work_held() -> VortexResult<()> { + let (liveness, events) = (Liveness::new(), Events::default()); + let mut run = Run::new().with_step_limit(100); + let root = + run.admit_with_liveness(chunker(&liveness, &events), scope(0..12), io(), liveness.clone()); + assert!(matches!(run.advance()?, Progress::Batch(_))); + assert!(events.take().is_empty()); + run.cancel(root); + assert_eq!(events.take(), ["drop 0"]); + assert!(!liveness.is_claimed(&(0..12))); + Ok(()) +} + +#[test] +fn a_scan_claim_keeps_values_after_the_work_finishes() -> VortexResult<()> { + let (liveness, events) = (Liveness::new(), Events::default()); + let scan = liveness.claim(0..12); + assert!(liveness.pin(Lifetime::File, Tracked("dictionary", events.clone()))); + let mut run = Run::new().with_step_limit(100); + run.admit_with_liveness(chunker(&liveness, &events), scope(0..12), io(), liveness.clone()); + while !matches!(run.advance()?, Progress::Idle) {} + assert!(events.take().is_empty()); + drop(scan); + let mut dropped = events.take(); + dropped.sort(); + assert_eq!(dropped, ["drop 0", "drop 1", "drop 2", "drop dictionary"]); + Ok(()) +} + +/// Reports remaining rows outside the scope it was admitted with. +struct Widening; + +impl IoConsumer for Widening { + fn set_io_result(&mut self, _request: IoRequestId, _result: IoResult) { + unreachable!("publishes no IO") + } +} + +impl Planner for Widening { + fn state(&self) -> State { + State::NeedsCompute + } + + fn compute(&mut self) -> VortexResult { + Ok(PlannerOutput::Continue) + } + + fn remaining_rows(&self) -> Option> { + Some(0..16) + } +} + +#[test] +fn remaining_rows_outside_the_claim_are_rejected() { + let mut run = Run::new().with_step_limit(100); + run.admit_with_liveness(Box::new(Widening), scope(0..8), io(), Liveness::new()); + let error = run.advance().err().vortex_expect("widening must fail"); + assert!( + error.to_string().contains("outside its claim"), + "unexpected error: {error}" + ); +} diff --git a/vortex-scan/src/planning/driver/mod.rs b/vortex-scan/src/planning/driver/mod.rs index db5baec3f2e..dca55f859f3 100644 --- a/vortex-scan/src/planning/driver/mod.rs +++ b/vortex-scan/src/planning/driver/mod.rs @@ -15,8 +15,12 @@ //! for IO, and the caller decides how to wait, by awaiting [`Run::poll_completion`] or by handing //! a completion it took from a source to [`Run::complete`]. [`Driver::run`] is the blocking //! convenience for one root. +//! +//! A root admitted with [`Run::admit_with_liveness`] also reports which rows its live work may +//! still touch, so values pinned to those rows are dropped once no work needs them. See +//! [`Liveness`]. -mod reads; +mod liveness; use std::collections::BTreeMap; use std::collections::VecDeque; @@ -24,10 +28,9 @@ use std::sync::Arc; use std::task::Context; use std::task::Poll; -pub use reads::FileReads; -pub use reads::ReadLifetime; -pub use reads::ReadLifetimes; -pub use reads::RowClaim; +pub use liveness::Lifetime; +pub use liveness::Liveness; +pub use liveness::RowClaim; use vortex_array::ArrayRef; use vortex_error::VortexResult; use vortex_error::vortex_bail; @@ -105,6 +108,9 @@ struct Work { next_child: u64, /// Published `Fetch` requests not yet delivered, with the target each must be answered with. outstanding: HashMap, + /// The rows this item may still touch, when its root tracks liveness. Dropping the item + /// releases them. + claim: Option, } impl Work { @@ -150,6 +156,32 @@ impl Work { self.consumer().set_io_result(request, result); Ok(()) } + + /// Narrows the item's claim to the rows it reports it may still touch. + fn narrow(&mut self) -> VortexResult<()> { + let Some(claim) = &mut self.claim else { + return Ok(()); + }; + let remaining = match &self.item { + Item::Planner(planner) => planner.remaining_rows(), + Item::Morsel(morsel) => morsel.remaining_rows(), + }; + let Some(rows) = remaining else { + return Ok(()); + }; + let claimed = claim.rows(); + if rows == *claimed { + return Ok(()); + } + if rows.start > rows.end || rows.start < claimed.start || rows.end > claimed.end { + vortex_bail!( + "work for scope {:?} reported remaining rows {rows:?} outside its claim {claimed:?}", + self.scope + ); + } + claim.restrict_to(rows); + Ok(()) + } } /// Keeps scheduling order separate from lookup for deliveries to runnable work. @@ -184,10 +216,12 @@ impl ReadyQueue { /// Poll IO even when one high-priority branch keeps producing CPU work. const IO_POLL_INTERVAL: usize = 64; -/// One admitted root: the session its descendants read through, and how many of them are live. +/// One admitted root: the session its descendants read through, how many of them are live, and +/// the liveness their claims report to. struct Root { io: Arc, live: usize, + liveness: Option, } /// A set of root planners advanced by its caller on one thread at a time. @@ -238,10 +272,41 @@ impl Run { root: Box, scope: WorkScope, io: Arc, + ) -> RootId { + self.admit_root(root, scope, io, None) + } + + /// Admits `root` like [`admit`](Self::admit), and has the root and every item descended from + /// it claim its scope's rows in `liveness` while it is live. + /// + /// Every root of one file should report to the same liveness, whichever run admits it. + pub fn admit_with_liveness( + &mut self, + root: Box, + scope: WorkScope, + io: Arc, + liveness: Liveness, + ) -> RootId { + self.admit_root(root, scope, io, Some(liveness)) + } + + fn admit_root( + &mut self, + root: Box, + scope: WorkScope, + io: Arc, + liveness: Option, ) -> RootId { let id = RootId(self.next_root); self.next_root += 1; - self.roots.insert(id, Root { io, live: 0 }); + self.roots.insert( + id, + Root { + io, + live: 0, + liveness, + }, + ); self.spawn(id, scope, Item::Planner(root), vec![id.0]); id } @@ -387,8 +452,13 @@ impl Run { fn spawn(&mut self, root: RootId, scope: WorkScope, item: Item, path: Vec) { let id = IoOwnerId(self.next_owner); self.next_owner += 1; + let mut claim = None; if let Some(root) = self.roots.get_mut(&root) { root.live += 1; + claim = root + .liveness + .as_ref() + .map(|liveness| liveness.claim(scope.rows.clone())); } let work = Box::new(Work { id, @@ -398,6 +468,7 @@ impl Run { path, next_child: 0, outstanding: HashMap::default(), + claim, }); self.queue.insert(work); } @@ -454,25 +525,34 @@ impl Run { self.retire(&work); } Output::Planner(PlannerOutput::Continue) | Output::Morsel(MorselOutput::Continue) => { + work.narrow()?; self.queue.insert(work); } Output::Planner(PlannerOutput::NeedsIO(batch)) | Output::Morsel(MorselOutput::NeedsIO(batch)) => { + work.narrow()?; self.submit(&mut work, batch)?; self.settle(work)?; } + // A child claims its rows when it is spawned, before its parent narrows, so rows + // handed from parent to child are never left unclaimed in between. Output::Planner(PlannerOutput::Planner(scope, child)) => { let path = work.child_path(); self.spawn(work.root, scope, Item::Planner(child), path); + work.narrow()?; self.queue.insert(work); } Output::Planner(PlannerOutput::Morsel(scope, morsel)) => { let path = work.child_path(); self.spawn(work.root, scope, Item::Morsel(morsel), path); + work.narrow()?; self.queue.insert(work); } + // The owner admits an independent child later, possibly on another run, so its rows + // are unclaimed in between unless the owner holds a claim over them. Output::Planner(PlannerOutput::Spawn(scope, child)) => { self.events.push_back(Progress::Spawn(scope, child)); + work.narrow()?; self.queue.insert(work); } Output::Morsel(MorselOutput::Batch(array)) => { @@ -484,6 +564,7 @@ impl Run { scope: work.scope.clone(), array, })); + work.narrow()?; self.queue.insert(work); } } diff --git a/vortex-scan/src/planning/driver/reads/mod.rs b/vortex-scan/src/planning/driver/reads/mod.rs deleted file mode 100644 index 098c58b1265..00000000000 --- a/vortex-scan/src/planning/driver/reads/mod.rs +++ /dev/null @@ -1,342 +0,0 @@ -// SPDX-License-Identifier: Apache-2.0 -// SPDX-FileCopyrightText: Copyright the Vortex contributors - -//! File-execution read sharing, bounded by unfinished consumer row ranges. - -mod progress; -#[cfg(test)] -mod tests; - -use std::collections::BTreeMap; -use std::collections::VecDeque; -use std::future::poll_fn; -use std::ops::Range; -use std::sync::Arc; -use std::task::Context; -use std::task::Poll; -use std::task::Wake; -use std::task::Waker; -use std::thread; - -use futures::FutureExt; -use futures::StreamExt; -use futures::future::AbortHandle; -use futures::future::Abortable; -use futures::future::BoxFuture; -use futures::future::Shared; -use futures::stream::FuturesUnordered; -use parking_lot::Mutex; -use vortex_error::SharedVortexResult; -use vortex_error::VortexError; -use vortex_error::VortexResult; -use vortex_error::vortex_ensure; -use vortex_error::vortex_err; -use vortex_io::request::Completion; -use vortex_io::request::IoBatch; -use vortex_io::request::IoIntent; -use vortex_io::request::IoOwnerId; -use vortex_io::request::IoRequest; -use vortex_io::request::IoRequestId; -use vortex_io::request::IoResult; -use vortex_io::request::IoService; -use vortex_io::request::IoSource; -use vortex_io::request::IoTarget; -use vortex_utils::aliases::hash_map::Entry; -use vortex_utils::aliases::hash_map::HashMap; - -pub use self::progress::RowClaim; - -/// The possible consumers of a read, expressed in the file's root row domain. -#[derive(Clone, Debug, PartialEq, Eq)] -pub enum ReadLifetime { - /// Only consumers overlapping this range can need the read. - Rows(Range), - /// No tighter bound is known; keep the read until the file execution ends. - File, -} - -/// Conservative read lifetimes derived by the layout planner. Missing targets live to file end. -pub type ReadLifetimes = Arc>; - -type SharedRead = Shared>>; - -/// Read sharing for one execution over one file, across all its workers and queued work. -/// -/// Reserve the scan's rows with [`claim`](Self::claim), then move and split that claim with -/// the work. Queued work retains its claim before any worker takes it. Completed reads and -/// unconsumed hints expire when no claim overlaps their consumer range. Dropping the last nonempty -/// claim clears even file-lifetime reads, independently of the service or prepared plan lifetime. -#[derive(Clone)] -pub struct FileReads { - transport: Arc, - lifetimes: ReadLifetimes, - state: Arc>, -} - -#[derive(Default)] -struct ReadState { - claims: progress::Claims, - entries: HashMap, - expiry: BTreeMap>, -} - -struct ReadEntry { - transport: Arc, - read: Option, - rows: Option>, - announced: bool, -} - -/// One target's transport scope. Clearing it also releases unused announcements on eviction. -struct ReadTransport(Arc); - -impl Drop for ReadTransport { - fn drop(&mut self) { - self.0.clear(); - } -} - -impl FileReads { - /// Creates fresh sharing state for one file execution. Lifetimes may be reused across - /// executions, but the service itself must not be shared with another execution or file. - pub fn new(transport: Arc, lifetimes: ReadLifetimes) -> Self { - Self { - transport, - lifetimes, - state: Arc::default(), - } - } - - /// Reserves the initial rows before any work runs. Descendants receive splits or shares - /// of this claim; they must not register fresh ranges after those rows have been released. - pub fn claim(&self, rows: Range) -> RowClaim { - RowClaim::new(self.clone(), rows) - } - - fn request(&self, request: IoRequest) -> VortexResult> { - let mut state = self.state.lock(); - vortex_ensure!( - !state.claims.is_empty(), - "file reads require a live row claim" - ); - let ReadState { - entries, expiry, .. - } = &mut *state; - let entry = match entries.entry(request.target) { - Entry::Occupied(entry) => entry.into_mut(), - Entry::Vacant(entry) => { - let lifetime = self - .lifetimes - .get(&request.target) - .cloned() - .unwrap_or(ReadLifetime::File); - let rows = match lifetime { - ReadLifetime::Rows(rows) => { - expiry.entry(rows.end).or_default().push(request.target); - Some(rows) - } - ReadLifetime::File => None, - }; - entry.insert(ReadEntry { - transport: Arc::new(ReadTransport(self.transport.session())), - read: None, - rows, - announced: false, - }) - } - }; - if request.intent == IoIntent::Announce { - if entry.read.is_none() && !entry.announced { - entry.transport.0.submit( - IoOwnerId(0), - vec![IoRequest { - request: IoRequestId(0), - ..request - }], - )?; - entry.announced = true; - } - return Ok(None); - } - if let Some(read) = &entry.read { - return Ok(Some(read.clone())); - } - // Prefetches become internal fetches: the coordinator owns their result, and only a - // subscribing fetch gets a completion under its original owner and request identity. - entry.transport.0.submit( - IoOwnerId(0), - vec![IoRequest { - intent: IoIntent::Fetch, - request: IoRequestId(0), - ..request - }], - )?; - let transport = Arc::clone(&entry.transport); - let read = async move { - let completion = poll_fn(|cx| transport.0.poll_completion(cx)).await?; - vortex_ensure!( - completion.owner == IoOwnerId(0) && completion.request == IoRequestId(0), - "transport completed an unknown read" - ); - let result = completion.result?; - if !result.matches(&request.target) { - return Err(vortex_err!( - "read of {:?} returned {}", - request.target, - result.kind() - )); - } - Ok(result) - } - .map(|result: VortexResult| result.map_err(Arc::new)) - .boxed() - .shared(); - entry.read = Some(read.clone()); - Ok(Some(read)) - } -} - -impl IoService for FileReads { - fn session(&self) -> Arc { - Arc::new(ReadSession { - file: self.clone(), - pending: Mutex::default(), - }) - } -} - -#[derive(Default)] -struct Pending { - reads: FuturesUnordered>>, - ready: VecDeque, - subscriptions: HashMap<(IoOwnerId, IoRequestId), AbortHandle>, -} - -struct ReadSession { - file: FileReads, - pending: Mutex, -} - -impl ReadSession { - fn next(&self, cx: &mut Context<'_>) -> Poll> { - let mut pending = self.pending.lock(); - if let Some(completion) = pending.ready.pop_front() { - return Poll::Ready(Some(completion)); - } - loop { - match pending.reads.poll_next_unpin(cx) { - Poll::Ready(Some(Some(completion))) => { - pending - .subscriptions - .remove(&(completion.owner, completion.request)); - return Poll::Ready(Some(completion)); - } - Poll::Ready(Some(None)) => continue, - Poll::Ready(None) => return Poll::Ready(None), - Poll::Pending => return Poll::Pending, - } - } - } -} - -impl IoSource for ReadSession { - fn submit(&self, owner: IoOwnerId, batch: IoBatch) -> VortexResult<()> { - let mut pending = self.pending.lock(); - let mut reads = Vec::with_capacity(batch.len()); - for request in batch { - if let Some(read) = self.file.request(request)? { - reads.push((request, read)); - } - } - for (request, mut read) in reads { - let ready = read.poll_unpin(&mut Context::from_waker(Waker::noop())); - if request.intent == IoIntent::Prefetch { - if let Poll::Ready(Err(error)) = ready { - return Err(VortexError::from(error)); - } - continue; - } - // Cached and in-memory reads need no asynchronous subscription allocation. - if let Poll::Ready(result) = ready { - pending.ready.push_back(Completion { - owner, - request: request.request, - result: result.map_err(VortexError::from), - }); - continue; - } - let (abort, registration) = AbortHandle::new_pair(); - pending - .subscriptions - .insert((owner, request.request), abort); - let completion = async move { - Completion { - owner, - request: request.request, - result: read.await.map_err(VortexError::from), - } - }; - pending.reads.push( - Abortable::new(completion, registration) - .map(Result::ok) - .boxed(), - ); - } - Ok(()) - } - - fn poll(&self) -> VortexResult> { - Ok(match self.next(&mut Context::from_waker(Waker::noop())) { - Poll::Ready(completion) => completion, - Poll::Pending => None, - }) - } - - fn poll_completion(&self, cx: &mut Context<'_>) -> Poll> { - match self.next(cx) { - Poll::Ready(Some(completion)) => Poll::Ready(Ok(completion)), - Poll::Ready(None) => Poll::Ready(Err(vortex_err!("waiting with no reads in flight"))), - Poll::Pending => Poll::Pending, - } - } - - fn wait(&self) -> VortexResult { - let waker = Waker::from(Arc::new(ThreadWake(thread::current()))); - let mut cx = Context::from_waker(&waker); - loop { - match self.poll_completion(&mut cx) { - Poll::Ready(completion) => return completion, - Poll::Pending => thread::park(), - } - } - } - - fn release(&self, owner: IoOwnerId) { - let mut pending = self.pending.lock(); - pending.ready.retain(|completion| completion.owner != owner); - pending.subscriptions.retain(|(subscriber, _), abort| { - if *subscriber == owner { - abort.abort(); - false - } else { - true - } - }); - } - - fn clear(&self) { - *self.pending.lock() = Pending::default(); - } -} - -struct ThreadWake(thread::Thread); - -impl Wake for ThreadWake { - fn wake(self: Arc) { - self.0.unpark(); - } - - fn wake_by_ref(self: &Arc) { - self.0.unpark(); - } -} diff --git a/vortex-scan/src/planning/driver/reads/progress.rs b/vortex-scan/src/planning/driver/reads/progress.rs deleted file mode 100644 index 31e5b2e4b70..00000000000 --- a/vortex-scan/src/planning/driver/reads/progress.rs +++ /dev/null @@ -1,252 +0,0 @@ -// SPDX-License-Identifier: Apache-2.0 -// SPDX-FileCopyrightText: Copyright the Vortex contributors - -//! Owned row claims travel with queued and running work. - -use std::collections::BTreeMap; -use std::ops::Bound::Excluded; -use std::ops::Bound::Included; -use std::ops::Range; - -use vortex_error::VortexExpect; - -use super::FileReads; -use super::ReadEntry; -use super::ReadState; - -/// Disjoint spans with the number of owners covering each span. Splitting ownership does not -/// change coverage; only sharing and releasing rows touch this index. -#[derive(Default)] -pub(super) struct Claims(BTreeMap); - -#[derive(Clone, Copy)] -struct Span { - end: u64, - owners: usize, -} - -impl Claims { - pub(super) fn is_empty(&self) -> bool { - self.0.is_empty() - } - - fn split_at(&mut self, row: u64) { - if let Some((&start, &span)) = self.0.range(..row).next_back() - && row < span.end - { - self.0.get_mut(&start).vortex_expect("span exists").end = row; - self.0.insert(row, span); - } - } - - fn join_at(&mut self, row: u64) { - if let Some((&start, &left)) = self.0.range(..row).next_back() - && let Some(&right) = self.0.get(&row) - && left.end == row - && left.owners == right.owners - { - self.0.get_mut(&start).vortex_expect("span exists").end = right.end; - self.0.remove(&row); - } - } - - fn add(&mut self, rows: &Range) { - if rows.is_empty() { - return; - } - self.split_at(rows.start); - self.split_at(rows.end); - let starts: Vec<_> = self - .0 - .range(rows.clone()) - .map(|(&start, _)| start) - .collect(); - let mut cursor = rows.start; - for start in starts { - if cursor < start { - self.0.insert( - cursor, - Span { - end: start, - owners: 1, - }, - ); - } - let span = self.0.get_mut(&start).vortex_expect("span exists"); - span.owners += 1; - cursor = span.end; - } - if cursor < rows.end { - self.0.insert( - cursor, - Span { - end: rows.end, - owners: 1, - }, - ); - } - self.join_at(rows.start); - self.join_at(rows.end); - } - - /// Returns newly uncovered gaps, including adjacent rows already released by other parts. - fn release(&mut self, rows: &Range) -> Vec> { - if rows.is_empty() { - return Vec::new(); - } - self.split_at(rows.start); - self.split_at(rows.end); - let starts: Vec<_> = self - .0 - .range(rows.clone()) - .map(|(&start, _)| start) - .collect(); - let mut removed = Vec::new(); - for start in starts { - let span = self.0.get_mut(&start).vortex_expect("span exists"); - span.owners -= 1; - if span.owners == 0 { - self.0.remove(&start); - removed.push(start); - } - } - self.join_at(rows.start); - self.join_at(rows.end); - let mut gaps = Vec::new(); - for row in removed { - let start = self - .0 - .range(..row) - .next_back() - .map_or(0, |(_, span)| span.end); - let end = self - .0 - .range(row..) - .next() - .map_or(u64::MAX, |(&start, _)| start); - let gap = start..end; - if gaps.last() != Some(&gap) { - gaps.push(gap); - } - } - gaps - } -} - -impl ReadState { - /// Return evicted entries so transport cancellation runs outside the state lock. - fn release(&mut self, rows: &Range) -> Vec { - let gaps = self.claims.release(rows); - if self.claims.is_empty() { - self.expiry.clear(); - return self.entries.drain().map(|(_, entry)| entry).collect(); - } - let mut evicted = Vec::new(); - for gap in gaps { - let ends: Vec<_> = self - .expiry - .range((Excluded(gap.start), Included(gap.end))) - .map(|(&end, _)| end) - .collect(); - for end in ends { - let targets = self.expiry.get_mut(&end).vortex_expect("expiry exists"); - targets.retain(|target| { - let entry = self.entries.get(target).vortex_expect("read exists"); - if entry - .rows - .as_ref() - .is_some_and(|rows| rows.start >= gap.start) - { - evicted.push(self.entries.remove(target).vortex_expect("read exists")); - false - } else { - true - } - }); - if targets.is_empty() { - self.expiry.remove(&end); - } - } - } - evicted - } -} - -/// An owned reservation for rows that may still read from a file execution. -/// -/// Move the claim with work through queues and planner handoffs. Split it before handing off -/// disjoint children; dropping it marks its remaining rows finished or cancelled. Output batches -/// must not own claims, since retaining a batch does not imply any future file reads. -#[must_use = "dropping a row claim releases its rows"] -pub struct RowClaim { - file: FileReads, - rows: Range, -} - -impl RowClaim { - pub(super) fn new(file: FileReads, rows: Range) -> Self { - assert!(rows.start <= rows.end, "claim rows must be ordered"); - file.state.lock().claims.add(&rows); - Self { file, rows } - } - - /// The file-local rows this claim still reserves. - pub fn rows(&self) -> &Range { - &self.rows - } - - /// Transfers the prefix ending at `end` into a child claim, keeping the suffix in `self`. - /// Coverage is unchanged, so splitting requires no lock or registration updates. - /// Panics if `end` is outside this claim's range. - pub fn split_to(&mut self, end: u64) -> Self { - assert!( - self.rows.contains(&end) || end == self.rows.end, - "split must lie within the claim" - ); - let rows = self.rows.start..end; - self.rows.start = end; - Self { - file: self.file.clone(), - rows, - } - } - - /// Releases rows proven unnecessary, retaining only the given subrange. - /// Panics if the range is not ordered and contained in this claim. - pub fn restrict_to(&mut self, rows: Range) { - assert!( - self.rows.start <= rows.start && rows.start <= rows.end && rows.end <= self.rows.end, - "remaining rows must be contained in the claim" - ); - if self.rows == rows { - return; - } - let evicted = { - let mut state = self.file.state.lock(); - let mut evicted = state.release(&(self.rows.start..rows.start)); - evicted.extend(state.release(&(rows.end..self.rows.end))); - self.rows = rows; - evicted - }; - drop(evicted); - } - - /// Creates another owner for the same rows, for consumers that overlap rather than split. - /// Each owner's remaining rows stay registered until that owner releases them. - pub fn share(&self) -> Self { - Self::new(self.file.clone(), self.rows.clone()) - } -} - -impl Drop for RowClaim { - fn drop(&mut self) { - if self.rows.is_empty() { - return; - } - let evicted = { - let mut state = self.file.state.lock(); - state.release(&self.rows) - }; - drop(evicted); - } -} diff --git a/vortex-scan/src/planning/driver/reads/tests.rs b/vortex-scan/src/planning/driver/reads/tests.rs deleted file mode 100644 index 1c4f5eddfa5..00000000000 --- a/vortex-scan/src/planning/driver/reads/tests.rs +++ /dev/null @@ -1,762 +0,0 @@ -// SPDX-License-Identifier: Apache-2.0 -// SPDX-FileCopyrightText: Copyright the Vortex contributors - -use std::collections::VecDeque; -use std::sync::Weak; -use std::sync::atomic::AtomicBool; -use std::sync::atomic::AtomicUsize; -use std::sync::atomic::Ordering; - -use futures::task::AtomicWaker; -use rstest::rstest; -use vortex_array::buffer::BufferHandle; -use vortex_buffer::ByteBuffer; -use vortex_io::request::IoConsumer; - -use super::*; -use crate::planning::driver::Progress; -use crate::planning::driver::Run; -use crate::planning::planner::Planner; -use crate::planning::planner::PlannerOutput; -use crate::planning::planner::State; -use crate::planning::planner::WorkScope; - -#[derive(Default)] -struct Control { - reads: AtomicUsize, - announcements: AtomicUsize, - clears: AtomicUsize, - ready: AtomicBool, - fail: AtomicBool, - sources: Mutex>>, -} - -impl Control { - fn complete(&self) { - self.ready.store(true, Ordering::SeqCst); - for source in self.sources.lock().iter().filter_map(Weak::upgrade) { - source.waker.wake(); - } - } -} - -struct TestService(Arc); - -impl IoService for TestService { - fn session(&self) -> Arc { - let source = Arc::new(TestSource { - control: Arc::clone(&self.0), - ready: Mutex::default(), - waker: AtomicWaker::new(), - }); - self.0.sources.lock().push(Arc::downgrade(&source)); - source - } -} - -struct TestSource { - control: Arc, - ready: Mutex>, - waker: AtomicWaker, -} - -impl IoSource for TestSource { - fn submit(&self, owner: IoOwnerId, batch: IoBatch) -> VortexResult<()> { - for request in batch { - if request.intent == IoIntent::Announce { - self.control.announcements.fetch_add(1, Ordering::SeqCst); - continue; - } - self.control.reads.fetch_add(1, Ordering::SeqCst); - self.ready.lock().push_back(Completion { - owner, - request: request.request, - result: if self.control.fail.load(Ordering::SeqCst) { - Err(vortex_err!("transport failure")) - } else { - Ok(IoResult::Bytes(BufferHandle::new_host(ByteBuffer::from( - vec![ - 7; - match request.target { - IoTarget::Range { len, .. } => len, - _ => 4, - } - ], - )))) - }, - }); - } - Ok(()) - } - - fn poll(&self) -> VortexResult> { - Ok(if self.control.ready.load(Ordering::SeqCst) { - self.ready.lock().pop_front() - } else { - None - }) - } - - fn poll_completion(&self, cx: &mut Context<'_>) -> Poll> { - self.waker.register(cx.waker()); - match self.poll()? { - Some(completion) => Poll::Ready(Ok(completion)), - None => Poll::Pending, - } - } - - fn wait(&self) -> VortexResult { - self.poll()? - .ok_or_else(|| vortex_err!("test source is not ready")) - } - - fn release(&self, owner: IoOwnerId) { - self.ready - .lock() - .retain(|completion| completion.owner != owner); - } - - fn clear(&self) { - self.control.clears.fetch_add(1, Ordering::SeqCst); - self.ready.lock().clear(); - } -} - -fn file(control: &Arc) -> FileReads { - FileReads::new( - Arc::new(TestService(Arc::clone(control))), - Arc::new( - [ - (IoTarget::range(0, 4), ReadLifetime::Rows(0..20)), - (IoTarget::range(4, 4), ReadLifetime::Rows(20..40)), - (IoTarget::range(8, 4), ReadLifetime::File), - ] - .into_iter() - .collect(), - ), - ) -} - -fn request(intent: IoIntent, id: u32, offset: u64) -> IoRequest { - IoRequest { - intent, - request: IoRequestId(id), - target: IoTarget::range(offset, 4), - } -} - -fn retained(file: &FileReads) -> (usize, usize) { - let state = file.state.lock(); - let bytes = state - .entries - .values() - .map( - |entry| match entry.read.as_ref().and_then(SharedRead::peek) { - Some(Ok(IoResult::Bytes(buffer))) => buffer.len(), - _ => 0, - }, - ) - .sum(); - (state.entries.len(), bytes) -} - -#[rstest] -#[case::flat(false)] -#[case::shared_dictionary(true)] -fn part_retention_compared_with_file_watermark( - #[case] dictionary: bool, - #[values(false, true)] bound_start: bool, -) -> VortexResult<()> { - const PARTS: u64 = 32; - const SEGMENT_BYTES: usize = 4096; - const DICTIONARY_BYTES: usize = 16384; - let control = Arc::new(Control::default()); - control.complete(); - let mut lifetimes: HashMap<_, _> = (0..PARTS) - .map(|part| { - ( - IoTarget::range(part * SEGMENT_BYTES as u64, SEGMENT_BYTES), - // Starting every region at zero reproduces the former file-wide watermark: - // a stalled first part keeps every later part's reads alive. - ReadLifetime::Rows(if bound_start { part * 20 } else { 0 }..(part + 1) * 20), - ) - }) - .collect(); - let values = IoTarget::range(PARTS * SEGMENT_BYTES as u64, DICTIONARY_BYTES); - // Values span two parts and must remain shared until both finish. The stalled first - // part and queued later parts cannot read these values. - lifetimes.insert( - values, - ReadLifetime::Rows(if bound_start { 20 } else { 0 }..60), - ); - let file = FileReads::new( - Arc::new(TestService(Arc::clone(&control))), - Arc::new(lifetimes), - ); - let mut remaining = file.claim(0..PARTS * 20); - let first = remaining.split_to(20); - let session = file.session(); - let mut peak = (0, 0); - for part in 0..PARTS { - let work = (part != 0).then(|| remaining.split_to((part + 1) * 20)); - session.submit( - IoOwnerId(0), - vec![IoRequest { - intent: IoIntent::Fetch, - request: IoRequestId(0), - target: IoTarget::range(part * SEGMENT_BYTES as u64, SEGMENT_BYTES), - }], - )?; - session.wait()?.result?; - if dictionary && (1..=2).contains(&part) { - session.submit( - IoOwnerId(0), - vec![IoRequest { - intent: IoIntent::Fetch, - request: IoRequestId(1), - target: values, - }], - )?; - session.wait()?.result?; - } - let current = retained(&file); - peak = (peak.0.max(current.0), peak.1.max(current.1)); - drop(work); - let keep_segments = if bound_start { - 1 - } else { - usize::try_from(part)? + 1 - }; - let keep_values = - usize::from(dictionary && if bound_start { part == 1 } else { part >= 1 }); - assert_eq!( - retained(&file), - ( - keep_segments + keep_values, - keep_segments * SEGMENT_BYTES + keep_values * DICTIONARY_BYTES - ) - ); - } - assert_eq!( - control.reads.load(Ordering::SeqCst), - usize::try_from(PARTS)? + usize::from(dictionary) - ); - let peak_segments = if bound_start { - 2 - } else { - usize::try_from(PARTS)? - }; - assert_eq!( - peak, - ( - peak_segments + usize::from(dictionary), - peak_segments * SEGMENT_BYTES + usize::from(dictionary) * DICTIONARY_BYTES - ) - ); - drop(first); - assert_eq!(retained(&file), (0, 0)); - Ok(()) -} - -#[test] -fn overlapping_claims_release_only_uncovered_segments() -> VortexResult<()> { - let control = Arc::new(Control::default()); - control.complete(); - let file = file(&control); - let mut original = file.claim(0..60); - let mut overlap = original.share(); - overlap.restrict_to(10..30); - let session = file.session(); - for offset in [0, 4] { - session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, offset)])?; - session.wait()?.result?; - } - original.restrict_to(40..60); - assert_eq!(retained(&file), (2, 8)); - overlap.restrict_to(20..30); - assert_eq!(retained(&file), (1, 4)); - drop(overlap); - assert_eq!(retained(&file), (0, 0)); - Ok(()) -} - -#[test] -fn trimming_a_claim_releases_segments_on_both_sides() -> VortexResult<()> { - let control = Arc::new(Control::default()); - control.complete(); - let file = file(&control); - let mut claim = file.claim(0..40); - let session = file.session(); - for offset in [0, 4] { - session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, offset)])?; - session.wait()?.result?; - } - claim.restrict_to(0..20); - assert_eq!(retained(&file), (1, 4)); - claim.restrict_to(10..10); - assert_eq!(retained(&file), (0, 0)); - Ok(()) -} - -#[rstest] -#[case::forward([0, 1, 2, 3])] -#[case::reverse([3, 2, 1, 0])] -#[case::outside_in([0, 3, 1, 2])] -#[case::inside_out([1, 2, 0, 3])] -fn eviction_matches_remaining_consumers(#[case] order: [usize; 4]) -> VortexResult<()> { - let control = Arc::new(Control::default()); - control.complete(); - let regions: Vec<_> = (0..80) - .step_by(10) - .flat_map(|start| (start + 10..=80).step_by(10).map(move |end| start..end)) - .collect(); - let lifetimes = regions - .iter() - .enumerate() - .map(|(index, rows)| { - ( - IoTarget::range(index as u64 * 4, 4), - ReadLifetime::Rows(rows.clone()), - ) - }) - .collect(); - let file = FileReads::new( - Arc::new(TestService(Arc::clone(&control))), - Arc::new(lifetimes), - ); - let mut root = file.claim(0..80); - let mut overlap = root.share(); - overlap.restrict_to(10..70); - let mut parts: Vec<_> = (1..=4).map(|part| Some(root.split_to(part * 20))).collect(); - let session = file.session(); - for index in 0..regions.len() { - session.submit( - IoOwnerId(0), - vec![request(IoIntent::Fetch, 0, index as u64 * 4)], - )?; - session.wait()?.result?; - } - for (step, index) in order.into_iter().enumerate() { - drop(parts[index].take()); - if step == 1 { - overlap.restrict_to(30..50); - } - let expected = regions - .iter() - .filter(|region| { - parts - .iter() - .flatten() - .chain(std::iter::once(&overlap)) - .any(|claim| claim.rows().start < region.end && region.start < claim.rows().end) - }) - .count(); - assert_eq!(retained(&file), (expected, expected * 4)); - } - drop(overlap); - assert_eq!(retained(&file), (0, 0)); - Ok(()) -} - -struct Hold { - _claim: RowClaim, -} - -impl IoConsumer for Hold { - fn set_io_result(&mut self, _request: IoRequestId, _result: IoResult) {} -} - -impl Planner for Hold { - fn state(&self) -> State { - State::NeedsCompute - } - - fn compute(&mut self) -> VortexResult { - Ok(PlannerOutput::Done) - } -} - -#[test] -fn completed_parts_release_reads_before_earlier_parts_finish() -> VortexResult<()> { - let control = Arc::new(Control::default()); - control.complete(); - let file = file(&control); - let mut third = file.claim(0..60); - let first = third.split_to(20); - let second = third.split_to(40); - let session = file.session(); - for (id, offset) in [0, 4, 8].into_iter().enumerate() { - session.submit( - IoOwnerId(0), - vec![request(IoIntent::Fetch, u32::try_from(id)?, offset)], - )?; - session.wait()?.result?; - } - drop(second); - assert_eq!(control.clears.load(Ordering::SeqCst), 1); - drop(first); - assert_eq!(control.clears.load(Ordering::SeqCst), 2); - drop(third); - assert_eq!(control.clears.load(Ordering::SeqCst), 3); - // The engine may still hold the service and session after all the file's work has ended. - assert!(file.state.lock().entries.is_empty()); - assert!(session.poll()?.is_none()); - Ok(()) -} - -#[test] -fn sequential_sessions_reuse_reads_until_the_region_finishes() -> VortexResult<()> { - let control = Arc::new(Control::default()); - control.complete(); - let file = file(&control); - let work = file.claim(0..20); - for id in 0..3 { - let session = file.session(); - session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, id, 0)])?; - assert_eq!(session.wait()?.request, IoRequestId(id)); - session.clear(); - } - assert_eq!(control.reads.load(Ordering::SeqCst), 1); - drop(work); - assert_eq!(control.clears.load(Ordering::SeqCst), 1); - Ok(()) -} - -#[rstest] -fn prefetch_and_fetch_share_one_read(#[values(false, true)] prefetch: bool) -> VortexResult<()> { - let control = Arc::new(Control::default()); - let file = file(&control); - let _work = file.claim(0..20); - let first = file.session(); - let second = file.session(); - let intent = if prefetch { - IoIntent::Prefetch - } else { - IoIntent::Fetch - }; - first.submit(IoOwnerId(0), vec![request(intent, 0, 0)])?; - second.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; - assert_eq!(control.reads.load(Ordering::SeqCst), 1); - assert!(first.poll()?.is_none()); - assert!(second.poll()?.is_none()); - // Cancelling the initiating session must not cancel the other session's shared read. - first.clear(); - control.complete(); - second.wait()?.result?; - assert!(first.poll()?.is_none()); - Ok(()) -} - -#[derive(Default)] -struct WakeCount(AtomicUsize); - -impl Wake for WakeCount { - fn wake(self: Arc) { - self.0.fetch_add(1, Ordering::SeqCst); - } -} - -#[test] -fn completion_wakes_every_worker_and_preserves_request_identity() -> VortexResult<()> { - let control = Arc::new(Control::default()); - let file = file(&control); - let _work = file.claim(0..20); - let workers: Vec<_> = (0..2) - .map(|_| (file.session(), Arc::new(WakeCount::default()))) - .collect(); - for (index, (session, wake)) in workers.iter().enumerate() { - session.submit( - IoOwnerId(9), - vec![request(IoIntent::Fetch, u32::try_from(index)?, 0)], - )?; - let waker = Waker::from(Arc::clone(wake)); - assert!( - session - .poll_completion(&mut Context::from_waker(&waker)) - .is_pending() - ); - wake.0.store(0, Ordering::SeqCst); - } - control.complete(); - for (index, (session, wake)) in workers.iter().enumerate() { - assert!(wake.0.load(Ordering::SeqCst) > 0); - let completion = session.wait()?; - assert_eq!(completion.owner, IoOwnerId(9)); - assert_eq!(completion.request, IoRequestId(u32::try_from(index)?)); - completion.result?; - } - assert_eq!(control.reads.load(Ordering::SeqCst), 1); - Ok(()) -} - -#[test] -fn read_errors_reach_every_subscriber() -> VortexResult<()> { - let control = Arc::new(Control::default()); - control.fail.store(true, Ordering::SeqCst); - control.complete(); - let file = file(&control); - let _work = file.claim(0..20); - for _ in 0..2 { - let session = file.session(); - session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; - let error = session.wait()?.result.expect_err("transport fails"); - assert!(error.to_string().contains("transport failure")); - } - assert_eq!(control.reads.load(Ordering::SeqCst), 1); - Ok(()) -} - -#[test] -fn duplicate_announcements_share_one_hint_and_expire_with_their_region() -> VortexResult<()> { - let control = Arc::new(Control::default()); - let file = file(&control); - let mut remaining = file.claim(0..40); - let first = remaining.split_to(20); - let session = file.session(); - session.submit( - IoOwnerId(0), - vec![ - request(IoIntent::Announce, 0, 0), - request(IoIntent::Announce, 1, 0), - ], - )?; - assert_eq!(control.announcements.load(Ordering::SeqCst), 1); - assert_eq!(control.reads.load(Ordering::SeqCst), 0); - drop(first); - assert_eq!(control.clears.load(Ordering::SeqCst), 1); - Ok(()) -} - -struct Producer(RowClaim); - -impl IoConsumer for Producer { - fn set_io_result(&mut self, _request: IoRequestId, _result: IoResult) {} -} - -impl Planner for Producer { - fn state(&self) -> State { - if self.0.rows().is_empty() { - State::Done - } else { - State::NeedsCompute - } - } - - fn compute(&mut self) -> VortexResult { - let end = self.0.rows().start + 20; - let claim = self.0.split_to(end); - let rows = claim.rows().clone(); - Ok(PlannerOutput::Spawn( - WorkScope { - file_ordinal: 0, - rows, - }, - Box::new(Hold { _claim: claim }), - )) - } -} - -#[test] -fn queued_children_keep_reads_live_across_run_handoffs() -> VortexResult<()> { - let control = Arc::new(Control::default()); - control.complete(); - let file = file(&control); - let root = Box::new(Producer(file.claim(0..40))); - let io = file.session(); - io.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; - io.wait()?.result?; - let mut producer = Run::new(); - producer.admit( - root, - WorkScope { - file_ordinal: 0, - rows: 0..40, - }, - io, - ); - let Progress::Spawn(first_scope, first) = producer.advance()? else { - panic!("first child") - }; - let Progress::Spawn(_, second) = producer.advance()? else { - panic!("second child") - }; - drop(producer); - assert_eq!(control.clears.load(Ordering::SeqCst), 0); - // The first child remains registered while in the engine's queue, then on another run. - let mut worker = Run::new(); - worker.admit(first, first_scope, file.session()); - assert!(matches!(worker.advance()?, Progress::RootDone(_))); - assert_eq!(control.clears.load(Ordering::SeqCst), 1); - drop(second); - assert!(file.state.lock().entries.is_empty()); - Ok(()) -} - -#[test] -fn executions_do_not_share_identical_byte_ranges() -> VortexResult<()> { - let control = Arc::new(Control::default()); - control.complete(); - for _ in 0..2 { - let file = file(&control); - let _work = file.claim(0..20); - let session = file.session(); - session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; - session.wait()?.result?; - } - assert_eq!(control.reads.load(Ordering::SeqCst), 2); - assert_eq!(control.clears.load(Ordering::SeqCst), 2); - Ok(()) -} - -#[rstest] -fn cancellation_releases_pending_reads(#[values(false, true)] cancel: bool) -> VortexResult<()> { - let control = Arc::new(Control::default()); - let file = file(&control); - let root = Box::new(Hold { - _claim: file.claim(0..20), - }); - let session = file.session(); - session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; - let mut run = Run::new(); - let root = run.admit( - root, - WorkScope { - file_ordinal: 0, - rows: 0..20, - }, - Arc::clone(&session), - ); - if cancel { - run.cancel(root); - } else { - drop(run); - } - assert_eq!(control.clears.load(Ordering::SeqCst), 1); - assert!(file.state.lock().entries.is_empty()); - assert!(session.poll()?.is_none()); - Ok(()) -} - -#[test] -fn releasing_one_owner_preserves_other_subscriptions() -> VortexResult<()> { - let control = Arc::new(Control::default()); - let file = file(&control); - let _work = file.claim(0..20); - let session = file.session(); - for owner in 0..2 { - session.submit(IoOwnerId(owner), vec![request(IoIntent::Fetch, 0, 0)])?; - } - session.release(IoOwnerId(0)); - control.complete(); - let completion = session.wait()?; - assert_eq!(completion.owner, IoOwnerId(1)); - completion.result?; - assert!(session.poll()?.is_none()); - assert_eq!(control.reads.load(Ordering::SeqCst), 1); - Ok(()) -} - -#[test] -fn unknown_lifetimes_are_bounded_by_file_completion() -> VortexResult<()> { - let control = Arc::new(Control::default()); - control.complete(); - let file = file(&control); - let mut second = file.claim(0..40); - let first = second.split_to(20); - let session = file.session(); - session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 12)])?; - session.wait()?.result?; - drop(first); - assert_eq!(control.clears.load(Ordering::SeqCst), 0); - drop(second); - assert_eq!(control.clears.load(Ordering::SeqCst), 1); - Ok(()) -} - -#[test] -fn splitting_transfers_rows_without_releasing_their_reads() -> VortexResult<()> { - let control = Arc::new(Control::default()); - control.complete(); - let file = file(&control); - let mut remaining = file.claim(0..40); - let session = file.session(); - session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; - session.wait()?.result?; - - let child = remaining.split_to(20); - assert_eq!(child.rows(), &(0..20)); - assert_eq!(remaining.rows(), &(20..40)); - assert_eq!(control.clears.load(Ordering::SeqCst), 0); - // Moving the claim between stages changes neither registration nor cached reads. - let next_stage = child; - drop(remaining); - assert_eq!(control.clears.load(Ordering::SeqCst), 0); - drop(next_stage); - assert_eq!(control.clears.load(Ordering::SeqCst), 1); - Ok(()) -} - -#[test] -fn restricting_a_claim_releases_skipped_rows() -> VortexResult<()> { - let control = Arc::new(Control::default()); - control.complete(); - let file = file(&control); - let mut claim = file.claim(0..40); - let session = file.session(); - for offset in [0, 8] { - session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, offset)])?; - session.wait()?.result?; - } - claim.restrict_to(20..35); - assert_eq!(control.clears.load(Ordering::SeqCst), 1); - claim.restrict_to(35..35); - assert_eq!(control.clears.load(Ordering::SeqCst), 2); - assert!(file.state.lock().claims.is_empty()); - drop(claim); - assert_eq!(control.clears.load(Ordering::SeqCst), 2); - Ok(()) -} - -#[test] -fn overlapping_consumers_keep_independent_claims() -> VortexResult<()> { - let control = Arc::new(Control::default()); - control.complete(); - let file = file(&control); - let mut first = file.claim(0..40); - let second = first.share(); - let session = file.session(); - session.submit(IoOwnerId(0), vec![request(IoIntent::Fetch, 0, 0)])?; - session.wait()?.result?; - first.restrict_to(20..40); - assert_eq!(control.clears.load(Ordering::SeqCst), 0); - drop(second); - assert_eq!(control.clears.load(Ordering::SeqCst), 1); - assert_eq!(first.rows(), &(20..40)); - Ok(()) -} - -#[rstest] -#[case::empty_prefix(0)] -#[case::two_ranges(20)] -#[case::empty_suffix(40)] -fn split_boundaries_preserve_coverage(#[case] end: u64) { - let control = Arc::new(Control::default()); - let file = file(&control); - let mut remaining = file.claim(0..40); - let child = remaining.split_to(end); - assert_eq!(child.rows(), &(0..end)); - assert_eq!(remaining.rows(), &(end..40)); - drop(child); - drop(remaining); - assert!(file.state.lock().claims.is_empty()); -} - -#[rstest] -#[case::before_start(9)] -#[case::after_end(41)] -#[should_panic(expected = "split must lie within the claim")] -fn splits_outside_the_claim_are_rejected(#[case] end: u64) { - let file = file(&Arc::new(Control::default())); - let mut claim = file.claim(10..40); - let _child = claim.split_to(end); -} diff --git a/vortex-scan/src/planning/morsel.rs b/vortex-scan/src/planning/morsel.rs index 407c58567e0..ea238b1c464 100644 --- a/vortex-scan/src/planning/morsel.rs +++ b/vortex-scan/src/planning/morsel.rs @@ -4,6 +4,7 @@ //! The morsel side of the protocol: array-producing work and its outputs. use std::fmt; +use std::ops::Range; use vortex_array::ArrayRef; use vortex_error::VortexResult; @@ -40,6 +41,12 @@ pub trait Morsel: IoConsumer + Send { /// Advances CPU work. Only called when [`state`](Self::state) is `NeedsCompute`. fn compute(&mut self) -> VortexResult; + + /// The rows of its scope this morsel may still touch. See + /// [`Planner::remaining_rows`](crate::planning::planner::Planner::remaining_rows). + fn remaining_rows(&self) -> Option> { + None + } } impl fmt::Debug for MorselOutput { diff --git a/vortex-scan/src/planning/planner.rs b/vortex-scan/src/planning/planner.rs index cf795c99d7b..dcfb570fac4 100644 --- a/vortex-scan/src/planning/planner.rs +++ b/vortex-scan/src/planning/planner.rs @@ -71,6 +71,16 @@ pub trait Planner: IoConsumer + Send { /// Advances CPU work. Only called when [`state`](Self::state) is `NeedsCompute`. fn compute(&mut self) -> VortexResult; + + /// The rows of its scope this planner, or a child it has yet to emit, may still touch. + /// + /// After every [`compute`](Self::compute), a run that tracks + /// [`Liveness`](super::driver::Liveness) narrows the planner's claim to these rows, releasing + /// values pinned only to rows it has handed to children or proven it does not need. It may + /// only shrink. `None`, the default, keeps the planner's current claim until it retires. + fn remaining_rows(&self) -> Option> { + None + } } impl fmt::Debug for PlannerOutput { From 4232f64ff2b67186b6a14c4dc6b0d9ab1a3df98f Mon Sep 17 00:00:00 2001 From: Joe Isaacs Date: Wed, 4 Nov 2026 15:17:15 +0000 Subject: [PATCH 3/4] docs(scan): reword liveness module doc to pass the typos check Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UeniBBmU6aRNmSqEsMdKGW Signed-off-by: Joe Isaacs --- vortex-scan/src/planning/driver/liveness/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vortex-scan/src/planning/driver/liveness/mod.rs b/vortex-scan/src/planning/driver/liveness/mod.rs index 662f310d06d..21d96243118 100644 --- a/vortex-scan/src/planning/driver/liveness/mod.rs +++ b/vortex-scan/src/planning/driver/liveness/mod.rs @@ -9,8 +9,8 @@ //! [`RowClaim`] over its scope's rows: the claim is taken when the work is spawned, narrowed to //! the work's [`remaining_rows`], and released when the work retires or is cancelled. //! -//! Anything decoded for those rows, such as arrays, dictionary values, or buffers, can be -//! [`pin`](Liveness::pin)ned to the rows it serves. The pin holds the value until no claim covers +//! Anything decoded for those rows, such as arrays, dictionary values, or buffers, can be pinned +//! to the rows it serves with [`Liveness::pin`]. The pin holds the value until no claim covers //! any of its rows, and then drops it. A cache that wants to find such a value again keeps a weak //! reference to it: the pin is the only strong reference that keeps it alive. //! From 2d9709862aac394b6cc4a340d986eb9266b175cf Mon Sep 17 00:00:00 2001 From: Joe Isaacs Date: Wed, 4 Nov 2026 21:09:28 +0000 Subject: [PATCH 4/4] style(scan): format liveness module with the pinned nightly rustfmt Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UeniBBmU6aRNmSqEsMdKGW Signed-off-by: Joe Isaacs --- .../src/planning/driver/liveness/mod.rs | 6 ++++- .../src/planning/driver/liveness/tests.rs | 22 +++++++++++++++---- 2 files changed, 23 insertions(+), 5 deletions(-) diff --git a/vortex-scan/src/planning/driver/liveness/mod.rs b/vortex-scan/src/planning/driver/liveness/mod.rs index 21d96243118..1f2d52be710 100644 --- a/vortex-scan/src/planning/driver/liveness/mod.rs +++ b/vortex-scan/src/planning/driver/liveness/mod.rs @@ -159,7 +159,11 @@ impl State { let ids = self.expiry.get_mut(&end).vortex_expect("expiry exists"); ids.retain(|id| { let pin = self.pins.get(id).vortex_expect("pin exists"); - if pin.rows.as_ref().is_some_and(|rows| rows.start >= gap.start) { + if pin + .rows + .as_ref() + .is_some_and(|rows| rows.start >= gap.start) + { evicted.push(self.pins.remove(id).vortex_expect("pin exists")); false } else { diff --git a/vortex-scan/src/planning/driver/liveness/tests.rs b/vortex-scan/src/planning/driver/liveness/tests.rs index 58728821d0a..ad7c0f355ef 100644 --- a/vortex-scan/src/planning/driver/liveness/tests.rs +++ b/vortex-scan/src/planning/driver/liveness/tests.rs @@ -190,7 +190,12 @@ fn io() -> Arc { fn the_driver_drops_each_chunks_values_once_its_morsel_retires() -> VortexResult<()> { let (liveness, events) = (Liveness::new(), Events::default()); let mut run = Run::new().with_step_limit(100); - run.admit_with_liveness(chunker(&liveness, &events), scope(0..12), io(), liveness.clone()); + run.admit_with_liveness( + chunker(&liveness, &events), + scope(0..12), + io(), + liveness.clone(), + ); loop { match run.advance()? { Progress::Batch(batch) => events.push(format!("batch {:?}", batch.scope.rows)), @@ -218,8 +223,12 @@ fn the_driver_drops_each_chunks_values_once_its_morsel_retires() -> VortexResult fn cancelling_a_root_drops_the_values_its_work_held() -> VortexResult<()> { let (liveness, events) = (Liveness::new(), Events::default()); let mut run = Run::new().with_step_limit(100); - let root = - run.admit_with_liveness(chunker(&liveness, &events), scope(0..12), io(), liveness.clone()); + let root = run.admit_with_liveness( + chunker(&liveness, &events), + scope(0..12), + io(), + liveness.clone(), + ); assert!(matches!(run.advance()?, Progress::Batch(_))); assert!(events.take().is_empty()); run.cancel(root); @@ -234,7 +243,12 @@ fn a_scan_claim_keeps_values_after_the_work_finishes() -> VortexResult<()> { let scan = liveness.claim(0..12); assert!(liveness.pin(Lifetime::File, Tracked("dictionary", events.clone()))); let mut run = Run::new().with_step_limit(100); - run.admit_with_liveness(chunker(&liveness, &events), scope(0..12), io(), liveness.clone()); + run.admit_with_liveness( + chunker(&liveness, &events), + scope(0..12), + io(), + liveness.clone(), + ); while !matches!(run.advance()?, Progress::Idle) {} assert!(events.take().is_empty()); drop(scan);