API reference › @evolu/common › Task › Semaphore

Defined in: packages/common/src/Task.ts:2373

A semaphore that limits the number of concurrent Tasks.

For mutual exclusion (limiting to exactly one Task), use Mutex instead.

Extends

Methods

[dispose]()

dispose: void;

Defined in: node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.esnext.disposable.d.ts:36

Inherited from

Disposable.[dispose]

Properties

snapshot

readonly snapshot: () => SemaphoreSnapshot;

Defined in: packages/common/src/Task.ts:2405

Returns the current semaphore state for monitoring/debugging.

withPermit

readonly withPermit: <T, E, D>(task: Task<T, E, D>) => Task<T, E, D>;

Defined in: packages/common/src/Task.ts:2381

Executes a Task while holding a semaphore permit.

The Task waits until a permit is available. If the semaphore is disposed while waiting or running, the Task is aborted with an AbortError whose reason is semaphoreDisposedError.

withPermits

readonly withPermits: <T, E, D>(permits: Concurrency) => (task: Task<T, E, D>) => Task<T, E, D>;

Defined in: packages/common/src/Task.ts:2400

Executes a Task while holding a specified number of permits.

If insufficient permits are available, waits in FIFO order until permits become available. If disposed while waiting or running, the Task is aborted with semaphoreDisposedError.

Use this for weighted concurrency where a Task represents a resource demand, not just "one more Task". One permit is one resource unit.

Example: with capacity 10, a lightweight operation can reserve 1 permit while a heavy operation reserves 4 permits. This models shared budgets such as DB connections, API credits, memory/CPU buckets, or batch processing slots.

Semaphore.withPermit is equivalent to withPermits(1).

Markdown for LLMs