src/utils/thread.jsjavascript
/**
* Fallback default thread pool size, used if the number of logical
* processors is not available.
*/
const FALLBACK_POOL_SIZE = 4;
/**
* Get the number of logical processors.
*
* @returns {number|undefined} The number of logical processors
* (`navigator.hardwareConcurrency`), undefined if not available.
*/
function getHardwareConcurrency() {
let res;
if (typeof navigator !== 'undefined' &&
typeof navigator.hardwareConcurrency !== 'undefined' &&
navigator.hardwareConcurrency > 0) {
res = navigator.hardwareConcurrency;
}
return res;
}
/**
* Get the default thread pool size: half the number of logical
* processors (at least one), or {@link FALLBACK_POOL_SIZE} if not
* available. Leaves room for the main thread and limits the number of
* workers (and their buffer copies), which matters on memory limited
* devices such as iOS ones.
*
* @returns {number} The pool size.
*/
export function getDefaultPoolSize() {
const hardwareConcurrency = getHardwareConcurrency();
let res = FALLBACK_POOL_SIZE;
if (typeof hardwareConcurrency !== 'undefined') {
res = Math.max(1, Math.floor(hardwareConcurrency / 2));
}
return res;
}
/**
* Clamp a thread pool size to the number of logical processors,
* if available.
*
* @param {number} poolSize The pool size.
* @returns {number} The clamped pool size.
*/
export function clampPoolSize(poolSize) {
const hardwareConcurrency = getHardwareConcurrency();
if (typeof hardwareConcurrency !== 'undefined' &&
poolSize > hardwareConcurrency) {
poolSize = hardwareConcurrency;
}
return poolSize;
}
/**
* Thread Pool.
*
* Highly inspired from {@link http://www.smartjava.org/content/html5-easily-parallelize-jobs-using-web-workers-and-threadpool}.
*/
export class ThreadPool {
/**
* @type {number}
*/
#poolSize;
/**
* @type {WorkerTask[]}
*/
#taskQueue;
/**
* @type {WorkerThread[]}
*/
#freeThreads;
/**
* @type {WorkerThread[]}
*/
#runningThreads;
/**
* @param {number} [poolSize] The size of the pool, defaults to
* {@link getDefaultPoolSize}. Must be a positive integer, it is
* clamped to the number of logical processors if available.
*/
constructor(poolSize) {
if (typeof poolSize === 'undefined') {
poolSize = getDefaultPoolSize();
}
if (!Number.isInteger(poolSize) || poolSize < 1) {
throw new Error(
`Thread pool size must be a positive integer: ${poolSize}`);
}
this.#poolSize = clampPoolSize(poolSize);
// initialize members
this.#init();
}
/**
* Initialize the thread pool.
*/
#init() {
// task queue
this.#taskQueue = [];
// list of available threads
this.#freeThreads = [];
// create 'poolSize' number of worker threads
for (let i = 0; i < this.#poolSize; ++i) {
this.#freeThreads.push(new WorkerThread(this));
}
// list of running threads (used in abort)
this.#runningThreads = [];
}
/**
* Add a worker task to the queue.
* Will be run when a thread is made available.
*
* @param {WorkerTask} workerTask The task to add to the queue.
*/
addWorkerTask(workerTask) {
// send work start if first task
if (this.#freeThreads.length === this.#poolSize) {
this.onworkstart({type: 'work-start'});
}
// launch task or queue
if (this.#freeThreads.length > 0) {
// get the first free worker thread
const workerThread = this.#freeThreads.shift();
// add the thread to the running list
this.#runningThreads.push(workerThread);
// run the input task
workerThread.run(workerTask);
} else {
// no free thread, add task to queue
this.#taskQueue.push(workerTask);
}
}
/**
* Abort all threads.
*/
abort() {
// stop all threads
this.#stop();
// reinitialize so the pool can be reused
this.#init();
// callback
this.onabort({type: 'work-abort'});
this.onworkend({type: 'work-end'});
}
/**
* Handle a task end.
*
* @param {WorkerThread} workerThread The thread to free.
*/
onTaskEnd(workerThread) {
// launch next task in queue or finish
if (this.#taskQueue.length > 0) {
// get waiting task
const workerTask = this.#taskQueue.shift();
// use input thread to run the waiting task
workerThread.run(workerTask);
} else {
// stop the worker
workerThread.stop();
// no task to run, add to free list
this.#freeThreads.push(workerThread);
// remove from running list
this.#runningThreads = this.#runningThreads.filter(
(thread) => thread.getId() !== workerThread.getId()
);
// the work is done when the queue is back to its initial size
if (this.#freeThreads.length === this.#poolSize) {
this.onwork({type: 'work'});
this.onworkend({type: 'work-end'});
}
}
}
/**
* Handle an error message from a worker.
*
* @param {object} event The error event.
*/
handleWorkerError = (event) => {
// stop all threads
this.#stop();
// callback
this.onerror({error: event});
this.onworkend({type: 'work-end'});
};
// private ----------------------------------------------------------------
/**
* Stop the pool: stop all running threads.
*/
#stop() {
for (const thread of this.#runningThreads) {
thread.stop();
}
this.#runningThreads = [];
}
/**
* Handle a work start event.
* Default does nothing.
*
* @param {object} _event The work start event.
*/
onworkstart(_event) {}
/**
* Handle a work item event.
* Default does nothing.
*
* @param {object} _event The work item event fired
* when a work item ended successfully.
*/
onworkitem(_event) {}
/**
* Handle a work event.
* Default does nothing.
*
* @param {object} _event The work event fired
* when a work ended successfully.
*/
onwork(_event) {}
/**
* Handle a work end event.
* Default does nothing.
*
* @param {object} _event The work end event fired
* when a work has completed, successfully or not.
*/
onworkend(_event) {}
/**
* Handle an error event.
* Default does nothing.
*
* @param {object} _event The error event.
*/
onerror(_event) {}
/**
* Handle an abort event.
* Default does nothing.
*
* @param {object} _event The abort event.
*/
onabort(_event) {}
} // ThreadPool
/**
* Worker background task.
*
* Ref: {@link https://developer.mozilla.org/en-US/docs/Web/API/Worker}.
*
* @external Worker
*/
/**
* Worker thread.
*/
class WorkerThread {
/**
* @type {ThreadPool}
*/
parentPool;
/**
* @type {string}
*/
id;
/**
* @type {WorkerTask}
*/
runningTask;
/**
* @type {Worker}
*/
worker;
/**
* @param {ThreadPool} parentPool The parent pool.
*/
constructor(parentPool) {
this.parentPool = parentPool;
// thread ID
this.id = Math.random().toString(36).substring(2, 15);
}
/**
* Get the thread ID.
*
* @returns {string} The thread ID (alphanumeric).
*/
getId() {
return this.id;
}
/**
* Run a worker task.
*
* @param {WorkerTask} workerTask The task to run.
*/
run(workerTask) {
// store task
this.runningTask = workerTask;
// create a new web worker if not done yet
if (typeof this.worker === 'undefined') {
this.worker = this.runningTask.getWorker();
// set callbacks
this.worker.onmessage = this.onmessage;
this.worker.onerror = this.onerror;
}
// launch the worker
const {message, transfer} = this.runningTask.getStartMessage();
this.worker.postMessage(message, transfer);
}
/**
* Finish a task.
*/
stop() {
// stop the worker
if (typeof this.worker !== 'undefined') {
this.worker.terminate();
// force create at next run
this.worker = undefined;
this.runningTask = undefined;
}
}
/**
* Message event handler.
* For now assume we only get a single callback from a worker
* which also indicates the end of this worker.
*
* @param {object} event The message event.
*/
onmessage = (event) => {
// augment event
event.itemNumber = this.runningTask.info.itemNumber;
event.numberOfItems = this.runningTask.info.numberOfItems;
event.index = this.runningTask.info.index;
event.indexOrigin = this.runningTask.info.indexOrigin;
// send event
this.parentPool.onworkitem(event);
// tell the parent pool the task is done
this.parentPool.onTaskEnd(this);
};
/**
* Error event handler.
*
* @param {object} event The error event.
*/
onerror = (event) => {
// augment event
event.itemNumber = this.runningTask.info.itemNumber;
event.numberOfItems = this.runningTask.info.numberOfItems;
event.index = this.runningTask.info.index;
event.indexOrigin = this.runningTask.info.indexOrigin;
// pass to parent
this.parentPool.handleWorkerError(event);
// stop the worker and free the thread
this.stop();
};
} // class WorkerThread
/**
* Worker task.
*/
export class WorkerTask {
/**
* @param {object} message The data to pass to the worker.
* @param {object} info Information object about the input data.
*/
constructor(message, info) {
// worker start message
this.startMessage = message;
// information about the work data
this.info = info;
}
/**
* Get the message to post to the worker, called just before
* running the task. The transferred objects are moved to the worker
* (no copy) and are no longer usable by the caller.
* Default returns the start message with no transferred objects.
*
* @returns {{message: object, transfer: Transferable[]}} The message
* and the list of objects to transfer.
*/
getStartMessage() {
return {message: this.startMessage, transfer: []};
}
/**
* Get the task web worker.
* Defaults returns undefined.
*
* @returns {Worker|undefined} The task worker.
*/
getWorker() {
return undefined;
}
}