threadsx 2.0.0

package/dist/master/invocation-proxy.js

@@ -0,0 +1,128 @@
+"use strict";
+/*
+ * 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…
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProxyFunction = createProxyFunction;
+exports.createProxyModule = createProxyModule;
+const debug_1 = __importDefault(require("debug"));
+const observable_fns_1 = require("observable-fns");
+const common_1 = require("../common");
+const observable_promise_1 = require("../observable-promise");
+const transferable_1 = require("../transferable");
+const messages_1 = require("../types/messages");
+const debugMessages = (0, debug_1.default)("threads:master:messages");
+let nextJobUID = 1;
+const dedupe = (array) => Array.from(new Set(array));
+const isJobErrorMessage = (data) => data && data.type === messages_1.WorkerMessageType.error;
+const isJobResultMessage = (data) => data && data.type === messages_1.WorkerMessageType.result;
+const isJobStartMessage = (data) => data && data.type === messages_1.WorkerMessageType.running;
+function createObservableForJob(worker, jobUID) {
+    return new observable_fns_1.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 (typeof event.data.payload !== "undefined") {
+                        observer.next((0, common_1.deserialize)(event.data.payload));
+                    }
+                    observer.complete();
+                    worker.removeEventListener("message", messageHandler);
+                }
+                else {
+                    if (event.data.payload) {
+                        observer.next((0, common_1.deserialize)(event.data.payload));
+                    }
+                    if (event.data.complete) {
+                        observer.complete();
+                        worker.removeEventListener("message", messageHandler);
+                    }
+                }
+            }
+            else if (isJobErrorMessage(event.data)) {
+                const error = (0, common_1.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: messages_1.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 ((0, transferable_1.isTransferDescriptor)(arg)) {
+            args.push((0, common_1.serialize)(arg.send));
+            transferables.push(...arg.transferables);
+        }
+        else {
+            args.push((0, common_1.serialize)(arg));
+        }
+    }
+    return {
+        args,
+        transferables: transferables.length === 0 ? transferables : dedupe(transferables)
+    };
+}
+function createProxyFunction(worker, method) {
+    return ((...rawArgs) => {
+        const uid = nextJobUID++;
+        const { args, transferables } = prepareArguments(rawArgs);
+        const runMessage = {
+            type: messages_1.MasterMessageType.run,
+            uid,
+            method,
+            args
+        };
+        debugMessages("Sending command to run function to worker:", runMessage);
+        try {
+            worker.postMessage(runMessage, transferables);
+        }
+        catch (error) {
+            return observable_promise_1.ObservablePromise.from(Promise.reject(error));
+        }
+        return observable_promise_1.ObservablePromise.from((0, observable_fns_1.multicast)(createObservableForJob(worker, uid)));
+    });
+}
+function createProxyModule(worker, methodNames) {
+    const proxy = {};
+    for (const methodName of methodNames) {
+        proxy[methodName] = createProxyFunction(worker, methodName);
+    }
+    return proxy;
+}

package/dist/master/pool-types.d.ts

@@ -0,0 +1,65 @@
+import { Thread } from "./thread";
+/** Pool event type. Specifies the type of each `PoolEvent`. */
+export declare enum PoolEventType {
+    initialized = "initialized",
+    taskCanceled = "taskCanceled",
+    taskCompleted = "taskCompleted",
+    taskFailed = "taskFailed",
+    taskQueued = "taskQueued",
+    taskQueueDrained = "taskQueueDrained",
+    taskStart = "taskStart",
+    terminated = "terminated"
+}
+export type TaskRunFunction<ThreadType extends Thread, Return> = (worker: ThreadType) => Promise<Return>;
+/** Pool event. Subscribe to those events using `pool.events()`. Useful for debugging. */
+export 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>>;
+};
+export interface WorkerDescriptor<ThreadType extends Thread> {
+    init: Promise<ThreadType>;
+    runningTasks: Array<Promise<any>>;
+}
+/**
+ * Task that has been `pool.queued()`-ed.
+ */
+export 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"];
+}

package/dist/master/pool-types.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PoolEventType = void 0;
+/** Pool event type. Specifies the type of each `PoolEvent`. */
+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 || (exports.PoolEventType = PoolEventType = {}));

package/dist/master/pool.d.ts

@@ -0,0 +1,89 @@
+import { Observable } from "observable-fns";
+import { PoolEvent, PoolEventType, QueuedTask, TaskRunFunction } from "./pool-types";
+import { Thread } from "./thread";
+export { PoolEvent, PoolEventType, QueuedTask, Thread };
+export 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.
+ */
+export 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>;
+}
+export 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>;
+/**
+ * Thread pool constructor. Creates a new pool and spawns its worker threads.
+ */
+export declare const Pool: typeof PoolConstructor & {
+    EventType: typeof PoolEventType;
+};

package/dist/master/pool.js

@@ -0,0 +1,290 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Pool = exports.Thread = exports.PoolEventType = void 0;
+const debug_1 = __importDefault(require("debug"));
+const observable_fns_1 = require("observable-fns");
+const ponyfills_1 = require("../ponyfills");
+const implementation_1 = require("./implementation");
+const pool_types_1 = require("./pool-types");
+Object.defineProperty(exports, "PoolEventType", { enumerable: true, get: function () { return pool_types_1.PoolEventType; } });
+const thread_1 = require("./thread");
+Object.defineProperty(exports, "Thread", { enumerable: true, get: function () { return thread_1.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.replace(/\W/g, " ").trim().replace(/\s+/g, "-");
+}
+function spawnWorkers(spawnWorker, count) {
+    return createArray(count).map(() => ({
+        init: spawnWorker(),
+        runningTasks: []
+    }));
+}
+class WorkerPool {
+    constructor(spawnWorker, optionsOrSize) {
+        this.eventSubject = new observable_fns_1.Subject();
+        this.initErrors = [];
+        this.isClosing = false;
+        this.nextTaskID = 1;
+        this.taskQueue = [];
+        const options = typeof optionsOrSize === "number"
+            ? { size: optionsOrSize }
+            : optionsOrSize || {};
+        const { size = implementation_1.defaultPoolSize } = options;
+        this.debug = (0, debug_1.default)(`threads:pool:${slugify(options.name || String(nextPoolID++))}`);
+        this.options = options;
+        this.workers = spawnWorkers(spawnWorker, size);
+        this.eventObservable = (0, observable_fns_1.multicast)(observable_fns_1.Observable.from(this.eventSubject));
+        Promise.all(this.workers.map(worker => worker.init)).then(() => this.eventSubject.next({
+            type: pool_types_1.PoolEventType.initialized,
+            size: this.workers.length
+        }), 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);
+    }
+    runPoolTask(worker, task) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const workerID = this.workers.indexOf(worker) + 1;
+            this.debug(`Running task #${task.id} on worker #${workerID}...`);
+            this.eventSubject.next({
+                type: pool_types_1.PoolEventType.taskStart,
+                taskID: task.id,
+                workerID
+            });
+            try {
+                const returnValue = yield task.run(yield worker.init);
+                this.debug(`Task #${task.id} completed successfully`);
+                this.eventSubject.next({
+                    type: pool_types_1.PoolEventType.taskCompleted,
+                    returnValue,
+                    taskID: task.id,
+                    workerID
+                });
+            }
+            catch (error) {
+                this.debug(`Task #${task.id} failed`);
+                this.eventSubject.next({
+                    type: pool_types_1.PoolEventType.taskFailed,
+                    taskID: task.id,
+                    error: error,
+                    workerID
+                });
+            }
+        });
+    }
+    run(worker, task) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const runPromise = (() => __awaiter(this, void 0, void 0, function* () {
+                const removeTaskFromWorkersRunningTasks = () => {
+                    worker.runningTasks = worker.runningTasks.filter(someRunPromise => someRunPromise !== runPromise);
+                };
+                // Defer task execution by one tick to give handlers time to subscribe
+                yield delay(0);
+                try {
+                    yield 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: pool_types_1.PoolEventType.taskQueueDrained });
+            return;
+        }
+        this.run(availableWorker, nextTask);
+    }
+    taskCompletion(taskID) {
+        return new Promise((resolve, reject) => {
+            const eventSubscription = this.events().subscribe(event => {
+                if (event.type === pool_types_1.PoolEventType.taskCompleted && event.taskID === taskID) {
+                    eventSubscription.unsubscribe();
+                    resolve(event.returnValue);
+                }
+                else if (event.type === pool_types_1.PoolEventType.taskFailed && event.taskID === taskID) {
+                    eventSubscription.unsubscribe();
+                    reject(event.error);
+                }
+                else if (event.type === pool_types_1.PoolEventType.terminated) {
+                    eventSubscription.unsubscribe();
+                    reject(Error("Pool has been terminated before task was run."));
+                }
+            });
+        });
+    }
+    settled() {
+        return __awaiter(this, arguments, void 0, function* (allowResolvingImmediately = false) {
+            const getCurrentlyRunningTasks = () => flatMap(this.workers, worker => worker.runningTasks);
+            const taskFailures = [];
+            const failureSubscription = this.eventObservable.subscribe(event => {
+                if (event.type === pool_types_1.PoolEventType.taskFailed) {
+                    taskFailures.push(event.error);
+                }
+            });
+            if (this.initErrors.length > 0) {
+                return Promise.reject(this.initErrors[0]);
+            }
+            if (allowResolvingImmediately && this.taskQueue.length === 0) {
+                yield (0, ponyfills_1.allSettled)(getCurrentlyRunningTasks());
+                return taskFailures;
+            }
+            yield new Promise((resolve, reject) => {
+                const subscription = this.eventObservable.subscribe({
+                    next(event) {
+                        if (event.type === pool_types_1.PoolEventType.taskQueueDrained) {
+                            subscription.unsubscribe();
+                            resolve(void 0);
+                        }
+                    },
+                    error: reject // make a pool-wide error reject the completed() result promise
+                });
+            });
+            yield (0, ponyfills_1.allSettled)(getCurrentlyRunningTasks());
+            failureSubscription.unsubscribe();
+            return taskFailures;
+        });
+    }
+    completed() {
+        return __awaiter(this, arguments, void 0, function* (allowResolvingImmediately = false) {
+            const settlementPromise = this.settled(allowResolvingImmediately);
+            const earlyExitPromise = new Promise((resolve, reject) => {
+                const subscription = this.eventObservable.subscribe({
+                    next(event) {
+                        if (event.type === pool_types_1.PoolEventType.taskQueueDrained) {
+                            subscription.unsubscribe();
+                            resolve(settlementPromise);
+                        }
+                        else if (event.type === pool_types_1.PoolEventType.taskFailed) {
+                            subscription.unsubscribe();
+                            reject(event.error);
+                        }
+                    },
+                    error: reject // make a pool-wide error reject the completed() result promise
+                });
+            });
+            const errors = yield Promise.race([
+                settlementPromise,
+                earlyExitPromise
+            ]);
+            if (errors.length > 0) {
+                throw errors[0];
+            }
+        });
+    }
+    events() {
+        return this.eventObservable;
+    }
+    queue(taskFunction) {
+        const { maxQueuedJobs = Infinity } = this.options;
+        if (this.isClosing) {
+            throw 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 = {
+            id: taskID,
+            run: taskFunction,
+            cancel: () => {
+                if (this.taskQueue.indexOf(task) === -1)
+                    return;
+                this.taskQueue = this.taskQueue.filter(someTask => someTask !== task);
+                this.eventSubject.next({
+                    type: pool_types_1.PoolEventType.taskCanceled,
+                    taskID: task.id
+                });
+            },
+            then: taskCompletion.then.bind(taskCompletion)
+        };
+        if (this.taskQueue.length >= maxQueuedJobs) {
+            throw 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({
+            type: pool_types_1.PoolEventType.taskQueued,
+            taskID: task.id
+        });
+        this.scheduleWork();
+        return task;
+    }
+    terminate(force) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.isClosing = true;
+            if (!force) {
+                yield this.completed(true);
+            }
+            this.eventSubject.next({
+                type: pool_types_1.PoolEventType.terminated,
+                remainingQueue: [...this.taskQueue]
+            });
+            this.eventSubject.complete();
+            yield Promise.all(this.workers.map((worker) => __awaiter(this, void 0, void 0, function* () { return thread_1.Thread.terminate(yield worker.init); })));
+        });
+    }
+}
+WorkerPool.EventType = pool_types_1.PoolEventType;
+/**
+ * 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 = pool_types_1.PoolEventType;
+/**
+ * Thread pool constructor. Creates a new pool and spawns its worker threads.
+ */
+exports.Pool = PoolConstructor;

package/dist/master/register.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/master/register.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+if (typeof global !== "undefined") {
+    global.Worker = index_1.Worker;
+}
+else if (typeof window !== "undefined") {
+    window.Worker = index_1.Worker;
+}

package/dist/master/spawn.d.ts

@@ -0,0 +1,20 @@
+import { FunctionThread, ModuleThread, StripAsync, Worker as WorkerType } from "../types/master";
+import { WorkerFunction, WorkerModule } from "../types/worker";
+type ArbitraryWorkerInterface = WorkerFunction & WorkerModule<string> & {
+    somekeythatisneverusedinproductioncode123: "magicmarker123";
+};
+type ArbitraryThreadType = FunctionThread<any, any> & ModuleThread<any>;
+export type ExposedToThreadType<Exposed extends WorkerFunction | WorkerModule<any>> = Exposed extends ArbitraryWorkerInterface ? ArbitraryThreadType : Exposed extends WorkerFunction ? FunctionThread<Parameters<Exposed>, StripAsync<ReturnType<Exposed>>> : Exposed extends WorkerModule<any> ? ModuleThread<Exposed> : never;
+/**
+ * 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 or a `worker_threads` worker.
+ * @param [options]
+ * @param [options.timeout] Init message timeout. Default: 10000 or set by environment variable.
+ */
+export declare function spawn<Exposed extends WorkerFunction | WorkerModule<any> = ArbitraryWorkerInterface>(worker: WorkerType, options?: {
+    timeout?: number;
+}): Promise<ExposedToThreadType<Exposed>>;
+export {};