Struct CachedStandaloneCanisterFixturePool 

pub struct CachedStandaloneCanisterFixturePool<B = fn() -> StandaloneCanisterFixture> { /* private fields */ }

Caller-owned runtime-capacity 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 Self::capacity leases can overlap; a caller waits only when every slot is in use.

One pool owns one fixture builder. The builder must produce the same Wasm, init arguments, topology, and seeded baseline each time it runs. It is not evaluated on a cache hit; 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<B> CachedStandaloneCanisterFixturePool<B>

where B: Fn() -> StandaloneCanisterFixture,

pub const fn new(capacity: NonZeroUsize, build: B) -> Self

Create a runtime-capacity pool that owns its fixture builder.

Construction is const and lazy: slots are allocated on first acquisition, and the builder runs only when a slot needs a fixture.

use std::num::NonZeroUsize;
use ic_testkit::pic::{CachedStandaloneCanisterFixturePool, StandaloneCanisterFixture};

static POOL: CachedStandaloneCanisterFixturePool =
    CachedStandaloneCanisterFixturePool::new(
        NonZeroUsize::new(2).unwrap(),
        build_fixture,
    );

// Local pools can choose their capacity at runtime.
let capacity = std::thread::available_parallelism()?;
let pool = CachedStandaloneCanisterFixturePool::new(capacity, build_fixture);

pub const fn capacity(&self) -> NonZeroUsize

Maximum number of simultaneously leased standalone fixtures.

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

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

pub fn acquire( &self, ) -> Result<(CachedStandaloneCanisterFixtureGuard<'_>, StandaloneFixturePoolOutcome), StandaloneFixturePoolError>

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

The pool’s builder runs only when an empty or invalid slot is 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.

Acquire one fixture with a structured lifecycle outcome and phase timings.

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.