concengine

Getting Started

Install concengine with your preferred package manager. The engine requires Node.js 18 or later and has zero runtime dependencies.

npm install concengine

Create an engine instance with default configuration. The create() method returns a fully initialized engine ready for task scheduling.

import { create } from 'concengine'

const engine = create({
  threads: 4,
  strategy: 'work-stealing'
})

Core API

The API surface is intentionally small. Four methods cover the full lifecycle of concurrent task execution.

engine.spawn(fn) schedules a function for concurrent execution and returns a task handle. The scheduler assigns the task to the least-loaded thread.

engine.await(handle) blocks until the referenced task completes and returns its result. Supports timeout via an optional second argument.

engine.all(handles) waits for multiple tasks to complete. Returns an array of results in the same order as the input handles.

engine.destroy() gracefully shuts down all threads and releases resources. In-flight tasks are allowed to complete before shutdown.

const taskA = engine.spawn(() => compute(dataA))
const taskB = engine.spawn(() => compute(dataB))

const [resultA, resultB] = engine.all([taskA, taskB])

engine.destroy()

Configuration

Concengine works with zero configuration for most use cases. When customization is needed, pass an options object to create().

threads sets the worker count. Defaults to the number of available CPU cores. Setting this to 1 runs tasks sequentially, useful for debugging.

strategy selects the scheduling algorithm. Options are 'round-robin', 'work-stealing', and 'priority'. Work-stealing provides the best throughput for heterogeneous workloads.

timeout sets a global timeout in milliseconds for all tasks. Tasks exceeding this limit are cancelled and return an error result.

Community

Concengine is open source under the MIT license. Contributions are welcome. See the contributing guide for development setup and code standards.

Report bugs and request features on GitHub Issues. For questions and discussion, join the community forum.