rama::io

Trait ReadAt

pub trait ReadAt {
    // Required methods
    fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> Result<(), Error>;
    fn size(&self) -> Result<u64, Error>;
}

Available on crate feature std only.

Expand description

Positional reads through &self, safe to call from many threads at once.

§Blocking

A read from a file is a blocking syscall (pread on Unix, ReadFile on Windows). While the file is cached in the OS page cache it costs microseconds, the same class of stall as a page fault on a memory map, so calling it from an async task is accepted. Should cold-disk latency ever matter, move the reads to spawn_blocking, to a dedicated reader thread, or to an async positional read API (io_uring, IOCP) behind this same trait.

Required Methods§

fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> Result<(), Error>

Fill all of buf with the bytes starting at offset.

§Errors

Returns io::ErrorKind::UnexpectedEof if the source ends before buf is full, or any I/O error of the source. The contents of buf are unspecified on error.

fn size(&self) -> Result<u64, Error>

The current size of the source in bytes.

§Errors

Returns the I/O error of the source if its size cannot be queried.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types§

§

impl ReadAt for File

Available on Unix or Windows only.

On Unix the read does not move the file cursor.

On Windows each read moves the cursor of the handle, and the OS serializes all reads on one handle; use ReadAtFiles to read a file from many threads in parallel.

§