Skip to content

Commit 52d6bce

Browse files
Dandandanclaude
andcommitted
fix(datasource): don't exit idle siblings while a donor is still pre-scan
Before: when every shared file is popped but no donor has reached its split point yet, an idle sibling saw empty queues and returned Done. Any row groups the donor subsequently pushed to the morsel queue were missed by that sibling. Now SharedWorkSource tracks an in-flight donor count via a FileLease RAII guard. Idle siblings that find both queues empty check the count and, if non-zero, wake_by_ref + Poll::Pending to re-poll. The lease drops at the morsel-to-reader transition — once a file is streaming, the donation window is closed, so we don't block siblings on the donor's assigned row groups. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
1 parent 26f09e4 commit 52d6bce

2 files changed

Lines changed: 132 additions & 9 deletions

File tree

‎datafusion/datasource/src/file_stream/scan_state.rs‎

Lines changed: 31 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ use datafusion_physical_plan::metrics::ScopedTimerGuard;
2626
use futures::stream::BoxStream;
2727
use futures::{FutureExt as _, StreamExt as _};
2828

29-
use super::work_source::WorkSource;
29+
use super::work_source::{FileLease, PopResult, WorkSource};
3030
use super::{FileStreamMetrics, OnError};
3131

3232
/// State [`FileStreamState::Scan`].
@@ -81,6 +81,12 @@ pub(super) struct ScanState {
8181
/// Once the I/O completes, yields the next planner and is pushed back
8282
/// onto `ready_planners`.
8383
pending_planner: Option<PendingMorselPlanner>,
84+
/// Lease on the current file popped from a shared work source. While
85+
/// held, idle siblings will wait for potential donations from this
86+
/// file instead of declaring the shared source drained. `None` for
87+
/// files that came from a local work source or for pre-finalized
88+
/// morsels.
89+
current_file_lease: Option<FileLease>,
8490
/// Metrics for the active scan queues.
8591
metrics: FileStreamMetrics,
8692
}
@@ -102,6 +108,7 @@ impl ScanState {
102108
ready_morsels: Default::default(),
103109
reader: None,
104110
pending_planner: None,
111+
current_file_lease: None,
105112
metrics,
106113
}
107114
}
@@ -146,6 +153,7 @@ impl ScanState {
146153
return match self.on_error {
147154
OnError::Skip => {
148155
self.metrics.files_processed.add(1);
156+
self.current_file_lease = None;
149157
ScanAndReturn::Continue
150158
}
151159
OnError::Fail => ScanAndReturn::Error(err),
@@ -174,6 +182,7 @@ impl ScanState {
174182
let batch = batch.slice(0, *remain);
175183
let done = 1 + self.work_source.skipped_on_limit();
176184
self.metrics.files_processed.add(done);
185+
self.current_file_lease = None;
177186
*remain = 0;
178187
(batch, true)
179188
}
@@ -197,6 +206,7 @@ impl ScanState {
197206
return match self.on_error {
198207
OnError::Skip => {
199208
self.metrics.files_processed.add(1);
209+
self.current_file_lease = None;
200210
ScanAndReturn::Continue
201211
}
202212
OnError::Fail => ScanAndReturn::Error(err),
@@ -205,6 +215,7 @@ impl ScanState {
205215
Poll::Ready(None) => {
206216
self.reader = None;
207217
self.metrics.files_processed.add(1);
218+
self.current_file_lease = None;
208219
self.metrics.time_scanning_until_data.stop();
209220
self.metrics.time_scanning_total.stop();
210221
return ScanAndReturn::Continue;
@@ -218,6 +229,11 @@ impl ScanState {
218229
self.metrics.time_scanning_until_data.start();
219230
self.metrics.time_scanning_total.start();
220231
self.reader = Some(morsel.into_stream());
232+
// A morsel is now streaming, so we're past the pre-scan window
233+
// where donations happen. Release the in-flight donor slot so
234+
// idle siblings can make progress (or exit) without waiting on
235+
// this stream to finish its assigned row groups.
236+
self.current_file_lease = None;
221237
return ScanAndReturn::Continue;
222238
}
223239

@@ -248,6 +264,7 @@ impl ScanState {
248264
}
249265
Ok(None) => {
250266
self.metrics.files_processed.add(1);
267+
self.current_file_lease = None;
251268
self.metrics.time_opening.stop();
252269
ScanAndReturn::Continue
253270
}
@@ -257,6 +274,7 @@ impl ScanState {
257274
match self.on_error {
258275
OnError::Skip => {
259276
self.metrics.files_processed.add(1);
277+
self.current_file_lease = None;
260278
ScanAndReturn::Continue
261279
}
262280
OnError::Fail => ScanAndReturn::Error(err),
@@ -266,10 +284,18 @@ impl ScanState {
266284
}
267285

268286
// No outstanding work remains, so begin planning the next unopened file.
269-
let part_file = match self.work_source.pop_front() {
270-
Some(part_file) => part_file,
271-
None => return ScanAndReturn::Done(None),
287+
let (part_file, lease) = match self.work_source.pop_front() {
288+
PopResult::Ready(file, lease) => (file, lease),
289+
PopResult::Pending => {
290+
// A sibling is pre-scan on a shared file that may still
291+
// donate morsels. Re-schedule ourselves so we re-check the
292+
// queues as soon as the scheduler picks us up.
293+
cx.waker().wake_by_ref();
294+
return ScanAndReturn::Return(Poll::Pending);
295+
}
296+
PopResult::Done => return ScanAndReturn::Done(None),
272297
};
298+
self.current_file_lease = lease;
273299

274300
self.metrics.time_opening.start();
275301
match self.morselizer.plan_file(part_file) {
@@ -283,6 +309,7 @@ impl ScanState {
283309
self.metrics.file_open_errors.add(1);
284310
self.metrics.time_opening.stop();
285311
self.metrics.files_processed.add(1);
312+
self.current_file_lease = None;
286313
ScanAndReturn::Continue
287314
}
288315
OnError::Fail => ScanAndReturn::Error(err),

‎datafusion/datasource/src/file_stream/work_source.rs‎

Lines changed: 101 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717

1818
use std::collections::VecDeque;
1919
use std::sync::Arc;
20+
use std::sync::atomic::{AtomicUsize, Ordering};
2021

2122
use crate::PartitionedFile;
2223
use crate::file_groups::FileGroup;
@@ -37,11 +38,18 @@ pub(super) enum WorkSource {
3738
}
3839

3940
impl WorkSource {
40-
/// Pop the next file to plan from this work source.
41-
pub(super) fn pop_front(&mut self) -> Option<PartitionedFile> {
41+
/// Try to pop the next item of work.
42+
///
43+
/// Returns [`PopResult::Pending`] for [`WorkSource::Shared`] when both
44+
/// queues are empty but a sibling is still processing a file that may
45+
/// donate more work. The caller must yield with its waker re-scheduled.
46+
pub(super) fn pop_front(&mut self) -> PopResult {
4247
match self {
43-
Self::Local(files) => files.pop_front(),
44-
Self::Shared(shared) => shared.pop_front(),
48+
Self::Local(files) => match files.pop_front() {
49+
Some(file) => PopResult::Ready(file, None),
50+
None => PopResult::Done,
51+
},
52+
Self::Shared(shared) => shared.pop_front_tracked(),
4553
}
4654
}
4755

@@ -55,6 +63,25 @@ impl WorkSource {
5563
}
5664
}
5765

66+
/// Outcome of a pop attempt against a [`WorkSource`].
67+
#[derive(Debug)]
68+
#[expect(
69+
clippy::large_enum_variant,
70+
reason = "Ready carries a PartitionedFile on the common path; boxing would add a heap alloc per pop and the other variants are markers"
71+
)]
72+
pub(super) enum PopResult {
73+
/// Work popped. The optional [`FileLease`] must be held until the file
74+
/// is fully processed; while it is alive, idle siblings treat the
75+
/// shared source as "donor may still publish" instead of drained.
76+
Ready(PartitionedFile, Option<FileLease>),
77+
/// No work currently available, but a sibling is still pre-scan on a
78+
/// file that may donate. The caller must register its waker to be
79+
/// re-polled and yield [`Poll::Pending`].
80+
Pending,
81+
/// No work available and no donors in flight — fully drained.
82+
Done,
83+
}
84+
5885
/// Shared source of work for sibling `FileStream`s.
5986
///
6087
/// Created once per execution and shared by all reorderable sibling streams.
@@ -69,6 +96,12 @@ impl WorkSource {
6996
/// state machine. Draining morsels first keeps their latency low and
7097
/// prevents siblings from starting fresh whole files while half-processed
7198
/// sub-file work sits idle.
99+
///
100+
/// Also tracks an in-flight donor count: every file popped from `files` is
101+
/// backed by a [`FileLease`] whose `Drop` decrements the count. While the
102+
/// count is non-zero, an idle sibling that sees both queues empty must wait
103+
/// rather than declare the source drained — the donor is still pre-scan
104+
/// and may yet push morsels.
72105
#[derive(Debug, Clone)]
73106
pub struct SharedWorkSource {
74107
inner: Arc<SharedWorkSourceInner>,
@@ -78,6 +111,9 @@ pub struct SharedWorkSource {
78111
pub(super) struct SharedWorkSourceInner {
79112
morsels: Mutex<VecDeque<PartitionedFile>>,
80113
files: Mutex<VecDeque<PartitionedFile>>,
114+
/// Number of files popped from `files` whose [`FileLease`] has not yet
115+
/// been dropped. Non-zero means "donor may still publish morsels."
116+
in_flight: AtomicUsize,
81117
}
82118

83119
impl Default for SharedWorkSource {
@@ -94,6 +130,7 @@ impl SharedWorkSource {
94130
inner: Arc::new(SharedWorkSourceInner {
95131
morsels: Mutex::new(VecDeque::new()),
96132
files: Mutex::new(files),
133+
in_flight: AtomicUsize::new(0),
97134
}),
98135
}
99136
}
@@ -106,14 +143,52 @@ impl SharedWorkSource {
106143
/// Pop the next item of work — morsels (pre-prepared sub-file chunks)
107144
/// first, then whole files.
108145
///
109-
/// Returns `None` if both queues are empty.
146+
/// Returns `None` if both queues are empty. Does *not* track in-flight
147+
/// donors; intended for tests and callers that only observe morsel
148+
/// donations. `ScanState` uses [`Self::pop_front_tracked`].
110149
pub fn pop_front(&self) -> Option<PartitionedFile> {
111150
if let Some(morsel) = self.inner.morsels.lock().pop_front() {
112151
return Some(morsel);
113152
}
114153
self.inner.files.lock().pop_front()
115154
}
116155

156+
/// Pop the next item of work for a sibling `FileStream`, returning a
157+
/// [`PopResult`] that distinguishes "nothing right now but donors may
158+
/// publish" from "truly drained."
159+
pub(super) fn pop_front_tracked(&self) -> PopResult {
160+
if let Some(morsel) = self.inner.morsels.lock().pop_front() {
161+
return PopResult::Ready(morsel, None);
162+
}
163+
// Increment before releasing the `files` lock so a concurrent peer
164+
// cannot observe empty-files && zero-counter while this donor is
165+
// about to register itself.
166+
let mut files = self.inner.files.lock();
167+
if let Some(file) = files.pop_front() {
168+
self.inner.in_flight.fetch_add(1, Ordering::Release);
169+
drop(files);
170+
return PopResult::Ready(
171+
file,
172+
Some(FileLease {
173+
inner: Arc::clone(&self.inner),
174+
}),
175+
);
176+
}
177+
drop(files);
178+
// Both queues empty. If any donor is still in flight, wait — it may
179+
// yet donate morsels.
180+
if self.inner.in_flight.load(Ordering::Acquire) > 0 {
181+
return PopResult::Pending;
182+
}
183+
// Counter observed zero. A donor that donated before dropping its
184+
// lease must have pushed morsels before the decrement; re-peek the
185+
// morsel queue to pick them up rather than exit prematurely.
186+
if let Some(morsel) = self.inner.morsels.lock().pop_front() {
187+
return PopResult::Ready(morsel, None);
188+
}
189+
PopResult::Done
190+
}
191+
117192
/// Push pre-prepared morsels onto the morsel queue.
118193
///
119194
/// Used when an in-flight file is sub-divided (e.g. parquet row-group
@@ -125,3 +200,24 @@ impl SharedWorkSource {
125200
queue.extend(items);
126201
}
127202
}
203+
204+
/// RAII guard tracking a file popped from a [`SharedWorkSource`]'s `files`
205+
/// queue. While alive, the counter on the source stays non-zero, which
206+
/// keeps idle sibling streams waiting for potential donations instead of
207+
/// declaring the source drained. Dropped when the donor finishes (or
208+
/// gives up on) the file.
209+
pub(super) struct FileLease {
210+
inner: Arc<SharedWorkSourceInner>,
211+
}
212+
213+
impl std::fmt::Debug for FileLease {
214+
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
215+
f.debug_struct("FileLease").finish_non_exhaustive()
216+
}
217+
}
218+
219+
impl Drop for FileLease {
220+
fn drop(&mut self) {
221+
self.inner.in_flight.fetch_sub(1, Ordering::Release);
222+
}
223+
}

0 commit comments

Comments
 (0)