diff --git a/cpp/src/arrow/dataset/scanner.cc b/cpp/src/arrow/dataset/scanner.cc index 222e1323d4a..21ede3cc059 100644 --- a/cpp/src/arrow/dataset/scanner.cc +++ b/cpp/src/arrow/dataset/scanner.cc @@ -94,11 +94,41 @@ Status ScanV2Options::AddFieldsNeededForFilter(ScanV2Options* options) { } namespace { +void StopScan(const std::weak_ptr& weak_plan) { + auto plan = weak_plan.lock(); + if (plan && !plan->finished().is_finished()) { + plan->StopProducing(); + } +} + +/// \brief An iterator over a scan that stops the scan when destroyed early +/// +/// Without threads, destroying the underlying iterator runs the rest of the scan, so +/// the plan is stopped first. The underlying iterator owns the plan and releases it, +/// with the files it reads, at the end of the scan, so only a weak reference is kept. +template +class StoppingIterator { + public: + StoppingIterator(Iterator it, std::weak_ptr plan) + : it_(std::move(it)), plan_(std::move(plan)) {} + StoppingIterator(StoppingIterator&&) = default; + ~StoppingIterator() { StopScan(plan_); } + + Result Next() { return it_.Next(); } + + private: + Iterator it_; + std::weak_ptr plan_; +}; + class ScannerRecordBatchReader : public RecordBatchReader { public: - explicit ScannerRecordBatchReader(std::shared_ptr schema, - TaggedRecordBatchIterator delegate) - : schema_(std::move(schema)), delegate_(std::move(delegate)) {} + ScannerRecordBatchReader(std::shared_ptr schema, + TaggedRecordBatchIterator delegate, + std::weak_ptr plan) + : schema_(std::move(schema)), + delegate_(std::move(delegate)), + plan_(std::move(plan)) {} std::shared_ptr schema() const override { return schema_; } Status ReadNext(std::shared_ptr* batch) override { @@ -112,17 +142,23 @@ class ScannerRecordBatchReader : public RecordBatchReader { } Status Close() override { + // End the scan and read from the iterator until the plan has finished + StopScan(plan_); std::shared_ptr batch; - RETURN_NOT_OK(ReadNext(&batch)); - while (batch != nullptr) { - RETURN_NOT_OK(ReadNext(&batch)); - } - return Status::OK(); + Status st; + do { + st = ReadNext(&batch); + } while (st.ok() && batch != nullptr); + // Release the scan now rather than when the reader is destroyed + delegate_ = TaggedRecordBatchIterator(); + // A stopped plan finishes with Cancelled + return st.IsCancelled() ? Status::OK() : st; } private: std::shared_ptr schema_; TaggedRecordBatchIterator delegate_; + std::weak_ptr plan_; }; const FieldVector kAugmentedFields{ @@ -282,8 +318,17 @@ class AsyncScanner : public Scanner, public std::enable_shared_from_this VisitBatchesAsync(std::function visitor, Executor* executor); + // Iterate over a scan synchronously, with an iterator that stops the scan when it is + // destroyed early. If plan is not null, it is set to the scan's plan. + template + Iterator IterateScan(MakeGenerator&& make_generator, + std::weak_ptr* plan = nullptr); + // If plan is not null, it is set to the plan backing the returned generator + Result ScanBatchesAsyncImpl( + Executor* executor, std::shared_ptr* plan); Result ScanBatchesUnorderedAsync( - Executor* executor, bool sequence_fragments, bool use_legacy_batching = false); + Executor* executor, bool sequence_fragments, bool use_legacy_batching = false, + std::shared_ptr* plan = nullptr); Future> ToTableAsync(Executor* executor); Future CountRowsAsync(Executor* executor); @@ -383,20 +428,33 @@ Result AsyncScanner::GetFragments() const { return MakeVectorGenerator(std::move(fragments_vec)); } -Result AsyncScanner::ScanBatches() { - return ::arrow::internal::IterateSynchronously( - [this](::arrow::internal::Executor* executor) { - return ScanBatchesAsync(executor); - }, +template +Iterator AsyncScanner::IterateScan(MakeGenerator&& make_generator, + std::weak_ptr* out_plan) { + std::shared_ptr plan; + // IterateSynchronously calls the function before it returns + auto it = ::arrow::internal::IterateSynchronously( + [&](Executor* executor) { return make_generator(executor, &plan); }, scan_options_->use_threads, scan_options_->cpu_executor); + if (out_plan != nullptr) { + *out_plan = plan; + } + return Iterator(StoppingIterator(std::move(it), plan)); +} + +Result AsyncScanner::ScanBatches() { + return IterateScan( + [this](Executor* executor, std::shared_ptr* plan) { + return ScanBatchesAsyncImpl(executor, plan); + }); } Result AsyncScanner::ScanBatchesUnordered() { - return ::arrow::internal::IterateSynchronously( - [this](::arrow::internal::Executor* executor) { - return ScanBatchesUnorderedAsync(executor); - }, - scan_options_->use_threads, scan_options_->cpu_executor); + return IterateScan( + [this](Executor* executor, std::shared_ptr* plan) { + return ScanBatchesUnorderedAsync(executor, /*sequence_fragments=*/false, + /*use_legacy_batching=*/false, plan); + }); } Result> AsyncScanner::ToTable() { @@ -435,7 +493,8 @@ Result ToEnumeratedRecordBatch( } Result AsyncScanner::ScanBatchesUnorderedAsync( - Executor* cpu_executor, bool sequence_fragments, bool use_legacy_batching) { + Executor* cpu_executor, bool sequence_fragments, bool use_legacy_batching, + std::shared_ptr* out_plan) { RETURN_NOT_OK(NormalizeScanOptions(scan_options_, dataset_->schema())); auto exec_context = @@ -491,6 +550,9 @@ Result AsyncScanner::ScanBatchesUnorderedAsync( return ToEnumeratedRecordBatch(batch, *options, *shared_fragments); }); + if (out_plan != nullptr) { + *out_plan = plan; + } return [mapped_gen = std::move(mapped_gen), plan = std::move(plan), stop_producing = std::move(stop_producing)] { auto next = mapped_gen(); @@ -616,9 +678,14 @@ Result AsyncScanner::ScanBatchesAsync() { Result AsyncScanner::ScanBatchesAsync( Executor* cpu_executor) { + return ScanBatchesAsyncImpl(cpu_executor, /*plan=*/nullptr); +} + +Result AsyncScanner::ScanBatchesAsyncImpl( + Executor* cpu_executor, std::shared_ptr* plan) { ARROW_ASSIGN_OR_RAISE( auto unordered, ScanBatchesUnorderedAsync(cpu_executor, /*sequence_fragments=*/true, - /*use_legacy_batching=*/true)); + /*use_legacy_batching=*/true, plan)); // We need an initial value sentinel, so we use one with fragment.index < 0 auto is_before_any = [](const EnumeratedRecordBatch& batch) { return batch.fragment.index < 0; @@ -800,9 +867,14 @@ Result AsyncScanner::CountRows() { } Result> AsyncScanner::ToRecordBatchReader() { - ARROW_ASSIGN_OR_RAISE(auto it, ScanBatches()); + std::weak_ptr scan_plan; + auto it = IterateScan( + [this](Executor* executor, std::shared_ptr* plan) { + return ScanBatchesAsyncImpl(executor, plan); + }, + &scan_plan); return std::make_shared(options()->projected_schema, - std::move(it)); + std::move(it), std::move(scan_plan)); } const std::shared_ptr& AsyncScanner::dataset() const { return dataset_; } diff --git a/cpp/src/arrow/dataset/scanner.h b/cpp/src/arrow/dataset/scanner.h index c5d0c6591d3..879dc204752 100644 --- a/cpp/src/arrow/dataset/scanner.h +++ b/cpp/src/arrow/dataset/scanner.h @@ -424,6 +424,9 @@ class ARROW_DS_EXPORT Scanner { /// much in memory (this is goverended by the readahead options and use_threads option). /// If the readahead queue fills up then I/O will pause until the calling thread catches /// up. + /// + /// Destroying the iterator before the end of the stream stops the scan. Reads that + /// were already in flight may finish in the background afterwards. virtual Result ScanBatches() = 0; virtual Result ScanBatchesAsync() = 0; virtual Result ScanBatchesAsync( @@ -434,7 +437,8 @@ class ARROW_DS_EXPORT Scanner { /// may be cached in RAM or just happen to get scheduled earlier by the I/O) /// /// To make up for the out-of-order iteration each batch is further tagged with - /// positional information. + /// positional information. As with ScanBatches, destroying the iterator early stops + /// the scan. virtual Result ScanBatchesUnordered() = 0; virtual Result ScanBatchesUnorderedAsync() = 0; virtual Result ScanBatchesUnorderedAsync( @@ -453,6 +457,10 @@ class ARROW_DS_EXPORT Scanner { virtual Future CountRowsAsync() = 0; /// \brief Convert the Scanner to a RecordBatchReader so it can be /// easily used with APIs that expect a reader. + /// + /// Closing or destroying the reader before the end of the stream stops the scan. + /// Close() returns once the scan's plan has finished, but reads that were already in + /// flight may finish in the background afterwards. virtual Result> ToRecordBatchReader() = 0; /// \brief Get the options for this scan. diff --git a/cpp/src/arrow/dataset/scanner_test.cc b/cpp/src/arrow/dataset/scanner_test.cc index a45847b49de..1e70c3077e9 100644 --- a/cpp/src/arrow/dataset/scanner_test.cc +++ b/cpp/src/arrow/dataset/scanner_test.cc @@ -2044,6 +2044,130 @@ TEST_F(TestBackpressure, ScanBatchesOrdered) { Finish(std::move(gen)); } +// A ControlledFragment whose batches are handed over by tasks on an executor, so that +// the scan waits for each batch like it does when reading a file +class ExecutorControlledFragment : public ControlledFragment { + public: + ExecutorControlledFragment(std::shared_ptr schema, + ::arrow::internal::Executor* executor) + : ControlledFragment(std::move(schema)), executor_(executor) {} + + Result ScanBatchesAsync( + const std::shared_ptr& options) override { + ARROW_ASSIGN_OR_RAISE(auto gen, ControlledFragment::ScanBatchesAsync(options)); + return [gen, executor = executor_]() { return DeferNotOk(executor->Submit(gen)); }; + } + + private: + ::arrow::internal::Executor* executor_; +}; + +// GH-40653: stopping a scan early should not read the rest of the dataset +class TestScanEarlyStop : public ::testing::TestWithParam { + protected: + static constexpr int kNumBatches = 1000; + static constexpr int kNumRows = 10; + // Without threads, batches delivered before the first read. The scan runs only while + // it is read, so the rest can be delivered after the first batch has been read. + static constexpr int kFirstBatches = 10; + + void SetUp() override { + ASSERT_OK_AND_ASSIGN(thread_pool_, ::arrow::internal::ThreadPool::Make(1)); + auto options = std::make_shared(); + if (GetParam()) { + fragment_ = + std::make_shared(schema_, thread_pool_.get()); + options->cpu_executor = thread_pool_.get(); + DeliverBatches(kNumBatches); + fragment_->Finish(); + } else { + fragment_ = std::make_shared(schema_); + DeliverBatches(kFirstBatches); + } + ScannerBuilder builder( + std::make_shared(schema_, FragmentVector{fragment_}), options); + ASSERT_OK(builder.UseThreads(GetParam())); + // With threads, backpressure pauses the scan while nothing is read + ASSERT_OK(builder.Backpressure( + acero::BackpressureOptions(kResumeIfBelowBytes, kPauseIfAboveBytes))); + ASSERT_OK_AND_ASSIGN(scanner_, builder.Finish()); + } + + void DeliverBatches(int num_batches) { + for (int i = 0; i < num_batches; i++) { + fragment_->DeliverBatch(kNumRows); + } + } + + // Without threads, deliver the rest of the batches after the first one has been read + void DeliverRemainingBatches() { + if (!GetParam()) { + DeliverBatches(kNumBatches - kFirstBatches); + fragment_->Finish(); + } + } + + void AssertStoppedEarly() { + // Let the tasks queued before the scan stopped run before the pool is destroyed + thread_pool_->WaitForIdle(); + // The scan stopped early: fewer than a tenth of the batches were requested + ASSERT_LT(fragment_->NumBatchesRead(), kNumBatches / 10); + } + + std::shared_ptr<::arrow::internal::ThreadPool> thread_pool_; + std::shared_ptr schema_ = schema({field("values", int32())}); + std::shared_ptr fragment_; + std::shared_ptr scanner_; +}; + +TEST_P(TestScanEarlyStop, CloseReader) { + ASSERT_OK_AND_ASSIGN(auto reader, scanner_->ToRecordBatchReader()); + ASSERT_OK_AND_ASSIGN(auto batch, reader->Next()); + ASSERT_NE(batch, nullptr); + DeliverRemainingBatches(); + ASSERT_OK(reader->Close()); + AssertStoppedEarly(); + // The reader is exhausted and can be closed again + ASSERT_OK_AND_ASSIGN(batch, reader->Next()); + ASSERT_EQ(batch, nullptr); + ASSERT_OK(reader->Close()); +} + +TEST_P(TestScanEarlyStop, CloseReaderAfterEnd) { + ASSERT_OK_AND_ASSIGN(auto reader, scanner_->ToRecordBatchReader()); + ASSERT_OK_AND_ASSIGN(auto batch, reader->Next()); + ASSERT_NE(batch, nullptr); + DeliverRemainingBatches(); + ASSERT_OK_AND_ASSIGN(auto table, reader->ToTable()); + ASSERT_EQ(table->num_rows(), (kNumBatches - 1) * kNumRows); + ASSERT_OK(reader->Close()); + thread_pool_->WaitForIdle(); +} + +TEST_P(TestScanEarlyStop, DestroyReader) { + ASSERT_OK_AND_ASSIGN(auto reader, scanner_->ToRecordBatchReader()); + ASSERT_OK_AND_ASSIGN(auto batch, reader->Next()); + ASSERT_NE(batch, nullptr); + DeliverRemainingBatches(); + reader.reset(); + AssertStoppedEarly(); +} + +// Head(), TakeRows() and pyarrow's to_batches() stop reading this iterator early +TEST_P(TestScanEarlyStop, DestroyIterator) { + ASSERT_OK_AND_ASSIGN(auto batch_it, scanner_->ScanBatches()); + ASSERT_OK_AND_ASSIGN(auto batch, batch_it.Next()); + ASSERT_NE(batch.record_batch, nullptr); + DeliverRemainingBatches(); + batch_it = TaggedRecordBatchIterator(); + AssertStoppedEarly(); +} + +INSTANTIATE_TEST_SUITE_P(TestScanEarlyStop, TestScanEarlyStop, ::testing::Bool(), + [](const ::testing::TestParamInfo& info) { + return info.param ? "Threaded" : "Serial"; + }); + struct BatchConsumer { explicit BatchConsumer(EnumeratedRecordBatchGenerator generator) : generator(std::move(generator)), next() {}