Struct glommio::io::ImmutableFile

pub struct ImmutableFile { /* fields omitted */ }

A Direct I/O enabled file abstraction that can not be written to.

Glommio cannot guarantee that the file is not modified outside the process. But so long as the file is only used within Glommio, using this API guarantees that the file will never change.

This allows us to employ optimizations like caching and request coalescing. The behavior of this API upon external modifications is undefined.

It can be read sequentially by building a stream with stream_reader, or randomly through the read_at (single read) or read_many (multiple reads) APIs.

To build an ImmutableFile, use ImmutableFileBuilder.

Implementations

impl ImmutableFile

pub fn path(&self) -> Option<Ref<'_, Path>>

Returns an Option containing the path associated with this open directory, or None if there isn’t one.

pub fn file_size(&self) -> u64

Returns the size of a file, in bytes

pub fn is_same(&self, other: &ImmutableFile) -> bool

Returns true if the [‘ImmutableFile’] represent the same file on the underlying device.

Files are considered to be the same if they live in the same file system and have the same Linux inode. Note that based on this rule a symlink is not considered to be the same file.

Files will be considered to be the same if:

• A file is opened multiple times (different file descriptors, but same file!)
• they are hard links.

pub async fn read_at(&self, pos: u64, size: usize) -> Result<ReadResult, ()>

Reads into buffer in buf from a specific position in the file.

It is not necessary to respect the O_DIRECT alignment of the file, and this API will internally convert the positions and sizes to match, at a cost.

pub fn read_many<V, S: Iterator<Item = V>>(
    &self,
    iovs: S,
    max_merged_buffer_size: usize,
    max_read_amp: Option<usize>
) -> ReadManyResult<V> where
    V: IoVec + Unpin,
    S: Iterator<Item = V>, 

Submit many reads and process the results in a stream-like fashion via a ReadManyResult.

This API will optimistically coalesce and deduplicate IO requests such that two overlapping or adjacent reads will result in a single IO request. This is transparent for the consumer, you will still receive individual ReadResults corresponding to what you asked for.

The first argument is an iterator of IoVec. The last two arguments control how aggressive the IO coalescing should be:

• max_merged_buffer_size controls how large a merged IO request can be. A value of 0 disables merging completely.
• max_read_amp is optional and defines the maximum read amplification you are comfortable with. If two read requests are separated by a distance less than this value, they will be merged. A value None disables all read amplification limitation.

It is not necessary to respect the O_DIRECT alignment of the file, and this API will internally convert the positions and sizes to match.

pub async fn rename<P: AsRef<Path>>(&self, new_path: P) -> Result<(), ()>

rename this file.

Warning: synchronous operation, will block the reactor

pub async fn remove(&self) -> Result<(), ()>

remove this file.

The file does not have to be closed to be removed. Removing removes the name from the filesystem but the file will still be accessible for as long as it is open.

Warning: synchronous operation, will block the reactor

pub async fn close(self) -> Result<(), ()>

Closes this ImmutableFile Note that this method returns an error if other entities hold references to the underlying file, such as read streams.

pub fn stream_reader(&self) -> DmaStreamReaderBuilder

Creates a DmaStreamReaderBuilder from this ImmutableFile.

The resulting builder can be augmented with any option available to the DmaStreamReaderBuilder and used to read this file sequentially.

Trait Implementations

impl Clone for ImmutableFile

fn clone(&self) -> ImmutableFile

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ImmutableFile

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

Formats the value using the given formatter.