Promise Pool

Bounded-concurrency task runner for promise-returning work — the common gap between b.workerPool (worker_threads for CPU-bound work) and b.queue (durable cross-process messaging). Wraps the typical "I have N parallel I/O fan-outs and want at most K in flight at any moment" pattern with back-pressure on enqueue (so the caller can't out-run the worker side) and a clean drain path that composes with b.appShutdown.

Two enqueue paths:

- pool.run(taskFn) returns a Promise that resolves to the task's return value (or rejects with the task's error). When the pool is at capacity, run waits until a slot frees BEFORE the task starts — back-pressure is part of the contract, not an opt.

- pool.fire(taskFn) is the synchronous-enqueue variant for fan-out from non-async contexts. Returns the same Promise but the call itself can't await — useful inside event handlers that fire-and-forget.

Drain semantics: pool.drain() resolves when every queued and in-flight task settles. Callers wire this into shutdown via b.appShutdown.create({ priority: 50, run: () => pool.drain() }) so the process doesn't tear down with work mid-flight.

The pool does NOT retry failed tasks; rejection of a task's promise is the caller's signal. Operators that want retry compose b.retry.withRetry inside the task body.

b.promisePool.create(opts) #

{
  concurrency: number,        // required; integer in [1, 65536]
  queueLimit:  number,        // default Infinity; once exceeded, enqueue throws
}

Build a bounded-concurrency pool. Returns { run, fire, drain, size, inFlight, queued, closed }. The pool is closed via drain({ close: true }); subsequent enqueues throw.

var pool = b.promisePool.create({ concurrency: 8 });
var results = await Promise.all(items.map(function (item) {
  return pool.run(function () { return fetchOne(item); });
}));
await pool.drain({ close: true });

Last updated 2026-08-08T16:39:49.652Z by seeder.