Skip to content
S42 Core

S42-Core Cluster class

Cluster Documentation

The Cluster class is part of the s42-core package and enables the creation and management of parallel processes using Bun workers. It simplifies task distribution in applications that need to utilize multiple CPUs or manage independent processes.

Purpose

The Cluster class:

  • Creates and manages multiple workers efficiently.
  • Supports bidirectional messaging between the main process and workers.
  • Includes support for automatic worker restarts in development mode (--watch).
  • Handles errors and provides a simple API for integration.

Installation

Install the s42-core package:

Terminal window
npm install s42-core

Usage

Basic Example

import { Cluster } from 's42-core';


const cluster = new Cluster({
  name: 'MyCluster',
  maxCPU: 4,
  watchMode: true, // Enables automatic worker restarts in development mode
  args: ['--experimental-modules'], // Passes additional arguments to the workers
});


cluster.start('./worker.js', (err) => {
  if (err) {
    console.error('Failed to start the cluster:', err);
  }
});


cluster.onWorkerMessage((message) => {
  console.info('Message from worker:', message);
});

Constructor

constructor(props: TypeConstructor & { watchMode?: boolean; args?: string[] });
  • props.name (string): Name of the cluster.
  • props.maxCPU (number): Maximum number of CPUs to use.
  • props.watchMode (boolean, optional): Enables automatic worker restarts in development mode (--watch).
  • props.args (string[], optional): Array of arguments passed to the script executed by the workers.

Key Methods

start(file: string, fallback: (err: Error) => void): void

Starts the cluster and spawns workers.

  • file (string): File to be executed by the workers.
  • fallback (function): Callback executed if an error occurs while starting the cluster.
cluster.start('./worker.js', (err) => {
  if (err) {
    console.error('Failed to start the cluster:', err);
  }
});

onWorkerMessage(callback: (message: string) => void): void

Registers a callback to handle messages sent by the workers to the main process.

cluster.onWorkerMessage((message) => {
  console.info('Message from worker:', message);
});

sendMessageToWorkers(message: string): void

Sends a message to all active workers.

cluster.sendMessageToWorkers('Hello Workers!');

getCurrentFile(): string

Returns the file currently executed by the workers.

console.info('Current file:', cluster.getCurrentFile());

getCurrentWorkers(): Array<ReturnType<typeof spawn>>

Returns a list of active workers.

console.info('Active workers:', cluster.getCurrentWorkers());

killWorkers(): void

Safely shuts down all active workers.

process.on('SIGINT', () => {
  cluster.killWorkers();
});

Features

  1. Parallelism: Utilizes all available CPUs or a specified number of them.
  2. Messaging: Supports bidirectional messaging between the main process and workers.
  3. Development Mode: Automatic worker restarts with the --watch option.
  4. Custom Arguments: Passes additional command-line arguments to the workers.
  5. Error Handling: Provides callbacks to handle initialization errors.
  6. Simple Integration: Designed for easy integration into applications.

Full Example

import { Cluster } from 's42-core';


const cluster = new Cluster({
  name: 'MyCluster',
  maxCPU: 2,
  watchMode: true,
  args: ['--experimental-modules'],
});


cluster.start('./worker.js', (err) => {
  if (err) {
    console.error('Failed to start the cluster:', err);
  }
});


cluster.onWorkerMessage((message) => {
  console.info('Message from worker:', message);
});


cluster.sendMessageToWorkers('Hello Workers!');


process.on('SIGINT', () => {
  cluster.killWorkers();
});

Advantages

  • Modularity: Designed to handle parallel processes easily.
  • Efficiency: Maximizes system resource utilization.
  • Flexibility: Configurable for different environments (development/production).
  • Simplicity: Intuitive and well-documented API.

License

This project is licensed under the MIT License. See the LICENSE file for more details.