[Feature] Decouple raw warmup and read-ahead caching from batch prefetch #512

Search before asking

• I searched the existing issues. This is the independent byte-cache/warmup follow-up described in [Feature] Warm up next data file in ConcatBatchReader #419.

Motivation

Warmup and the shared read-ahead cache currently depend on batch prefetch. The factory creates the cache only when prefetch is enabled, and the delegating reader skips warmup when the format or adaptive strategy disables prefetch.

The default configuration therefore cannot warm synchronous Parquet/ORC reads:

builder.EnablePrefetch(false)
    .SetReadAheadCacheEnabled(true)
    .SetWarmupLevel(WarmupLevel::RAW);

Users should be able to overlap raw-byte I/O without enabling parallel batch decoding or maintaining decoded batches for the next file.

Solution

Keep warmup limited to NONE and RAW, and decouple raw-byte caching from batch prefetch:

• Share cache creation, byte-range registration, late-materialization callbacks, I/O metrics and cache lifecycle between synchronous and parallel readers.
• Let synchronous Parquet/ORC reads use one format reader, without a prefetch executor or queue configuration.
• RAW warms the byte cache without decoding batches. It is a no-op when the cache is disabled.
• NONE disables early warmup while retaining caching during actual reads.
• Keep RAW warmup working when the format or adaptive strategy declines batch prefetch.
• Remove DECODED warmup and its early background decoding. Actual batch reads start the normal parallel decode loop when prefetch is enabled.
• Disable Parquet's own pre-buffering whenever the shared byte cache is active.

Anything else?

Removing WarmupLevel::DECODED is an intentional source API change. Callers using it must select RAW or NONE. Keep the remaining enum values, RAW default, cache/prefetch defaults, storage format and lookahead window unchanged.

Warming may fetch bytes for an unconsumed file, and closing a reader waits for in-flight byte fetches. RAW only overlaps I/O when the filesystem's ReadAsync is asynchronous; use NONE to avoid early synchronous fetches on local filesystems. Other format plugins retain their plain read path.

Validation covers cache on/off, both remaining warmup levels, explicit/adaptive/format prefetch fallback, late materialization, predicates and bitmaps, row IDs, repeated warmup, schema reset, deferred failures and early close. Tests must prove Warmup never decodes batches and synchronous reads remain on the caller thread.

Are you willing to submit a PR?

• I'm willing to submit a PR!

Generated-by: OpenAI Codex (codex-cli 0.166.0)