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/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..1f2d52be710 --- /dev/null +++ b/vortex-scan/src/planning/driver/liveness/mod.rs @@ -0,0 +1,234 @@ +// 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 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. +//! +//! [`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..ad7c0f355ef --- /dev/null +++ b/vortex-scan/src/planning/driver/liveness/tests.rs @@ -0,0 +1,293 @@ +// 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 e9cf27da3c2..dca55f859f3 100644 --- a/vortex-scan/src/planning/driver/mod.rs +++ b/vortex-scan/src/planning/driver/mod.rs @@ -15,6 +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 liveness; use std::collections::BTreeMap; use std::collections::VecDeque; @@ -22,6 +28,9 @@ use std::sync::Arc; use std::task::Context; use std::task::Poll; +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; @@ -99,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 { @@ -144,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. @@ -178,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. @@ -232,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 } @@ -381,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, @@ -392,6 +468,7 @@ impl Run { path, next_child: 0, outstanding: HashMap::default(), + claim, }); self.queue.insert(work); } @@ -448,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)) => { @@ -478,6 +564,7 @@ impl Run { scope: work.scope.clone(), array, })); + work.narrow()?; self.queue.insert(work); } } 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 {