Struct L2Table 

pub(super) struct L2Table {
    cluster: Option<HostCluster>,
    data: Box<[AtomicL2Entry]>,
    cluster_bits: u32,
    external_data_file: bool,
    modified: AtomicBool,
    writer_lock: OwnedRwLock<()>,
    writeback_lock: Mutex<()>,
}

L2 table.

Fields

cluster: Option<HostCluster>

Cluster of the L2 table.

data: Box<[AtomicL2Entry]>

Table data.

cluster_bits: u32

log2 of the cluster size.

external_data_file: bool

Whether this image uses an external data file.

modified: AtomicBool

Whether this table has been modified since it was last written.

writer_lock: OwnedRwLock<()>

Lock for creating L2TableWriteGuard (write) and CompressedClusterReadGuard (read).

This is an owning (Arc-backed) lock, i.e. any access guard will have a strong reference to it and can thus be held independently of lifetime concerns, e.g. across a data write while a prepared mapping is not yet committed (see Qcow2::prepare_data_mapping()).

Consequently, it may be held outside of qcow2 code paths, e.g. while a data write is in flight (between preparing and committing a data mapping for it). Thus, writing this table to disk must work without the lock because otherwise flushing the table would deadlock against such writes.

writeback_lock: Mutex<()>

Serializes writing this table back to disk (see L2Table::write_if_modified()).

Implementations

impl L2Table

pub fn new_cleared(header: &Header) -> Self

Create a new zeroed L2 table.

pub fn get_mapping(&self, lookup_cluster: GuestCluster) -> Result<L2Mapping>

Look up a cluster mapping.

pub async fn lock_write(self: &Arc<Self>) -> L2TableWriteGuard

Allow modifying this L2 table.

Note that readers are allowed to exist while modifications are happening, unless they hold a CompressedClusterReadGuard.

The returned guard keeps the table pinned in the L2 cache.

pub async fn lock_compressed_read( &self, cluster: GuestCluster, ) -> Result<Option<CompressedClusterReadGuard<'_>>>

Lock the given compressed cluster for reading.

Prevent modifications of this L2 table while the returned guard is held.

Return None if cluster is not compressed (checked under the guard).

pub async fn write_if_modified<S: Storage>( &self, image: &S, cluster: HostCluster, ) -> Result<()>

Write this table to disk if it has been modified since it was last written.

This is the entry point for writing back a table that is part of the L2 cache; it serializes such write-backs against each other via writeback_lock. Writing the table clears the modified flag before copying the entries, so without that lock, two concurrent write-backs could race such that the one with the older copy writes last, leaving that older copy on disk while the table no longer appears modified. Holding the lock across the modified check means that a write-back which has to wait only writes again if something changed after the preceding write-back’s copy.

cluster is the cluster this table is expected to belong to; an assert!() verifies that it really is the table’s cluster.

Trait Implementations

impl Clone for L2Table

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for L2Table

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

Formats the value using the given formatter.

impl Drop for L2Table

fn drop(&mut self)

Executes the destructor for this type.

impl Table for L2Table

const NAME: &'static str = "L2 table"

User-readable struct name.

const MAX_ENTRIES: usize

Maximum allowable number of entries.

type InternalEntry = AtomicL2Entry

Internal type for each table entry.

type Entry = L2Entry

Externally visible type for each table entry.

fn from_data(data: Box<[AtomicL2Entry]>, header: &Header) -> Self

Create a new table with the given contents

fn entries(&self) -> usize

Number of entries.

fn get_ref(&self, index: usize) -> Option<&AtomicL2Entry>

Get the given entry (as reference).

fn get(&self, index: usize) -> L2Entry

Get the given entry (copied).

fn get_cluster(&self) -> Option<HostCluster>

Get this table’s (first) cluster in the image file.

fn get_offset(&self) -> Option<HostOffset>

Get this table’s offset in the image file.

fn set_cluster(&mut self, cluster: HostCluster)

Set this table’s (first) cluster in the image file (for writing).

fn unset_cluster(&mut self)

Remove the table’s association with any cluster in the image file.

fn is_modified(&self) -> bool

Check whether this table has been modified since it was last written.

fn clear_modified(&self)

Clear the modified flag.

fn set_modified(&self)

Set the modified flag.

fn cluster_bits(&self) -> u32

Return log2 of the cluster size.

fn byte_size(&self) -> usize

Table size in bytes.

fn cluster_count(&self) -> ClusterCount

Number of clusters used by this table.

async fn load<S: Storage>( image: &S, header: &Header, cluster: HostCluster, entries: usize, ) -> Result<Self>

Load a table from the image file.

async fn write<S: Storage>(&self, image: &S) -> Result<()>

Write a table to the image file.

async fn write_entry<S: Storage>(&self, image: &S, index: usize) -> Result<()>

Write at least the given single (modified) entry to the image file.