Struct Qcow2CreateBuilder

pub struct Qcow2CreateBuilder<S: Storage + 'static, F: WrappedFormat<S> + 'static = FormatAccess<S>> {
    base: FormatCreateBuilderBase<S>,
    backing: Option<(String, String)>,
    data_file: Option<(String, S)>,
    cluster_size: usize,
    refcount_width: usize,
    _wrapped_format: PhantomData<F>,
}

Options builder for creating (formatting) a qcow2 image.

Allows setting various options for a new qcow2 image.

Fields

base: FormatCreateBuilderBase<S>

Basic options.

backing: Option<(String, String)>

Backing image filename and format

data_file: Option<(String, S)>

External data file name and the file itself

cluster_size: usize

Cluster size

refcount_width: usize

Refcount bit width

_wrapped_format: PhantomData<F>

Needed for the correct create_open() return type

Implementations

impl<S: Storage + 'static, F: WrappedFormat<S> + 'static> Qcow2CreateBuilder<S, F>

pub fn backing(self, backing_filename: String, backing_format: String) -> Self

Set a backing image.

Set the path to the backing image to be written into the image header; this path will be interpreted relative to the qcow2 image file.

The backing format should be one of “qcow2” or “raw”.

Neither of filename or format are checked for validity.

pub fn data_file(self, filename: String, file: S) -> Self

Set an external data file.

Set the path for an external data file. This path will be interpreted relative to the qcow2 image file. This path is not checked for whether it matches file or even points to anything at all.

file is the data file itself; it is necessary to pass this storage object into the builder for preallocation purposes.

pub fn cluster_size(self, size: usize) -> Self

Set the cluster size (in bytes).

A cluster is the unit of allocation for qcow2 images. Smaller clusters can lead to better COW performance, but worse performance for fully allocated images, and have increased metadata size overhead.

Must be a power of two between 512 and 2 MiB (inclusive).

The default is 64 KiB.

pub fn refcount_width(self, bits: usize) -> Self

Set the refcount width in bits.

Reference counting is used to determine empty areas in the image file, though this only needs refcounts of 0 and 1, i.e. a reference bit width of 1.

Larger refcount bit widths are only needed when using internal snapshots, in which case multiple snapshots can share clusters.

Must be a power of two between 1 and 64 (inclusive).

The default is 16 bits.

Trait Implementations

impl<S: Storage + 'static, F: WrappedFormat<S> + 'static> FormatCreateBuilder<S> for Qcow2CreateBuilder<S, F>

const FORMAT: Format = Format::Qcow2

Which format this is.

type DriverBuilder = Qcow2OpenBuilder<S, F>

Open builder type for this format.

fn new(image: S) -> Self

Prepare formatting the given image file.

fn size(self, size: u64) -> Self

Set the virtual disk size.

fn preallocate(self, prealloc_mode: PreallocateMode) -> Self

Set the desired preallocation mode.

fn get_size(&self) -> u64

Get the set virtual disk size.

fn get_preallocate(&self) -> PreallocateMode

Get the preallocation mode.

async fn create(self) -> Result<()>

Format the image file.

async fn create_open<G: ImplicitOpenGate<S>, OBF: FnOnce(S) -> Result<Qcow2OpenBuilder<S, F>>>( self, open_gate: G, open_builder_fn: OBF, ) -> Result<Qcow2<S, F>>

Format the image file and open it.