lxy-9602 commented on code in PR #513:
URL: https://github.com/apache/paimon-cpp/pull/513#discussion_r4547307044


##########
docs/source/user_guide/metrics.rst:
##########
@@ -86,8 +86,9 @@ These metrics are C++-only and have no counterparts in Java 
Paimon.
 Prefetch I/O
 ------------
 
-``PrefetchIoMetrics`` describes only I/O that passes through the prefetch 
reader's instrumented
-input streams. It is not a whole-query or whole-table I/O total. All counters 
accumulate for the
+``PrefetchIoMetrics`` describes only I/O that passes through the instrumented
+file input streams, including synchronous reads with batch prefetch disabled.
+It is not a whole-query or whole-table I/O total. All counters accumulate for 
the

Review Comment:
   Not fully sure I understand—if we’ve already disabled prefetch, why does 
`PrefetchIoMetrics` still show I/O?



##########
test/inte/write_and_read_inte_with_index_test.cpp:
##########
@@ -1945,13 +1945,15 @@ TEST_P(WriteAndReadInteWithIndexTest, 
TestWithAlterTable) {
             file_name2 = "data-2efd8477-9fb4-44a6-9a39-901dd5a83b28-0.parquet";
         }
 
+        ASSERT_OK_AND_ASSIGN(std::unique_ptr<FileSystem> file_system,
+                             FileSystemFactory::Get("local", path, {}));
         auto create_data_file_meta = [&](const std::string& file_name, int32_t 
schema_id,
                                          const std::vector<uint8_t>& 
embedded_bytes) {
-            EXPECT_OK_AND_ASSIGN(FileStatus file_status,
-                                 LocalFileSystem().GetFileStatus(path + 
"bucket-0/" + file_name));
             auto embedded_index = 
std::make_shared<Bytes>(embedded_bytes.size(), pool_.get());
             memcpy(embedded_index->data(), reinterpret_cast<const 
void*>(embedded_bytes.data()),
                    embedded_bytes.size());
+            EXPECT_OK_AND_ASSIGN(FileStatus file_status,
+                                 file_system->GetFileStatus(path + "bucket-0/" 
+ file_name));
             return std::make_shared<DataFileMeta>(

Review Comment:
   Is this change related to `warmup` in any way?



##########
src/paimon/common/reader/late_materializing_reader_builder.h:
##########
@@ -55,9 +56,16 @@ class LateMaterializingReaderBuilder : public ReaderBuilder {
         const std::shared_ptr<InputStream>& stream) const override {
         PAIMON_ASSIGN_OR_RAISE(std::unique_ptr<FileBatchReader> format_reader,
                                inner_->Build(stream));
-        PAIMON_ASSIGN_OR_RAISE(
-            std::unique_ptr<LateMaterializingFileBatchReader> reader,
-            LateMaterializingFileBatchReader::Create(std::move(format_reader), 
arrow_pool_));
+        auto cache_stream = 
std::dynamic_pointer_cast<CacheInputStream>(stream);
+        if (cache_stream && 
!dynamic_cast<PrefetchFileBatchReader*>(format_reader.get())) {
+            // LM exposes the prefetch interface even for plain format 
readers. Do not let the
+            // outer factory enable a cache based on the wrapper's interface 
alone.
+            cache_stream->ClearCacheFactory();

Review Comment:
   Non-blocking. The LM reader is integrated from the prefetch reader, 
regardless of whether the underlying reader itself supports prefetch—this feels 
a bit weird here... That’s because the order between the prefetch reader and 
the LM reader.



##########
docs/source/user_guide/prefetch.rst:
##########
@@ -118,3 +122,19 @@ on top of the file being read. It may also fetch data from 
a file that the
 reader never consumes: a read that stops early, for example because of a LIMIT,
 may already have warmed the next file, and closing it waits for that file's
 in-flight fetches.
+
+For synchronous reads, including adaptive fallback, the pre-buffer limit also
+bounds retained range buffers. Completed buffers outside the current window can
+be evicted; later reads can fetch them again. In-flight I/O and buffers 
retained
+by callbacks count against that budget, so a full budget can temporarily cause 
a
+read to bypass range caching. The block cache has its separate limit. Parallel
+prefetch retains its existing range-buffer retention policy.
+
+ORC retains its existing byte-range discovery across all stripes. Preparing
+these ranges can read every stripe footer before the first batch is returned.
+
+Late-materialization payloads prepare their ranges through the shared internal
+cache context. Format readers expose their initial ranges
+through ``PreBufferRange()``; the public prefetch reader has no range callback
+setter. Plugins overriding the former callback setter must remove that override
+and rebuild against the updated interface.

Review Comment:
   Do we need to document this in the code? Otherwise the next person will only 
see a static piece of documentation and won’t necessarily understand the 
rationale behind this change.



##########
src/paimon/format/parquet/parquet_file_batch_reader.cpp:
##########
@@ -176,7 +176,7 @@ bool IsChunkFullyDictionaryEncoded(const 
::parquet::ColumnChunkMetaData& chunk)
 // the same byte ranges are not buffered twice. Without hints, fall back to 
the option.
 Result<bool> ResolvePreBufferEnabled(const std::map<std::string, std::string>& 
options,
                                      const std::optional<ReadHints>& hints) {
-    if (hints.has_value() && hints->prefetch_enabled && 
hints->read_ahead_cache_enabled) {
+    if (hints.has_value() && hints->read_ahead_cache_enabled) {

Review Comment:
   Shared caching sets `pre_buffer=false`, but the page-filtered path still 
calls `DispatchPreBuffer()` → `PreBufferRanges()` unconditionally. Bitmap point 
lookups and late-materialization payload reads taking this path can therefore 
buffer the same raw bytes in both Paimon’s `ReadAheadCache` and Parquet’s range 
cache. Please honor the shared-cache setting here, or at least add an TODO 
documenting the duplicate buffering and the required follow-up.



##########
src/paimon/common/reader/data_file_reader_factory_test.cpp:
##########
@@ -22,20 +22,235 @@
 
 #include "arrow/api.h"
 #include "arrow/array/array_nested.h"
+#include "arrow/c/bridge.h"
 #include "arrow/ipc/json_simple.h"
 #include "gtest/gtest.h"
+#include "paimon/common/io/cache_input_stream.h"
 #include "paimon/common/reader/delegating_prefetch_reader.h"
+#include "paimon/common/reader/late_materializing_reader_builder.h"
+#include "paimon/common/reader/warmup_file_batch_reader.h"
 #include "paimon/common/utils/arrow/mem_utils.h"
+#include "paimon/common/utils/checked_cast.h"
 #include "paimon/executor.h"
+#include "paimon/factories/factory_creator.h"
+#include "paimon/format/file_format_factory.h"
 #include "paimon/memory/memory_pool.h"
+#include "paimon/predicate/literal.h"
+#include "paimon/predicate/predicate_builder.h"
 #include "paimon/reader/file_batch_reader.h"
+#include "paimon/testing/mock/mock_file_format.h"
 #include "paimon/testing/mock/mock_file_system.h"
 #include "paimon/testing/mock/mock_format_reader_builder.h"
 #include "paimon/testing/utils/testharness.h"
 #include "paimon/utils/prefetch_cache_config.h"
 
 namespace paimon::test {
 
+// Deliberately expose only FileBatchReader, even though the test data source 
can report ranges.
+class PlainFileBatchReader : public FileBatchReader {
+ public:
+    explicit PlainFileBatchReader(std::unique_ptr<FileBatchReader> reader)
+        : reader_(std::move(reader)) {}
+
+    Result<ReadBatch> NextBatch() override {
+        return reader_->NextBatch();
+    }
+    Result<ReadBatchWithBitmap> NextBatchWithBitmap() override {
+        return reader_->NextBatchWithBitmap();
+    }
+    std::shared_ptr<Metrics> GetReaderMetrics() const override {
+        return reader_->GetReaderMetrics();
+    }
+    Result<std::unique_ptr<::ArrowSchema>> GetFileSchema() const override {
+        return reader_->GetFileSchema();
+    }
+    Status SetReadSchema(::ArrowSchema* schema, const 
std::shared_ptr<Predicate>& predicate,
+                         const std::optional<RoaringBitmap32>& bitmap) 
override {
+        return reader_->SetReadSchema(schema, predicate, bitmap);
+    }
+    Result<uint64_t> GetPreviousBatchFileRowId(uint64_t row) const override {
+        return reader_->GetPreviousBatchFileRowId(row);
+    }
+    Result<uint64_t> GetNumberOfRows() const override {
+        return reader_->GetNumberOfRows();
+    }
+    bool SupportPreciseBitmapSelection() const override {
+        return reader_->SupportPreciseBitmapSelection();
+    }
+    void Close() override {
+        reader_->Close();
+    }
+
+ private:
+    std::unique_ptr<FileBatchReader> reader_;
+};
+
+class CapabilityReaderBuilder : public MockFormatReaderBuilder {
+ public:
+    CapabilityReaderBuilder(const std::shared_ptr<arrow::Array>& data,
+                            const std::shared_ptr<arrow::DataType>& type, bool 
capable)
+        : MockFormatReaderBuilder(data, type, /*read_batch_size=*/2), 
capable_(capable) {
+        SetPreBufferRangesPerSchema({{{0, 4}}});
+    }
+
+    Result<std::unique_ptr<FileBatchReader>> Build(
+        const std::shared_ptr<InputStream>& input) const override {
+        ++build_count;
+        stream = std::dynamic_pointer_cast<CacheInputStream>(input);
+        PAIMON_ASSIGN_OR_RAISE(std::unique_ptr<FileBatchReader> reader,
+                               MockFormatReaderBuilder::Build(input));
+        
checked_cast<MockFileBatchReader*>(reader.get())->EnableRandomizeBatchSize(false);
+        if (!capable_) {
+            reader = std::make_unique<PlainFileBatchReader>(std::move(reader));
+        }
+        original_reader = reader.get();
+        return reader;
+    }
+
+    mutable uint32_t build_count = 0;
+    mutable FileBatchReader* original_reader = nullptr;
+    mutable std::shared_ptr<CacheInputStream> stream;
+
+ private:
+    bool capable_;
+};
+
+class CountingOpenFileSystem : public MockFileSystem {
+ public:
+    using MockFileSystem::Open;
+    Result<std::unique_ptr<InputStream>> Open(const std::string& path) const 
override {
+        if (++open_count == 2 && fail_cache_open) {
+            return Status::IOError("cache stream open failed");
+        }
+        return MockFileSystem::Open(path);
+    }
+    mutable uint32_t open_count = 0;
+    bool fail_cache_open = false;
+};

Review Comment:
   There seems to be too much `CountingFileSystem` usage in the code right now. 
Please refactor these into the test utilities/tools.



##########
include/paimon/read_context.h:
##########
@@ -435,26 +435,27 @@ class PAIMON_EXPORT ReadContextBuilder {
     ///
     /// A read-ahead cache is used to prebuffer data ranges before they are 
needed,
     /// which can improve read performance by reducing redundant I/O 
operations.
+    /// It also works without batch prefetch for readers exposing byte ranges 
through
+    /// PrefetchFileBatchReader, including Parquet and ORC.
     /// @param enabled Whether to enable the read-ahead cache (default: true)
     /// @return Reference to this builder for method chaining.
     ReadContextBuilder& SetReadAheadCacheEnabled(bool enabled);
 
-    /// Set the cache configuration for prefetch read operations.
+    /// Set the read-ahead cache configuration for synchronous and prefetch 
reads.
     ///
     /// @param config The cache configuration to use.
     /// @return Reference to this builder for method chaining.
     ReadContextBuilder& WithCacheConfig(const CacheConfig& config);
 
-    /// Set how far the reader prepares the next file before it is read.
+    /// Set whether the reader fetches the next file's raw bytes before it is 
read.
     ///
-    /// Warmup overlaps remote-storage latency with the read of the current 
file. Higher levels hide
-    /// more latency but use more memory, and may warm files that a query 
never reads (for example
-    /// when a LIMIT stops the scan early).
+    /// Warmup can overlap remote-storage latency with reading the current 
file. It may fetch bytes
+    /// for files that a query never reads, for example when a LIMIT stops the 
scan early.
     /// @param level The warmup level to use (default: WarmupLevel::RAW).
     /// @return Reference to this builder for method chaining.
     /// @note WarmupLevel::RAW warms the read-ahead cache, so it has no effect 
and behaves like
     /// WarmupLevel::NONE when the cache is off (see 
SetReadAheadCacheEnabled()).
-    /// WarmupLevel::DECODED does not depend on the cache.
+    /// RAW also works with EnablePrefetch(false) and never starts batch 
decoding.
     /// @see WarmupLevel

Review Comment:
   I feel like the places we’re saying `warmup` can be supported even when 
prefetch isn’t enabled might be a bit too broad—doesn’t it feel a little forced?



##########
src/paimon/common/reader/late_materializing_file_batch_reader.cpp:
##########
@@ -263,23 +271,11 @@ Status 
LateMaterializingFileBatchReader::SetInnerReadSchema(
     return Status::OK();
 }
 
-Status LateMaterializingFileBatchReader::ReportPayloadPreBufferRanges() {
-    // The payload byte ranges only exist now: setting the payload schema 
refined the inner
-    // reader's target row groups down to the pages holding the matched rows. 
Reporting them
-    // here lets the shared read-ahead cache fetch them while this pass is 
still assembling
-    // its first batch, instead of every payload read waiting for its own IO.
-    if (!pre_buffer_range_callback_ || prefetch_inner_ == nullptr) {
+Status LateMaterializingFileBatchReader::PreparePayloadRanges() {
+    if (!read_ahead_ || prefetch_inner_ == nullptr) {
         return Status::OK();
     }

Review Comment:
   Is this still coupling `read ahead` cache with `prefetch`? Is it because 
`PreBufferRange`’s interface is now on `PreBufferBatchReader`? If so, shouldn’t 
we decouple this part as well?



##########
src/paimon/common/utils/read_ahead_cache.cpp:
##########
@@ -208,27 +226,91 @@ void ReadAheadCache::PreBuffer(uint64_t offset) {
             if (entry->Published()) {
                 continue;
             }
+            if (bounded_retention_ &&
+                !MakeRoomLocked(entry->range.length, window_begin_offset, 
window_end_offset)) {
+                break;
+            }
             auto promise = std::make_shared<std::promise<Status>>();
             auto future = promise->get_future();
-            auto buffer = AllocateBytesKeepingPoolAlive(entry->range.length, 
memory_pool_);
+            auto buffer = AllocateRangeBuffer(entry->range.length);
             fetches.push_back({entry->range, buffer, promise});
             // Published IN PLACE under the write lock, before the IO is 
dispatched below: a
             // reader racing the prefetch then finds the entry and waits on 
its future instead of
-            // issuing a second fetch for the same bytes. Entries are never 
evicted, so an
-            // in-flight fetch always keeps its entry and thus its future 
reachable.
+            // issuing a second fetch for the same bytes. In-flight entries 
are never evicted,
+            // so every pending fetch remains reachable for Close()/Reset() to 
wait on.
             entry->buffer = std::move(buffer);
             entry->future = std::move(future).share();
+            resident_ranges_.insert(entry->range.offset);
         }
     }
     // Dispatched OUTSIDE the lock, so that a fetch completing inline does not 
deadlock against a
     // Read() waiting for it.
     DispatchFetches(fetches);
 }
 
+void ReadAheadCache::SetBoundedRetention(bool enabled) {
+    std::unique_lock<std::shared_mutex> lock(rw_mutex_);
+    bounded_retention_ = enabled;
+}
+
+bool ReadAheadCache::MakeRoomLocked(uint64_t size, uint64_t window_begin, 
uint64_t window_end) {
+    const uint64_t limit = config_.GetPreBufferLimit();
+    if (size > limit) {
+        return false;
+    }
+    auto candidate = resident_ranges_.lower_bound(eviction_offset_);
+    const size_t candidate_count = resident_ranges_.size();
+    for (size_t visited = 0; visited < candidate_count; ++visited) {
+        if (budget_->resident_bytes.load(std::memory_order_acquire) <= limit - 
size) {
+            return true;
+        }
+        if (candidate == resident_ranges_.end()) {
+            candidate = resident_ranges_.begin();
+        }
+        auto current = candidate++;
+        auto it = std::lower_bound(ranges_.begin(), ranges_.end(), *current,
+                                   [](const RangeCacheEntry& entry, uint64_t 
offset) {
+                                       return entry.range.offset < offset;
+                                   });
+        assert(it != ranges_.end() && it->range.offset == *current && 
it->Published());
+        auto& entry = *it;
+        eviction_offset_ = candidate == resident_ranges_.end() ? 0 : 
*candidate;
+        // Keep this window, pending I/O, failed results and buffers being 
copied or retained by
+        // a filesystem callback. Re-reading an evicted range simply publishes 
it again.
+        if ((entry.range.offset >= window_begin && entry.range.offset < 
window_end) ||
+            entry.buffer.use_count() != 1 ||
+            entry.future.wait_for(std::chrono::seconds(0)) != 
std::future_status::ready ||
+            !entry.future.get().ok()) {
+            continue;
+        }
+        entry.buffer.reset();
+        entry.future = {};
+        resident_ranges_.erase(current);
+    }
+    return budget_->resident_bytes.load(std::memory_order_acquire) <= limit - 
size;
+}
+
+std::shared_ptr<Bytes> ReadAheadCache::AllocateRangeBuffer(uint64_t size) {
+    auto buffer = AllocateBytesKeepingPoolAlive(size, memory_pool_);
+    budget_->resident_bytes.fetch_add(size, std::memory_order_relaxed);
+    // Account until the LAST owner releases the buffer, even if a callback 
retains it after
+    // Reset(). The captured buffer also retains the allocating memory pool.
+    return std::shared_ptr<Bytes>(
+        buffer.get(), [buffer, budget = budget_, size](Bytes* bytes) mutable {
+            assert(bytes == buffer.get());
+            buffer.reset();
+            budget->resident_bytes.fetch_sub(size, std::memory_order_release);
+        });
+}
+
 ReadAheadCache::ReadAheadCache(const std::shared_ptr<InputStream>& stream,

Review Comment:
   **[P2] Make prefetch publication safe under allocation failure**
   
   Not blocking. `PreBuffer()` publishes entries incrementally but dispatches 
their I/O only after preparing the entire window. If a later buffer allocation 
throws `std::bad_alloc`, `DispatchFetches()` is never reached, and destroying 
the pending promises leaves previously published entries with broken promises. 
The allocation exception escapes `Warmup()`, while subsequent reads can throw 
`std::future_error` instead of returning a `Status`. The new 
`resident_ranges_.insert()` introduces another allocation failure point after 
publication. Please convert allocation failures to `Status::OutOfMemory` and 
either roll back undispatched entries or complete their futures with an error, 
keeping the resident index consistent.



##########
src/paimon/common/utils/read_ahead_cache.cpp:
##########
@@ -50,6 +52,10 @@ struct PendingFetch {
     std::shared_ptr<std::promise<Status>> promise;
 };
 
+struct ReadAheadCacheBudget {
+    std::atomic<uint64_t> resident_bytes{0};
+};
+

Review Comment:
   I don’t understand why this member needs to use an anonymous `struct` design.



##########
src/paimon/common/utils/read_ahead_cache.cpp:
##########
@@ -208,27 +226,91 @@ void ReadAheadCache::PreBuffer(uint64_t offset) {
             if (entry->Published()) {
                 continue;
             }
+            if (bounded_retention_ &&
+                !MakeRoomLocked(entry->range.length, window_begin_offset, 
window_end_offset)) {
+                break;
+            }
             auto promise = std::make_shared<std::promise<Status>>();
             auto future = promise->get_future();
-            auto buffer = AllocateBytesKeepingPoolAlive(entry->range.length, 
memory_pool_);
+            auto buffer = AllocateRangeBuffer(entry->range.length);
             fetches.push_back({entry->range, buffer, promise});
             // Published IN PLACE under the write lock, before the IO is 
dispatched below: a
             // reader racing the prefetch then finds the entry and waits on 
its future instead of
-            // issuing a second fetch for the same bytes. Entries are never 
evicted, so an
-            // in-flight fetch always keeps its entry and thus its future 
reachable.
+            // issuing a second fetch for the same bytes. In-flight entries 
are never evicted,
+            // so every pending fetch remains reachable for Close()/Reset() to 
wait on.
             entry->buffer = std::move(buffer);
             entry->future = std::move(future).share();
+            resident_ranges_.insert(entry->range.offset);
         }
     }
     // Dispatched OUTSIDE the lock, so that a fetch completing inline does not 
deadlock against a
     // Read() waiting for it.
     DispatchFetches(fetches);
 }
 
+void ReadAheadCache::SetBoundedRetention(bool enabled) {
+    std::unique_lock<std::shared_mutex> lock(rw_mutex_);
+    bounded_retention_ = enabled;
+}
+
+bool ReadAheadCache::MakeRoomLocked(uint64_t size, uint64_t window_begin, 
uint64_t window_end) {
+    const uint64_t limit = config_.GetPreBufferLimit();
+    if (size > limit) {
+        return false;
+    }
+    auto candidate = resident_ranges_.lower_bound(eviction_offset_);
+    const size_t candidate_count = resident_ranges_.size();
+    for (size_t visited = 0; visited < candidate_count; ++visited) {
+        if (budget_->resident_bytes.load(std::memory_order_acquire) <= limit - 
size) {
+            return true;
+        }
+        if (candidate == resident_ranges_.end()) {
+            candidate = resident_ranges_.begin();
+        }
+        auto current = candidate++;
+        auto it = std::lower_bound(ranges_.begin(), ranges_.end(), *current,
+                                   [](const RangeCacheEntry& entry, uint64_t 
offset) {
+                                       return entry.range.offset < offset;
+                                   });
+        assert(it != ranges_.end() && it->range.offset == *current && 
it->Published());
+        auto& entry = *it;
+        eviction_offset_ = candidate == resident_ranges_.end() ? 0 : 
*candidate;
+        // Keep this window, pending I/O, failed results and buffers being 
copied or retained by
+        // a filesystem callback. Re-reading an evicted range simply publishes 
it again.
+        if ((entry.range.offset >= window_begin && entry.range.offset < 
window_end) ||
+            entry.buffer.use_count() != 1 ||
+            entry.future.wait_for(std::chrono::seconds(0)) != 
std::future_status::ready ||
+            !entry.future.get().ok()) {
+            continue;
+        }
+        entry.buffer.reset();
+        entry.future = {};
+        resident_ranges_.erase(current);
+    }
+    return budget_->resident_bytes.load(std::memory_order_acquire) <= limit - 
size;
+}

Review Comment:
   **[P2] Normalize overlapping ranges before merging**
   
      `MergeRangesLocked()` assumes that `new_ranges` is internally disjoint, 
but `CoalesceByteRanges()` can retain partially overlapping ranges when their 
combined span exceeds the size limit. For example, with `range_size_limit=32` 
and `hole_size_limit=0`, registering `{{10,10},{30,10}}` followed by 
`{{0,25},{5,30}}` produces `[0,10), [10,20), [20,25), [5,30), [30,40)`. This 
breaks the ordering required by the binary searches, and `MakeRoomLocked()` can 
subsequently fail its offset assertion during eviction. Please normalize the 
new ranges into a disjoint union before splitting and merging, and add coverage 
for overlapping ranges whose combined span exceeds the limit.



##########
src/paimon/common/reader/warmup_file_batch_reader.h:
##########
@@ -0,0 +1,66 @@
+/*
+ * 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.
+ */
+#pragma once
+
+#include <memory>
+#include <optional>
+
+#include "arrow/c/abi.h"
+#include "paimon/common/reader/file_read_ahead.h"
+#include "paimon/reader/file_batch_reader.h"
+
+namespace paimon {
+
+/// A synchronous file reader with independent byte caching and raw warmup.
+class WarmupFileBatchReader : public FileBatchReader {
+ public:

Review Comment:
   Please add reader layout comments for the `WarmupFileBatchReader` in the 
`SplitRead` class header. Now it’s hard to tell how each reader is called.



##########
src/paimon/common/reader/file_read_ahead.cpp:
##########
@@ -0,0 +1,492 @@
+/*
+ * 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.
+ */
+#include "paimon/common/reader/file_read_ahead.h"
+
+#include <algorithm>
+#include <atomic>
+#include <chrono>
+#include <future>
+#include <utility>
+
+#include "fmt/format.h"
+#include "paimon/common/executor/future.h"
+#include "paimon/common/io/cache_input_stream.h"
+#include "paimon/common/metrics/metrics_impl.h"
+#include "paimon/common/reader/warmup_file_batch_reader.h"
+#include "paimon/common/utils/checked_cast.h"
+#include "paimon/format/reader_builder.h"
+
+namespace paimon {
+
+struct PrefetchIoMetricsState {
+    std::atomic<uint64_t> read_requests{0};
+    std::atomic<uint64_t> read_requested_bytes{0};
+    std::atomic<uint64_t> read_physical_bytes{0};
+    std::atomic<uint64_t> read_failed{0};
+    std::atomic<uint64_t> read_latency_count{0};
+    std::atomic<uint64_t> read_latency_sum_us{0};
+    std::atomic<uint64_t> async_requests{0};
+    std::atomic<uint64_t> async_requested_bytes{0};
+    std::atomic<uint64_t> async_physical_bytes{0};
+    std::atomic<uint64_t> async_completed{0};
+    std::atomic<uint64_t> async_failed{0};
+    std::atomic<uint64_t> async_pending{0};
+    std::atomic<uint64_t> async_latency_count{0};
+    std::atomic<uint64_t> async_latency_sum_us{0};
+};
+
+namespace {
+
+constexpr std::memory_order kMetricsMemoryOrder = std::memory_order_relaxed;
+
+template <typename Func>
+auto RunOrSubmit(Executor* executor, Func&& task) -> 
std::future<decltype(task())> {
+    if (executor) {
+        return Via(executor, std::forward<Func>(task));
+    }
+    std::promise<decltype(task())> promise;
+    auto future = promise.get_future();
+    promise.set_value(task());
+    return future;
+}
+
+uint64_t ElapsedMicros(const std::chrono::steady_clock::time_point& start) {
+    return 
static_cast<uint64_t>(std::chrono::duration_cast<std::chrono::microseconds>(
+                                     std::chrono::steady_clock::now() - start)
+                                     .count());
+}
+
+void RecordLatency(uint64_t latency_us, std::atomic<uint64_t>* count,
+                   std::atomic<uint64_t>* sum_us) {
+    count->fetch_add(1, kMetricsMemoryOrder);
+    sum_us->fetch_add(latency_us, kMetricsMemoryOrder);
+}
+
+class MetricsInputStream : public InputStream {
+ public:
+    MetricsInputStream(const std::shared_ptr<InputStream>& stream,
+                       const std::shared_ptr<PrefetchIoMetricsState>& metrics,
+                       const std::shared_ptr<std::atomic<uint64_t>>& 
storage_read_bytes)
+        : stream_(stream), metrics_(metrics), 
storage_read_bytes_(storage_read_bytes) {}
+
+    MetricsInputStream(std::unique_ptr<InputStream>&& stream,
+                       const std::shared_ptr<PrefetchIoMetricsState>& metrics,
+                       const std::shared_ptr<std::atomic<uint64_t>>& 
storage_read_bytes)
+        : stream_(std::move(stream)), metrics_(metrics), 
storage_read_bytes_(storage_read_bytes) {}
+
+    Status Seek(int64_t offset, SeekOrigin origin) override {
+        return stream_->Seek(offset, origin);
+    }
+
+    Result<int64_t> GetPos() const override {
+        return stream_->GetPos();
+    }
+
+    Result<int64_t> Read(char* buffer, int64_t size) override {
+        return RecordRead([&]() { return stream_->Read(buffer, size); }, size);
+    }
+
+    Result<int64_t> Read(char* buffer, int64_t size, int64_t offset) override {
+        return RecordRead([&]() { return stream_->Read(buffer, size, offset); 
}, size);
+    }
+
+    void ReadAsync(char* buffer, int64_t size, int64_t offset,
+                   std::function<void(Status)>&& callback) override {
+        auto storage_read_bytes = storage_read_bytes_;
+        auto counted_callback = [storage_read_bytes, size,
+                                 callback = std::move(callback)](Status 
status) mutable {
+            if (status.ok()) {
+                
storage_read_bytes->fetch_add(static_cast<uint64_t>(std::max<int64_t>(0, size)),
+                                              kMetricsMemoryOrder);
+            }
+            callback(status);
+        };
+        if (!metrics_) {
+            stream_->ReadAsync(buffer, size, offset, 
std::move(counted_callback));
+            return;
+        }
+        metrics_->async_requests.fetch_add(1, kMetricsMemoryOrder);
+        
metrics_->async_requested_bytes.fetch_add(static_cast<uint64_t>(std::max<int64_t>(0,
 size)),
+                                                  kMetricsMemoryOrder);
+        metrics_->async_pending.fetch_add(1, kMetricsMemoryOrder);
+        std::shared_ptr<PrefetchIoMetricsState> metrics = metrics_;
+        const auto start = std::chrono::steady_clock::now();
+        stream_->ReadAsync(
+            buffer, size, offset,
+            [metrics, size, start, callback = 
std::move(counted_callback)](Status status) mutable {
+                metrics->async_pending.fetch_sub(1, kMetricsMemoryOrder);
+                if (status.ok()) {
+                    metrics->async_completed.fetch_add(1, kMetricsMemoryOrder);
+                    metrics->async_physical_bytes.fetch_add(
+                        static_cast<uint64_t>(std::max<int64_t>(0, size)), 
kMetricsMemoryOrder);
+                } else {
+                    metrics->async_failed.fetch_add(1, kMetricsMemoryOrder);
+                }
+                RecordLatency(ElapsedMicros(start), 
&metrics->async_latency_count,
+                              &metrics->async_latency_sum_us);
+                callback(status);
+            });
+    }
+
+    Status Close() override {
+        return stream_->Close();
+    }
+
+    Result<std::string> GetUri() const override {
+        return stream_->GetUri();
+    }
+
+    Result<int64_t> Length() const override {
+        return stream_->Length();
+    }
+
+ private:
+    template <typename ReadFunction>
+    Result<int64_t> RecordRead(ReadFunction&& read, int64_t size) {
+        if (!metrics_) {
+            Result<int64_t> result = read();
+            if (result.ok()) {
+                storage_read_bytes_->fetch_add(
+                    static_cast<uint64_t>(std::max<int64_t>(0, 
result.value())),
+                    kMetricsMemoryOrder);
+            }
+            return result;
+        }
+        metrics_->read_requests.fetch_add(1, kMetricsMemoryOrder);
+        
metrics_->read_requested_bytes.fetch_add(static_cast<uint64_t>(std::max<int64_t>(0,
 size)),
+                                                 kMetricsMemoryOrder);
+        const auto start = std::chrono::steady_clock::now();
+        Result<int64_t> result = read();
+        if (result.ok()) {
+            storage_read_bytes_->fetch_add(
+                static_cast<uint64_t>(std::max<int64_t>(0, result.value())), 
kMetricsMemoryOrder);
+            metrics_->read_physical_bytes.fetch_add(
+                static_cast<uint64_t>(std::max<int64_t>(0, result.value())), 
kMetricsMemoryOrder);
+        } else {
+            metrics_->read_failed.fetch_add(1, kMetricsMemoryOrder);
+        }
+        RecordLatency(ElapsedMicros(start), &metrics_->read_latency_count,
+                      &metrics_->read_latency_sum_us);
+        return result;
+    }
+
+    std::shared_ptr<InputStream> stream_;
+    std::shared_ptr<PrefetchIoMetricsState> metrics_;
+    std::shared_ptr<std::atomic<uint64_t>> storage_read_bytes_;
+};
+
+}  // namespace
+
+std::shared_ptr<FileReadAhead> FileReadAhead::Create(const 
std::shared_ptr<ReadAheadCache>& cache,
+                                                     const std::string& path) {
+    return std::shared_ptr<FileReadAhead>(new FileReadAhead(cache, path));
+}
+
+Result<FileReadAhead::OpenedReaders> FileReadAhead::Open(
+    const std::string& path, int64_t file_size, const ReaderBuilder* builder,
+    const std::shared_ptr<FileSystem>& fs, uint32_t reader_count,
+    const std::shared_ptr<Executor>& executor, bool cache_enabled, const 
CacheConfig& cache_config,
+    bool enable_io_metrics, const std::shared_ptr<MemoryPool>& pool) {
+    if (file_size < 0 || !builder || !fs || reader_count == 0 || (!executor && 
reader_count > 1)) {
+        return Status::Invalid("invalid file read-ahead open arguments");
+    }
+    std::shared_ptr<PrefetchIoMetricsState> io_metrics;
+    if (enable_io_metrics) {
+        io_metrics = std::make_shared<PrefetchIoMetricsState>();
+    }
+    // Synchronous reads need no executor and open/build inline. With an 
executor, opening a file
+    // mostly waits on remote I/O, so the streams are all opened concurrently
+    // instead of opening the cache's stream first and paying its round trip 
before the readers'
+    // begin. Both waves run on the read context's `executor`, which is sized 
to the prefetch
+    // parallelism, so no separate pool is spun up and torn down per file and 
the open/build
+    // concurrency follows the configured parallelism instead of a fixed 
default. That reuse is
+    // safe: neither wave's tasks wait on one another or on `executor`, and 
Create never runs on
+    // an `executor` worker, so the CollectAll calls below only ever wait on 
tasks that progress.
+    // The build has to be a second wave rather than folded into the first: 
each build task wraps
+    // its stream in the cache, and a task waiting on the cache would block a 
worker while the
+    // cache's own open is still queued behind it. Wave one only opens, so its 
tasks never wait on
+    // one another.
+    const uint32_t open_count = cache_enabled ? reader_count + 1 : 
reader_count;
+    std::vector<std::future<Result<std::unique_ptr<InputStream>>>> 
open_futures;
+    open_futures.reserve(open_count);
+    for (uint32_t i = 0; i < open_count; i++) {
+        open_futures.push_back(RunOrSubmit(
+            executor.get(), [&fs, &path, file_size]() -> 
Result<std::unique_ptr<InputStream>> {
+                return fs->Open(FileStatus(path, file_size));
+            }));
+    }
+    // The tasks only reference locals of this frame, which stay alive because 
both CollectAll
+    // calls below drain every future before returning.
+    std::vector<Result<std::unique_ptr<InputStream>>> opened_streams = 
CollectAll(open_futures);
+    std::vector<std::unique_ptr<InputStream>> streams;
+    streams.reserve(opened_streams.size());
+    for (auto& opened_stream : opened_streams) {
+        if (!opened_stream.ok()) {
+            return opened_stream.status();
+        }
+        streams.push_back(std::move(opened_stream).value());
+    }
+
+    auto state = Create(nullptr, path);
+    state->io_metrics_ = io_metrics;
+    size_t next_stream = 0;
+    std::shared_ptr<ReadAheadCache> cache;
+    if (cache_enabled) {
+        std::shared_ptr<InputStream> input_stream = 
std::move(streams[next_stream++]);
+        input_stream = std::make_shared<MetricsInputStream>(input_stream, 
io_metrics,
+                                                            
state->storage_read_bytes_);
+        // The file size lets the cache align its blocks to the end of the 
file,
+        // where the metadata the readers read before any range is registered
+        // lives. A zero size means unknown and disables the block cache.
+        cache = std::make_shared<ReadAheadCache>(input_stream, cache_config,
+                                                 
static_cast<uint64_t>(file_size), pool);
+    }
+    state->cache_ = cache;
+    // Wave two builds the readers, which reads each file's footer and so 
still needs the cache
+    // above to exist. The builds are concurrent, like the opens were.
+    std::vector<std::future<Result<std::unique_ptr<FileBatchReader>>>> futures;
+    futures.reserve(reader_count);
+    for (uint32_t i = 0; i < reader_count; i++) {
+        futures.push_back(RunOrSubmit(
+            executor.get(),
+            [&builder, &cache, &streams, i, next_stream, io_metrics,

Review Comment:
   **[P2] Wait for all submitted tasks before unwinding `Open()`**
   
   `CollectAll()` exits immediately if a `future.get()` throws; it does not 
drain the remaining futures on that path. These tasks capture `builder`, 
`cache`, and `streams` by reference, so an allocation failure in one task can 
unwind `Open()` and destroy its locals while another task is still accessing 
them, causing a use-after-free. An exception while submitting a later task has 
the same problem. Destroying these promise-backed futures does not wait for the 
tasks to finish. Please ensure exception-safe cleanup waits for all accepted 
tasks before destroying the objects they reference.



-- 
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]

Reply via email to