alamb commented on code in PR #21342: URL: https://github.com/apache/datafusion/pull/21342#discussion_r3073038084
########## datafusion/datasource/src/file_stream/scan_state.rs: ########## @@ -0,0 +1,261 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +use std::collections::VecDeque; +use std::task::{Context, Poll}; + +use crate::PartitionedFile; +use crate::morsel::{Morsel, MorselPlanner, Morselizer}; +use arrow::record_batch::RecordBatch; +use datafusion_common::{DataFusionError, Result}; +use datafusion_physical_plan::metrics::ScopedTimerGuard; +use futures::future::BoxFuture; +use futures::stream::BoxStream; +use futures::{FutureExt as _, StreamExt as _}; + +use super::{FileStreamMetrics, OnError}; + +/// Planner-owned asynchronous I/O discovered while planning a file. +/// +/// Once `io_future` completes, `planner` becomes CPU-ready again and can be +/// pushed back onto the scan queue for further planning. +struct PendingOpen { + /// The planner to resume after the I/O completes. + planner: Box<dyn MorselPlanner>, + /// The outstanding I/O future for `planner`. + io_future: BoxFuture<'static, Result<()>>, +} + +/// All mutable state for the active `FileStreamState::Scan` lifecycle. +/// +/// This groups together ready planners, ready morsels, the active reader, +/// pending planner I/O, the remaining files and limit, and the metrics +/// associated with processing that work. +pub(super) struct ScanState { + /// Files that still need to be planned. + file_iter: VecDeque<PartitionedFile>, + /// Remaining record limit, if any. + remain: Option<usize>, + /// The file-format-specific morselizer used to plan files. + morselizer: Box<dyn Morselizer>, + /// Describes the behavior if opening or scanning a file fails. + on_error: OnError, + /// CPU-ready planners for the current file. + ready_planners: VecDeque<Box<dyn MorselPlanner>>, + /// Ready morsels for the current file. + ready_morsels: VecDeque<Box<dyn Morsel>>, + /// The active reader, if any. + reader: Option<BoxStream<'static, Result<RecordBatch>>>, Review Comment: You can see how cross stream sharing works in the next stacked PR: - https://github.com/apache/datafusion/pull/21351 the ScanState is not shared across partitions, but it has a new work_queue that is (potentially) shared. The relevant change is to replace the file_iter with this `work_source` thing and then handle setting up the work_source in the DataSource exec ```rust pub(super) struct ScanState { /// Files that still need to be planned. file_iter: VecDeque<PartitionedFile>, ... ``` Wth ```rust pub(super) struct ScanState { /// Unopened files that still need to be planned for this stream. work_source: WorkSource, ... ``` ########## datafusion/datasource/src/file_stream/scan_state.rs: ########## @@ -0,0 +1,283 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +use std::collections::VecDeque; +use std::task::{Context, Poll}; + +use crate::PartitionedFile; +use crate::morsel::{Morsel, MorselPlanner, Morselizer, PendingMorselPlanner}; +use arrow::record_batch::RecordBatch; +use datafusion_common::{DataFusionError, Result}; +use datafusion_physical_plan::metrics::ScopedTimerGuard; +use futures::stream::BoxStream; +use futures::{FutureExt as _, StreamExt as _}; + +use super::{FileStreamMetrics, OnError}; + +/// State [`FileStreamState::Scan`]. +/// +/// There is one `ScanState` per `FileStream`, and thus per output partition. +/// +/// It groups together the lifecycle of scanning that partition's files: +/// unopened files, CPU-ready planners, pending planner I/O, ready morsels, +/// the active reader, and the metrics associated with processing that work. +/// +/// # State Transitions +/// +/// ```text +/// file_iter +/// | +/// v +/// morselizer.plan_file(file) +/// | +/// v +/// ready_planners ---> plan() ---> ready_morsels ---> into_stream() ---> reader ---> RecordBatches +/// ^ | +/// | v +/// | pending_planner +/// | | +/// | v +/// +-------- poll until ready +/// ``` +/// +/// [`FileStreamState::Scan`]: super::FileStreamState::Scan +pub(super) struct ScanState { + /// Files that still need to be planned. + file_iter: VecDeque<PartitionedFile>, + /// Remaining row limit, if any. + remain: Option<usize>, + /// The morselizer used to plan files. + morselizer: Box<dyn Morselizer>, + /// Behavior if opening or scanning a file fails. + on_error: OnError, + /// CPU-ready planners for the current file. + ready_planners: VecDeque<Box<dyn MorselPlanner>>, + /// Ready morsels for the current file. + ready_morsels: VecDeque<Box<dyn Morsel>>, + /// The active reader, if any. + reader: Option<BoxStream<'static, Result<RecordBatch>>>, + /// The single planner currently blocked on I/O, if any. + pending_planner: Option<PendingMorselPlanner>, + /// Metrics for the active scan queues. + metrics: FileStreamMetrics, +} + +impl ScanState { + pub(super) fn new( + file_iter: impl Into<VecDeque<PartitionedFile>>, + remain: Option<usize>, + morselizer: Box<dyn Morselizer>, + on_error: OnError, + metrics: FileStreamMetrics, + ) -> Self { + let file_iter = file_iter.into(); + Self { + file_iter, + remain, + morselizer, + on_error, + ready_planners: Default::default(), + ready_morsels: Default::default(), + reader: None, + pending_planner: None, + metrics, + } + } + + /// Updates how scan errors are handled while the stream is still active. + pub(super) fn set_on_error(&mut self, on_error: OnError) { + self.on_error = on_error; + } + + /// Drives one iteration of the active scan state. + /// + /// Work is attempted in this order: + /// 1. resolve any pending planner I/O + /// 2. poll the active reader + /// 3. turn a ready morsel into the active reader + /// 4. run CPU planning on a ready planner + /// 5. morselize the next unopened file + /// + /// The return [`ScanAndReturn`] tells `poll_inner` how to update the + /// outer `FileStreamState`. + pub(super) fn poll_scan(&mut self, cx: &mut Context<'_>) -> ScanAndReturn { + let _processing_timer: ScopedTimerGuard<'_> = + self.metrics.time_processing.timer(); + + // Try and resolve outstanding IO first + if let Some(mut pending_planner) = self.pending_planner.take() { + match pending_planner.poll_unpin(cx) { + // IO is still pending + Poll::Pending => { + self.pending_planner = Some(pending_planner); + return ScanAndReturn::Return(Poll::Pending); + } + // IO resolved, and the planner is ready for CPU work + Poll::Ready(Ok(planner)) => { + self.ready_planners.push_back(planner); + return ScanAndReturn::Continue; + } + // IO Error + Poll::Ready(Err(err)) => { + self.metrics.file_open_errors.add(1); + self.metrics.time_opening.stop(); + return match self.on_error { + OnError::Skip => { + self.metrics.files_processed.add(1); + ScanAndReturn::Continue + } + OnError::Fail => ScanAndReturn::Error(err), + }; + } + } + } + + // Next try and get the next batch from the active reader, if any. + if let Some(reader) = self.reader.as_mut() { + match reader.poll_next_unpin(cx) { + // Morsels should ideally only expose ready-to-decode streams, + // but tolerate pending readers here. Review Comment: That is a good question... I think we would have to change the inner API to use something other than Stream (perhaps just an iterator). I'll see what I can come up with ########## datafusion/datasource/src/file_stream/scan_state.rs: ########## @@ -0,0 +1,283 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +use std::collections::VecDeque; +use std::task::{Context, Poll}; + +use crate::PartitionedFile; +use crate::morsel::{Morsel, MorselPlanner, Morselizer, PendingMorselPlanner}; +use arrow::record_batch::RecordBatch; +use datafusion_common::{DataFusionError, Result}; +use datafusion_physical_plan::metrics::ScopedTimerGuard; +use futures::stream::BoxStream; +use futures::{FutureExt as _, StreamExt as _}; + +use super::{FileStreamMetrics, OnError}; + +/// State [`FileStreamState::Scan`]. +/// +/// There is one `ScanState` per `FileStream`, and thus per output partition. +/// +/// It groups together the lifecycle of scanning that partition's files: +/// unopened files, CPU-ready planners, pending planner I/O, ready morsels, +/// the active reader, and the metrics associated with processing that work. +/// +/// # State Transitions +/// +/// ```text +/// file_iter +/// | +/// v +/// morselizer.plan_file(file) +/// | +/// v +/// ready_planners ---> plan() ---> ready_morsels ---> into_stream() ---> reader ---> RecordBatches +/// ^ | +/// | v +/// | pending_planner +/// | | +/// | v +/// +-------- poll until ready +/// ``` +/// +/// [`FileStreamState::Scan`]: super::FileStreamState::Scan +pub(super) struct ScanState { + /// Files that still need to be planned. + file_iter: VecDeque<PartitionedFile>, + /// Remaining row limit, if any. + remain: Option<usize>, + /// The morselizer used to plan files. + morselizer: Box<dyn Morselizer>, + /// Behavior if opening or scanning a file fails. + on_error: OnError, + /// CPU-ready planners for the current file. + ready_planners: VecDeque<Box<dyn MorselPlanner>>, + /// Ready morsels for the current file. + ready_morsels: VecDeque<Box<dyn Morsel>>, + /// The active reader, if any. + reader: Option<BoxStream<'static, Result<RecordBatch>>>, + /// The single planner currently blocked on I/O, if any. + pending_planner: Option<PendingMorselPlanner>, + /// Metrics for the active scan queues. + metrics: FileStreamMetrics, +} + +impl ScanState { + pub(super) fn new( + file_iter: impl Into<VecDeque<PartitionedFile>>, + remain: Option<usize>, + morselizer: Box<dyn Morselizer>, + on_error: OnError, + metrics: FileStreamMetrics, + ) -> Self { + let file_iter = file_iter.into(); + Self { + file_iter, + remain, + morselizer, + on_error, + ready_planners: Default::default(), + ready_morsels: Default::default(), + reader: None, + pending_planner: None, + metrics, + } + } + + /// Updates how scan errors are handled while the stream is still active. + pub(super) fn set_on_error(&mut self, on_error: OnError) { + self.on_error = on_error; + } + + /// Drives one iteration of the active scan state. + /// + /// Work is attempted in this order: + /// 1. resolve any pending planner I/O + /// 2. poll the active reader + /// 3. turn a ready morsel into the active reader + /// 4. run CPU planning on a ready planner + /// 5. morselize the next unopened file + /// + /// The return [`ScanAndReturn`] tells `poll_inner` how to update the + /// outer `FileStreamState`. + pub(super) fn poll_scan(&mut self, cx: &mut Context<'_>) -> ScanAndReturn { + let _processing_timer: ScopedTimerGuard<'_> = + self.metrics.time_processing.timer(); + + // Try and resolve outstanding IO first + if let Some(mut pending_planner) = self.pending_planner.take() { + match pending_planner.poll_unpin(cx) { + // IO is still pending + Poll::Pending => { + self.pending_planner = Some(pending_planner); + return ScanAndReturn::Return(Poll::Pending); + } + // IO resolved, and the planner is ready for CPU work + Poll::Ready(Ok(planner)) => { + self.ready_planners.push_back(planner); + return ScanAndReturn::Continue; + } + // IO Error + Poll::Ready(Err(err)) => { + self.metrics.file_open_errors.add(1); + self.metrics.time_opening.stop(); + return match self.on_error { + OnError::Skip => { + self.metrics.files_processed.add(1); + ScanAndReturn::Continue + } + OnError::Fail => ScanAndReturn::Error(err), + }; + } + } + } + + // Next try and get the next batch from the active reader, if any. + if let Some(reader) = self.reader.as_mut() { + match reader.poll_next_unpin(cx) { + // Morsels should ideally only expose ready-to-decode streams, + // but tolerate pending readers here. + Poll::Pending => return ScanAndReturn::Return(Poll::Pending), + Poll::Ready(Some(Ok(batch))) => { + self.metrics.time_scanning_until_data.stop(); + self.metrics.time_scanning_total.stop(); + // Apply any remaining row limit. + let (batch, finished) = match &mut self.remain { + Some(remain) => { + if *remain > batch.num_rows() { + *remain -= batch.num_rows(); + self.metrics.time_scanning_total.start(); + (batch, false) + } else { + let batch = batch.slice(0, *remain); + let done = 1 + self.file_iter.len(); + self.metrics.files_processed.add(done); + *remain = 0; + (batch, true) + } + } + None => { + self.metrics.time_scanning_total.start(); + (batch, false) + } + }; + return if finished { + ScanAndReturn::Done(Some(Ok(batch))) + } else { + ScanAndReturn::Return(Poll::Ready(Some(Ok(batch)))) + }; + } + Poll::Ready(Some(Err(err))) => { + self.reader = None; + self.metrics.file_scan_errors.add(1); + self.metrics.time_scanning_until_data.stop(); + self.metrics.time_scanning_total.stop(); + return match self.on_error { + OnError::Skip => { + self.metrics.files_processed.add(1); + ScanAndReturn::Continue + } + OnError::Fail => ScanAndReturn::Error(err), + }; + } + Poll::Ready(None) => { + self.reader = None; + self.metrics.files_processed.add(1); + self.metrics.time_scanning_until_data.stop(); + self.metrics.time_scanning_total.stop(); + return ScanAndReturn::Continue; + } + } + } + + // No active reader, but a morsel is ready to become the reader. + if let Some(morsel) = self.ready_morsels.pop_front() { + self.metrics.time_opening.stop(); + self.metrics.time_scanning_until_data.start(); + self.metrics.time_scanning_total.start(); + self.reader = Some(morsel.into_stream()); + return ScanAndReturn::Continue; + } + + // No reader or morsel, so try to produce more work via CPU planning. + if let Some(planner) = self.ready_planners.pop_front() { + return match planner.plan() { + Ok(Some(mut plan)) => { + // Queue any newly-ready morsels, planners, or planner I/O. + self.ready_morsels.extend(plan.take_morsels()); + self.ready_planners.extend(plan.take_ready_planners()); + if let Some(pending_planner) = plan.take_pending_planner() { + self.pending_planner = Some(pending_planner); Review Comment: THis is a good call -- I think a queue of pending planners is best. Will do -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
