@ms-cloudpack/worker-pool

Provides utilities for simplifying worker execution.

It can manage either worker threads or child processes depending on the workerType option.

Usage

Code using the worker pool has two parts:

Host code which creates the pool and enqueues work
Worker entry file, a .js file which hosts the code to be executed within the worker

⚠️ Warning

For worker reuse to work properly, the method(s) being run must not have any async/scheduled code which continues running after the result is returned. Otherwise, if the scheduled code causes an error after the method returns, the error will either be swallowed (if no method was running in the worker at the time) or associated with the wrong method call (if another method call has been started).

If running arbitrary external code in a worker, it's recommended to overwrite all methods for async scheduling (setTimeout etc) with no-op versions.

Also be mindful of any cleanup of global state which might need to happen in between runs. This can be done with afterEach (see below).

Setting up a worker entry

First, let's set up the worker entry that will execute work inside the worker. Use initializeWorker to set up your api surface:

workerEntry.ts:

import { initializeWorker } from '@ms-cloudpack/worker-pool';
import { methodA, methodB } from './methods';

// Load any environmental side effects here.

// Then initialize the worker with the appropriate listeners and api dictionary.
initializeWorker({
  beforeEach: () => {...}, // optional
  afterEach: () => {...}, // optional
  methods: {
    methodA,
    methodB,
  },
});

Setting up the pool

In the host where we want to execute things to asynchronously run in the pool of worker threads:

import { WorkerPool } from '@ms-cloudpack/worker-pool';
import path from 'path';
import { fileURLToPath } from 'url';

// or use __dirname if not using ES modules
const dirname = path.dirname(fileURLToPath(import.meta.url));

const pool = new WorkerPool({
  entryPath: path.join(dirname, 'workerEntry.js'),
});

Worker threads are recommended due to their better performance. If the child operation specifically requires a new Node process with command line arguments or custom options, use workerType: 'process':

const pool = new WorkerPool({
  entryPath: path.join(dirname, 'processEntry.js'),
  workerType: 'process',
  // fill in as needed
  childProcessArgs: [],
  childProcessOptions: {},
});

Executing work

Work is executed from the pool created above:

const result = await pool.execute({
  method: 'methodA',
  args: [arg1, arg2, etc],
});