@xylabs/threads 3.0.4

package/dist-esm/master/invocation-proxy.js

@@ -0,0 +1,122 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/*
+ * This source file contains the code for proxying calls in the master thread to calls in the workers
+ * by `.postMessage()`-ing.
+ *
+ * Keep in mind that this code can make or break the program's performance! Need to optimize more…
+ */
+import DebugLogger from 'debug';
+import { multicast, Observable } from 'observable-fns';
+import { deserialize, serialize } from '../common';
+import { ObservablePromise } from '../observable-promise';
+import { isTransferDescriptor } from '../transferable';
+import { MasterMessageType, WorkerMessageType, } from '../types/messages';
+const debugMessages = DebugLogger('threads:master:messages');
+let nextJobUID = 1;
+const dedupe = (array) => [...new Set(array)];
+const isJobErrorMessage = (data) => data && data.type === WorkerMessageType.error;
+const isJobResultMessage = (data) => data && data.type === WorkerMessageType.result;
+const isJobStartMessage = (data) => data && data.type === WorkerMessageType.running;
+function createObservableForJob(worker, jobUID) {
+    return new Observable((observer) => {
+        let asyncType;
+        const messageHandler = ((event) => {
+            debugMessages('Message from worker:', event.data);
+            if (!event.data || event.data.uid !== jobUID)
+                return;
+            if (isJobStartMessage(event.data)) {
+                asyncType = event.data.resultType;
+            }
+            else if (isJobResultMessage(event.data)) {
+                if (asyncType === 'promise') {
+                    if (event.data.payload !== undefined) {
+                        observer.next(deserialize(event.data.payload));
+                    }
+                    observer.complete();
+                    worker.removeEventListener('message', messageHandler);
+                }
+                else {
+                    if (event.data.payload) {
+                        observer.next(deserialize(event.data.payload));
+                    }
+                    if (event.data.complete) {
+                        observer.complete();
+                        worker.removeEventListener('message', messageHandler);
+                    }
+                }
+            }
+            else if (isJobErrorMessage(event.data)) {
+                const error = deserialize(event.data.error);
+                if (asyncType === 'promise' || !asyncType) {
+                    observer.error(error);
+                }
+                else {
+                    observer.error(error);
+                }
+                worker.removeEventListener('message', messageHandler);
+            }
+        });
+        worker.addEventListener('message', messageHandler);
+        return () => {
+            if (asyncType === 'observable' || !asyncType) {
+                const cancelMessage = {
+                    type: MasterMessageType.cancel,
+                    uid: jobUID,
+                };
+                worker.postMessage(cancelMessage);
+            }
+            worker.removeEventListener('message', messageHandler);
+        };
+    });
+}
+function prepareArguments(rawArgs) {
+    if (rawArgs.length === 0) {
+        // Exit early if possible
+        return {
+            args: [],
+            transferables: [],
+        };
+    }
+    const args = [];
+    const transferables = [];
+    for (const arg of rawArgs) {
+        if (isTransferDescriptor(arg)) {
+            args.push(serialize(arg.send));
+            transferables.push(...arg.transferables);
+        }
+        else {
+            args.push(serialize(arg));
+        }
+    }
+    return {
+        args,
+        transferables: transferables.length === 0 ? transferables : dedupe(transferables),
+    };
+}
+export function createProxyFunction(worker, method) {
+    return ((...rawArgs) => {
+        const uid = nextJobUID++;
+        const { args, transferables } = prepareArguments(rawArgs);
+        const runMessage = {
+            args,
+            method,
+            type: MasterMessageType.run,
+            uid,
+        };
+        debugMessages('Sending command to run function to worker:', runMessage);
+        try {
+            worker.postMessage(runMessage, transferables);
+        }
+        catch (error) {
+            return ObservablePromise.from(Promise.reject(error));
+        }
+        return ObservablePromise.from(multicast(createObservableForJob(worker, uid)));
+    });
+}
+export function createProxyModule(worker, methodNames) {
+    const proxy = {};
+    for (const methodName of methodNames) {
+        proxy[methodName] = createProxyFunction(worker, methodName);
+    }
+    return proxy;
+}

package/dist-esm/master/pool-types.js

@@ -0,0 +1,12 @@
+/** Pool event type. Specifies the type of each `PoolEvent`. */
+export var PoolEventType;
+(function (PoolEventType) {
+    PoolEventType["initialized"] = "initialized";
+    PoolEventType["taskCanceled"] = "taskCanceled";
+    PoolEventType["taskCompleted"] = "taskCompleted";
+    PoolEventType["taskFailed"] = "taskFailed";
+    PoolEventType["taskQueued"] = "taskQueued";
+    PoolEventType["taskQueueDrained"] = "taskQueueDrained";
+    PoolEventType["taskStart"] = "taskStart";
+    PoolEventType["terminated"] = "terminated";
+})(PoolEventType || (PoolEventType = {}));

package/dist-esm/master/pool.js

@@ -0,0 +1,273 @@
+/* eslint-disable unicorn/no-thenable */
+/* eslint-disable @typescript-eslint/no-floating-promises */
+/* eslint-disable require-await */
+/* eslint-disable @typescript-eslint/member-ordering */
+/* eslint-disable unicorn/no-array-reduce */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable import/export */
+/* eslint-disable @typescript-eslint/no-namespace */
+import DebugLogger from 'debug';
+import { multicast, Observable, Subject } from 'observable-fns';
+import { allSettled } from '../ponyfills';
+import { defaultPoolSize } from './implementation';
+import { PoolEventType } from './pool-types';
+import { Thread } from './thread';
+let nextPoolID = 1;
+function createArray(size) {
+    const array = [];
+    for (let index = 0; index < size; index++) {
+        array.push(index);
+    }
+    return array;
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function flatMap(array, mapper) {
+    return array.reduce((flattened, element) => [...flattened, ...mapper(element)], []);
+}
+function slugify(text) {
+    return text.replaceAll(/\W/g, ' ').trim().replaceAll(/\s+/g, '-');
+}
+function spawnWorkers(spawnWorker, count) {
+    return createArray(count).map(() => ({
+        init: spawnWorker(),
+        runningTasks: [],
+    }));
+}
+class WorkerPool {
+    static EventType = PoolEventType;
+    debug;
+    eventObservable;
+    options;
+    workers;
+    eventSubject = new Subject();
+    initErrors = [];
+    isClosing = false;
+    nextTaskID = 1;
+    taskQueue = [];
+    constructor(spawnWorker, optionsOrSize) {
+        const options = typeof optionsOrSize === 'number' ? { size: optionsOrSize } : optionsOrSize || {};
+        const { size = defaultPoolSize } = options;
+        this.debug = DebugLogger(`threads:pool:${slugify(options.name || String(nextPoolID++))}`);
+        this.options = options;
+        this.workers = spawnWorkers(spawnWorker, size);
+        this.eventObservable = multicast(Observable.from(this.eventSubject));
+        Promise.all(this.workers.map((worker) => worker.init)).then(() => this.eventSubject.next({
+            size: this.workers.length,
+            type: PoolEventType.initialized,
+        }), (error) => {
+            this.debug('Error while initializing pool worker:', error);
+            this.eventSubject.error(error);
+            this.initErrors.push(error);
+        });
+    }
+    findIdlingWorker() {
+        const { concurrency = 1 } = this.options;
+        return this.workers.find((worker) => worker.runningTasks.length < concurrency);
+    }
+    async runPoolTask(worker, task) {
+        const workerID = this.workers.indexOf(worker) + 1;
+        this.debug(`Running task #${task.id} on worker #${workerID}...`);
+        this.eventSubject.next({
+            taskID: task.id,
+            type: PoolEventType.taskStart,
+            workerID,
+        });
+        try {
+            const returnValue = await task.run(await worker.init);
+            this.debug(`Task #${task.id} completed successfully`);
+            this.eventSubject.next({
+                returnValue,
+                taskID: task.id,
+                type: PoolEventType.taskCompleted,
+                workerID,
+            });
+        }
+        catch (error) {
+            this.debug(`Task #${task.id} failed`);
+            this.eventSubject.next({
+                error,
+                taskID: task.id,
+                type: PoolEventType.taskFailed,
+                workerID,
+            });
+        }
+    }
+    async run(worker, task) {
+        const runPromise = (async () => {
+            const removeTaskFromWorkersRunningTasks = () => {
+                worker.runningTasks = worker.runningTasks.filter((someRunPromise) => someRunPromise !== runPromise);
+            };
+            // Defer task execution by one tick to give handlers time to subscribe
+            await delay(0);
+            try {
+                await this.runPoolTask(worker, task);
+            }
+            finally {
+                removeTaskFromWorkersRunningTasks();
+                if (!this.isClosing) {
+                    this.scheduleWork();
+                }
+            }
+        })();
+        worker.runningTasks.push(runPromise);
+    }
+    scheduleWork() {
+        this.debug('Attempt de-queueing a task in order to run it...');
+        const availableWorker = this.findIdlingWorker();
+        if (!availableWorker)
+            return;
+        const nextTask = this.taskQueue.shift();
+        if (!nextTask) {
+            this.debug('Task queue is empty');
+            this.eventSubject.next({ type: PoolEventType.taskQueueDrained });
+            return;
+        }
+        this.run(availableWorker, nextTask);
+    }
+    taskCompletion(taskID) {
+        return new Promise((resolve, reject) => {
+            const eventSubscription = this.events().subscribe((event) => {
+                if (event.type === PoolEventType.taskCompleted && event.taskID === taskID) {
+                    eventSubscription.unsubscribe();
+                    resolve(event.returnValue);
+                }
+                else if (event.type === PoolEventType.taskFailed && event.taskID === taskID) {
+                    eventSubscription.unsubscribe();
+                    reject(event.error);
+                }
+                else if (event.type === PoolEventType.terminated) {
+                    eventSubscription.unsubscribe();
+                    reject(Error('Pool has been terminated before task was run.'));
+                }
+            });
+        });
+    }
+    async settled(allowResolvingImmediately = false) {
+        const getCurrentlyRunningTasks = () => flatMap(this.workers, (worker) => worker.runningTasks);
+        const taskFailures = [];
+        const failureSubscription = this.eventObservable.subscribe((event) => {
+            if (event.type === PoolEventType.taskFailed) {
+                taskFailures.push(event.error);
+            }
+        });
+        if (this.initErrors.length > 0) {
+            throw this.initErrors[0];
+        }
+        if (allowResolvingImmediately && this.taskQueue.length === 0) {
+            await allSettled(getCurrentlyRunningTasks());
+            return taskFailures;
+        }
+        await new Promise((resolve, reject) => {
+            const subscription = this.eventObservable.subscribe({
+                error: reject,
+                next(event) {
+                    if (event.type === PoolEventType.taskQueueDrained) {
+                        subscription.unsubscribe();
+                        resolve(void 0);
+                    }
+                }, // make a pool-wide error reject the completed() result promise
+            });
+        });
+        await allSettled(getCurrentlyRunningTasks());
+        failureSubscription.unsubscribe();
+        return taskFailures;
+    }
+    async completed(allowResolvingImmediately = false) {
+        const settlementPromise = this.settled(allowResolvingImmediately);
+        const earlyExitPromise = new Promise((resolve, reject) => {
+            const subscription = this.eventObservable.subscribe({
+                error: reject,
+                next(event) {
+                    if (event.type === PoolEventType.taskQueueDrained) {
+                        subscription.unsubscribe();
+                        resolve(settlementPromise);
+                    }
+                    else if (event.type === PoolEventType.taskFailed) {
+                        subscription.unsubscribe();
+                        reject(event.error);
+                    }
+                }, // make a pool-wide error reject the completed() result promise
+            });
+        });
+        const errors = await Promise.race([settlementPromise, earlyExitPromise]);
+        if (errors.length > 0) {
+            throw errors[0];
+        }
+    }
+    events() {
+        return this.eventObservable;
+    }
+    queue(taskFunction) {
+        const { maxQueuedJobs = Number.POSITIVE_INFINITY } = this.options;
+        if (this.isClosing) {
+            throw new Error('Cannot schedule pool tasks after terminate() has been called.');
+        }
+        if (this.initErrors.length > 0) {
+            throw this.initErrors[0];
+        }
+        const taskID = this.nextTaskID++;
+        const taskCompletion = this.taskCompletion(taskID);
+        taskCompletion.catch((error) => {
+            // Prevent unhandled rejections here as we assume the user will use
+            // `pool.completed()`, `pool.settled()` or `task.catch()` to handle errors
+            this.debug(`Task #${taskID} errored:`, error);
+        });
+        const task = {
+            cancel: () => {
+                if (!this.taskQueue.includes(task))
+                    return;
+                this.taskQueue = this.taskQueue.filter((someTask) => someTask !== task);
+                this.eventSubject.next({
+                    taskID: task.id,
+                    type: PoolEventType.taskCanceled,
+                });
+            },
+            id: taskID,
+            run: taskFunction,
+            then: taskCompletion.then.bind(taskCompletion),
+        };
+        if (this.taskQueue.length >= maxQueuedJobs) {
+            throw new Error('Maximum number of pool tasks queued. Refusing to queue another one.\n' +
+                'This usually happens for one of two reasons: We are either at peak ' +
+                "workload right now or some tasks just won't finish, thus blocking the pool.");
+        }
+        this.debug(`Queueing task #${task.id}...`);
+        this.taskQueue.push(task);
+        this.eventSubject.next({
+            taskID: task.id,
+            type: PoolEventType.taskQueued,
+        });
+        this.scheduleWork();
+        return task;
+    }
+    async terminate(force) {
+        this.isClosing = true;
+        if (!force) {
+            await this.completed(true);
+        }
+        this.eventSubject.next({
+            remainingQueue: [...this.taskQueue],
+            type: PoolEventType.terminated,
+        });
+        this.eventSubject.complete();
+        await Promise.all(this.workers.map(async (worker) => Thread.terminate(await worker.init)));
+    }
+}
+/**
+ * Thread pool constructor. Creates a new pool and spawns its worker threads.
+ */
+function PoolConstructor(spawnWorker, optionsOrSize) {
+    // The function exists only so we don't need to use `new` to create a pool (we still can, though).
+    // If the Pool is a class or not is an implementation detail that should not concern the user.
+    return new WorkerPool(spawnWorker, optionsOrSize);
+}
+;
+PoolConstructor.EventType = PoolEventType;
+/**
+ * Thread pool constructor. Creates a new pool and spawns its worker threads.
+ */
+export const Pool = PoolConstructor;
+export { PoolEventType } from './pool-types';
+export { Thread } from './thread';

package/dist-esm/master/register.js

@@ -0,0 +1,10 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Worker as WorkerImplementation } from './index';
+if (typeof global !== 'undefined') {
+    ;
+    global.Worker = WorkerImplementation;
+}
+else if (window !== undefined) {
+    ;
+    window.Worker = WorkerImplementation;
+}

package/dist-esm/master/spawn.js

@@ -0,0 +1,123 @@
+/* eslint-disable @typescript-eslint/no-floating-promises */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import DebugLogger from 'debug';
+import { Observable } from 'observable-fns';
+import { deserialize } from '../common';
+import { createPromiseWithResolver } from '../promise';
+import { $errors, $events, $terminate, $worker } from '../symbols';
+import { WorkerEventType, } from '../types/master';
+import { createProxyFunction, createProxyModule } from './invocation-proxy';
+const debugMessages = DebugLogger('threads:master:messages');
+const debugSpawn = DebugLogger('threads:master:spawn');
+const debugThreadUtils = DebugLogger('threads:master:thread-utils');
+const isInitMessage = (data) => data && data.type === 'init';
+const isUncaughtErrorMessage = (data) => data && data.type === 'uncaughtError';
+const initMessageTimeout = typeof process !== 'undefined' && process.env !== undefined && process.env.THREADS_WORKER_INIT_TIMEOUT ?
+    Number.parseInt(process.env.THREADS_WORKER_INIT_TIMEOUT, 10)
+    : 10000;
+async function withTimeout(promise, timeoutInMs, errorMessage) {
+    let timeoutHandle;
+    const timeout = new Promise((resolve, reject) => {
+        timeoutHandle = setTimeout(() => reject(Error(errorMessage)), timeoutInMs);
+    });
+    const result = await Promise.race([promise, timeout]);
+    clearTimeout(timeoutHandle);
+    return result;
+}
+function receiveInitMessage(worker) {
+    return new Promise((resolve, reject) => {
+        const messageHandler = ((event) => {
+            debugMessages('Message from worker before finishing initialization:', event.data);
+            if (isInitMessage(event.data)) {
+                worker.removeEventListener('message', messageHandler);
+                resolve(event.data);
+            }
+            else if (isUncaughtErrorMessage(event.data)) {
+                worker.removeEventListener('message', messageHandler);
+                reject(deserialize(event.data.error));
+            }
+        });
+        worker.addEventListener('message', messageHandler);
+    });
+}
+function createEventObservable(worker, workerTermination) {
+    return new Observable((observer) => {
+        const messageHandler = ((messageEvent) => {
+            const workerEvent = {
+                data: messageEvent.data,
+                type: WorkerEventType.message,
+            };
+            observer.next(workerEvent);
+        });
+        const rejectionHandler = ((errorEvent) => {
+            debugThreadUtils('Unhandled promise rejection event in thread:', errorEvent);
+            const workerEvent = {
+                error: Error(errorEvent.reason),
+                type: WorkerEventType.internalError,
+            };
+            observer.next(workerEvent);
+        });
+        worker.addEventListener('message', messageHandler);
+        worker.addEventListener('unhandledrejection', rejectionHandler);
+        workerTermination.then(() => {
+            const terminationEvent = {
+                type: WorkerEventType.termination,
+            };
+            worker.removeEventListener('message', messageHandler);
+            worker.removeEventListener('unhandledrejection', rejectionHandler);
+            observer.next(terminationEvent);
+            observer.complete();
+        });
+    });
+}
+function createTerminator(worker) {
+    const [termination, resolver] = createPromiseWithResolver();
+    const terminate = async () => {
+        debugThreadUtils('Terminating worker');
+        // Newer versions of worker_threads workers return a promise
+        await worker.terminate();
+        resolver();
+    };
+    return { terminate, termination };
+}
+function setPrivateThreadProps(raw, worker, workerEvents, terminate) {
+    const workerErrors = workerEvents
+        .filter((event) => event.type === WorkerEventType.internalError)
+        .map((errorEvent) => errorEvent.error);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return Object.assign(raw, {
+        [$errors]: workerErrors,
+        [$events]: workerEvents,
+        [$terminate]: terminate,
+        [$worker]: worker,
+    });
+}
+/**
+ * Spawn a new thread. Takes a fresh worker instance, wraps it in a thin
+ * abstraction layer to provide the transparent API and verifies that
+ * the worker has initialized successfully.
+ *
+ * @param worker Instance of `Worker`. Either a web worker, `worker_threads` worker or `tiny-worker` worker.
+ * @param [options]
+ * @param [options.timeout] Init message timeout. Default: 10000 or set by environment variable.
+ */
+export async function spawn(worker, options) {
+    debugSpawn('Initializing new thread');
+    const timeout = options && options.timeout ? options.timeout : initMessageTimeout;
+    const initMessage = await withTimeout(receiveInitMessage(worker), timeout, `Timeout: Did not receive an init message from worker after ${timeout}ms. Make sure the worker calls expose().`);
+    const exposed = initMessage.exposed;
+    const { termination, terminate } = createTerminator(worker);
+    const events = createEventObservable(worker, termination);
+    if (exposed.type === 'function') {
+        const proxy = createProxyFunction(worker);
+        return setPrivateThreadProps(proxy, worker, events, terminate);
+    }
+    else if (exposed.type === 'module') {
+        const proxy = createProxyModule(worker, exposed.methods);
+        return setPrivateThreadProps(proxy, worker, events, terminate);
+    }
+    else {
+        const type = exposed.type;
+        throw new Error(`Worker init message states unexpected type of expose(): ${type}`);
+    }
+}

package/dist-esm/master/thread.js

@@ -0,0 +1,19 @@
+import { $errors, $events, $terminate } from '../symbols';
+function fail(message) {
+    throw new Error(message);
+}
+/** Thread utility functions. Use them to manage or inspect a `spawn()`-ed thread. */
+export const Thread = {
+    /** Return an observable that can be used to subscribe to all errors happening in the thread. */
+    errors(thread) {
+        return thread[$errors] || fail('Error observable not found. Make sure to pass a thread instance as returned by the spawn() promise.');
+    },
+    /** Return an observable that can be used to subscribe to internal events happening in the thread. Useful for debugging. */
+    events(thread) {
+        return thread[$events] || fail('Events observable not found. Make sure to pass a thread instance as returned by the spawn() promise.');
+    },
+    /** Terminate a thread. Remember to terminate every thread when you are done using it. */
+    terminate(thread) {
+        return thread[$terminate]();
+    },
+};