Struct File 

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

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.

zero_align: usize

Minimum required alignment for zero writes.

discard_align: usize

Minimum required alignment for effective discards.

size: AtomicU64

Cached file length.

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

common_storage_helper: CommonStorageHelper

Storage helper.

discard_unsupported: AtomicBool

Set once we know that discard is unsupported and we can skip trying.

Implementations

impl File

pub fn from_open_file(file: File, opts: StorageOpenOptions) -> Result<Self>

Use an existing file with explicitly known open options.

The filename is not used to reopen the file, but is retained to resolve relative paths. The writable and direct I/O options must match how the file was opened.

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

Central internal function to create a File object.

fn detect_open_mode(file: &File) -> (bool, bool)

Detect access and direct I/O modes for an externally supplied file.

Returns (direct_io, writable), indicating whether direct I/O is enabled and whether the file is open for writing.

fn host_page_size() -> usize

Host page size, rounded up to a power of two.

fn get_fs_zero_discard_align(file: &File) -> (usize, usize)

Filesystem block size used as write-zeroes / discard alignment.

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

Probe minimal direct I/O request, memory, zero and discard 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 map_os_err(err: Error) -> Error

For special operations, ensure the error kind is usable.

When invoking OS I/O operations directly, we turn the returned raw OS error code into an io::Error object via io::Error::last_os_error(). To differentiate between different error cases, in generic imago code, we then don’t use that raw error code, but the error kind (io::ErrorKind) instead, specifically it’s important to properly return an error of kind io::ErrorKind::Unsupported when an operation is unsupported, so fall-backs can be employed.

Rust’s standard library only assigns this error kind (Unsupported) to EOPNOTSUPP (= ENOTSUP) and ENOSYS. However, some “special” operations (fallocate(), fcntl(F_PUNCHHOLE), ioctl(), …) can return other error codes for when an operation is not supported on a specific file, e.g. ENODEV or ENXIO.

Assign the appropriate error kind to such errors so the generic code can handle them.

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

Attempt to discard range by truncating the file.

If the range reaches the end of the file, truncate and restore the original file length. 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.

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

Ensure the given range reads back as zeroes, or return an error.

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

Via OS-specific means, ensure the given range reads back as zeroes, or return an error.

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 zero_align(&self) -> usize

Minimum required alignment for zero writes.

fn discard_align(&self) -> usize

Minimum required alignment for effective discards.

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_write_allocated_zeroes( &self, offset: u64, length: u64, ) -> Result<()>

Ensure the given range is allocated, and 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.

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.