Primeiro commit do projeto Angular

This commit is contained in:
2026-03-14 20:41:55 +00:00
parent 9bebe1de72
commit 94f4f46395
22413 changed files with 3221690 additions and 0 deletions
+45
View File
@@ -0,0 +1,45 @@
import type { EventEmitter } from 'node:events';
interface AbortSignalEventTargetAddOptions {
once: boolean;
}
export interface AbortSignalEventTarget {
addEventListener: (
name: 'abort',
listener: () => void,
options?: AbortSignalEventTargetAddOptions
) => void;
removeEventListener: (name: 'abort', listener: () => void) => void;
aborted?: boolean;
reason?: unknown;
}
export interface AbortSignalEventEmitter {
off: (name: 'abort', listener: () => void) => void;
once: (name: 'abort', listener: () => void) => void;
}
export type AbortSignalAny = AbortSignalEventTarget | AbortSignalEventEmitter;
export class AbortError extends Error {
constructor (reason?: AbortSignalEventTarget['reason']) {
// TS does not recognizes the cause clause
// @ts-expect-error
super('The task has been aborted', { cause: reason });
}
get name () {
return 'AbortError';
}
}
export function onabort (abortSignal: AbortSignalAny, listener: () => void): () => void {
if ('addEventListener' in abortSignal) {
abortSignal.addEventListener('abort', listener, { once: true });
return () => abortSignal.removeEventListener('abort', listener);
} else {
abortSignal.once('abort', listener);
return () => (abortSignal as EventEmitter).removeListener('abort', listener);
}
}
+79
View File
@@ -0,0 +1,79 @@
import { fileURLToPath, URL } from 'node:url';
import { availableParallelism } from 'node:os';
import { kMovable, kTransferable, kValue } from './symbols';
// States wether the worker is ready to receive tasks
export const READY = '_WORKER_READY';
/**
* True if the object implements the Transferable interface
*
* @export
* @param {unknown} value
* @return {*} {boolean}
*/
export function isTransferable (value: unknown): boolean {
return (
value != null &&
typeof value === 'object' &&
kTransferable in value &&
kValue in value
);
}
/**
* True if object implements Transferable and has been returned
* by the Piscina.move() function
*
* TODO: narrow down the type of value
* @export
* @param {(unknown & PiscinaMovable)} value
* @return {*} {boolean}
*/
export function isMovable (value: any): boolean {
return isTransferable(value) && value[kMovable] === true;
}
export function markMovable (value: {}): void {
Object.defineProperty(value, kMovable, {
enumerable: false,
configurable: true,
writable: true,
value: true
});
}
// State of Piscina pool
export const commonState = {
isWorkerThread: false,
workerData: undefined
};
export function maybeFileURLToPath (filename : string) : string {
return filename.startsWith('file:')
? fileURLToPath(new URL(filename))
: filename;
}
export function getAvailableParallelism () : number {
return availableParallelism();
}
export function promiseResolvers <T = any> () :
{ promise: Promise<T>,
resolve: (res: T) => void,
reject: (err: Error) => void
} {
// @ts-expect-error - available from v24 onwards
if (Promise.withResolvers != null) return Promise.withResolvers();
let res: (res: T) => void;
let rej: (err: Error) => void
return {
promise: new Promise<T>((resolve, reject) => { res = resolve; rej = reject; } ),
resolve: res!,
reject: rej!
}
}
+9
View File
@@ -0,0 +1,9 @@
export const Errors = {
ThreadTermination: () => new Error('Terminating worker thread'),
FilenameNotProvided: () =>
new Error('filename must be provided to run() or in options object'),
TaskQueueAtLimit: () => new Error('Task queue is at limit'),
NoTaskQueueAvailable: () =>
new Error('No task queue available and all Workers are busy'),
CloseTimeout: () => new Error('Close operation timed out')
};
+104
View File
@@ -0,0 +1,104 @@
import { RecordableHistogram, createHistogram } from 'node:perf_hooks';
export type PiscinaHistogramSummary = {
average: number;
mean: number;
stddev: number;
min: number;
max: number;
p0_001: number;
p0_01: number;
p0_1: number;
p1: number;
p2_5: number;
p10: number;
p25: number;
p50: number;
p75: number;
p90: number;
p97_5: number;
p99: number;
p99_9: number;
p99_99: number;
p99_999: number;
};
export type PiscinaHistogram = {
runTime: PiscinaHistogramSummary;
waitTime: PiscinaHistogramSummary;
resetRunTime(): void;
resetWaitTime(): void;
};
export class PiscinaHistogramHandler {
#runTime: RecordableHistogram;
#waitTime: RecordableHistogram;
constructor() {
this.#runTime = createHistogram();
this.#waitTime = createHistogram();
}
get runTimeSummary(): PiscinaHistogramSummary {
return PiscinaHistogramHandler.createHistogramSummary(this.#runTime);
}
get waitTimeSummary(): PiscinaHistogramSummary {
return PiscinaHistogramHandler.createHistogramSummary(this.#waitTime);
}
get runTimeCount(): number {
return this.#runTime.count;
}
recordRunTime(value: number) {
this.#runTime.record(PiscinaHistogramHandler.toHistogramIntegerNano(value));
}
recordWaitTime(value: number) {
this.#waitTime.record(
PiscinaHistogramHandler.toHistogramIntegerNano(value)
);
}
resetWaitTime(): void {
this.#waitTime.reset();
}
resetRunTime(): void {
this.#runTime.reset();
}
static createHistogramSummary(
histogram: RecordableHistogram
): PiscinaHistogramSummary {
const { mean, stddev, min, max } = histogram;
return {
average: mean / 1000,
mean: mean / 1000,
stddev: stddev / 1000,
min: min / 1000,
max: max / 1000,
p0_001: histogram.percentile(0.001) / 1000,
p0_01: histogram.percentile(0.01) / 1000,
p0_1: histogram.percentile(0.1) / 1000,
p1: histogram.percentile(1) / 1000,
p2_5: histogram.percentile(2.5) / 1000,
p10: histogram.percentile(10) / 1000,
p25: histogram.percentile(25) / 1000,
p50: histogram.percentile(50) / 1000,
p75: histogram.percentile(75) / 1000,
p90: histogram.percentile(90) / 1000,
p97_5: histogram.percentile(97.5) / 1000,
p99: histogram.percentile(99) / 1000,
p99_9: histogram.percentile(99.9) / 1000,
p99_99: histogram.percentile(99.99) / 1000,
p99_999: histogram.percentile(99.999) / 1000,
};
}
static toHistogramIntegerNano(milliseconds: number): number {
return Math.max(1, Math.trunc(milliseconds * 1000));
}
}
+994
View File
@@ -0,0 +1,994 @@
import { Worker, MessageChannel, MessagePort } from 'node:worker_threads';
import { once, EventEmitterAsyncResource } from 'node:events';
import { resolve } from 'node:path';
import { inspect, types } from 'node:util';
import { performance } from 'node:perf_hooks';
import { setTimeout as sleep } from 'node:timers/promises';
import { version } from '../package.json';
import type {
ResponseMessage,
StartupMessage,
Transferable,
ResourceLimits,
EnvSpecifier,
} from './types';
import {
kQueueOptions,
kTransferable,
kValue,
kWorkerData
} from './symbols';
import {
TaskQueue,
isTaskQueue,
ArrayTaskQueue,
FixedQueue,
TaskInfo,
PiscinaTask,
TransferList,
TransferListItem
} from './task_queue';
import {
WorkerInfo,
AsynchronouslyCreatedResourcePool,
PiscinaLoadBalancer,
PiscinaWorker,
LeastBusyBalancer
} from './worker_pool';
import {
AbortSignalAny,
AbortSignalEventTarget,
AbortError,
} from './abort';
import {
PiscinaHistogram,
PiscinaHistogramHandler,
} from './histogram';
import { Errors } from './errors';
import {
READY,
commonState,
isTransferable,
markMovable,
getAvailableParallelism,
maybeFileURLToPath,
promiseResolvers
} from './common';
const cpuParallelism : number = getAvailableParallelism();
interface Options {
filename? : string | null,
name?: string,
minThreads? : number,
maxThreads? : number,
idleTimeout? : number,
maxQueue? : number | 'auto',
concurrentTasksPerWorker? : number,
atomics? : 'sync' | 'async' | 'disabled',
resourceLimits? : ResourceLimits,
argv? : string[],
execArgv? : string[],
env? : EnvSpecifier,
workerData? : any,
taskQueue? : TaskQueue,
niceIncrement? : number,
trackUnmanagedFds? : boolean,
closeTimeout?: number,
recordTiming?: boolean,
loadBalancer?: PiscinaLoadBalancer,
workerHistogram?: boolean,
}
interface FilledOptions extends Options {
filename : string | null,
name: string,
minThreads : number,
maxThreads : number,
idleTimeout : number,
maxQueue : number,
concurrentTasksPerWorker : number,
atomics: Options['atomics'],
taskQueue : TaskQueue,
niceIncrement : number,
closeTimeout : number,
recordTiming : boolean,
workerHistogram: boolean,
}
interface RunOptions {
transferList? : TransferList,
filename? : string | null,
signal? : AbortSignalAny | null,
name? : string | null
}
interface FilledRunOptions extends RunOptions {
transferList : TransferList | never,
filename : string | null,
signal : AbortSignalAny | null,
name : string | null
}
interface CloseOptions {
force?: boolean,
}
const kDefaultOptions : FilledOptions = {
filename: null,
name: 'default',
minThreads: Math.max(Math.floor(cpuParallelism / 2), 1),
maxThreads: cpuParallelism * 1.5,
idleTimeout: 0,
maxQueue: Infinity,
concurrentTasksPerWorker: 1,
atomics: 'sync',
taskQueue: new ArrayTaskQueue(),
niceIncrement: 0,
trackUnmanagedFds: true,
closeTimeout: 30000,
recordTiming: true,
workerHistogram: false
};
const kDefaultRunOptions : FilledRunOptions = {
transferList: undefined,
filename: null,
signal: null,
name: null
};
const kDefaultCloseOptions : Required<CloseOptions> = {
force: false
};
class DirectlyTransferable implements Transferable {
#value : object;
constructor (value : object) {
this.#value = value;
}
get [kTransferable] () : object { return this.#value; }
get [kValue] () : object { return this.#value; }
}
class ArrayBufferViewTransferable implements Transferable {
#view : ArrayBufferView;
constructor (view : ArrayBufferView) {
this.#view = view;
}
get [kTransferable] () : object { return this.#view.buffer; }
get [kValue] () : object { return this.#view; }
}
class ThreadPool {
publicInterface : Piscina;
workers : AsynchronouslyCreatedResourcePool<WorkerInfo>;
options : FilledOptions;
taskQueue : TaskQueue;
skipQueue : TaskInfo[] = [];
completed : number = 0;
histogram: PiscinaHistogramHandler | null = null;
_needsDrain : boolean;
start : number = performance.now();
inProcessPendingMessages : boolean = false;
startingUp : boolean = false;
closingUp : boolean = false;
workerFailsDuringBootstrap : boolean = false;
destroying : boolean = false;
maxCapacity: number;
balancer: PiscinaLoadBalancer;
constructor (publicInterface : Piscina, options : Options) {
this.publicInterface = publicInterface;
this.taskQueue = options.taskQueue ?? new FixedQueue();
const filename =
options.filename ? maybeFileURLToPath(options.filename) : null;
this.options = { ...kDefaultOptions, ...options, filename, maxQueue: 0 };
if (this.options.recordTiming) {
this.histogram = new PiscinaHistogramHandler();
}
// The >= and <= could be > and < but this way we get 100 % coverage 🙃
if (options.maxThreads !== undefined &&
this.options.minThreads >= options.maxThreads) {
this.options.minThreads = options.maxThreads;
}
if (options.minThreads !== undefined &&
this.options.maxThreads <= options.minThreads) {
this.options.maxThreads = options.minThreads;
}
if (options.maxQueue === 'auto') {
this.options.maxQueue = this.options.maxThreads ** 2;
} else {
this.options.maxQueue = options.maxQueue ?? kDefaultOptions.maxQueue;
}
this.balancer = this.options.loadBalancer ?? LeastBusyBalancer({ maximumUsage: this.options.concurrentTasksPerWorker });
this.workers = new AsynchronouslyCreatedResourcePool<WorkerInfo>(
this.options.concurrentTasksPerWorker);
this.workers.onTaskDone(this._onWorkerTaskDone.bind(this));
this.maxCapacity = this.options.maxThreads * this.options.concurrentTasksPerWorker;
this.startingUp = true;
this._ensureMinimumWorkers();
this.startingUp = false;
this._needsDrain = false;
}
_ensureMinimumWorkers () : void {
if (this.closingUp || this.destroying) {
return;
}
while (this.workers.size < this.options.minThreads) {
this._addNewWorker();
}
}
_addNewWorker () : void {
if (this.closingUp === true) return;
const { port1, port2 } = new MessageChannel();
const workerInfo = new WorkerInfo({
worker: {
filename: resolve(__dirname, 'worker.js'),
env: this.options.env,
argv: this.options.argv,
execArgv: this.options.execArgv,
resourceLimits: this.options.resourceLimits,
workerData: this.options.workerData,
trackUnmanagedFds: this.options.trackUnmanagedFds
},
port: port1,
enableHistogram: this.options.workerHistogram
}, onMessage.bind(this));
const message : StartupMessage = {
filename: this.options.filename,
name: this.options.name,
port: port2,
sharedBuffer: workerInfo.sharedBuffer,
atomics: this.options.atomics!,
niceIncrement: this.options.niceIncrement
};
workerInfo.onDestroy(() => {
this.publicInterface.emit('workerDestroy', workerInfo.interface);
});
workerInfo.onWorkerMessage(onWorkerMessage.bind(this));
workerInfo.onWorkerError(onWorkerError.bind(this));
workerInfo.onWorkerExit(onWorkerExit.bind(this));
workerInfo.onPortClose(() => { workerInfo.workerRef(); });
if (this.startingUp === true) {
// There is no point in waiting for the initial set of Workers to indicate
// that they are ready, we just mark them as such from the start.
workerInfo.markAsReady();
// We need to emit the event in the next microtask, so that the user can
// attach event listeners before the event is emitted.
queueMicrotask(() => {
this.publicInterface.emit('workerCreate', workerInfo.interface);
this._onWorkerReady(workerInfo);
});
} else {
workerInfo.onReady(() => {
this.publicInterface.emit('workerCreate', workerInfo.interface);
this._onWorkerReady(workerInfo);
});
}
workerInfo.init(message, [port2]).workerUnref();
this.workers.add(workerInfo);
function onMessage (this: ThreadPool, message : ResponseMessage) {
const { taskId, result } = message;
// In case of success: Call the callback that was passed to `runTask`,
// remove the `TaskInfo` associated with the Worker, which marks it as
// free again.
const taskInfo = workerInfo.popTask(taskId);
this.workers.taskDone(workerInfo);
if (taskInfo == null) { /* c8 ignore next */
const err = new Error(
`Unexpected message from Worker: ${inspect(message)}`);
this.publicInterface.emit('error', err);
} else {
taskInfo.done(message.error, result);
}
this._processPendingMessages();
}
function onWorkerReady () {
workerInfo.currentUsage() === 0 && workerInfo.unref();
workerInfo.isReady() === false && workerInfo.markAsReady();
}
function onEventMessage (this: ThreadPool, message: any) {
this.publicInterface.emit('message', message);
}
function onWorkerMessage (this: ThreadPool, message: any) {
message instanceof Object && READY in message ? onWorkerReady() : onEventMessage.call(this, message);
}
function onWorkerError (this: ThreadPool, err: Error) {
this._onError(workerInfo, err, false);
}
function onWorkerExit (this: ThreadPool, code: number) {
if (this.destroying === false) {
const err = new Error(`worker exited with code: ${code}`);
// Only error unfinished tasks on process exit, since there are legitimate
// reasons to exit workers and we want to handle that gracefully when possible.
this._onError(workerInfo, err, true);
}
}
}
_onError (workerInfo: WorkerInfo, err: Error, onlyErrorUnfinishedTasks: boolean) {
const taskInfos = [...workerInfo.taskInfos.values()];
workerInfo.taskInfos.clear();
// Remove the worker from the list and potentially start a new Worker to
// replace the current one.
this._removeWorker(workerInfo);
if (workerInfo.isReady() && !this.workerFailsDuringBootstrap) {
this._ensureMinimumWorkers();
} else {
// Do not start new workers over and over if they already fail during
// bootstrap, there's no point.
this.workerFailsDuringBootstrap = true;
}
if (taskInfos.length > 0) {
// If there are remaining unfinished tasks, call the callback that was
// passed to `postTask` with the error
for (const taskInfo of taskInfos) {
taskInfo.done(err, null);
}
} else if (!onlyErrorUnfinishedTasks) {
// If there are no unfinished tasks, instead emit an 'error' event
this.publicInterface.emit('error', err);
}
}
_processPendingMessages () {
if (this.inProcessPendingMessages || this.options.atomics === 'disabled') {
return;
}
this.inProcessPendingMessages = true;
try {
for (const workerInfo of this.workers) {
workerInfo.processPendingMessages();
}
} finally {
this.inProcessPendingMessages = false;
}
}
_removeWorker (workerInfo : WorkerInfo) : void {
workerInfo.destroy();
this.workers.delete(workerInfo);
}
_onWorkerReady (workerInfo : WorkerInfo) : void {
this._onWorkerAvailable(workerInfo);
}
_onWorkerTaskDone (workerInfo: WorkerInfo) : void {
this._onWorkerAvailable(workerInfo);
}
_onWorkerAvailable (workerInfo : WorkerInfo) : void {
let workers: PiscinaWorker[] | null = null;
while ((this.taskQueue.size > 0 || this.skipQueue.length > 0)) {
// The skipQueue will have tasks that we previously shifted off
// the task queue but had to skip over... we have to make sure
// we drain that before we drain the taskQueue.
const taskInfo = this.skipQueue.shift() ||
this.taskQueue.shift() as TaskInfo;
if (workers == null) {
workers = [...this.workers].map(workerInfo => workerInfo.interface);
}
const distributed = this._distributeTask(taskInfo, workers);
if (distributed) {
// If task was distributed, we should continue to distribute more tasks
continue;
} else if (this.workers.size < this.options.maxThreads) {
// We spawn if possible
// TODO: scheduler will intercept this.
this._addNewWorker();
continue;
} else {
// If balancer states that pool is busy, we should stop trying to distribute tasks
break;
}
}
//If Infinity was sent as a parameter, we skip setting the Timeout that clears the worker
if (this.options.idleTimeout === Infinity) {
return;
}
// If more workers than minThreads, we can remove idle workers
if (workerInfo.currentUsage() === 0 &&
this.workers.size > this.options.minThreads) {
workerInfo.setIdleTimeout(() => {
// Exit early - we can't safely remove the worker as there is workload in the middle.
// Once task is exited, timeout will be set once more for tearing up idle worker
if (workerInfo.currentUsage() !== 0) {
return;
}
if (this.workers.size > this.options.minThreads) {
this._removeWorker(workerInfo);
}
}, this.options.idleTimeout);
}
}
_distributeTask (task: TaskInfo, workers: PiscinaWorker[]): boolean {
// We need to verify if the task is aborted already or not
// otherwise we might be distributing aborted tasks to workers
if (task.aborted) return true;
const candidate = this.balancer(task.interface, workers);
// Seeking for a real worker instead of customized one
if (candidate != null && candidate[kWorkerData] != null) {
const now = performance.now();
this.histogram?.recordWaitTime(now - task.created)
task.started = now;
candidate[kWorkerData].postTask(task);
queueMicrotask(() => this._maybeDrain());
// If candidate, let's try to distribute more tasks
return true;
}
if (task.abortSignal != null) {
this.skipQueue.push(task);
} else {
this.taskQueue.push(task);
}
return false;
}
runTask (
task : any,
options : RunOptions) : Promise<any> {
let {
filename,
name
} = options;
const {
transferList = []
} = options;
filename = filename ?? this.options.filename;
name = name ?? this.options.name;
if (typeof filename !== 'string') {
return Promise.reject(Errors.FilenameNotProvided());
}
filename = maybeFileURLToPath(filename);
let signal: AbortSignalAny | null;
if (this.closingUp || this.destroying) {
const closingUpAbortController = new AbortController();
closingUpAbortController.abort('queue is being terminated');
signal = closingUpAbortController.signal;
} else {
signal = options.signal ?? null;
}
const { promise: ret, resolve, reject } = promiseResolvers();
const taskInfo = new TaskInfo({
task,
transferList,
filename,
name,
abortSignal: signal,
triggerAsyncId: this.publicInterface.asyncResource.asyncId()
},
(err : Error | null, result : any) => {
this.completed++;
if (taskInfo.started) {
this.histogram?.recordRunTime(performance.now() - taskInfo.started);
}
if (err !== null) {
reject(err);
} else {
resolve(result);
}
queueMicrotask(this._maybeDrain.bind(this))
});
if (signal != null) {
// If the AbortSignal has an aborted property and it's truthy,
// reject immediately.
if ((signal as AbortSignalEventTarget).aborted) {
reject!(new AbortError((signal as AbortSignalEventTarget).reason));
return ret;
}
taskInfo.onAbort(() => {
// Call reject() first to make sure we always reject with the AbortError
// if the task is aborted, not with an Error from the possible
// thread termination below.
reject(new AbortError((signal as AbortSignalEventTarget).reason));
if (taskInfo.workerInfo != null) {
// Already running: We cancel the Worker this is running on.
this._removeWorker(taskInfo.workerInfo);
this._ensureMinimumWorkers();
} else {
// Not yet running: Remove it from the queue.
// Call should be idempotent
this.taskQueue.remove(taskInfo);
}
});
taskInfo.setAbortListener(signal);
}
if (this.taskQueue.size > 0) {
const totalCapacity = this.options.maxQueue + this.pendingCapacity();
if (this.taskQueue.size >= totalCapacity) {
if (this.options.maxQueue === 0) {
reject!(Errors.NoTaskQueueAvailable());
} else {
reject!(Errors.TaskQueueAtLimit());
}
} else {
this.taskQueue.push(taskInfo);
}
queueMicrotask(this._maybeDrain.bind(this))
return ret;
}
const workers = [...this.workers.readyItems].map(workerInfo => workerInfo.interface);
const distributed = this._distributeTask(taskInfo, workers);
if (!distributed) {
// We spawn if possible
// TODO: scheduler will intercept this.
if (this.workers.size < this.options.maxThreads) {
this._addNewWorker();
}
// We reject if no task queue set and no more pending capacity.
if (this.options.maxQueue <= 0 && this.pendingCapacity() === 0) {
reject!(Errors.NoTaskQueueAvailable());
}
};
queueMicrotask(this._maybeDrain.bind(this))
return ret;
}
pendingCapacity () : number {
return this.workers.pendingItems.size *
this.options.concurrentTasksPerWorker;
}
_maybeDrain () {
/**
* Our goal is to make it possible for user space to use the pool
* in a way where always waiting === 0,
* since we want to avoid creating tasks that can't execute
* immediately in order to provide back pressure to the task source.
*/
const { maxCapacity } = this;
const currentUsage = this.workers.getCurrentUsage();
if (maxCapacity === currentUsage) {
this._needsDrain = true;
queueMicrotask(() => this.publicInterface.emit('needsDrain'));
} else if (maxCapacity > currentUsage && this._needsDrain) {
this._needsDrain = false;
queueMicrotask(() => this.publicInterface.emit('drain'));
}
}
async destroy () {
this.destroying = true;
while (this.skipQueue.length > 0) {
const taskInfo : TaskInfo = this.skipQueue.shift() as TaskInfo;
taskInfo.done(new Error('Terminating worker thread'));
}
while (this.taskQueue.size > 0) {
const taskInfo : TaskInfo = this.taskQueue.shift() as TaskInfo;
taskInfo.done(new Error('Terminating worker thread'));
}
const exitEvents : Promise<any[]>[] = [];
while (this.workers.size > 0) {
const [workerInfo] = this.workers;
exitEvents.push(once(workerInfo.worker, 'exit'));
this._removeWorker(workerInfo);
}
await Promise.allSettled(exitEvents);
this.destroying = false;
}
async close (options : Required<CloseOptions>) {
this.closingUp = true;
if (options.force) {
const skipQueueLength = this.skipQueue.length;
for (let i = 0; i < skipQueueLength; i++) {
const taskInfo : TaskInfo = this.skipQueue.shift() as TaskInfo;
if (taskInfo.workerInfo === null) {
taskInfo.done(new AbortError('pool is closed'));
} else {
this.skipQueue.push(taskInfo);
}
}
const taskQueueLength = this.taskQueue.size;
for (let i = 0; i < taskQueueLength; i++) {
const taskInfo : TaskInfo = this.taskQueue.shift() as TaskInfo;
if (taskInfo.workerInfo === null) {
taskInfo.done(new AbortError('pool is closed'));
} else {
this.taskQueue.push(taskInfo);
}
}
}
const onPoolFlushed = () => new Promise<void>((resolve) => {
const numberOfWorkers = this.workers.size;
if (numberOfWorkers === 0) {
resolve();
return;
}
let numberOfWorkersDone = 0;
const checkIfWorkerIsDone = (workerInfo: WorkerInfo) => {
if (workerInfo.taskInfos.size === 0) {
numberOfWorkersDone++;
}
if (numberOfWorkers === numberOfWorkersDone) {
resolve();
}
};
this.workers.onTaskDone(checkIfWorkerIsDone);
for (const workerInfo of this.workers) {
checkIfWorkerIsDone(workerInfo);
this.workers.onTaskDone(checkIfWorkerIsDone);
}
});
const throwOnTimeOut = async (timeout: number) => {
await sleep(timeout, null, { ref: false });
throw Errors.CloseTimeout();
};
try {
await Promise.race([
onPoolFlushed(),
throwOnTimeOut(this.options.closeTimeout)
]);
} catch (error) {
this.publicInterface.emit('error', error);
} finally {
await this.destroy();
this.publicInterface.emit('close');
this.closingUp = false;
}
}
}
export default class Piscina<T = any, R = any> extends EventEmitterAsyncResource {
#pool : ThreadPool;
#histogram: PiscinaHistogram | null = null;
constructor (options : Options = {}) {
super({ ...options, name: 'Piscina' });
if (typeof options.filename !== 'string' && options.filename != null) {
throw new TypeError('options.filename must be a string or null');
}
if (typeof options.name !== 'string' && options.name != null) {
throw new TypeError('options.name must be a string or null');
}
if (options.minThreads !== undefined &&
(typeof options.minThreads !== 'number' || options.minThreads < 0)) {
throw new TypeError('options.minThreads must be a non-negative integer');
}
if (options.maxThreads !== undefined &&
(typeof options.maxThreads !== 'number' || options.maxThreads < 1)) {
throw new TypeError('options.maxThreads must be a positive integer');
}
if (options.minThreads !== undefined && options.maxThreads !== undefined &&
options.minThreads > options.maxThreads) {
throw new RangeError('options.minThreads and options.maxThreads must not conflict');
}
if (options.idleTimeout !== undefined &&
(typeof options.idleTimeout !== 'number' || options.idleTimeout < 0)) {
throw new TypeError('options.idleTimeout must be a non-negative integer');
}
if (options.maxQueue !== undefined &&
options.maxQueue !== 'auto' &&
(typeof options.maxQueue !== 'number' || options.maxQueue < 0)) {
throw new TypeError('options.maxQueue must be a non-negative integer');
}
if (options.concurrentTasksPerWorker !== undefined &&
(typeof options.concurrentTasksPerWorker !== 'number' ||
options.concurrentTasksPerWorker < 1)) {
throw new TypeError(
'options.concurrentTasksPerWorker must be a positive integer');
}
if (options.atomics != null && (typeof options.atomics !== 'string' ||
!['sync', 'async', 'disabled'].includes(options.atomics))) {
throw new TypeError('options.atomics should be a value of sync, sync or disabled.');
}
if (options.resourceLimits !== undefined &&
(typeof options.resourceLimits !== 'object' ||
options.resourceLimits === null)) {
throw new TypeError('options.resourceLimits must be an object');
}
if (options.taskQueue !== undefined && !isTaskQueue(options.taskQueue)) {
throw new TypeError('options.taskQueue must be a TaskQueue object');
}
if (options.niceIncrement !== undefined &&
(typeof options.niceIncrement !== 'number' || (options.niceIncrement < 0 && process.platform !== 'win32'))) {
throw new TypeError('options.niceIncrement must be a non-negative integer on Unix systems');
}
if (options.trackUnmanagedFds !== undefined &&
typeof options.trackUnmanagedFds !== 'boolean') {
throw new TypeError('options.trackUnmanagedFds must be a boolean value');
}
if (options.closeTimeout !== undefined && (typeof options.closeTimeout !== 'number' || options.closeTimeout < 0)) {
throw new TypeError('options.closeTimeout must be a non-negative integer');
}
if (options.loadBalancer !== undefined && (typeof options.loadBalancer !== 'function' || options.loadBalancer.length < 1)) {
throw new TypeError('options.loadBalancer must be a function with at least two args');
}
if (options.workerHistogram !== undefined && (typeof options.workerHistogram !== 'boolean')) {
throw new TypeError('options.workerHistogram must be a boolean');
}
this.#pool = new ThreadPool(this, options);
}
run (task : T, options : RunOptions = kDefaultRunOptions): Promise<R> {
if (options === null || typeof options !== 'object') {
return Promise.reject(
new TypeError('options must be an object'));
}
const {
transferList,
filename,
name,
signal
} = options;
if (transferList !== undefined && !Array.isArray(transferList)) {
return Promise.reject(
new TypeError('transferList argument must be an Array'));
}
if (filename != null && typeof filename !== 'string') {
return Promise.reject(
new TypeError('filename argument must be a string'));
}
if (name != null && typeof name !== 'string') {
return Promise.reject(new TypeError('name argument must be a string'));
}
if (signal != null && typeof signal !== 'object') {
return Promise.reject(
new TypeError('signal argument must be an object'));
}
return this.#pool.runTask(task, { transferList, filename, name, signal });
}
async close (options : CloseOptions = kDefaultCloseOptions) {
if (options === null || typeof options !== 'object') {
throw TypeError('options must be an object');
}
let { force } = options;
if (force !== undefined && typeof force !== 'boolean') {
return Promise.reject(
new TypeError('force argument must be a boolean'));
}
force ??= kDefaultCloseOptions.force;
return this.#pool.close({
force
});
}
destroy () {
return this.#pool.destroy();
}
[Symbol.dispose]() {
this.close();
}
[Symbol.asyncDispose]() {
return this.close();
}
get maxThreads (): number {
return this.#pool.options.maxThreads;
}
get minThreads (): number {
return this.#pool.options.minThreads;
}
get options () : FilledOptions {
return this.#pool.options;
}
get threads () : Worker[] {
const ret : Worker[] = [];
for (const workerInfo of this.#pool.workers) { ret.push(workerInfo.worker); }
return ret;
}
get queueSize () : number {
const pool = this.#pool;
return Math.max(pool.taskQueue.size - pool.pendingCapacity(), 0);
}
get completed () : number {
return this.#pool.completed;
}
get histogram () : PiscinaHistogram {
if (this.#histogram == null) {
const piscinahistogram = {
// @ts-expect-error
get runTime() { return this.histogram?.runTimeSummary! },
// @ts-expect-error
get waitTime() { return this.histogram?.waitTimeSummary! },
resetRunTime() {
// @ts-expect-error
this.histogram?.resetRunTime()
},
resetWaitTime() {
// @ts-expect-error
this.histogram?.resetWaitTime()
},
}
Object.defineProperty(piscinahistogram, 'histogram', {
value: this.#pool.histogram,
writable: false,
enumerable: false,
configurable: false,
})
this.#histogram = piscinahistogram;
};
return this.#histogram;
}
get utilization () : number {
if (this.#pool.histogram == null) {
return 0;
}
// count is available as of Node.js v16.14.0 but not present in the types
const count = this.#pool.histogram.runTimeCount;
if (count === 0) {
return 0;
}
// The capacity is the max compute time capacity of the
// pool to this point in time as determined by the length
// of time the pool has been running multiplied by the
// maximum number of threads.
const capacity = this.duration * this.#pool.options.maxThreads;
const totalMeanRuntime = (this.#pool.histogram.runTimeSummary.mean / 1000) * count;
// We calculate the appoximate pool utilization by multiplying
// the mean run time of all tasks by the number of runtime
// samples taken and dividing that by the capacity. The
// theory here is that capacity represents the absolute upper
// limit of compute time this pool could ever attain (but
// never will for a variety of reasons. Multiplying the
// mean run time by the number of tasks sampled yields an
// approximation of the realized compute time. The utilization
// then becomes a point-in-time measure of how active the
// pool is.
return totalMeanRuntime / capacity;
}
get duration () : number {
return performance.now() - this.#pool.start;
}
get needsDrain () : boolean {
return this.#pool._needsDrain;
}
static get isWorkerThread () : boolean {
return commonState.isWorkerThread;
}
static get workerData () : any {
return commonState.workerData;
}
static get version () : string {
return version;
}
static get Piscina () {
return Piscina;
}
static get FixedQueue () {
return FixedQueue;
}
static get ArrayTaskQueue () {
return ArrayTaskQueue;
}
static move (val : Transferable | TransferListItem | ArrayBufferView | ArrayBuffer | MessagePort) {
if (val != null && typeof val === 'object' && typeof val !== 'function') {
if (!isTransferable(val)) {
if ((types as any).isArrayBufferView(val)) {
val = new ArrayBufferViewTransferable(val as ArrayBufferView);
} else {
val = new DirectlyTransferable(val);
}
}
markMovable(val);
}
return val;
}
static get transferableSymbol () { return kTransferable; }
static get valueSymbol () { return kValue; }
static get queueOptionsSymbol () { return kQueueOptions; }
}
export const move = Piscina.move;
export const isWorkerThread = Piscina.isWorkerThread;
export const workerData = Piscina.workerData;
export {
Piscina,
PiscinaTask,
TaskQueue,
kTransferable as transferableSymbol,
kValue as valueSymbol,
kQueueOptions as queueOptionsSymbol,
version,
FixedQueue,
ArrayTaskQueue,
};
+4
View File
@@ -0,0 +1,4 @@
import Piscina from './index';
// Used as the require() entry point to maintain existing behavior
export = Piscina;
+10
View File
@@ -0,0 +1,10 @@
// Internal symbol used to mark Transferable objects returned
// by the Piscina.move() function
export const kMovable = Symbol('Piscina.kMovable');
export const kWorkerData = Symbol('Piscina.kWorkerData');
export const kTransferable = Symbol.for('Piscina.transferable');
export const kValue = Symbol.for('Piscina.valueOf');
export const kQueueOptions = Symbol.for('Piscina.queueOptions');
export const kRequestCountField = 0;
export const kResponseCountField = 1;
export const kFieldCount = 2;
+25
View File
@@ -0,0 +1,25 @@
import assert from 'node:assert';
import type { TaskQueue, Task } from '.';
export class ArrayTaskQueue implements TaskQueue {
tasks: Task[] = []
get size () {
return this.tasks.length;
}
shift (): Task | null {
return this.tasks.shift() ?? null;
}
push (task: Task): void {
this.tasks.push(task);
}
remove (task: Task): void {
const index = this.tasks.indexOf(task);
assert.notStrictEqual(index, -1);
this.tasks.splice(index, 1);
}
}
+21
View File
@@ -0,0 +1,21 @@
import type { kQueueOptions } from '../symbols';
export interface TaskQueue {
readonly size: number;
shift(): Task | null;
remove(task: Task): void;
push(task: Task): void;
}
// Public Interface
export interface PiscinaTask extends Task {
taskId: number;
filename: string;
name: string;
created: number;
isAbortable: boolean;
}
export interface Task {
readonly [kQueueOptions]: object | null
};
+177
View File
@@ -0,0 +1,177 @@
/*
* Modified Fixed Queue Implementation based on the one from Node.js Project
* License: MIT License
* Source: https://github.com/nodejs/node/blob/de7b37880f5a541d5f874c1c2362a65a4be76cd0/lib/internal/fixed_queue.js
*/
import assert from 'node:assert';
import type { Task } from './common';
import { TaskQueue } from '.';
// Currently optimal queue size, tested on V8 6.0 - 6.6. Must be power of two.
const kSize = 2048;
const kMask = kSize - 1;
// The FixedQueue is implemented as a singly-linked list of fixed-size
// circular buffers. It looks something like this:
//
// head tail
// | |
// v v
// +-----------+ <-----\ +-----------+ <------\ +-----------+
// | [null] | \----- | next | \------- | next |
// +-----------+ +-----------+ +-----------+
// | item | <-- bottom | item | <-- bottom | [empty] |
// | item | | item | | [empty] |
// | item | | item | | [empty] |
// | item | | item | | [empty] |
// | item | | item | bottom --> | item |
// | item | | item | | item |
// | ... | | ... | | ... |
// | item | | item | | item |
// | item | | item | | item |
// | [empty] | <-- top | item | | item |
// | [empty] | | item | | item |
// | [empty] | | [empty] | <-- top top --> | [empty] |
// +-----------+ +-----------+ +-----------+
//
// Or, if there is only one circular buffer, it looks something
// like either of these:
//
// head tail head tail
// | | | |
// v v v v
// +-----------+ +-----------+
// | [null] | | [null] |
// +-----------+ +-----------+
// | [empty] | | item |
// | [empty] | | item |
// | item | <-- bottom top --> | [empty] |
// | item | | [empty] |
// | [empty] | <-- top bottom --> | item |
// | [empty] | | item |
// +-----------+ +-----------+
//
// Adding a value means moving `top` forward by one, removing means
// moving `bottom` forward by one. After reaching the end, the queue
// wraps around.
//
// When `top === bottom` the current queue is empty and when
// `top + 1 === bottom` it's full. This wastes a single space of storage
// but allows much quicker checks.
class FixedCircularBuffer {
bottom: number = 0
top: number = 0
list: Array<Task | undefined> = new Array(kSize)
next: FixedCircularBuffer | null = null
isEmpty () {
return this.top === this.bottom;
}
isFull () {
return ((this.top + 1) & kMask) === this.bottom;
}
push (data:Task) {
this.list[this.top] = data;
this.top = (this.top + 1) & kMask;
}
shift () {
const nextItem = this.list[this.bottom];
if (nextItem === undefined) { return null; }
this.list[this.bottom] = undefined;
this.bottom = (this.bottom + 1) & kMask;
return nextItem;
}
remove (task: Task) {
const indexToRemove = this.list.indexOf(task);
assert.notStrictEqual(indexToRemove, -1);
let curr = indexToRemove;
while (true) {
const next = (curr + 1) & kMask;
this.list[curr] = this.list[next];
if (this.list[curr] === undefined) {
break;
}
if (next === indexToRemove) {
this.list[curr] = undefined;
break;
}
curr = next;
}
this.top = (this.top - 1) & kMask;
}
}
export class FixedQueue implements TaskQueue {
head: FixedCircularBuffer
tail: FixedCircularBuffer
#size: number = 0
constructor () {
this.head = this.tail = new FixedCircularBuffer();
}
isEmpty () {
return this.head.isEmpty();
}
push (data:Task) {
if (this.head.isFull()) {
// Head is full: Creates a new queue, sets the old queue's `.next` to it,
// and sets it as the new main queue.
this.head = this.head.next = new FixedCircularBuffer();
}
this.head.push(data);
this.#size++;
}
shift (): Task | null {
const tail = this.tail;
const next = tail.shift();
if (next !== null) this.#size--;
if (tail.isEmpty() && tail.next !== null) {
// If there is another queue, it forms the new tail.
this.tail = tail.next;
tail.next = null;
}
return next;
}
remove (task: Task) {
let prev: FixedCircularBuffer | null = null;
let buffer = this.tail;
while (true) {
if (buffer.list.includes(task)) {
buffer.remove(task);
this.#size--;
break;
}
if (buffer.next === null) break;
prev = buffer;
buffer = buffer.next;
}
if (buffer.isEmpty()) {
// removing tail
if (prev === null) {
// if tail is not the last buffer
if (buffer.next !== null) this.tail = buffer.next;
} else {
// removing head
if (buffer.next === null) {
this.head = prev;
} else {
// removing buffer from middle
prev.next = buffer.next;
}
}
}
}
get size () {
return this.#size;
}
};
+153
View File
@@ -0,0 +1,153 @@
import type { MessagePort } from 'node:worker_threads';
import { performance } from 'node:perf_hooks';
import { AsyncResource } from 'node:async_hooks';
import type { WorkerInfo } from '../worker_pool';
import type { Task, TaskQueue, PiscinaTask } from './common';
import { onabort, type AbortSignalAny } from '../abort';
import { isMovable } from '../common';
import { kTransferable, kValue, kQueueOptions } from '../symbols';
export { ArrayTaskQueue } from './array_queue';
export { FixedQueue } from './fixed_queue';
export type TaskCallback = (err: Error, result: any) => void
// Grab the type of `transferList` off `MessagePort`. At the time of writing,
// only ArrayBuffer and MessagePort are valid, but let's avoid having to update
// our types here every time Node.js adds support for more objects.
export type TransferList = MessagePort extends {
postMessage: (value: any, transferList: infer T) => any
}
? T
: never
export type TransferListItem = TransferList extends Array<infer T> ? T : never
type TaskInfoParameters = {
task : any;
transferList : TransferList;
filename : string;
name : string;
abortSignal : AbortSignalAny | null;
triggerAsyncId : number;
}
/**
* Verifies if a given TaskQueue is valid
*
* @export
* @param {*} value
* @return {*} {boolean}
*/
export function isTaskQueue (value: TaskQueue): boolean {
return (
typeof value === 'object' &&
value !== null &&
'size' in value &&
typeof value.shift === 'function' &&
typeof value.remove === 'function' &&
typeof value.push === 'function'
);
}
let taskIdCounter = 0;
// Extend AsyncResource so that async relations between posting a task and
// receiving its result are visible to diagnostic tools.
export class TaskInfo extends AsyncResource implements Task {
callback : TaskCallback;
task : any;
transferList : TransferList;
filename : string;
name : string;
taskId : number;
abortSignal : AbortSignalAny | null;
workerInfo : WorkerInfo | null = null;
created : number;
started : number;
aborted = false;
_abortListener: (() => void) = () => { this.aborted = true; };
_abortCleaner: (() => void) | null = null;
constructor ({
task,
transferList,
filename,
name,
abortSignal,
triggerAsyncId,
}: TaskInfoParameters,
callback: TaskCallback) {
super('Piscina.Task', { requireManualDestroy: true, triggerAsyncId });
this.callback = callback;
this.task = task;
this.transferList = transferList;
// If the task is a Transferable returned by
// Piscina.move(), then add it to the transferList
// automatically
if (isMovable(task)) {
// This condition should never be hit but typescript
// complains if we dont do the check.
/* c8 ignore next */
if (this.transferList == null) {
this.transferList = [];
}
this.transferList = this.transferList.concat(task[kTransferable]);
this.task = task[kValue];
}
this.filename = filename;
this.name = name;
// TODO: This should not be global
this.taskId = taskIdCounter++;
this.abortSignal = abortSignal;
this.created = performance.now();
this.started = 0;
}
onAbort (value: (() => void)) {
this._abortListener = () => {
this.aborted = true;
value();
};
}
setAbortListener(signal: AbortSignalAny) : void {
this._abortCleaner = onabort(signal, this._abortListener);
}
releaseTask () : any {
const ret = this.task;
this.task = null;
return ret;
}
// TODO: implement - helpful for streaming chunks of data from worker to parent
onResponse(_result: any) {}
done (err : Error | null, result? : any) : void {
this.runInAsyncScope(this.callback, null, err, result);
this.emitDestroy(); // `TaskInfo`s are used only once.
// If an abort signal was used, remove the listener from it when
// done to make sure we do not accidentally leak.
this._abortCleaner?.();
}
get [kQueueOptions] () : {} | null {
return this.task?.[kQueueOptions] ?? null;
}
get interface (): PiscinaTask {
return {
taskId: this.taskId,
filename: this.filename,
name: this.name,
created: this.created,
isAbortable: this.abortSignal !== null,
[kQueueOptions]: this[kQueueOptions]
};
}
}
export { Task, TaskQueue, PiscinaTask };
+52
View File
@@ -0,0 +1,52 @@
import type { MessagePort, Worker } from 'node:worker_threads';
import type { READY } from './common';
import type { kTransferable, kValue } from './symbols';
export interface StartupMessage {
filename: string | null
name: string
port: MessagePort
sharedBuffer: Int32Array
atomics: 'async' | 'sync' | 'disabled'
niceIncrement: number
}
export interface RequestMessage {
taskId: number
task: any
filename: string
name: string
histogramEnabled: number
}
export interface ReadyMessage {
[READY]: true
}
export interface ResponseMessage {
taskId: number
result: any
error: Error | null
time: number | null
}
export const commonState = {
isWorkerThread: false,
workerData: undefined
};
export interface Transferable {
readonly [kTransferable]: object;
readonly [kValue]: object;
}
export type ResourceLimits = Worker extends {
resourceLimits?: infer T;
}
? T
: {};
export type EnvSpecifier = typeof Worker extends {
new (filename: never, options?: { env: infer T }): Worker;
}
? T
: never;
+239
View File
@@ -0,0 +1,239 @@
import { parentPort, MessagePort, receiveMessageOnPort, workerData } from 'node:worker_threads';
import { pathToFileURL } from 'node:url';
import { performance } from 'node:perf_hooks';
import type {
ReadyMessage,
RequestMessage,
ResponseMessage,
StartupMessage
} from './types';
import {
kResponseCountField,
kRequestCountField,
kTransferable,
kValue
} from './symbols';
import {
READY,
commonState,
isMovable
} from './common';
commonState.isWorkerThread = true;
commonState.workerData = workerData;
/* c8 ignore next*/
function noop (): void {}
const handlerCache : Map<string, Function> = new Map();
let useAtomics : boolean = process.env.PISCINA_DISABLE_ATOMICS !== '1';
let useAsyncAtomics : boolean = process.env.PISCINA_ENABLE_ASYNC_ATOMICS === '1';
// Get `import(x)` as a function that isn't transpiled to `require(x)` by
// TypeScript for dual ESM/CJS support.
// Load this lazily, so that there is no warning about the ESM loader being
// experimental (on Node v12.x) until we actually try to use it.
let importESMCached : (specifier : string) => Promise<any> | undefined;
function getImportESM () {
if (importESMCached === undefined) {
// eslint-disable-next-line no-new-func
importESMCached = new Function('specifier', 'return import(specifier)') as typeof importESMCached;
}
return importESMCached;
}
// Look up the handler function that we call when a task is posted.
// This is either going to be "the" export from a file, or the default export.
async function getHandler (filename : string, name : string) : Promise<Function | null> {
let handler = handlerCache.get(`${filename}/${name}`);
if (handler != null) {
return handler;
}
try {
// With our current set of TypeScript options, this is transpiled to
// `require(filename)`.
handler = await import(filename);
if (typeof handler !== 'function') {
handler = await ((handler as any)[name]);
}
} catch {}
if (typeof handler !== 'function') {
handler = await getImportESM()(pathToFileURL(filename).href);
if (typeof handler !== 'function') {
handler = await ((handler as any)[name]);
}
}
if (typeof handler !== 'function') {
return null;
}
// Limit the handler cache size. This should not usually be an issue and is
// only provided for pathological cases.
/* c8 ignore next */
if (handlerCache.size > 1000) {
const [[key]] = handlerCache;
handlerCache.delete(key);
}
handlerCache.set(`${filename}/${name}`, handler);
return handler;
}
// We should only receive this message once, when the Worker starts. It gives
// us the MessagePort used for receiving tasks, a SharedArrayBuffer for fast
// communication using Atomics, and the name of the default filename for tasks
// (so we can pre-load and cache the handler).
parentPort!.on('message', async (message: StartupMessage) => {
const { port, sharedBuffer, filename, name, niceIncrement } = message;
if (niceIncrement !== 0) {
(await import('@napi-rs/nice').catch(noop))?.nice(niceIncrement);
}
try {
if (filename != null) {
await getHandler(filename, name);
}
const readyMessage : ReadyMessage = { [READY]: true };
useAtomics = useAtomics !== false && message.atomics !== 'disabled';
useAsyncAtomics = useAtomics !== false && (useAsyncAtomics || message.atomics === 'async');
parentPort!.postMessage(readyMessage);
port.on('message', onMessage.bind(null, port, sharedBuffer));
if (useAtomics) {
const res = atomicsWaitLoop(port, sharedBuffer);
if (res?.then != null) await res;
}
} catch (error) {
throwInNextTick(error as Error);
}
});
let currentTasks : number = 0;
let lastSeenRequestCount : number = 0;
function atomicsWaitLoop (port : MessagePort, sharedBuffer : Int32Array) {
// This function is entered either after receiving the startup message, or
// when we are done with a task. In those situations, the *only* thing we
// expect to happen next is a 'message' on `port`.
// That call would come with the overhead of a C++ → JS boundary crossing,
// including async tracking. So, instead, if there is no task currently
// running, we wait for a signal from the parent thread using Atomics.wait(),
// and read the message from the port instead of generating an event,
// in order to avoid that overhead.
// The one catch is that this stops asynchronous operations that are still
// running from proceeding. Generally, tasks should not spawn asynchronous
// operations without waiting for them to finish, though.
if (useAsyncAtomics === true) {
// @ts-expect-error - for some reason not supported by TS
const { async, value } = Atomics.waitAsync(sharedBuffer, kRequestCountField, lastSeenRequestCount);
// We do not check for result
/* c8 ignore start */
return async === true && value.then(() => {
lastSeenRequestCount = Atomics.load(sharedBuffer, kRequestCountField);
// We have to read messages *after* updating lastSeenRequestCount in order
// to avoid race conditions.
let entry;
while ((entry = receiveMessageOnPort(port)) !== undefined) {
onMessage(port, sharedBuffer, entry.message);
}
});
/* c8 ignore stop */
}
while (currentTasks === 0) {
// Check whether there are new messages by testing whether the current
// number of requests posted by the parent thread matches the number of
// requests received.
// We do not check for result
Atomics.wait(sharedBuffer, kRequestCountField, lastSeenRequestCount);
lastSeenRequestCount = Atomics.load(sharedBuffer, kRequestCountField);
// We have to read messages *after* updating lastSeenRequestCount in order
// to avoid race conditions.
let entry;
while ((entry = receiveMessageOnPort(port)) !== undefined) {
onMessage(port, sharedBuffer, entry.message);
}
}
}
async function onMessage (
port : MessagePort,
sharedBuffer : Int32Array,
message : RequestMessage) {
currentTasks++;
const { taskId, task, filename, name } = message;
let response : ResponseMessage;
let transferList : any[] = [];
const start = message.histogramEnabled === 1 ? performance.now() : null;
try {
const handler = await getHandler(filename, name);
if (handler === null) {
throw new Error(`No handler function exported from ${filename}`);
}
let result = await handler(task);
if (isMovable(result)) {
transferList = transferList.concat(result[kTransferable]);
result = result[kValue];
}
response = {
taskId,
result,
error: null,
time: start == null ? null : Math.round(performance.now() - start)
};
if (useAtomics && !useAsyncAtomics) {
// If the task used e.g. console.log(), wait for the stream to drain
// before potentially entering the `Atomics.wait()` loop, and before
// returning the result so that messages will always be printed even
// if the process would otherwise be ready to exit.
if (process.stdout.writableLength > 0) {
await new Promise((resolve) => process.stdout.write('', resolve));
}
if (process.stderr.writableLength > 0) {
await new Promise((resolve) => process.stderr.write('', resolve));
}
}
} catch (error) {
response = {
taskId,
result: null,
// It may be worth taking a look at the error cloning algorithm we
// use in Node.js core here, it's quite a bit more flexible
error: <Error>error,
time: start == null ? null : Math.round(performance.now() - start)
};
}
currentTasks--;
try {
// Post the response to the parent thread, and let it know that we have
// an additional message available. If possible, use Atomics.wait()
// to wait for the next message.
port.postMessage(response, transferList);
Atomics.add(sharedBuffer, kResponseCountField, 1);
if (useAtomics) {
const res = atomicsWaitLoop(port, sharedBuffer);
if (res?.then != null) await res;
}
} catch (error) {
throwInNextTick(error as Error);
}
}
function throwInNextTick (error : Error) {
queueMicrotask(() => { throw error; });
}
+39
View File
@@ -0,0 +1,39 @@
import type { PiscinaTask } from '../../task_queue';
import type { PiscinaWorker } from '..';
export type PiscinaLoadBalancer = (
task: PiscinaTask,
workers: PiscinaWorker[]
) => PiscinaWorker | null; // If candidate is passed, it will be used as the result of the load balancer and ingore the command;
export type LeastBusyBalancerOptions = {
maximumUsage: number;
};
export function LeastBusyBalancer (
opts: LeastBusyBalancerOptions
): PiscinaLoadBalancer {
const { maximumUsage } = opts;
return (task, workers) => {
let candidate: PiscinaWorker | null = null;
let checkpoint = maximumUsage;
for (const worker of workers) {
if (worker.currentUsage === 0) {
candidate = worker;
break;
}
if (worker.isRunningAbortableTask) continue;
if (
task.isAbortable === false &&
(worker.currentUsage < checkpoint)
) {
candidate = worker;
checkpoint = worker.currentUsage;
}
}
return candidate;
};
}
+126
View File
@@ -0,0 +1,126 @@
import assert from 'node:assert';
export abstract class AsynchronouslyCreatedResource {
onreadyListeners : (() => void)[] | null = [];
ondestroyListeners : (() => void)[] | null = [];
markAsReady () : void {
const listeners = this.onreadyListeners;
assert(listeners != null);
this.onreadyListeners = null;
for (const listener of listeners) {
listener();
}
}
isReady () : boolean {
return this.onreadyListeners == null;
}
onReady (fn : () => void) {
if (this.onreadyListeners == null) {
fn(); // Zalgo is okay here.
return;
}
this.onreadyListeners.push(fn);
}
onDestroy (fn : () => void) {
if (this.ondestroyListeners == null) {
return;
}
this.ondestroyListeners.push(fn);
}
markAsDestroyed () {
const listeners = this.ondestroyListeners;
assert(listeners != null);
this.ondestroyListeners = null;
for (const listener of listeners) {
listener();
}
}
isDestroyed () {
return this.ondestroyListeners == null;
}
abstract currentUsage() : number;
}
// TODO: this will eventually become an scheduler
export class AsynchronouslyCreatedResourcePool<
T extends AsynchronouslyCreatedResource> {
pendingItems = new Set<T>();
readyItems = new Set<T>();
maximumUsage : number;
onAvailableListeners : ((item : T) => void)[];
onTaskDoneListeners : ((item : T) => void)[];
constructor (maximumUsage : number) {
this.maximumUsage = maximumUsage;
this.onAvailableListeners = [];
this.onTaskDoneListeners = [];
}
add (item : T) {
this.pendingItems.add(item);
item.onReady(() => {
/* istanbul ignore else */
if (this.pendingItems.has(item)) {
this.pendingItems.delete(item);
this.readyItems.add(item);
this.maybeAvailable(item);
}
});
}
delete (item : T) {
this.pendingItems.delete(item);
this.readyItems.delete(item);
}
* [Symbol.iterator] () {
yield * this.pendingItems;
yield * this.readyItems;
}
get size () {
return this.pendingItems.size + this.readyItems.size;
}
maybeAvailable (item : T) {
/* istanbul ignore else */
if (item.currentUsage() < this.maximumUsage) {
for (const listener of this.onAvailableListeners) {
listener(item);
}
}
}
onAvailable (fn : (item : T) => void) {
this.onAvailableListeners.push(fn);
}
taskDone (item : T) {
for (let i = 0; i < this.onTaskDoneListeners.length; i++) {
this.onTaskDoneListeners[i](item);
}
}
onTaskDone (fn : (item : T) => void) {
this.onTaskDoneListeners.push(fn);
}
getCurrentUsage (): number {
let inFlight = 0;
for (const worker of this.readyItems) {
const currentUsage = worker.currentUsage();
if (Number.isFinite(currentUsage)) inFlight += currentUsage;
}
return inFlight;
}
}
+249
View File
@@ -0,0 +1,249 @@
import { Worker, MessagePort, receiveMessageOnPort, WorkerOptions, Transferable } from 'node:worker_threads';
import { createHistogram, RecordableHistogram } from 'node:perf_hooks';
import assert from 'node:assert';
import { RequestMessage, ResponseMessage, StartupMessage } from '../types';
import { Errors } from '../errors';
import { TaskInfo } from '../task_queue';
import { kFieldCount, kRequestCountField, kResponseCountField, kWorkerData } from '../symbols';
import { PiscinaHistogramHandler, PiscinaHistogramSummary } from '../histogram';
import { AsynchronouslyCreatedResource, AsynchronouslyCreatedResourcePool } from './base';
export * from './balancer';
type ResponseCallback = (response : ResponseMessage) => void;
export type PiscinaWorker = {
id: number;
currentUsage: number;
isRunningAbortableTask: boolean;
histogram: PiscinaHistogramSummary | null;
terminating: boolean;
destroyed: boolean;
[kWorkerData]: WorkerInfo;
}
type WorkerInfoParams = {
worker: {
filename: string,
} & WorkerOptions,
port: MessagePort,
enableHistogram: boolean,
}
export class WorkerInfo extends AsynchronouslyCreatedResource {
worker : Worker;
taskInfos : Map<number, TaskInfo>;
idleTimeout : NodeJS.Timeout | null = null;
port : MessagePort;
sharedBuffer : Int32Array;
lastSeenResponseCount : number = 0;
onMessage : ResponseCallback;
histogram: RecordableHistogram | null;
terminating = false;
destroyed = false;
constructor (
{
worker,
port,
enableHistogram
}: WorkerInfoParams,
onMessage: ResponseCallback
) {
super();
const { filename, ...workerOpts } = worker;
this.worker = new Worker(filename, workerOpts);
this.port = port;
this.onMessage = onMessage;
this.port.on('message', this._handleResponse.bind(this));
this.taskInfos = new Map();
this.sharedBuffer = new Int32Array(
new SharedArrayBuffer(kFieldCount * Int32Array.BYTES_PER_ELEMENT));
this.histogram = enableHistogram ? createHistogram() : null;
}
get id (): number {
return this.worker.threadId;
}
onWorkerMessage(handler: (msg: any) => void): void {
this.worker.on('message', handler);
}
onWorkerError(handler: (err: Error) => void): void {
this.worker.on('error', handler);
}
onWorkerExit(handler: (code: number) => void): void {
this.worker.on('exit', handler);
}
onPortClose(handler: () => void): void {
this.port.on('close', handler);
}
init(msg: StartupMessage, toTransfer: Transferable[]): WorkerInfo {
this.worker.postMessage(msg, toTransfer);
return this;
}
workerRef(): WorkerInfo {
this.worker.ref();
return this;
}
workerUnref(): WorkerInfo {
this.worker.unref();
return this;
}
destroy () : void {
if (this.terminating || this.destroyed) return;
this.terminating = true;
this.clearIdleTimeout();
this.worker.terminate();
this.port.close();
for (const taskInfo of this.taskInfos.values()) {
taskInfo.done(Errors.ThreadTermination());
}
this.taskInfos.clear();
this.terminating = false;
this.destroyed = true;
this.markAsDestroyed();
}
setIdleTimeout (handler: (_: void) => void, ms: number, ...args: any[]) : void {
this.idleTimeout = setTimeout(handler, ms, ...args).unref();
}
clearIdleTimeout () : void {
if (this.idleTimeout != null) {
clearTimeout(this.idleTimeout);
this.idleTimeout = null;
}
}
ref () : WorkerInfo {
this.port.ref();
return this;
}
unref () : WorkerInfo {
this.port.unref();
return this;
}
_handleResponse (message : ResponseMessage) : void {
// Both cannot be in different state if histogram enabled.
this.histogram?.record(PiscinaHistogramHandler.toHistogramIntegerNano(message?.time!));
this.onMessage(message);
if (this.taskInfos.size === 0) {
// No more tasks running on this Worker means it should not keep the
// process running.
this.unref();
}
}
postTask (taskInfo : TaskInfo) {
// Avoid duplicates
assert(!this.taskInfos.has(taskInfo.taskId));
// Avoid posting when pool is shutting down or worker already destroyed
assert(!this.terminating && !this.destroyed);
const message : RequestMessage = {
task: taskInfo.releaseTask(),
taskId: taskInfo.taskId,
filename: taskInfo.filename,
name: taskInfo.name,
histogramEnabled: this.histogram != null ? 1 : 0
};
try {
this.port.postMessage(message, taskInfo.transferList);
queueMicrotask(() => this.clearIdleTimeout())
taskInfo.workerInfo = this;
this.taskInfos.set(taskInfo.taskId, taskInfo);
this.ref();
// Inform the worker that there are new messages posted, and wake it up
// if it is waiting for one.
Atomics.add(this.sharedBuffer, kRequestCountField, 1);
Atomics.notify(this.sharedBuffer, kRequestCountField, 1);
} catch (err) {
// This would mostly happen if e.g. message contains unserializable data
// or transferList is invalid.
taskInfo.done(<Error>err);
}
}
processPendingMessages () {
if (this.destroyed) return;
// If we *know* that there are more messages than we have received using
// 'message' events yet, then try to load and handle them synchronously,
// without the need to wait for more expensive events on the event loop.
// This would usually break async tracking, but in our case, we already have
// the extra TaskInfo/AsyncResource layer that rectifies that situation.
const actualResponseCount =
Atomics.load(this.sharedBuffer, kResponseCountField);
if (actualResponseCount !== this.lastSeenResponseCount) {
this.lastSeenResponseCount = actualResponseCount;
let entry;
while ((entry = receiveMessageOnPort(this.port)) != null) {
this._handleResponse(entry.message);
}
}
}
isRunningAbortableTask () : boolean {
// If there are abortable tasks, we are running one at most per Worker.
if (this.taskInfos.size !== 1) return false;
const [[, task]] = this.taskInfos;
return task.abortSignal != null;
}
currentUsage () : number {
return this.isRunningAbortableTask() ? Infinity : this.taskInfos.size;
}
popTask (taskId: number) : TaskInfo | null {
const task = this.taskInfos.get(taskId) ?? null;
if (task != null) this.taskInfos.delete(taskId);
return task;
}
get interface (): PiscinaWorker {
const worker = this;
return {
get id () {
return worker.worker.threadId;
},
get currentUsage () {
return worker.currentUsage();
},
get isRunningAbortableTask () {
return worker.isRunningAbortableTask();
},
get histogram () {
return worker.histogram != null ? PiscinaHistogramHandler.createHistogramSummary(worker.histogram) : null;
},
get terminating () {
return worker.terminating;
},
get destroyed () {
return worker.destroyed;
},
[kWorkerData]: worker
};
}
}
export { AsynchronouslyCreatedResourcePool };