Skip to main content

agave_fs/
buffered_reader.rs

1#![allow(clippy::arithmetic_side_effects)]
2
3//! File I/O buffered readers for AppendVec
4//! Specialized `BufRead`-like types for reading account data.
5//!
6//! Callers can use these types to iterate efficiently over append vecs. They can do so by repeatedly
7//! calling:
8//! * `fill_buf_required(account_meta_len)` to scan the account metadata parts and determine the account
9//!   data size,
10//!  * optionally extend the obtained buffer to full account data using
11//!    `fill_buf_required(account_all_bytes_len)`
12//!  * `consume(account_all_bytes_len)` to move to the next account
13//!
14//! When reading full accounts data whose sizes exceed the small stack buffer, the `BufReaderWithOverflow`
15//! should be used, which supports dynamically allocated buffer for preparing contiguous data slices.
16#[cfg(target_os = "linux")]
17pub use crate::io_uring::sequential_file_reader::{
18    SequentialFileReader, SequentialFileReaderBuilder,
19};
20use {
21    crate::{
22        FileSize,
23        file_io::{read_into_buffer, read_more_buffer},
24        io_setup::IoSetupState,
25    },
26    std::{
27        fs::File,
28        io::{self, BufRead},
29        mem::MaybeUninit,
30        ops::Range,
31        path::Path,
32        slice,
33    },
34};
35
36/// A stack-allocated buffer.
37///
38/// This is a fixed-size buffer that is allocated on the stack.
39///
40/// This should be used when the required size is known at compile time and is within reasonable stack
41/// limits.
42struct Stack<const N: usize>([MaybeUninit<u8>; N]);
43
44impl<const N: usize> Stack<N> {
45    #[inline(always)]
46    const fn new() -> Self {
47        Self([MaybeUninit::uninit(); N])
48    }
49}
50
51impl<const N: usize> Stack<N> {
52    fn capacity(&self) -> usize {
53        N
54    }
55
56    #[inline(always)]
57    unsafe fn as_slice(&self) -> &[u8] {
58        unsafe { slice::from_raw_parts(self.0.as_ptr() as *const u8, N) }
59    }
60
61    #[inline(always)]
62    unsafe fn as_mut_slice(&mut self) -> &mut [u8] {
63        unsafe { slice::from_raw_parts_mut(self.0.as_mut_ptr() as *mut u8, N) }
64    }
65}
66
67/// An extension of the `BufRead` trait for file readers that allow tracking file
68/// read position offset.
69pub trait FileBufRead<'a>: BufRead {
70    /// Activate the given `file` as source of reads of this reader.
71    ///
72    /// Resets the internal buffer to an empty state and sets the file offset to 0.
73    ///
74    /// `read_limit` provides a pre-defined limit on the number of bytes that can be read
75    /// from the file (unless EOF is reached).
76    ///
77    /// If the file was previously queued via `add_file_to_prefetch`, the reader
78    /// advances to that file (validating identity / `read_limit`) rather than
79    /// re-queueing it.
80    fn set_file(&mut self, file: &'a File, read_limit: FileSize) -> io::Result<()>;
81
82    /// Queue `file` for read-ahead (prefetch). Files are processed in FIFO order
83    /// by subsequent `set_file` calls.
84    ///
85    /// This is a hint to keep the read pipeline saturated for readers that
86    /// support concurrent read-ahead. Implementations without read-ahead may
87    /// ignore the call. Callers must still invoke `set_file` to switch the
88    /// active file.
89    fn add_file_to_prefetch(&mut self, file: &'a File, read_limit: FileSize) -> io::Result<()>;
90
91    /// Returns the current file offset corresponding to the start of the buffer
92    /// that will be returned by the next call to `fill_buf`.
93    ///
94    /// This offset represents the position within the underlying file where data
95    /// will be consumed from.
96    fn get_file_offset(&self) -> FileSize;
97
98    /// Advance the offset by `amt` bytes, potentially skipping past the current buffer
99    /// into the underlying file.
100    ///
101    /// Unlike `BufRead::consume`, `amt` is not constrained by the size of the buffer
102    /// returned by `fill_buf` — any bytes beyond what is currently buffered are skipped
103    /// by advancing the file read offset, so the next `fill_buf` starts at the correct
104    /// position.
105    fn consume_or_skip(&mut self, n: usize);
106}
107
108/// An extension of the `BufRead` trait for readers that require stronger control
109/// over returned buffer size.
110///
111/// Unlike the standard `BufRead`, which only guarantees a non-empty buffer,
112/// this trait allows callers to enforce a minimum number of contiguous bytes
113/// to be made available.
114pub trait RequiredLenBufRead: BufRead {
115    /// Ensures the internal buffer contains at least `required_len` contiguous bytes,
116    /// and returns a slice of that buffer.
117    ///
118    /// Note: subsequent calls with the same or larger `required_len` are allowed, but
119    /// before requesting smaller length all already provided bytes should be consumed
120    /// using a single `consume` call.
121    ///
122    /// Returns `Err(io::ErrorKind::UnexpectedEof)` if the end of file is reached
123    /// before the required number of bytes is available.
124    ///
125    /// Returns `Err(io::ErrorKind::QuotaExceeded)` if `required_len` exceeds supported limit.
126    fn fill_buf_required(&mut self, required_len: usize) -> io::Result<&[u8]>;
127}
128
129pub trait RequiredLenBufFileRead<'a>: RequiredLenBufRead + FileBufRead<'a> {}
130impl<'a, T: RequiredLenBufRead + FileBufRead<'a>> RequiredLenBufFileRead<'a> for T {}
131
132/// read a file a large buffer at a time and provide access to a slice in that buffer
133pub struct BufferedReader<'a, const N: usize> {
134    /// when we are next asked to read from file, start at this offset
135    file_offset_of_next_read: FileSize,
136    /// the most recently read data. `buf_valid_bytes` specifies the range of `buf` that is valid.
137    buf: Stack<N>,
138    /// specifies the range of `buf` that contains valid data that has not been used by the caller
139    buf_valid_bytes: Range<usize>,
140    /// offset in the file of the `buf_valid_bytes`.`start`
141    file_last_offset: FileSize,
142    /// how many bytes are valid in the file. The file's len may be longer.
143    file_len_valid: FileSize,
144    /// reference to file handle
145    file: Option<&'a File>,
146}
147
148impl<'a, const N: usize> BufferedReader<'a, N> {
149    pub const fn new() -> Self {
150        Self {
151            file_offset_of_next_read: 0,
152            buf: Stack::new(),
153            buf_valid_bytes: 0..0,
154            file_last_offset: 0,
155            file_len_valid: 0,
156            file: None,
157        }
158    }
159
160    pub fn with_file(mut self, file: &'a File, read_limit: FileSize) -> Self {
161        self.do_set_file(file, read_limit);
162        self
163    }
164
165    fn do_set_file(&mut self, file: &'a File, read_limit: FileSize) {
166        self.file = Some(file);
167        self.file_len_valid = read_limit;
168        self.file_last_offset = 0;
169        self.file_offset_of_next_read = 0;
170        self.buf_valid_bytes = 0..0;
171    }
172
173    /// Reset to idle state and re-type with a fresh lifetime `'b`.
174    pub fn rebind<'b>(self) -> io::Result<BufferedReader<'b, N>> {
175        Ok(BufferedReader {
176            file_offset_of_next_read: 0,
177            buf: self.buf,
178            buf_valid_bytes: 0..0,
179            file_last_offset: 0,
180            file_len_valid: 0,
181            file: None,
182        })
183    }
184}
185
186impl<'a, const N: usize> FileBufRead<'a> for BufferedReader<'a, N> {
187    fn set_file(&mut self, file: &'a File, read_limit: FileSize) -> io::Result<()> {
188        self.do_set_file(file, read_limit);
189        Ok(())
190    }
191
192    /// `BufferedReader` does not perform read-ahead — the call is a no-op and
193    /// the file becomes active only when `set_file` is later invoked.
194    fn add_file_to_prefetch(&mut self, _file: &'a File, _read_limit: FileSize) -> io::Result<()> {
195        Ok(())
196    }
197
198    #[inline(always)]
199    fn get_file_offset(&self) -> FileSize {
200        if self.buf_valid_bytes.is_empty() {
201            self.file_offset_of_next_read
202        } else {
203            self.file_last_offset + self.buf_valid_bytes.start as FileSize
204        }
205    }
206
207    fn consume_or_skip(&mut self, amt: usize) {
208        if self.buf_valid_bytes.len() >= amt {
209            self.buf_valid_bytes.start += amt;
210        } else {
211            let additional_amount_to_skip = amt - self.buf_valid_bytes.len();
212            self.buf_valid_bytes = 0..0;
213            self.file_offset_of_next_read += additional_amount_to_skip as FileSize;
214        }
215    }
216}
217
218impl<const N: usize> BufferedReader<'_, N> {
219    /// Defragment buffer and read more bytes to make sure we have filled available
220    /// space as much as possible.
221    fn read_more_bytes(&mut self) -> io::Result<()> {
222        // we haven't used all the bytes we read last time, so adjust the effective offset
223        debug_assert!(self.buf_valid_bytes.len() as FileSize <= self.file_offset_of_next_read);
224        self.file_last_offset =
225            self.file_offset_of_next_read - self.buf_valid_bytes.len() as FileSize;
226        let Some(file) = &self.file else {
227            return Err(io::Error::new(io::ErrorKind::BrokenPipe, "no open file"));
228        };
229        read_more_buffer(
230            file,
231            self.file_len_valid,
232            &mut self.file_offset_of_next_read,
233            // SAFETY: `read_more_buffer` will only _write_ to uninitialized memory and lifetime is tied to self.
234            unsafe { self.buf.as_mut_slice() },
235            &mut self.buf_valid_bytes,
236        )
237    }
238
239    fn valid_slice(&self) -> &[u8] {
240        // SAFETY: We only read from memory that has been initialized by `read_more_buffer`
241        // and lifetime is tied to self.
242        unsafe { &self.buf.as_slice()[self.buf_valid_bytes.clone()] }
243    }
244}
245
246impl<const N: usize> io::Read for BufferedReader<'_, N> {
247    fn read(&mut self, mut buf: &mut [u8]) -> io::Result<usize> {
248        let available_len = self.buf_valid_bytes.len();
249        if available_len > 0 {
250            // Copy already read data to buf.
251            let available_valid_data = self.valid_slice();
252            if available_len >= buf.len() {
253                buf.copy_from_slice(&available_valid_data[..buf.len()]);
254                self.consume(buf.len());
255                return Ok(buf.len());
256            }
257            // Only part of the buffer can be filled.
258            buf[..available_len].copy_from_slice(available_valid_data);
259            buf = &mut buf[available_len..];
260        }
261
262        // Read directly from file into space still left in the buf.
263        let Some(file) = &self.file else {
264            return Err(io::Error::new(io::ErrorKind::BrokenPipe, "no open file"));
265        };
266        let bytes_read = read_into_buffer(
267            file,
268            self.file_len_valid,
269            self.file_offset_of_next_read,
270            buf,
271        )?;
272        let filled_len = bytes_read + available_len;
273        // Buffer was successfully filled, drop buffered data and move offset.
274        self.consume_or_skip(filled_len);
275        Ok(filled_len)
276    }
277}
278
279/// `BufferedReader` implements a more permissive API compared to `BufRead`
280/// by allowing `consume` to advance beyond the end of the buffer returned by `fill_buf`.
281impl<const N: usize> BufRead for BufferedReader<'_, N> {
282    fn fill_buf(&mut self) -> io::Result<&[u8]> {
283        if self.buf_valid_bytes.is_empty() {
284            self.read_more_bytes()?;
285        }
286        Ok(self.valid_slice())
287    }
288
289    /// Advance the buffer position by `amt`, clamped to the end of the currently buffered data.
290    ///
291    /// This follows the standard `BufRead::consume` contract: `amt` must not exceed the buffer
292    /// length returned by the preceding `fill_buf`. To skip bytes beyond the current buffer,
293    /// use [`FileBufRead::consume_or_skip`] instead.
294    fn consume(&mut self, amt: usize) {
295        self.buf_valid_bytes.start = self
296            .buf_valid_bytes
297            .end
298            .min(self.buf_valid_bytes.start + amt)
299    }
300}
301
302/// Supported `required_len` is limited by backing buffer size without ability to grow.
303impl<const N: usize> RequiredLenBufRead for BufferedReader<'_, N> {
304    fn fill_buf_required(&mut self, required_len: usize) -> io::Result<&[u8]> {
305        if self.buf_valid_bytes.len() < required_len {
306            self.read_more_bytes()?;
307            if self.buf_valid_bytes.len() < required_len {
308                if required_len > self.buf.capacity() {
309                    return Err(io::Error::new(
310                        io::ErrorKind::QuotaExceeded,
311                        "requested more bytes than supported by buffer",
312                    ));
313                }
314                return Err(io::Error::new(
315                    io::ErrorKind::UnexpectedEof,
316                    "unable to read enough data",
317                ));
318            }
319        }
320        Ok(self.valid_slice())
321    }
322}
323
324/// A buffered reader that wraps `BufRead` instance and implements `RequiredLenBufRead`.
325///
326/// It uses auxiliary overflow buffer when `fill_buf` returns slice that doesn't satisfy
327/// the length requirement.
328pub struct BufReaderWithOverflow<R> {
329    reader: R,
330    overflow_buf: Vec<u8>,
331    overflow_min_capacity: usize,
332    overflow_max_capacity: usize,
333}
334
335impl<R: BufRead> BufReaderWithOverflow<R> {
336    pub fn new(reader: R, overflow_min_capacity: usize, overflow_max_capacity: usize) -> Self {
337        Self {
338            reader,
339            overflow_buf: Vec::new(),
340            overflow_min_capacity,
341            overflow_max_capacity,
342        }
343    }
344
345    fn rebind_with<S: BufRead>(
346        mut self,
347        rebind_fn: impl FnOnce(R) -> io::Result<S>,
348    ) -> io::Result<BufReaderWithOverflow<S>> {
349        let reader = rebind_fn(self.reader)?;
350        self.overflow_buf.clear();
351        Ok(BufReaderWithOverflow {
352            reader,
353            overflow_buf: self.overflow_buf,
354            overflow_min_capacity: self.overflow_min_capacity,
355            overflow_max_capacity: self.overflow_max_capacity,
356        })
357    }
358}
359
360impl<const N: usize> BufReaderWithOverflow<BufferedReader<'_, N>> {
361    pub fn rebind<'b>(self) -> io::Result<BufReaderWithOverflow<BufferedReader<'b, N>>> {
362        self.rebind_with(BufferedReader::rebind)
363    }
364}
365
366#[cfg(target_os = "linux")]
367impl BufReaderWithOverflow<SequentialFileReader<'_>> {
368    pub fn rebind<'b>(self) -> io::Result<BufReaderWithOverflow<SequentialFileReader<'b>>> {
369        self.rebind_with(SequentialFileReader::rebind)
370    }
371}
372
373impl<R: BufRead> io::Read for BufReaderWithOverflow<R> {
374    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
375        let available_len = self.overflow_buf.len();
376        if available_len == 0 {
377            self.reader.read(buf)
378        } else {
379            assert!(
380                buf.len() >= available_len,
381                "should read all previously required bytes"
382            );
383            buf[..available_len].copy_from_slice(&self.overflow_buf);
384            self.overflow_buf.clear();
385            if buf.len() > available_len {
386                let bytes_read = self.reader.read(&mut buf[available_len..])?;
387                Ok(available_len + bytes_read)
388            } else {
389                Ok(available_len)
390            }
391        }
392    }
393}
394
395impl<R: BufRead> BufRead for BufReaderWithOverflow<R> {
396    fn fill_buf(&mut self) -> io::Result<&[u8]> {
397        if self.overflow_buf.is_empty() {
398            self.reader.fill_buf()
399        } else {
400            Ok(self.overflow_buf.as_slice())
401        }
402    }
403
404    fn consume(&mut self, mut amt: usize) {
405        let overflow_len = self.overflow_buf.len();
406        if overflow_len > 0 {
407            amt = amt
408                .checked_sub(overflow_len)
409                .expect("should consume all previously required bytes");
410            self.overflow_buf.clear();
411        }
412        self.reader.consume(amt);
413    }
414}
415
416impl<'a, R: FileBufRead<'a>> FileBufRead<'a> for BufReaderWithOverflow<R> {
417    fn set_file(&mut self, file: &'a File, read_limit: FileSize) -> io::Result<()> {
418        self.overflow_buf.clear();
419        self.reader.set_file(file, read_limit)
420    }
421
422    fn add_file_to_prefetch(&mut self, file: &'a File, read_limit: FileSize) -> io::Result<()> {
423        self.reader.add_file_to_prefetch(file, read_limit)
424    }
425
426    fn get_file_offset(&self) -> FileSize {
427        self.reader.get_file_offset() - self.overflow_buf.len() as FileSize
428    }
429
430    fn consume_or_skip(&mut self, mut amt: usize) {
431        let overflow_len = self.overflow_buf.len();
432        if overflow_len > 0 {
433            amt = amt
434                .checked_sub(overflow_len)
435                .expect("should consume all previously required bytes");
436            self.overflow_buf.clear();
437        }
438        self.reader.consume_or_skip(amt);
439    }
440}
441
442/// Support large `required_len` (within configured limits) by using overflow buffer
443/// retained during lifetime of the reader.
444impl<R: BufRead> RequiredLenBufRead for BufReaderWithOverflow<R> {
445    fn fill_buf_required(&mut self, required_len: usize) -> io::Result<&[u8]> {
446        let available_len = self.overflow_buf.len();
447        if available_len == 0 {
448            let buf = self.reader.fill_buf()?;
449            if buf.len() >= required_len {
450                // Separate fill_buf call is needed due to borrow checker's limitation
451                // https://rust-lang.github.io/rfcs/2094-nll.html#problem-case-3-conditional-control-flow-across-functions
452                return self.reader.fill_buf();
453            }
454        }
455        assert!(
456            available_len <= required_len,
457            "fill_buf_required should keep or grow required_len until consume"
458        );
459        if required_len > self.overflow_buf.capacity() {
460            let target_capacity = required_len
461                .next_power_of_two()
462                .clamp(self.overflow_min_capacity, self.overflow_max_capacity);
463            if required_len > target_capacity {
464                return Err(io::Error::new(
465                    io::ErrorKind::QuotaExceeded,
466                    "requested more bytes than allowed capacity range",
467                ));
468            }
469            self.overflow_buf
470                .reserve_exact(target_capacity - available_len);
471        }
472        // Safety: we have reserved capacity and all of it will be filled by read
473        unsafe { self.overflow_buf.set_len(required_len) };
474
475        // On error overflow buffer is completely cleared to avoid access to
476        // uninitialized memory.
477        self.reader
478            .read_exact(&mut self.overflow_buf[available_len..])
479            .inspect_err(|_| self.overflow_buf.clear())?;
480        Ok(self.overflow_buf.as_slice())
481    }
482}
483
484/// Open file at `path` with buffering reader using `buf_size` memory and doing
485/// read-ahead IO reads (if `io_uring` is supported by the platform)
486pub fn large_file_buf_reader(
487    path: &Path,
488    buf_size: usize,
489    io_setup: &IoSetupState,
490) -> io::Result<impl BufRead + use<>> {
491    #[cfg(target_os = "linux")]
492    {
493        assert!(agave_io_uring::io_uring_supported());
494
495        let mut reader = SequentialFileReaderBuilder::new()
496            .shared_sqpoll(io_setup.shared_sqpoll_fd())
497            .use_direct_io(io_setup.use_direct_io)
498            .use_registered_buffers(io_setup.use_registered_io_uring_buffers)
499            .build(buf_size)?;
500        reader.set_path(path)?;
501        Ok(reader)
502    }
503    #[cfg(not(target_os = "linux"))]
504    {
505        use std::io::BufReader;
506        let file = File::open(path)?;
507        let _ = io_setup;
508        Ok(BufReader::with_capacity(buf_size, file))
509    }
510}
511
512#[cfg(test)]
513mod tests {
514    use {
515        super::*,
516        std::io::{Read as _, Write},
517        tempfile::tempfile,
518    };
519
520    #[inline(always)]
521    fn rand_bytes<const N: usize>() -> [u8; N] {
522        use rand::Rng;
523        let mut rng = rand::rng();
524        std::array::from_fn(|_| rng.random::<u8>())
525    }
526
527    #[test]
528    fn test_buffered_reader() {
529        // Setup a sample file with 32 bytes of data read using 16 bytes buffer
530        const BUFFER_SIZE: usize = 16;
531        const FILE_SIZE: usize = 32;
532        let mut sample_file = tempfile().unwrap();
533        let bytes = rand_bytes::<FILE_SIZE>();
534        sample_file.write_all(&bytes).unwrap();
535
536        // First read 16 bytes to fill buffer
537        let file_len_valid = 32;
538        let default_min_read = 8;
539        let mut reader =
540            BufferedReader::<BUFFER_SIZE>::new().with_file(&sample_file, file_len_valid);
541        let offset = reader.get_file_offset();
542        let slice = reader.fill_buf_required(default_min_read).unwrap();
543        let mut expected_offset = 0;
544        assert_eq!(offset, expected_offset);
545        assert_eq!(slice.len(), BUFFER_SIZE);
546        assert_eq!(slice, &bytes[0..BUFFER_SIZE]);
547
548        // Consume the data and attempt to read next 32 bytes, which is above supported buffer size,
549        // so file offset is moved, but call returns quota error.
550        let advance = 16;
551        let mut required_len = 32;
552        reader.consume(advance);
553        let offset = reader.get_file_offset();
554        expected_offset += advance as FileSize;
555        assert_eq!(offset, expected_offset);
556        assert_eq!(
557            reader
558                .fill_buf_required(required_len)
559                .expect_err("should fail due to required length above buffer size")
560                .kind(),
561            io::ErrorKind::QuotaExceeded
562        );
563
564        // Continue reading should yield EOF.
565        reader.consume(advance);
566        let offset = reader.get_file_offset();
567        expected_offset += advance as FileSize;
568        assert_eq!(offset, expected_offset);
569        required_len = 16;
570        assert_eq!(
571            reader
572                .fill_buf_required(required_len)
573                .expect_err("should hit EOF")
574                .kind(),
575            io::ErrorKind::UnexpectedEof
576        );
577
578        // set_required_data to zero and offset should not change, and slice should be empty.
579        required_len = 0;
580        let offset = reader.get_file_offset();
581        let slice = reader.fill_buf_required(required_len).unwrap();
582        let expected_offset = file_len_valid;
583        assert_eq!(offset, expected_offset);
584        let expected_slice_len = 0;
585        assert_eq!(slice.len(), expected_slice_len);
586    }
587
588    #[test]
589    fn test_buffered_reader_with_extra_data_in_file() {
590        // Setup a sample file with 32 bytes of data read using 16 bytes buffer
591        const BUFFER_SIZE: usize = 16;
592        const FILE_SIZE: usize = 32;
593        let mut sample_file = tempfile().unwrap();
594        let bytes = rand_bytes::<FILE_SIZE>();
595        sample_file.write_all(&bytes).unwrap();
596
597        // Set file valid_len to 30 (i.e. 2 garbage bytes at the end of the file)
598        let valid_len = 30;
599
600        // First read 16 bytes to fill buffer
601        let default_min_read_size = 8;
602        let mut reader = BufferedReader::<BUFFER_SIZE>::new().with_file(&sample_file, valid_len);
603        let offset = reader.get_file_offset();
604        let slice = reader.fill_buf_required(default_min_read_size).unwrap();
605        let mut expected_offset = 0;
606        assert_eq!(offset, expected_offset);
607        assert_eq!(slice.len(), BUFFER_SIZE);
608        assert_eq!(slice, &bytes[0..BUFFER_SIZE]);
609
610        // Consume the data and attempt read next 16 bytes, expect to hit `valid_len`, and only read 14 bytes
611        let mut advance = 16;
612        let mut required_data_len = 16;
613        reader.consume_or_skip(advance);
614        let offset = reader.get_file_offset();
615        expected_offset += advance as FileSize;
616        assert_eq!(offset, expected_offset);
617        assert_eq!(
618            reader
619                .fill_buf_required(required_data_len)
620                .expect_err("should hit EOF")
621                .kind(),
622            io::ErrorKind::UnexpectedEof
623        );
624
625        // Continue reading should yield EOF.
626        advance = 14;
627        required_data_len = 16;
628        reader.consume_or_skip(advance);
629        let offset = reader.get_file_offset();
630        expected_offset += advance as FileSize;
631        assert_eq!(offset, expected_offset);
632        assert_eq!(
633            reader
634                .fill_buf_required(required_data_len)
635                .expect_err("should hit EOF")
636                .kind(),
637            io::ErrorKind::UnexpectedEof
638        );
639
640        // Move the offset passed `valid_len`, expect to hit EOF.
641        advance = 1;
642        required_data_len = 8;
643        reader.consume_or_skip(advance);
644        let offset = reader.get_file_offset();
645        expected_offset += advance as FileSize;
646        assert_eq!(offset, expected_offset);
647        assert_eq!(
648            reader
649                .fill_buf_required(required_data_len)
650                .expect_err("should hit EOF")
651                .kind(),
652            io::ErrorKind::UnexpectedEof
653        );
654
655        // Move the offset passed file_len, expect to hit EOF.
656        advance = 3;
657        required_data_len = 8;
658        reader.consume_or_skip(advance);
659        let offset = reader.get_file_offset();
660        expected_offset += advance as FileSize;
661        assert_eq!(offset, expected_offset);
662        assert_eq!(
663            reader
664                .fill_buf_required(required_data_len)
665                .expect_err("Should hit EOF")
666                .kind(),
667            io::ErrorKind::UnexpectedEof
668        );
669    }
670
671    #[test]
672    fn test_buffered_reader_partial_consume() {
673        // Setup a sample file with 32 bytes of data read using 16 bytes buffer
674        const BUFFER_SIZE: usize = 16;
675        const FILE_SIZE: usize = 32;
676        let mut sample_file = tempfile().unwrap();
677        let bytes = rand_bytes::<FILE_SIZE>();
678        sample_file.write_all(&bytes).unwrap();
679
680        // First read 16 bytes to fill buffer
681        let file_len_valid = 32;
682        let default_min_read_size = 8;
683        let mut reader =
684            BufferedReader::<BUFFER_SIZE>::new().with_file(&sample_file, file_len_valid);
685        let offset = reader.get_file_offset();
686        let slice = reader.fill_buf_required(default_min_read_size).unwrap();
687        let mut expected_offset = 0;
688        assert_eq!(offset, expected_offset);
689        assert_eq!(slice.len(), BUFFER_SIZE);
690        assert_eq!(slice, &bytes[0..BUFFER_SIZE]);
691
692        // Consume the partial data (8 byte) and attempt to read next 8 bytes
693        let mut advance = 8;
694        let mut required_len = 8;
695        reader.consume(advance);
696        let offset = reader.get_file_offset();
697        let slice = reader.fill_buf_required(required_len).unwrap();
698        expected_offset += advance as FileSize;
699        assert_eq!(offset, expected_offset);
700        assert_eq!(slice.len(), required_len);
701        assert_eq!(
702            slice,
703            &bytes[expected_offset as usize..expected_offset as usize + required_len]
704        ); // no need to read more
705
706        // Continue reading should succeed and read the rest 16 bytes.
707        advance = 8;
708        required_len = 16;
709        reader.consume(advance);
710        let offset = reader.get_file_offset();
711        let slice = reader.fill_buf_required(required_len).unwrap();
712        expected_offset += advance as FileSize;
713        assert_eq!(offset, expected_offset);
714        assert_eq!(slice.len(), required_len);
715        assert_eq!(
716            slice,
717            &bytes[expected_offset as usize..expected_offset as usize + required_len]
718        );
719
720        // Continue reading should yield EOF and empty slice.
721        advance = 16;
722        required_len = 16;
723        reader.consume(advance);
724        let offset = reader.get_file_offset();
725        expected_offset += advance as FileSize;
726        assert_eq!(offset, expected_offset);
727        assert_eq!(
728            reader
729                .fill_buf_required(required_len)
730                .expect_err("should hit EOF")
731                .kind(),
732            io::ErrorKind::UnexpectedEof
733        );
734
735        // Attempt to read more than the buffer size
736        required_len = 32;
737        assert_eq!(
738            reader
739                .fill_buf_required(required_len)
740                .expect_err("should fail due to too large required length")
741                .kind(),
742            io::ErrorKind::QuotaExceeded
743        );
744    }
745
746    #[test]
747    fn test_buffered_reader_partial_consume_with_move() {
748        // Setup a sample file with 32 bytes of data read using 16 bytes buffer
749        const BUFFER_SIZE: usize = 16;
750        const FILE_SIZE: usize = 32;
751        let mut sample_file = tempfile().unwrap();
752        let bytes = rand_bytes::<FILE_SIZE>();
753        sample_file.write_all(&bytes).unwrap();
754
755        // First read 16 bytes to fill buffer
756        let valid_len = 32;
757        let default_min_read = 8;
758        let mut reader = BufferedReader::<BUFFER_SIZE>::new().with_file(&sample_file, valid_len);
759        let offset = reader.get_file_offset();
760        let slice = reader.fill_buf_required(default_min_read).unwrap();
761        let mut expected_offset = 0;
762        assert_eq!(offset, expected_offset);
763        assert_eq!(slice.len(), BUFFER_SIZE);
764        assert_eq!(slice, &bytes[0..BUFFER_SIZE]);
765
766        // Consume the partial data (8 bytes) and attempt to read next 16 bytes
767        // This will move the leftover 8bytes and read next 8 bytes.
768        let mut advance = 8;
769        let mut required_data_len = 16;
770        reader.consume(advance);
771        let offset = reader.get_file_offset();
772        let slice = reader.fill_buf_required(required_data_len).unwrap();
773        expected_offset += advance as FileSize;
774        assert_eq!(offset, expected_offset);
775        assert_eq!(slice.len(), required_data_len);
776        assert_eq!(
777            slice,
778            &bytes[expected_offset as usize..expected_offset as usize + required_data_len]
779        );
780
781        // Continue reading should succeed and read the rest 8 bytes.
782        advance = 16;
783        required_data_len = 8;
784        reader.consume(advance);
785        let offset = reader.get_file_offset();
786        let slice = reader.fill_buf_required(required_data_len).unwrap();
787        expected_offset += advance as FileSize;
788        assert_eq!(offset, expected_offset);
789        assert_eq!(slice.len(), required_data_len);
790        assert_eq!(
791            slice,
792            &bytes[expected_offset as usize..expected_offset as usize + required_data_len]
793        );
794    }
795
796    #[test]
797    fn test_fill_buf_required_or_overflow() {
798        // Setup a sample file with 32 bytes of data read using 16 bytes buffer
799        const BUFFER_SIZE: usize = 16;
800        const FILE_SIZE: usize = 32;
801        let mut sample_file = tempfile().unwrap();
802        let bytes = rand_bytes::<FILE_SIZE>();
803        sample_file.write_all(&bytes).unwrap();
804
805        let mut reader = BufReaderWithOverflow::new(
806            BufferedReader::<BUFFER_SIZE>::new().with_file(&sample_file, FILE_SIZE as FileSize),
807            0,
808            usize::MAX,
809        );
810
811        // Case 1: required_len <= BUFFER_SIZE (no overflow needed)
812        let required_len = 8;
813        let slice = reader.fill_buf_required(required_len).unwrap();
814        assert_eq!(&slice[..required_len], &bytes[..required_len]);
815
816        // Consume part of the buffer to simulate partial reading
817        reader.consume_or_skip(required_len);
818
819        // Case 2: required_len > buffer_size (overflow required)
820        let required_len = BUFFER_SIZE + 8;
821        let slice = reader.fill_buf_required(required_len).unwrap();
822
823        // Internal buffer is size `buffer_size`, overflow should extend with the remaining `8` bytes
824        assert_eq!(slice.len(), required_len);
825        assert_eq!(slice, &bytes[8..8 + required_len]);
826
827        // Consume everything to reach EOF
828        reader.consume_or_skip(required_len);
829
830        // Case 3: required_len larger than remaining data (expect UnexpectedEof)
831        let required_len = 64;
832        let result = reader.fill_buf_required(required_len);
833        assert_eq!(result.unwrap_err().kind(), io::ErrorKind::UnexpectedEof);
834
835        // Case 4: required_len = 0 (should return empty slice)
836        let required_len = 0;
837        let offset_before = reader.get_file_offset();
838        let slice = reader.fill_buf_required(required_len).unwrap();
839        assert_eq!(slice.len(), 0);
840        let offset_after = reader.get_file_offset();
841        assert_eq!(offset_before, offset_after);
842    }
843
844    #[test]
845    fn test_overflow_reader_read_and_fill_buf() {
846        const BUFFER_SIZE: usize = 16;
847        const FILE_SIZE: usize = 64;
848        let mut sample_file = tempfile().unwrap();
849        let bytes = rand_bytes::<FILE_SIZE>();
850        sample_file.write_all(&bytes).unwrap();
851
852        let mut reader = BufReaderWithOverflow::new(
853            BufferedReader::<BUFFER_SIZE>::new().with_file(&sample_file, FILE_SIZE as FileSize),
854            0,
855            32,
856        );
857        let buf = reader.fill_buf().unwrap();
858        assert_eq!(buf, &bytes[0..BUFFER_SIZE]);
859
860        reader.consume_or_skip(8);
861        let mut buf = [0; 8];
862        assert_eq!(reader.read(&mut buf).unwrap(), 8);
863        assert_eq!(buf, &bytes[8..BUFFER_SIZE]);
864
865        assert_eq!(
866            reader
867                .fill_buf_required(40)
868                .expect_err("should exceed len limit")
869                .kind(),
870            io::ErrorKind::QuotaExceeded
871        );
872
873        // Required buffer is at maximum configured limit.
874        let buf = reader.fill_buf_required(32).unwrap();
875        assert_eq!(buf, &bytes[BUFFER_SIZE..BUFFER_SIZE + 32]);
876        // Same buffer should be returned.
877        let buf = reader.fill_buf().unwrap();
878        assert_eq!(buf, &bytes[BUFFER_SIZE..BUFFER_SIZE + 32]);
879
880        let mut buf = [0; 48];
881        assert_eq!(reader.read(&mut buf).unwrap(), 48);
882        assert_eq!(buf, &bytes[BUFFER_SIZE..BUFFER_SIZE + 48]);
883
884        assert_eq!(reader.read(&mut buf).unwrap(), 0);
885
886        assert_eq!(
887            reader
888                .fill_buf_required(1)
889                .expect_err("should reach EOF")
890                .kind(),
891            io::ErrorKind::UnexpectedEof
892        );
893    }
894
895    #[test]
896    fn test_overflow_reader_rebind() {
897        let reader = BufReaderWithOverflow::new(BufferedReader::<16>::new(), 64, 128);
898        let (mut reader, allocation, capacity) = {
899            let mut file = tempfile().unwrap();
900            file.write_all(&[1; 96]).unwrap();
901            let mut reader = reader.rebind().unwrap();
902            reader.set_file(&file, 96).unwrap();
903            assert_eq!(reader.fill_buf_required(48).unwrap(), &[1; 48]);
904            let allocation = reader.overflow_buf.as_ptr();
905            let capacity = reader.overflow_buf.capacity();
906            // Rebind with unread overflow bytes, releasing the borrow before the file is dropped.
907            (reader.rebind().unwrap(), allocation, capacity)
908        };
909        assert!(reader.overflow_buf.is_empty());
910        assert_eq!(reader.get_file_offset(), 0);
911        assert_eq!(reader.overflow_buf.as_ptr(), allocation);
912        assert_eq!(reader.overflow_buf.capacity(), capacity);
913        assert_eq!(reader.overflow_min_capacity, 64);
914        assert_eq!(reader.overflow_max_capacity, 128);
915
916        let mut file = tempfile().unwrap();
917        file.write_all(&[2; 96]).unwrap();
918        reader.set_file(&file, 96).unwrap();
919        assert_eq!(reader.fill_buf_required(48).unwrap(), &[2; 48]);
920        assert_eq!(reader.overflow_buf.as_ptr(), allocation);
921        assert_eq!(reader.overflow_buf.capacity(), capacity);
922
923        // Switching files within a batch also clears data without reallocating.
924        reader.set_file(&file, 96).unwrap();
925        assert_eq!(reader.get_file_offset(), 0);
926        assert!(reader.overflow_buf.is_empty());
927        assert_eq!(reader.fill_buf_required(48).unwrap(), &[2; 48]);
928        assert_eq!(reader.overflow_buf.as_ptr(), allocation);
929    }
930}