A library for performing multiple tasks in parallel with control over resource usage.

npm install basic-cluster

The cluster controls the execution of multiple async tasks. It has a size which will control how many instances it can manage.

The cluster also accepts options for how it retries obtaining an instance to run submitted tasks. Retries are managed via exponential-backoff so check the docs over there for options.

An instance is simply an object managed by the cluster and acts as a context for tasks to run in. While running a task, an instance is considered busy and it cannot accept a new task until the current one completes.

Task is what you submit to the cluster for it to run when possible.

Here's what you do:

1. Create a Cluster.
2. Submit tasks to it.
3. When you are done, you can shutdown the cluster.

The BasicCluster class makes it easy to run a bunch of parallel tasks which don't depend on a managed instance object.

import { BasicCluster } from './src/cluster/BasicCluster';

const clusterSize = 3;
const cluster: BasicCluster = new BasicCluster(clusterSize);

const result = cluster.submit(async () => {
    // Do something
});

If you no longer require the cluster, you can shut it down. There are two options for this:

1. Cluster#shutdown() will attempt to wait for any running task to complete before shutting down.
   1. After shutdown is requested, new task submissions are immediately rejected. Tasks waiting to be picked up will also be rejected.
   2. If there are running tasks, the cluster will retry to shutdown at a later time.
   3. When gracefully shutdown retries are exhausted, the cluster will forcefully shutdown.
2. Cluster#shutdownNow() will forcefully shutdown the cluster, calling shutdown() on all its instances immediately.
   1. This does not cancel running tasks, so depending on how their built and what stage their in, they might still complete successfully.

You can create clusters that use (potentially complex) instance objects, reusing them for new tasks. The example that inspired this package was a cluster of Puppeteer browser instances, which take some time to initiate and, as such, are a prime candidate for pooling.

To do so, you can implement the Instance interface and use the Cluster class directly with your instance.

The SimpleInstance is a utility for when you need an instance with some state and the shutdown is a no-op. Here's an example:

let i = 0;
const cluster: Cluster<SimpleInstance<number>> = new Cluster(3, () => new SimpleInstance(++i));
cluster.submit((instance) => {
    console.log(`Running task on instance ${instance.getValue()}`);
    // do something with the instance
});