API reference › @evolu/common › Task › Semaphore

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

Coordinates concurrent Tasks by acquiring and releasing permits.

Use Semaphore.withPermit or Semaphore.withPermits to acquire permits for one Task and release them when it settles. Use Semaphore.take when one permit must cover several child Tasks; the returned SemaphorePermit owns release and is disposable.

Requests are not capped by the current permit count because Semaphore.resize can increase it later.

Acquisition uses the "fifo" SemaphorePolicy by default.

Capacity is always positive. Use Gate when work should start closed and be released later.

Semaphore is permit-counting, not owner tracking. Acquiring permits while already holding permits consumes additional permits and can wait if not enough permits are available.

See

createSemaphore

Properties

isIdle

readonly isIdle: () => boolean;

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

Whether no permits are held and no requests are queued.

resize

readonly resize: (permits: Int1To100OrPositiveInt) => void;

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

Changes the total permit count without revoking held permits.

Permit count must stay positive; resizing to 0 is not supported. Use Gate for closed/open coordination.

If the total permit count is reduced below currently held permits, new acquisitions wait until enough permits are released.

snapshot

readonly snapshot: () => SemaphoreSnapshot;

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

Returns the current semaphore state for monitoring and debugging.

take

readonly take: (permits: Int1To100OrPositiveInt) => Task<SemaphorePermit>;

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

Acquires permits and returns an owned SemaphorePermit.

The Task waits until enough permits are available. Dispose or release the returned permit to make them available again.

When the request exceeds the current total permit count, the Task remains pending until Semaphore.resize increases capacity or the Task is aborted.

withPermit

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

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

Runs a Task while holding one permit.

withPermits

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

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

Runs a Task while holding the requested permits.

withPermitsIfAvailable

readonly withPermitsIfAvailable: (permits: Int1To100OrPositiveInt) => <T, E, D>(task: Task<T, E, D>) => Task<Option<T>, E, D>;

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

Runs a Task only when the requested permits are immediately available.

Returns none without running the Task when the request cannot be granted immediately.