[API reference](https://evolu.dev/docs/api-reference) › [@evolu/common](https://evolu.dev/docs/api-reference/common) › [Task](https://evolu.dev/docs/api-reference/common/Task) › Semaphore

Defined in: [packages/common/src/Task.ts:2373](https://github.com/evoluhq/evolu/blob/e7144e2bbe9069362b62dec1b64a8aa922b8f1b0/packages/common/src/Task.ts#L2373)

A semaphore that limits the number of concurrent [Task](https://evolu.dev/docs/api-reference/common/Task/type-aliases/Task)s.

For mutual exclusion (limiting to exactly one [Task](https://evolu.dev/docs/api-reference/common/Task/type-aliases/Task)), use [Mutex](https://evolu.dev/docs/api-reference/common/Task/interfaces/Mutex)
instead.

## Extends

- [`Disposable`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management)

## Methods

<a id="dispose"></a>

### \[dispose\]()

```ts
dispose: void;
```

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

#### Inherited from

```ts
Disposable.[dispose]
```

## Properties

<a id="snapshot"></a>

### snapshot

```ts
readonly snapshot: () => SemaphoreSnapshot;
```

Defined in: [packages/common/src/Task.ts:2405](https://github.com/evoluhq/evolu/blob/e7144e2bbe9069362b62dec1b64a8aa922b8f1b0/packages/common/src/Task.ts#L2405)

Returns the current semaphore state for monitoring/debugging.

### withPermit

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

Defined in: [packages/common/src/Task.ts:2381](https://github.com/evoluhq/evolu/blob/e7144e2bbe9069362b62dec1b64a8aa922b8f1b0/packages/common/src/Task.ts#L2381)

Executes a [Task](https://evolu.dev/docs/api-reference/common/Task/type-aliases/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](https://evolu.dev/docs/api-reference/common/Task/variables/AbortError)
whose reason is [semaphoreDisposedError](https://evolu.dev/docs/api-reference/common/Task/variables/semaphoreDisposedError).

### withPermits

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

Defined in: [packages/common/src/Task.ts:2400](https://github.com/evoluhq/evolu/blob/e7144e2bbe9069362b62dec1b64a8aa922b8f1b0/packages/common/src/Task.ts#L2400)

Executes a [Task](https://evolu.dev/docs/api-reference/common/Task/type-aliases/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](https://evolu.dev/docs/api-reference/common/Task/variables/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](https://evolu.dev/docs/api-reference/common/Task/interfaces/Semaphore#withpermit) is equivalent to `withPermits(1)`.