1717
1818use std:: collections:: VecDeque ;
1919use std:: sync:: Arc ;
20+ use std:: sync:: atomic:: { AtomicUsize , Ordering } ;
2021
2122use crate :: PartitionedFile ;
2223use crate :: file_groups:: FileGroup ;
@@ -37,11 +38,18 @@ pub(super) enum WorkSource {
3738}
3839
3940impl 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 ) ]
73106pub struct SharedWorkSource {
74107 inner : Arc < SharedWorkSourceInner > ,
@@ -78,6 +111,9 @@ pub struct SharedWorkSource {
78111pub ( 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
83119impl 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