Extend FS buffer prefetch to async multi-buffer path

[eniac1024]

Problem

RocksDB's FilePrefetchBuffer supports an optimization where the filesystem provides its own buffer (fs_scratch), avoiding an extra memory copy. However, this optimization was restricted to the synchronous single-buffer path (num_buffers_ == 1). The async multi-buffer prefetch path — used for scan-ahead with 2+ buffers — always allocated its own buffers and copied data, missing the zero-copy benefit.

Solution

Remove the num_buffers_ == 1 gate from UseFSBuffer() and plumb use_fs_buffer through the entire async pipeline:

• ReadAsync: sets scratch = nullptr to signal the FS to provide its own buffer; sync fallback routes to FSBufferDirectRead
• PrefetchAsyncCallback: adopts FS-provided buffer via SetBuffer() instead of updating pre-allocated buffer size
• HandleOverlappingAsyncData: handles the single-buffer-remaining case for FS buffers by polling async reads and copying partial data to overlap_buf_; passes use_fs_buffer through the multi-buffer path
• PrefetchAsync / PrefetchRemBuffers: compute use_fs_buffer once and thread it through all ReadAheadSizeTuning, PrepareBufferForRead, and ReadAsync calls

Tests are updated to exercise FS buffer mode in async paths, with two new tests (PrefetchAsyncWithFSBuffer, SequentialReadWithFSBuffer) validating correctness.

file/file_prefetch_buffer.h

• Removed num_buffers_ == 1 restriction from UseFSBuffer()

• Added use_fs_buffer parameter to ReadAsync() and PrefetchRemBuffers()

• Updated comment on UseFSBuffer() to remove stale "async not handled" note

file/file_prefetch_buffer.cc

• ReadAsync: sets scratch = nullptr when use_fs_buffer; sync fallback routes to FSBufferDirectRead

• PrefetchAsyncCallback: added fs_scratch branch adopting FS buffer via SetBuffer() with offset_/initial_end_offset_ update

• HandleOverlappingAsyncData: added single-buffer FS path — polls async read if in progress, copies partial data to overlap_buf_; multi-buffer path computes and passes use_fs_buffer instead of hardcoded false

• PrefetchInternal: added num_buffers_ == 1 guard on HandleOverlappingSyncData; replaced redundant UseFSBuffer(reader) call with cached local

• PrefetchAsync: computes use_fs_buffer once and threads it through all ReadAheadSizeTuning, PrepareBufferForRead, and ReadAsync calls

• PrefetchRemBuffers: accepts and threads use_fs_buffer to ReadAheadSizeTuning and ReadAsync

file/prefetch_test.cc

• SetUp always uses BufferReuseFS (previously skipped for async)

• Added ReadAsync override in mock FS with fs_scratch allocation (scratch == nullptr check) and io_handle/del_fn set to nullptr

• Updated FSBufferPrefetchStatsInternals with separate use_fs_buffer assertion branches for async path

• Refactored FSBufferPrefetchUnalignedReads — unified sync/async assertions where FS buffer alignment = 1 makes them identical

• New test: PrefetchAsyncWithFSBuffer — async prefetch at non-zero offset, num_buffers = 2

• New test: SequentialReadWithFSBuffer — two consecutive sequential reads with both sync and async paths

db/db_io_failure_test.cc

• Added ReadAsync override in CorruptionFS with fs_scratch allocation for FS buffer mode

• IterReadCorruptionRetry: skips fs_buffer + async_io combination (read ordering changes cause corruption to hit wrong read)

[github-actions]

✅ clang-tidy: No findings on changed lines

Completed in 179.7s.