Struct CachedStandaloneCanisterFixturePool 

pub struct CachedStandaloneCanisterFixturePool<const CAPACITY: usize> { /* private fields */ }

Caller-owned bounded pool of independently restorable standalone fixtures.

Each slot owns one PocketIC instance, one installed canister, and one captured baseline snapshot. Acquiring a populated slot restores that snapshot before returning it. At most CAPACITY leases can overlap; a caller waits only when every slot is in use.

One pool represents one logical fixture recipe. Every call to acquire must supply a builder for the same Wasm, init arguments, topology, and seeded baseline. The builder is not evaluated on a cache hit, so callers should use a separate pool for each recipe.

Snapshot restoration rewinds the installed canister, not the surrounding PocketIC instance. Instance time, other canisters, and cycle changes not covered by the selected SnapshotRestoreFunding policy may persist.

The pool contains no process-global state. Downstream suites select a capacity that fits their host and keep lifecycle-sensitive tests on fresh StandaloneCanisterFixture values when snapshot restoration is not the intended isolation boundary.

Implementations

impl<const CAPACITY: usize> CachedStandaloneCanisterFixturePool<CAPACITY>

pub const fn new() -> Self

Create an empty caller-owned fixture pool.

Panics

Panics at compile time for a statically initialized zero-capacity pool, or at runtime if constructed dynamically with zero capacity.

pub const fn with_restore_funding(self, funding: SnapshotRestoreFunding) -> Self

Select the cycle-funding policy applied immediately before each snapshot restore.

pub fn acquire<B>( &self, build: B, ) -> Result<(CachedStandaloneCanisterFixtureGuard<'_>, bool), ControllerSnapshotError>

where B: Fn() -> StandaloneCanisterFixture,

Acquire one isolated fixture, building a slot on first use and restoring its captured snapshot on later uses.

build must create the same logical fixture baseline on every call to this pool. It runs only when an empty slot is first populated or a dead PocketIC instance must be replaced.

A recognized dead-instance transport failure evicts and rebuilds only the affected slot. Other snapshot failures are returned unchanged and invalidate the possibly partially restored slot for the next lease.

Errors

Returns the structured snapshot capture or restore failure for the selected slot.

pub fn acquire_with_outcome<B>( &self, build: B, ) -> Result<(CachedStandaloneCanisterFixtureGuard<'_>, StandaloneFixturePoolOutcome), StandaloneFixturePoolError>

where B: Fn() -> StandaloneCanisterFixture,

Acquire one fixture with structured lifecycle outcome and phase timings.

This is the diagnostic counterpart to acquire. It distinguishes a new slot from restoration and reconstruction while the compatibility method continues to report restoration as a boolean.

Errors

Returns the failed preparation stage, the structured snapshot error, and all phase timings completed before failure. If dead-transport restoration and replacement capture both fail, both errors are retained.

Trait Implementations

impl<const CAPACITY: usize> Default for CachedStandaloneCanisterFixturePool<CAPACITY>

fn default() -> Self

Returns the “default value” for a type.