From 9536a9729b9ab695e9519a3fe91736919c5e29a0 Mon Sep 17 00:00:00 2001 From: Prawal Pokharel <57414987+prawalpokharel@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:52:55 -0600 Subject: [PATCH 1/2] GH-40653: [C++] Add tests for stopping a dataset scan early Without threads, closing or destroying the reader from Scanner::ToRecordBatchReader(), or destroying a ScanBatches() iterator early, reads every remaining batch. Close() does the same with threads. These tests fail on main. --- cpp/src/arrow/dataset/scanner_test.cc | 124 ++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) diff --git a/cpp/src/arrow/dataset/scanner_test.cc b/cpp/src/arrow/dataset/scanner_test.cc index a45847b49def..1e70c3077e9f 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() {} From e00ed633bdc02f9c24c655586c735705412c4751 Mon Sep 17 00:00:00 2001 From: Prawal Pokharel <57414987+prawalpokharel@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:52:55 -0600 Subject: [PATCH 2/2] GH-40653: [C++] Stop a dataset scan that is closed or dropped early ScanBatches(), ScanBatchesUnordered() and ToRecordBatchReader() now return an iterator that stops the scan's plan when it is destroyed before the end. The reader's Close() stops the plan before draining it, as PlanReader::Close() in Acero does. Before, destroying the iterator without threads ran the rest of the scan, and Close() did so in both modes. The plan is held through a weak pointer, so it and the files it reads are still released at the end of the scan. --- cpp/src/arrow/dataset/scanner.cc | 118 +++++++++++++++++++++++++------ cpp/src/arrow/dataset/scanner.h | 10 ++- 2 files changed, 104 insertions(+), 24 deletions(-) diff --git a/cpp/src/arrow/dataset/scanner.cc b/cpp/src/arrow/dataset/scanner.cc index 222e1323d4a8..21ede3cc0591 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 c5d0c6591d3f..879dc2047525 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.