Struct DirectIoFile

pub struct DirectIoFile { /* private fields */ }

Wrapper data structure for direct/unbuffered/uncached I/O.

Depending on OS, this will use direct I/O, unbuffered, uncaches passthrough file reads/writes, bypassing as much of OS machinery as possible.

NOTE: There are major alignment requirements described here: https://learn.microsoft.com/en-us/windows/win32/fileio/file-buffering#alignment-and-file-access-requirements https://man7.org/linux/man-pages/man2/open.2.html

Implementations

impl DirectIoFile

pub fn open<P>(options: OpenOptions, path: P) -> Result<Self>

where P: AsRef<Path>,

Open a file with basic open options at the specified path for direct/unbuffered I/O for reads and writes.

options allows configuring things like read/write/create/truncate, but custom options will be overridden internally.

This is especially important on Windows to prevent huge memory usage.

pub fn len(&self) -> Result<u64>

Get file size

pub fn is_empty(&self) -> Result<bool>

Returns Ok(true) if the file is empty

pub fn allocate(&self, len: u64) -> Result<()>

Make sure the file has a specified number of bytes allocated on the disk.

Later writes within len will not fail due to lack of disk space.

pub fn set_len(&self, len: u64) -> Result<()>

Truncates or extends the underlying file, updating the size of this file to become len.

Note if len is larger than the previous file size, it will result in a sparse file. If you’d like to pre-allocate space on disk, use Self::allocate(), which may be followed by this method to truncate the file if the new file size is smaller than the previous (Self::allocate() doesn’t truncate the file).

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

Read the exact number of bytes needed to fill buf at offset.

NOTE: This uses locking and buffering internally, prefer Self::write_all_at_raw() if you can control data alignment.

pub fn write_all_at(&self, buf: &[u8], offset: u64) -> Result<()>

Write all bytes at buf at offset.

NOTE: This uses locking and buffering internally, prefer Self::write_all_at_raw() if you can control data alignment.

pub fn read_exact_at_raw( &self, buf: &mut [AlignedPageSize], offset: u64, ) -> Result<()>

Low-level reading into aligned memory.

offset needs to be page-aligned as well or use Self::read_exact_at() if you’re willing to pay for the corresponding overhead.

pub fn write_all_at_raw( &self, buf: &[AlignedPageSize], offset: u64, ) -> Result<()>

Low-level writing from aligned memory.

offset needs to be page-aligned as well or use Self::write_all_at() if you’re willing to pay for the corresponding overhead.

pub fn file(&self) -> &File

Access internal File instance

Trait Implementations

impl Debug for DirectIoFile

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.