Struct glommio::io::ImmutableFileBuilder

pub struct ImmutableFileBuilder<P> where
    P: AsRef<Path>,  { /* fields omitted */ }

Builds a new ImmutableFile, allowing linear and random access to a Direct I/O DmaFile.

Working with an ImmutableFile happens in two steps:

• First, all the writes are done, through the ImmutableFilePreSealSink, which has no read methods.
• Then, after the sink is sealed, it is no longer possible to write to it

Implementations

impl<P> ImmutableFileBuilder<P> where
    P: AsRef<Path>, 

pub fn new(fname: P) -> Self

Creates a new ImmutableFileBuilder.

If this is a new file, use build_sink to build the ImmutableFilePreSealSink stage that will allow writes until seal. In that case, the filename must not exist. However, no error happens until build_sink is attempted.

If this is an existing file that will be exclusively read, use build_existing to create an ImmutableFile directly, skipping the ImmutableFilePreSealSink stage

pub fn with_sequential_concurrency(self, concurrency: usize) -> Self

Define the number of buffers that will be used by the ImmutableFile during sequential access.

This number is upheld for both the sink and read phases of the ImmutableFile. Higher numbers mean more concurrency but also more memory usage.

pub fn with_sync_on_close_disabled(self, flush_disabled: bool) -> Self

Does not issue a sync operation when sealing the file. This is dangerous and in most cases may lead to data loss.

Please note that even for O_DIRECT files, data may still be present in your device’s internal cache until a sync happens.

This option is ignored if you are creating an ImmutableFile directly and skipping the ImmutableFilePreSealSink step

pub fn with_buffer_size(self, buffer_size: usize) -> Self

Define the buffer size that will be used by the sequential operations on this ImmutableFile

pub fn with_pre_allocation(self, size: Option<u64>) -> Self

pre-allocates space in the filesystem to hold a file at least as big as the size argument.

pub fn with_hint_extent_size(self, size: Option<usize>) -> Self

Hint to the OS the size of increase of this file, to allow more efficient allocation of blocks.

Allocating blocks at the filesystem level turns asynchronous writes into threaded synchronous writes, as we need to first find the blocks to host the file.

If the extent is larger, that means many blocks are allocated at a time. For instance, if the extent size is 1MB, that means that only 1 out of 4 256kB writes will be turned synchronous. Combined with diligent use of fallocate we can greatly minimize context switches.

It is important not to set the extent size too big. Writes can fail otherwise if the extent can’t be allocated.

pub async fn build_sink(self) -> Result<ImmutableFilePreSealSink, ()>

Builds an ImmutableFilePreSealSink with the properties defined by this builder.

The resulting sink can be written to until seal is called.

pub async fn build_existing(self) -> Result<ImmutableFile, ()>

Builds an ImmutableFile with the properties defined by this builder.

The resulting file cannot be written to. Glommio may optimize access patterns by assuming the file is read only. Writing to this file from an external process leads to undefined behavior.

Trait Implementations

impl<P: Debug> Debug for ImmutableFileBuilder<P> where
    P: AsRef<Path>, 

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

Formats the value using the given formatter.