feat(kernel range reader): Add buffer pooling support for large reads on regional buckets

[abhishek10004]

Description

Overview

This PR optimizes memory usage and reduces allocation overhead during large file reads by introducing a sync.Pool for buffer allocation and refactoring the vectored reading mechanism to allocate buffers on-demand (lazily).

High-Level Changes

1. Read Buffer Pooling (internal/fs)

• sync.Pool Integration: Introduced a 1 MiB buffer pool (readBufferPool) in fileSystem to reuse read buffers across requests and minimize GC pressure.
• Pool-Backed Read Requests: When serving reads without a destination buffer (op.Dst == nil), the filesystem now attaches a BufferPool wrapper to the read request instead of pre-allocating static slices upfront.
• Validation: Restricted buffer pool allocation to regional buckets with the kernel reader enabled.

2. Lazy Vectored Buffer Allocation (internal/gcsx)

• On-Demand Allocation: Introduced the BufferPool interface in ReadRequest, replacing static Buffers [][]byte slices. Refactored VectoredWriter to allocate buffers lazily from the pool up to a requested maximum size as data is read.
• Inode Vectored Reads: Added ReadFromOffset in VectoredWriter to support zero-copy vectored reading directly from inode sources when source generation is not authoritative.
• Automated Buffer Recycling: Added VectoredWriter.Release(), ensuring allocated buffers are returned to the pool immediately upon completion via response callbacks, or on 0-byte reads and early errors.

3. Kernel Reader Integration (internal/gcsx/kernel_readers)

• Vectored Reader Support: Updated KernelRangeReader.ReadAt to stream data into a pool-backed VectoredWriter when BufferPool is provided.
• Lifecycle Management: Configured read response callbacks to release buffers back to the pool once consumed by the FUSE layer.

4. Comprehensive Testing & Coverage

• Regional Read Integration: Added regional read tests (large_read_regional_test.go) verifying pool allocation and zero-copy read behavior.
• Vectored Writer Unit Tests: Added comprehensive table-driven unit tests in vectored_writer_test.go in AAA format covering buffer recycling (Release), non-zero offset reads (ReadFromOffset), oversized buffer truncation, pool exhaustion, and zero/negative max size limits.

Link to the issue in case of a bug fix.

b/530765312

Testing details

1. Manual - NA
2. Unit tests - NA
3. Integration tests - NA

Any backward incompatible change? If so, please explain.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request optimizes memory management for large file reads by implementing a buffer pooling strategy. By using a sync.Pool and lazy allocation, the system significantly reduces allocation overhead and memory fragmentation during high-throughput read operations on regional buckets.

Highlights

• Read Buffer Pooling: Introduced a sync.Pool for 1 MiB buffers in the filesystem to reduce GC pressure and reuse memory across read requests.
• Lazy Vectored Buffer Allocation: Refactored the vectored reading mechanism to allocate buffers on-demand from the pool, replacing static slice pre-allocation.
• Kernel Reader Integration: Updated the kernel range reader to support pool-backed vectored writes, including automated buffer recycling via response callbacks.
• Testing and Validation: Added comprehensive integration tests for regional buckets and unit tests for the vectored writer, covering edge cases like pool exhaustion and buffer recycling.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces on-demand buffer allocation and recycling using a sync.Pool for vectored reads when the kernel reader is enabled on regional buckets. It refactors ReadRequest to accept a BufferPool interface and updates VectoredWriter to allocate and release buffers dynamically. The review feedback highlights two critical issues: a potential runtime panic in bufferPoolWrapper.Put if the slice capacity is smaller than expected, and a potential memory leak in ReadWithKernelReader if an error occurs during a partial read, as the release callback might not be executed by the FUSE server.

[codecov]

Codecov Report

❌ Patch coverage is 94.00000% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.70%. Comparing base (2afb683) to head (7997793).
⚠️ Report is 5 commits behind head on master.

Files with missing lines	Patch %	Lines
internal/gcsx/test_buffer_pool.go	69.23%	4 Missing ⚠️
...nternal/gcsx/kernel_readers/kernel_range_reader.go	72.72%	2 Missing and 1 partial ⚠️
internal/gcsx/vectored_read_buffer.go	96.92%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4852      +/-   ##
==========================================
+ Coverage   83.67%   83.70%   +0.03%     
==========================================
  Files         170      172       +2     
  Lines       20948    21026      +78     
==========================================
+ Hits        17528    17600      +72     
- Misses       2763     2769       +6     
  Partials      657      657              

Flag	Coverage Δ
unittests	83.70% <94.00%> (+0.03%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[raj-prince]

Should we use mock instead for unit test?

[abhishek10004]

I thought about it and for now let's use this stub implementation as well. This allows us to test the state that's needed and also prevents test from getting noisy (otherwise we'd have to add extra statements in all tests). If in future, we need to modify the test pool or add extra functionality, then we can consider moving to mock. Let me know what you think.

[raj-prince]

Overall LGTM, added couple of minor comments.