new feature: support bounded buffered consumption of Python async file streams

[Xuanwo]

Feature Description

Offer a bounded consumption path that amortizes native-to-Python async crossings without converting a sequential stream into repeated Range requests.

Problem and Solution

AsyncFile.read(size) calls the core read_buffer(size), which can return the current underlying network buffer rather than filling the requested size. Each returned fragment crosses the Tokio/asyncio boundary and creates a Python result. A large requested size therefore does not by itself amortize small transport fragments.

An explicit buffered reader or iterator could aggregate existing network buffers within Rust under a bounded byte budget. Reuse the current core reader rather than issuing an HTTP range for every application chunk.

Acceptance criteria:

• Preserve the existing short-read, low-latency behavior of the default API.
• Define buffering limits, EOF/error delivery, seek/ranges, and cancellation.
• Compare natural sequential reads with the same consumer, recording actual request count, return-size histogram, CPU, first-byte latency, and memory.
• Verify that fewer crossings do not come from unbounded buffering or withholding small responses indefinitely.

Additional Context

Related to #8159, which already tracks asynchronous listing crossings. This request concerns file-stream consumption.

AsyncFile.read; Core read_buffer

read(size) and transport chunk are different controls. The existing unchunked reader is the baseline; forcing a chunk changes request strategy. Fewer callbacks may primarily improve CPU efficiency even when total transfer time is unchanged.

Source references are pinned to b6cf44f7b8a1523409e0e998e478c996ac970f03. This request describes an optimization opportunity; it does not claim a measured end-to-end speedup.

[Xuanwo]

The completed real-S3 benchmark now provides direct evidence that requested read size does not determine the number of Python crossings.

Measured OpenDAL commit: 4b132b0d33c8a5b84ff83f6fcfbab264860c5b3d; harness commit: c4c203859ed72d9a0ffac7438486a2d205649102. Real S3 in us-east-2, c7i.8xlarge with a 4-vCPU/1-GiB client limit, six formal repeats. Boto3 1.43.88 uses native APIs, without a transfer manager. Values below are medians, not significance claims. The harness and raw archive are currently private, so these numbers are descriptive evidence, not a publicly reproducible benchmark package.

Natural sequential download consumes the same 59,158,238-byte object with a SHA-256 consumer. Each client calls read(1 MiB) repeatedly until EOF; no explicit parallel Range strategy is enabled. consume_calls counts nonempty results actually passed to the consumer.

Client	Elapsed (s)	Process CPU (s)	Nonempty read results
Boto3	0.595	0.097	57
OpenDAL File	0.595	0.125	1173.5
OpenDAL AsyncFile	0.597	0.205	1083.5

Fractional call counts are medians across six runs. AsyncFile delivered about 19 times as many chunks as Boto3 despite the same requested size. Each chunk also invokes the Python SHA consumer; the CPU difference therefore includes both binding crossings and the additional consumer invocations. This is not an isolated measurement of bridge or mutex overhead.

This supports the existing bounded-buffered-consumption proposal. Merely increasing the caller's read(size) is not sufficient when the core returns a smaller available transport buffer. Preserve default short-read latency and backpressure; compare an explicit bounded buffering path using actual return-size distributions, first-byte latency, CPU, memory, and request counts. The current result demonstrates a CPU-efficiency opportunity, not a download wall-clock speedup.