Trait RootfsProvider

Source

pub trait RootfsProvider: Send + Sync {
Show 13 methods    // Required methods
    fn prepare(&self, box_dir: &Path, cache_dir: &Path) -> Result<PathBuf>;
    fn cleanup(&self, box_dir: &Path, persistent: bool) -> Result<()>;
    fn name(&self) -> &'static str;

    // Provided methods
    fn resume_for_boot(
        &self,
        box_dir: &Path,
        options: RootfsResumeOptions,
    ) -> Result<Option<ResumedRootfs>> { ... }
    fn prepare_oci_for_boot(
        &self,
        box_dir: &Path,
        options: RootfsOciPrepareOptions<'_>,
    ) -> Result<Option<ResumedRootfs>> { ... }
    fn prepare_empty(&self, box_dir: &Path) -> Result<PathBuf> { ... }
    fn finalize_for_boot(
        &self,
        box_dir: &Path,
        staged_rootfs: &Path,
        options: RootfsFinalizeOptions,
    ) -> Result<RootfsSource> { ... }
    fn preserve_on_boot_failure(&self, box_dir: &Path) -> bool { ... }
    fn record_clean_stop(&self, box_dir: &Path) -> Result<()> { ... }
    fn supports_artifact_cache(&self) -> bool { ... }
    fn supports_direct_oci_assembly(&self) -> bool { ... }
    fn guest_owns_terminal_fencing(&self) -> bool { ... }
    fn guest_owns_diff_baseline(&self) -> bool { ... }
}

Expand description

Abstracts how a rootfs directory is prepared for a box from a cached lower layer.

Required Methods§

Source

fn prepare(&self, box_dir: &Path, cache_dir: &Path) -> Result<PathBuf>

Prepare a rootfs at box_dir from the cached read-only layer at cache_dir.

The returned directory is the host-side staging view. Runtime code may still inspect and update it until Self::finalize_for_boot is called.

Source

fn cleanup(&self, box_dir: &Path, persistent: bool) -> Result<()>

Cleanup after box stops.

When persistent is true, the writable layer (overlay upper dir or copy rootfs) is preserved on disk so changes survive the next start. When false, the writable layer is wiped for a clean slate.

Source

fn name(&self) -> &'static str

Human-readable name for logging.

Provided Methods§

Source

fn resume_for_boot( &self, box_dir: &Path, options: RootfsResumeOptions, ) -> Result<Option<ResumedRootfs>>

Reopen a durable guest-owned generation without reconstructing a host staging tree. Directory providers return None.

Source

fn prepare_oci_for_boot( &self, box_dir: &Path, options: RootfsOciPrepareOptions<'_>, ) -> Result<Option<ResumedRootfs>>

Build a rootfs artifact directly from verified OCI layers. Providers that require a directory staging view return None and retain the compatibility preparation flow.

Source

fn prepare_empty(&self, box_dir: &Path) -> Result<PathBuf>

Prepare an empty writable rootfs for an OCI cache miss.

Source

fn finalize_for_boot( &self, box_dir: &Path, staged_rootfs: &Path, options: RootfsFinalizeOptions, ) -> Result<RootfsSource>

Finalize the staged tree and choose the root filesystem transport.

This is called exactly after the last host-side rootfs mutation and before the VMM starts. Directory providers keep the existing virtio-fs behavior. A guest-native provider can atomically publish a raw ext4 artifact here, detach any temporary host staging mount, and return an RootfsSource::Ext4Disk.

disk_mib is the configured logical capacity, not a request to eagerly allocate every byte on the host.

Source

fn preserve_on_boot_failure(&self, box_dir: &Path) -> bool

Whether a failed boot must retain the provider’s rootfs generations.

Most providers can discard a partially prepared first boot. A provider performing an in-place migration must keep both the rollback source and the atomically published target until the migration is verified.

Source

fn record_clean_stop(&self, box_dir: &Path) -> Result<()>

Record that a guest-owned rootfs completed a verified clean stop.

The default is a no-op. Migration providers use this hook to advance a durable transaction only after the runtime has observed the guest’s read-only handoff acknowledgement.

Source