Struct File

pub struct File {
    file: RwLock<File>,
    filename: Option<PathBuf>,
    req_align: usize,
    mem_align: usize,
    size: AtomicU64,
    common_storage_helper: CommonStorageHelper,
}

Use a plain file or host block device as a storage object.

Fields

file: RwLock<File>

The file.

filename: Option<PathBuf>

For debug purposes, and to resolve relative filenames.

req_align: usize

Minimal I/O alignment for requests.

mem_align: usize

Minimal memory buffer alignment.

size: AtomicU64

Cached file length.

Third parties changing the length concurrently is pretty certain to break things anyway.

common_storage_helper: CommonStorageHelper

Storage helper.

Implementations

impl File

fn new(file: File, filename: Option<PathBuf>, direct_io: bool) -> Result<Self>

Central internal function to create a File object.

direct_io should be true if direct I/O was requested, and can be false if that status is unknown.

fn probe_alignments( file: &mut File, min_req_align: usize, min_mem_align: usize, ) -> (usize, usize)

Probe minimal request and memory alignments.

Start at min_req_align and min_mem_align.

fn probe_access( file: &mut File, slice: &mut [u8], offset: off_t, may_write: &mut bool, ) -> Result<bool>

Do an alignment-probing I/O access.

Return Ok(true) if everything was OK, and Ok(false) if the request was reported to be misaligned.

may_write is a boolean that controls whether this is allowed to write (the same data read before) to improve reliability. Is automatically set to false if writing is found to not be possible.

fn get_min_dio_req_align(file: &File) -> usize

Get system-reported minimum request alignment for direct I/O.

fn get_min_dio_mem_align(_file: &File) -> usize

Get system-reported minimum memory alignment for direct I/O.

fn do_open_sync( opts: StorageOpenOptions, base_fs_opts: OpenOptions, ) -> Result<Self>

Implementation for anything that opens a file.

fn try_discard_by_truncate(&self, offset: u64, length: u64) -> Result<bool>

Attempt to discard range by truncating the file.

If the given range is at the end of the file, discard it by simply truncating the file. Return true on success.

If the range is not at the end of the file, i.e. another method of discarding is needed, return false.

Trait Implementations

impl Debug for File

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

Formats the value using the given formatter.

impl Display for File

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

Formats the value using the given formatter.

impl Storage for File

async fn open(opts: StorageOpenOptions) -> Result<Self>

Open a storage object.

fn open_sync(opts: StorageOpenOptions) -> Result<Self>

Synchronous wrapper around Storage::open().

async fn create_open(opts: StorageCreateOptions) -> Result<Self>

Create a storage object and open it.

fn mem_align(&self) -> usize

Minimum required alignment for memory buffers.

fn req_align(&self) -> usize

Minimum required alignment for offsets and lengths.

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

Storage object length.

fn resolve_relative_path<P: AsRef<Path>>(&self, relative: P) -> Result<PathBuf>

Resolve the given path relative to this storage object.

fn get_filename(&self) -> Option<PathBuf>

Return a filename, if possible.

async unsafe fn pure_readv( &self, bufv: IoVectorMut<'_>, offset: u64, ) -> Result<()>

Read data at offset into bufv.

async unsafe fn pure_writev( &self, bufv: IoVector<'_>, offset: u64, ) -> Result<()>

Write data from bufv to offset.

async unsafe fn pure_write_zeroes(&self, offset: u64, length: u64) -> Result<()>

Ensure the given range reads back as zeroes.

async unsafe fn pure_discard(&self, offset: u64, length: u64) -> Result<()>

Discard the given range, with undefined contents when read back.

async fn flush(&self) -> Result<()>

Flush internal buffers.

async fn sync(&self) -> Result<()>

Sync data already written to the storage hardware.

async unsafe fn invalidate_cache(&self) -> Result<()>

Drop internal buffers.

fn get_storage_helper(&self) -> &CommonStorageHelper

Return the storage helper object (used by the StorageExt implementation).

async fn resize( &self, new_size: u64, prealloc_mode: PreallocateMode, ) -> Result<()>

Resize to the given size.

async fn create(opts: StorageCreateOptions) -> Result<()>

Create a storage object.

fn zero_align(&self) -> usize

Minimum required alignment for zero writes.

fn discard_align(&self) -> usize

Minimum required alignment for effective discards.

impl TryFrom<File> for File

fn try_from(file: File) -> Result<Self>

Use the given existing std::fs::File.

Convert the given existing std::fs::File object into an imago storage object.

When using this, the resulting object will not know its own filename. That makes it impossible to auto-resolve relative paths to it, e.g. qcow2 backing file names.

type Error = Error

The type returned in the event of a conversion error.