shield-bridge-sdk/dist/workerPool.d.ts

Shield Bridge SDK

import * as Comlink from 'comlink';
import type { SaplingWorker } from './worker.js';
/** Default maximum number of workers in the pool */
export declare const DEFAULT_POOL_SIZE = 5;
/** How long (ms) an idle worker stays alive before being reaped. Default: 5 minutes */
export declare const DEFAULT_IDLE_TIMEOUT_MS: number;
export interface PoolEntry {
    worker: Comlink.Remote<SaplingWorker>;
    busy: boolean;
    /** Whether the heavy sapling params (~50 MB) have been loaded in this worker */
    paramsLoaded: boolean;
    /** Timestamp (Date.now()) of the last time this entry was returned to the pool */
    lastUsed: number;
}
/**
 * A bounded, lazy-growing pool of Comlink-wrapped Sapling Web Workers.
 *
 * Design goals:
 * - **Lazy creation** – workers are only spawned when checkout() cannot find an
 *   idle worker and the pool has capacity.
 * - **Bounded concurrency** – at most `maxSize` workers exist simultaneously.
 * - **Worker reuse** – checked-in workers stay alive with their heavy sapling
 *   params already initialised, avoiding repeated ~50 MB fetches.
 * - **Back-pressure** – when all workers are busy the caller awaits a Promise
 *   that resolves as soon as any worker is returned.
 * - **Idle reaping** – a periodic sweep terminates workers that have been idle
 *   longer than `idleTimeoutMs`.
 */
export declare class SaplingWorkerPool {
    /** Max workers that can exist at once */
    readonly maxSize: number;
    /** Factory that creates a new Comlink-wrapped worker */
    private readonly createWorkerFn;
    /** How long (ms) an idle worker stays alive before being reaped */
    private readonly idleTimeoutMs;
    private pool;
    private pendingCheckouts;
    private idleTimer;
    /** Whether the pool has been destroyed */
    private destroyed;
    /**
     * Number of workers currently being created (awaiting createWorkerFn).
     * This is used to prevent the pool from exceeding maxSize when multiple
     * concurrent checkout() calls race past the capacity check before the
     * first worker creation completes and pushes to the pool.
     */
    private creating;
    constructor(
    /** Max workers that can exist at once */
    maxSize: number, 
    /** Factory that creates a new Comlink-wrapped worker */
    createWorkerFn: () => Promise<Comlink.Remote<SaplingWorker>>, 
    /** How long (ms) an idle worker stays alive before being reaped */
    idleTimeoutMs?: number);
    /**
     * Acquire an idle worker from the pool.
     *
     * - If an idle worker exists it is returned immediately.
     * - If the pool has room, a new worker is created and returned.
     * - Otherwise the caller is queued until a worker becomes available.
     *
     * The returned `PoolEntry` **must** be given back via `release()` when done.
     */
    checkout(): Promise<PoolEntry>;
    /**
     * Return a worker to the pool. Any queued `checkout()` callers are served
     * immediately (FIFO).
     */
    release(entry: PoolEntry): void;
    /**
     * Destroy all workers and reject any pending checkouts.
     * After calling this the pool is unusable.
     */
    destroy(): void;
    /** Current number of workers (busy + idle) */
    get size(): number;
    /** Number of workers currently checked out */
    get busyCount(): number;
    /** Number of idle workers ready for checkout */
    get idleCount(): number;
    /** Number of callers waiting for a worker */
    get pendingCount(): number;
    /**
     * Periodically terminate workers that have been idle too long to reclaim
     * memory (each worker holds ~60-80 MB of sapling WASM + params).
     */
    private startIdleReaper;
}
//# sourceMappingURL=workerPool.d.ts.map