Struct FirecrackerPool 

pub struct FirecrackerPool { /* private fields */ }

Pre-booted Firecracker VM pool for fast cell startup.

Each slot is a VM that has booted to the kernel’s init stage and been snapshot’d — ready to restore in ~10 ms vs cold-boot ~125 ms.

Thread-safety: the pool is currently &mut self-driven for clarity. The wiring inside FirecrackerCellBackend will wrap it in tokio::sync::Mutex<FirecrackerPool> (same pattern as running_vms) so concurrent create / destroy calls serialize on slot allocation.

Implementations

impl FirecrackerPool

pub fn new(size: usize) -> Self

Construct an empty pool with size slots, all in PoolSlot::Empty. size==0 is valid and yields a pool whose checkout always returns None — the wiring code uses this to short-circuit when the env var is unset or zero.

pub fn size(&self) -> usize

Number of slots configured for this pool (any state).

pub fn available(&self) -> usize

Number of PoolSlot::Available slots — the number of cells that can be served by the fast-path right now.

pub fn in_use(&self) -> usize

Number of PoolSlot::InUse slots.

pub async fn checkout(&mut self, cell_id: &str) -> Option<PathBuf>

Reserve an available snapshot for cell_id, transitioning the slot from Available to InUse. Returns the snapshot path on success, or None if no Available slot exists (caller falls back to cold-boot).

Marked async for symmetry with the future implementation that will hold a tokio::sync::Mutex. The body is currently synchronous.

pub async fn checkin(&mut self, cell_id: &str) -> bool

Release the slot previously checked out by cell_id, transitioning it to PoolSlot::Empty. A background filler is expected to re-populate the slot via Self::fill; this is intentional — a VM that ran a real cell is no longer at the parked-init state, so re-using its snapshot would leak workload-side state into the next cell.

Returns true if a matching InUse { cell_id } slot was found and reset, false otherwise (call was a no-op).

pub async fn fill(&mut self, firecracker_bin: &str, kernel: &str, rootfs: &str)

Boot one VM per Empty slot, snapshot it, and transition the slot to PoolSlot::Available. No-op for slots already in Available or InUse.

On Linux (the only platform Firecracker runs on) this spawns one VMM per empty slot, drives the configure → InstanceStart → wait-for-init → PATCH-Paused → PUT-snapshot/create sequence, then kills the child process. The pair of (snapshot_path, mem_file_path) files left behind on disk is the durable artifact a future checkout will load.

Off-Linux this is a no-op — Firecracker is not available, so the pool stays empty and checkout returns None, falling FirecrackerCellBackend::create through to its cold-boot path.

Failures during fill are logged and the slot is left Empty (so a subsequent fill can retry); we don’t propagate errors out of fill because the pool is a best-effort latency optimisation, not a correctness gate.