Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
7654cf7
[feature](be) Add linear file range coalescing
bobhan1 Aug 28, 2026
90cf5b6
[feature](be) Add cache-aware file range planning
bobhan1 Aug 28, 2026
85894d0
[feature](be) Add file range read scheduler
bobhan1 Aug 28, 2026
c64e719
[feature](be) Reuse remote-only reads for no-write ranges
bobhan1 Aug 28, 2026
563b5ba
[feature](be) Add query read-ahead runtime ownership
bobhan1 Aug 28, 2026
e2a4012
[improvement](be) Add opt-in file range IO tracing
bobhan1 Sep 22, 2026
8a08ae1
[fix](be) Scope filesystem error-code imports to their functions
bobhan1 Oct 15, 2026
4271da9
[feature](be) Add page-driven column read-ahead windows
bobhan1 Aug 28, 2026
e7dbfa1
[feature](be) Add segment range read-ahead coordination
bobhan1 Oct 29, 2026
00fa56b
[feature](be) Connect scalar column readers to range read-ahead
bobhan1 Sep 2, 2026
8190e0f
[feature](be) Initialize scan read-ahead once after pruning
bobhan1 Oct 29, 2026
d03f274
[feature](be) Add complete-block cache write handoff and admission
bobhan1 Aug 28, 2026
a547700
[feature](be) Split consumed ranges for cache writeback
bobhan1 Aug 28, 2026
7cfe76c
[feature](be) Add cache block hole-fill planning
bobhan1 Aug 28, 2026
a7e3899
[feature](be) Add background partial block writeback
bobhan1 Aug 28, 2026
999f5c6
[feature](be) Initialize background hole fill
bobhan1 Aug 28, 2026
6fd7bb6
[feature](be) Route consumed ranges to cache writeback
bobhan1 Aug 28, 2026
1ae1272
[feature](be) Connect read-ahead range writeback
bobhan1 Aug 28, 2026
fd6df2c
[feature](be) Extend range read-ahead to point queries
bobhan1 Sep 2, 2026
a881473
[fix](be) Validate S3 upload buffer alignment on config updates
bobhan1 Oct 29, 2026
b237ebc
[fix](be) Handle irregular cache blocks in writeback coverage checks
bobhan1 Oct 29, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
[feature](be) Route consumed ranges to cache writeback
### What problem does this PR solve?

Issue Number: Part of #67611

Related PR: #67292, #67579

Problem Summary: Consumed read-ahead buffers can span complete and partial cache blocks. Split each range, submit complete blocks to the existing asynchronous cache writer, and enqueue partial fragments for background completion under the captured invalidation epoch. Preserve unified cache/inflight reuse and mixed outcomes. Carry the originating read identity into partial tasks and interval traces, and separate complete/partial foreground dispatch time in Profile counters. Read and persistence outcomes remain best effort.

### Release note

None

### Check List (For Author)

- Test: Unit Test
    - Component tests are included with the implementation; rebase and synchronization validation is recorded in the related PRs and tracking issue.
    - Repository clang-format 16, header hygiene and git diff --check passed before folding.
    - No cluster, external-object-store benchmark or clang-tidy run during synchronization.
- Behavior changed: Yes, includes final component behavior and applicable diagnostic instrumentation; default enable switches remain off.
- Does this need documentation: Yes, tools/read_io_trace/README.md and related PR/tracking descriptions.
  • Loading branch information
bobhan1 committed Oct 29, 2026
commit 6fd7bb6550ad40e1a9909cb2a1ae7c60ba129de9
176 changes: 176 additions & 0 deletions be/src/io/cache/range_cache_writeback.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
// 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 "io/cache/range_cache_writeback.h"

#include <utility>

#include "common/logging.h"
#include "io/cache/partial_block_writeback_manager.h"
#include "io/fs/read_ahead_metrics.h"
#include "io/fs/read_io_trace.h"
#include "util/time.h"

namespace doris::io {

RangeCacheWriteback::RangeCacheWriteback(RangeCacheWritebackOptions options)
: _options(std::move(options)) {
DORIS_CHECK(_options.write_manager != nullptr);
DORIS_CHECK(_options.partial_block_manager != nullptr);
DORIS_CHECK(_options.source_reader != nullptr);
DORIS_CHECK(_options.file_size > 0);
DORIS_CHECK(_options.source_reader->size() == _options.file_size);
DORIS_CHECK(_options.block_size > 0);
}

std::optional<AsyncCacheWriteEpoch> RangeCacheWriteback::capture_write_epoch() const {
if (!_options.write_manager->accepting()) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Start a cache writer before replacing the cache-populating read path. With the default enable_async_file_cache_write=false, BlockFileCache leaves its writer unstarted; only enabling that separate flag starts it. Turning on enable_query_read_ahead alone still forces range reads to NO_WRITE, but this guard then returns no epoch and the consumed-range callback skips every writeback. Successfully prefetched cold data pages consequently never populate File Cache (and repeat remote GETs whenever Page Cache does not retain them), whereas the original synchronous path did populate it. Arrange a functioning writer for read-ahead or preserve the normal cache-population path when the writer is unavailable; cover this default flag combination.

return std::nullopt;
}
return _options.write_manager->current_write_epoch(_options.cache_hash);
}

RangeWritebackDispatchResult RangeCacheWriteback::submit_consumed_range(
const FileRange& range, Slice data, const AsyncCacheWriteEpoch& write_epoch,
ReadAheadStatistics* statistics, uint64_t trace_id) {
DORIS_CHECK(write_epoch.key_token != nullptr);
SCOPED_TIMER(statistics != nullptr ? &statistics->writeback_time : nullptr);
const bool trace_enabled = ReadIOTrace::enabled();
const auto start_ns = trace_enabled ? MonotonicNanos() : 0;
RangeWritebackTiming timing;
auto trace_context = _options.io_context.io_context;
trace_context.read_trace_source = FileReadTraceSource::READ_AHEAD;
Defer trace_done {[&] {
if (trace_enabled) {
ReadIOTrace::record({.event = "range_writeback_done",
.context = &trace_context,
.file = _options.source_reader->path().native(),
.id = trace_id,
.offset = range.offset,
.size = range.size,
.time_ns = MonotonicNanos(),
.start_ns = start_ns,
.writeback_timing = &timing});
}
}};
if (!_options.write_manager->accepting()) {
return {};
}
if (trace_enabled) {
const auto trace_start = MonotonicNanos();
ReadIOTrace::record({.event = "range_writeback",
.context = &trace_context,
.file = _options.source_reader->path().native(),
.id = trace_id,
.offset = range.offset,
.size = range.size});
timing.lifecycle_trace_ns += MonotonicNanos() - trace_start;
}
RangeWritebackDispatcher dispatcher(
_options.file_size, _options.block_size,
[&](const FileCacheBlockFragment& fragment) {
const auto start = trace_enabled ? MonotonicNanos() : 0;
const auto result = _submit_complete_block(fragment, write_epoch, statistics);
if (trace_enabled) {
timing.complete_submit_ns += MonotonicNanos() - start;
}
return result;
},
[&](const FileCacheBlockFragment& fragment) {
const auto start = trace_enabled ? MonotonicNanos() : 0;
const auto result =
_submit_partial_block(fragment, write_epoch, statistics, trace_id);
if (trace_enabled) {
timing.partial_submit_ns += MonotonicNanos() - start;
}
return result;
});
return dispatcher.dispatch(range, data);
}

bool RangeCacheWriteback::_submit_complete_block(const FileCacheBlockFragment& fragment,
const AsyncCacheWriteEpoch& write_epoch,
ReadAheadStatistics* statistics) {
DORIS_CHECK(fragment.complete());
SCOPED_TIMER(statistics != nullptr ? &statistics->complete_block_submit_time : nullptr);
const auto result = _options.write_manager->try_submit_block(AsyncCacheWriteBlockRequest {
.cache_hash = _options.cache_hash,
.file_offset = fragment.block_offset,
.data = fragment.data,
.buffer_size = _options.block_size,
.admission_ctx = _options.admission_ctx,
.write_epoch = write_epoch,
.inflight_index = _options.inflight_index,
});
if (statistics != nullptr) {
if (result == AsyncCacheWriteBlockSubmitResult::SUBMITTED) {
COUNTER_UPDATE(&statistics->complete_blocks_submitted, 1);
COUNTER_UPDATE(&statistics->complete_block_bytes, fragment.data.size);
} else if (result == AsyncCacheWriteBlockSubmitResult::ALREADY_INFLIGHT) {
COUNTER_UPDATE(&statistics->writeback_deduplicated_blocks, 1);
} else {
COUNTER_UPDATE(&statistics->writeback_rejected_blocks, 1);
}
}
return result == AsyncCacheWriteBlockSubmitResult::SUBMITTED ||
result == AsyncCacheWriteBlockSubmitResult::ALREADY_INFLIGHT;
}

bool RangeCacheWriteback::_submit_partial_block(const FileCacheBlockFragment& fragment,
const AsyncCacheWriteEpoch& write_epoch,
ReadAheadStatistics* statistics,
uint64_t trace_id) {
DORIS_CHECK(!fragment.complete());
SCOPED_TIMER(statistics != nullptr ? &statistics->partial_block_submit_time : nullptr);
auto io_context = _options.io_context;
io_context.io_context.read_trace_id = trace_id;
io_context.io_context.read_trace_source = FileReadTraceSource::READ_AHEAD;
const auto result = _options.partial_block_manager->try_submit(PartialBlockWritebackRequest {
.write_manager = _options.write_manager,
.inflight_index = _options.inflight_index,
.source_reader = _options.source_reader,
.cache_hash = _options.cache_hash,
.block_offset = fragment.block_offset,
.block_valid_size = fragment.block_valid_size,
.fragment_offset = fragment.fragment_offset,
.data = fragment.data,
.admission_ctx = _options.admission_ctx,
.write_epoch = write_epoch,
.io_context = std::move(io_context),
});
if (statistics != nullptr) {
if (result == PartialBlockSubmitResult::QUEUED ||
result == PartialBlockSubmitResult::MERGED) {
auto* counter = result == PartialBlockSubmitResult::QUEUED
? &statistics->partial_blocks_queued
: &statistics->partial_blocks_merged;
COUNTER_UPDATE(counter, 1);
COUNTER_UPDATE(&statistics->partial_fragment_bytes, fragment.data.size);
} else if (result == PartialBlockSubmitResult::ACTIVE_DEDUPLICATED ||
result == PartialBlockSubmitResult::CACHE_BLOCK_PRESENT) {
COUNTER_UPDATE(&statistics->writeback_deduplicated_blocks, 1);
} else {
COUNTER_UPDATE(&statistics->writeback_rejected_blocks, 1);
}
}
return result == PartialBlockSubmitResult::QUEUED ||
result == PartialBlockSubmitResult::MERGED ||
result == PartialBlockSubmitResult::ACTIVE_DEDUPLICATED ||
result == PartialBlockSubmitResult::CACHE_BLOCK_PRESENT;
}

} // namespace doris::io
80 changes: 80 additions & 0 deletions be/src/io/cache/range_cache_writeback.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
// 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 <cstddef>
#include <optional>

#include "io/cache/async_cache_write_manager.h"
#include "io/cache/range_writeback_dispatcher.h"
#include "io/fs/file_range_read_scheduler.h"
#include "io/fs/file_reader.h"

namespace doris::io {

class InflightWriteBufferIndex;
class PartialBlockWritebackManager;

struct RangeCacheWritebackOptions {
/// Non-owning asynchronous destinations; both must outlive this RangeCacheWriteback.
AsyncCacheWriteManager* write_manager {nullptr};
PartialBlockWritebackManager* partial_block_manager {nullptr};
/// Optional block-level deduplication index owned by the cached reader.
InflightWriteBufferIndex* inflight_index {nullptr};
/// Retained for background reads that complete partial blocks.
FileReaderSPtr source_reader;
UInt128Wrapper cache_hash;
size_t file_size {0};
size_t block_size {0};
/// Immutable admission and asynchronous IO state captured from the foreground query.
CacheAdmissionContext admission_ctx;
FileRangeReadIOContext io_context;
};

/// Routes an already consumed variable-length range into the two File Cache writeback paths.
/// Complete blocks enter the asynchronous cache writer directly; partial fragments enter the
/// BE-level hole-fill queue.
class RangeCacheWriteback {
public:
explicit RangeCacheWriteback(RangeCacheWritebackOptions options);

/// Capture the invalidation fence before the foreground range read starts. No epoch is retained
/// while asynchronous cache writing is disabled or shutting down.
std::optional<AsyncCacheWriteEpoch> capture_write_epoch() const;

/// Copy each block fragment into its owning asynchronous path. The range buffer only needs to
/// remain valid for this call.
RangeWritebackDispatchResult submit_consumed_range(const FileRange& range, Slice data,
const AsyncCacheWriteEpoch& write_epoch,
ReadAheadStatistics* statistics = nullptr,
uint64_t trace_id = 0);

private:
/// Copy a complete fragment directly into the asynchronous cache writer.
bool _submit_complete_block(const FileCacheBlockFragment& fragment,
const AsyncCacheWriteEpoch& write_epoch,
ReadAheadStatistics* statistics);
/// Copy a partial fragment into the background hole-fill manager.
bool _submit_partial_block(const FileCacheBlockFragment& fragment,
const AsyncCacheWriteEpoch& write_epoch,
ReadAheadStatistics* statistics, uint64_t trace_id);

const RangeCacheWritebackOptions _options;
};

} // namespace doris::io
Loading