@xylabs/threads/dist/browser/master/pool-browser.d.ts

Web workers & worker threads as simple as a function call

import { Observable } from 'observable-fns';
import { T as Thread$1, b as WorkerEvent } from '../master-C8XAGDqb.js';
import '../transferable-Blu_CzPT.js';

type Thread = Thread$1;
/** Thread utility functions. Use them to manage or inspect a `spawn()`-ed thread. */
declare const Thread: {
    /** Return an observable that can be used to subscribe to all errors happening in the thread. */
    errors<ThreadT extends Thread$1>(thread: ThreadT): Observable<Error>;
    /** Return an observable that can be used to subscribe to internal events happening in the thread. Useful for debugging. */
    events<ThreadT extends Thread$1>(thread: ThreadT): Observable<WorkerEvent>;
    /** Terminate a thread. Remember to terminate every thread when you are done using it. */
    terminate<ThreadT extends Thread$1>(thread: ThreadT): Promise<void>;
};

/** Pool event type. Specifies the type of each `PoolEvent`. */
declare enum PoolEventType {
    initialized = "initialized",
    taskCanceled = "taskCanceled",
    taskCompleted = "taskCompleted",
    taskFailed = "taskFailed",
    taskQueued = "taskQueued",
    taskQueueDrained = "taskQueueDrained",
    taskStart = "taskStart",
    terminated = "terminated"
}
type TaskRunFunction<ThreadType extends Thread, Return> = (worker: ThreadType) => Promise<Return>;
/** Pool event. Subscribe to those events using `pool.events()`. Useful for debugging. */
type PoolEvent<ThreadType extends Thread> = {
    type: PoolEventType.initialized;
    size: number;
} | {
    type: PoolEventType.taskQueued;
    taskID: number;
} | {
    type: PoolEventType.taskQueueDrained;
} | {
    type: PoolEventType.taskStart;
    taskID: number;
    workerID: number;
} | {
    type: PoolEventType.taskCompleted;
    returnValue: any;
    taskID: number;
    workerID: number;
} | {
    type: PoolEventType.taskFailed;
    error: Error;
    taskID: number;
    workerID: number;
} | {
    type: PoolEventType.taskCanceled;
    taskID: number;
} | {
    type: PoolEventType.terminated;
    remainingQueue: Array<QueuedTask<ThreadType, any>>;
};
/**
 * Task that has been `pool.queued()`-ed.
 */
interface QueuedTask<ThreadType extends Thread, Return> {
    /** @private */
    id: number;
    /** @private */
    run: TaskRunFunction<ThreadType, Return>;
    /**
     * Queued tasks can be cancelled until the pool starts running them on a worker thread.
     */
    cancel(): void;
    /**
     * `QueuedTask` is thenable, so you can `await` it.
     * Resolves when the task has successfully been executed. Rejects if the task fails.
     */
    then: Promise<Return>['then'];
}

interface PoolOptions {
    /** Maximum no. of tasks to run on one worker thread at a time. Defaults to one. */
    concurrency?: number;
    /** Maximum no. of jobs to be queued for execution before throwing an error. */
    maxQueuedJobs?: number;
    /** Gives that pool a name to be used for debug logging, letting you distinguish between log output of different pools. */
    name?: string;
    /** No. of worker threads to spawn and to be managed by the pool. */
    size?: number;
}
declare class WorkerPool<ThreadType extends Thread> implements Pool<ThreadType> {
    static EventType: typeof PoolEventType;
    private readonly debug;
    private readonly eventObservable;
    private readonly options;
    private readonly workers;
    private readonly eventSubject;
    private initErrors;
    private isClosing;
    private nextTaskID;
    private taskQueue;
    constructor(spawnWorker: () => Promise<ThreadType>, optionsOrSize?: number | PoolOptions);
    private findIdlingWorker;
    private runPoolTask;
    private run;
    private scheduleWork;
    private taskCompletion;
    settled(allowResolvingImmediately?: boolean): Promise<Error[]>;
    completed(allowResolvingImmediately?: boolean): Promise<void>;
    events(): Observable<PoolEvent<ThreadType>>;
    queue(taskFunction: TaskRunFunction<ThreadType, any>): QueuedTask<ThreadType, any>;
    terminate(force?: boolean): Promise<void>;
}
/**
 * Thread pool constructor. Creates a new pool and spawns its worker threads.
 */
declare function PoolConstructor<ThreadType extends Thread>(spawnWorker: () => Promise<ThreadType>, optionsOrSize?: number | PoolOptions): WorkerPool<ThreadType>;
declare namespace Pool {
    type Event<ThreadType extends Thread = any> = PoolEvent<ThreadType>;
    type EventType = PoolEventType;
}
/**
 * Thread pool managing a set of worker threads.
 * Use it to queue tasks that are run on those threads with limited
 * concurrency.
 */
interface Pool<ThreadType extends Thread> {
    /**
     * Returns a promise that resolves once the task queue is emptied.
     * Promise will be rejected if any task fails.
     *
     * @param allowResolvingImmediately Set to `true` to resolve immediately if task queue is currently empty.
     */
    completed(allowResolvingImmediately?: boolean): Promise<any>;
    /**
     * Returns a promise that resolves once the task queue is emptied.
     * Failing tasks will not cause the promise to be rejected.
     *
     * @param allowResolvingImmediately Set to `true` to resolve immediately if task queue is currently empty.
     */
    settled(allowResolvingImmediately?: boolean): Promise<Error[]>;
    /**
     * Returns an observable that yields pool events.
     */
    events(): Observable<PoolEvent<ThreadType>>;
    /**
     * Queue a task and return a promise that resolves once the task has been dequeued,
     * started and finished.
     *
     * @param task An async function that takes a thread instance and invokes it.
     */
    queue<Return>(task: TaskRunFunction<ThreadType, Return>): QueuedTask<ThreadType, Return>;
    /**
     * Terminate all pool threads.
     *
     * @param force Set to `true` to kill the thread even if it cannot be stopped gracefully.
     */
    terminate(force?: boolean): Promise<void>;
}
/**
 * Thread pool constructor. Creates a new pool and spawns its worker threads.
 */
declare const Pool: typeof PoolConstructor & {
    EventType: typeof PoolEventType;
};

export { Pool, type PoolEvent, PoolEventType, type QueuedTask, Thread };