feat(Semaphore, Mutex): Add Semaphore & Mutex

docs/ja/reference/promise/Mutex.md

@@ -0,0 +1,41 @@
+# Mutex
+
+非同期タスクが特定のコード領域で同時に一度だけ実行されるようにするためのミューテックス（Mutex）です。
+
+## インターフェース
+
+```typescript
+class Mutex {
+  isLocked: boolean;
+
+  acquire(): Promise<void>;
+  release(): void;
+}
+```
+
+## プロパティ
+
+- `isLocked` (`boolean`): 現在ミューテックスが使用中かどうかを確認します。`true`の場合、既に実行中の非同期タスクがあることを意味します。
+
+## メソッド
+
+- `acquire` (`() => Promise<void>`): ミューテックスを取得し、必要に応じて利用可能になるまでブロックします。
+- `release` (`() => void`): ミューテックスを解放し、他の待機中のタスクが続行できるようにします。
+
+## 例
+
+```typescript
+const mutex = new Mutex();
+
+async function criticalSection() {
+  await mutex.acquire();
+  try {
+    // This code section cannot be executed simultaneously
+  } finally {
+    mutex.release();
+  }
+}
+
+criticalSection();
+criticalSection(); // This call will wait until the first call releases the mutex.
+```

docs/ja/reference/promise/Semaphore.md

@@ -0,0 +1,51 @@
+# Semaphore
+
+同時に実行される非同期タスクの数を制限するために使用できるセマフォです。
+
+- `acquire` メソッドを実行すると、許可を得て非同期タスクを実行するか、許可が得られるまで待機します。
+- `release` メソッドを実行すると、待機中の次のタスクが実行できるようになります。
+
+このセマフォは、`acquire` を実行した順序に従って、先着順で非同期タスクを実行します。
+
+## インターフェース
+
+```typescript
+class Semaphore {
+  public capacity: number;
+  public available: number;
+
+  constructor(capacity: number);
+
+  acquire(): Promise<void>;
+  release(): void;
+}
+```
+
+## プロパティ
+
+- `capacity` (`number`): 同時に実行できるタスクの最大数。
+- `available` (`number`): 現在残っている実行可能なタスクの数。
+
+## メソッド
+
+- `acquire` (`() => Promise<void>`): 許可を取得して非同期タスクを実行するか、許可が得られるまで待機します。
+- `release` (`() => void`): 待機中の次のタスクが実行できるようになります。
+
+## 例
+
+```typescript
+const sema = new Semaphore(2);
+
+async function task() {
+  await sema.acquire();
+  try {
+    // This code can only be executed by two tasks at the same time
+  } finally {
+    sema.release();
+  }
+}
+
+task();
+task();
+task(); // This task will wait until one of the previous tasks releases the semaphore.
+```

docs/ko/reference/promise/Mutex.md

@@ -0,0 +1,41 @@
+# Mutex
+
+비동기 작업이 특정 코드 영역에서 동시에 한 번만 실행되도록 할 수 있는 뮤텍스(Mutex)예요.
+
+## 인터페이스
+
+```typescript
+class Mutex {
+  isLocked: boolean;
+
+  acquire(): Promise<void>;
+  release(): void;
+}
+```
+
+## 프로퍼티
+
+- `isLocked` (`boolean`): 현재 뮤텍스가 사용 중인지 여부. `true`라면 이미 실행 중인 비동기 작업이 있다는 뜻이에요.
+
+## 메서드
+
+- `acquire` (`() => Promise<void>`): 허가를 받고 비동기 작업을 실행하거나, 허가를 받을 때까지 기다려요.
+- `release` (`() => void`): 대기 중인 다음 작업이 실행될 수 있도록 해요.
+
+## 예시
+
+```typescript
+const mutex = new Mutex();
+
+async function criticalSection() {
+  await mutex.acquire();
+  try {
+    // This code section cannot be executed simultaneously
+  } finally {
+    mutex.release();
+  }
+}
+
+criticalSection();
+criticalSection(); // This call will wait until the first call releases the mutex.
+```

docs/ko/reference/promise/Semaphore.md

@@ -0,0 +1,51 @@
+# Semaphore
+
+동시에 실행되는 비동기 작업의 숫자를 제한하기 위해 사용할 수 있는 세마포어예요.
+
+- `acquire` 메서드를 실행하면, 허가를 받고 비동기 작업을 실행하거나, 허가를 받을 때까지 기다려요.
+- `release` 메서드를 실행하면, 대기 중인 다음 작업이 실행될 수 있도록 해요.
+
+이 세마포어는 `acquire`를 실행한 순서에 따라 선착순으로 비동기 작업을 실행해요.
+
+## Signature
+
+```typescript
+class Semaphore {
+  public capacity: number;
+  public available: number;
+
+  constructor(capacity: number);
+
+  acquire(): Promise<void>;
+  release(): void;
+}
+```
+
+## 프로퍼티
+
+- `capacity` (`number`): 동시에 실행될 수 있는 작업의 최댓값.
+- `available` (`number`): 현재 남은 실행 가능한 작업의 숫자.
+
+## 메서드
+
+- `acquire` (`() => Promise<void>`): 허가를 받고 비동기 작업을 실행하거나, 허가를 받을 때까지 기다려요.
+- `release` (`() => void`): 대기 중인 다음 작업이 실행될 수 있도록 해요.
+
+## 예시
+
+```typescript
+const sema = new Semaphore(2);
+
+async function task() {
+  await sema.acquire();
+  try {
+    // This code can only be executed by two tasks at the same time
+  } finally {
+    sema.release();
+  }
+}
+
+task();
+task();
+task(); // This task will wait until one of the previous tasks releases the semaphore.
+```

docs/reference/promise/Mutex.md

@@ -0,0 +1,42 @@
+# Mutex
+
+A mutex (mutual exclusion lock) for async functions.
+It allows only one async task to access a critical section at a time.
+
+## Signature
+
+```typescript
+class Mutex {
+  isLocked: boolean;
+
+  acquire(): Promise<void>;
+  release(): void;
+}
+```
+
+## Properties
+
+- `isLocked` (`boolean`): Checks if the mutex is currently locked.
+
+## Methods
+
+- `acquire` (`() => Promise<void>`): Acquires the mutex, blocking if necessary until it is available.
+- `release` (`() => void`): Releases the mutex, allowing another waiting task to proceed.
+
+## Examples
+
+```typescript
+const mutex = new Mutex();
+
+async function criticalSection() {
+  await mutex.acquire();
+  try {
+    // This code section cannot be executed simultaneously
+  } finally {
+    mutex.release();
+  }
+}
+
+criticalSection();
+criticalSection(); // This call will wait until the first call releases the mutex.
+```

docs/reference/promise/Semaphore.md

@@ -0,0 +1,52 @@
+# Semaphore
+
+A counting semaphore for async functions that manages available permits.
+Semaphores are mainly used to limit the number of concurrent async tasks.
+
+- Each `acquire` operation takes a permit or waits until one is available.
+- Each `release` operation adds a permit, potentially allowing a waiting task to proceed.
+
+The semaphore ensures fairness by maintaining a FIFO (First In, First Out) order for acquirers.
+
+## Signature
+
+```typescript
+class Semaphore {
+  public capacity: number;
+  public available: number;
+
+  constructor(capacity: number);
+
+  acquire(): Promise<void>;
+  release(): void;
+}
+```
+
+## Properties
+
+- `capacity` (`number`): The maximum number of concurrent operations allowed.
+- `available` (`number`): The number of available permits.
+
+## Methods
+
+- `acquire` (`() => Promise<void>`): Acquires a semaphore, blocking if necessary until one is available.
+- `release` (`() => void`): Releases a semaphore, allowing one more operation to proceed.
+
+## Examples
+
+```typescript
+const sema = new Semaphore(2);
+
+async function task() {
+  await sema.acquire();
+  try {
+    // This code can only be executed by two tasks at the same time
+  } finally {
+    sema.release();
+  }
+}
+
+task();
+task();
+task(); // This task will wait until one of the previous tasks releases the semaphore.
+```

docs/zh_hans/reference/promise/Mutex.md

@@ -0,0 +1,41 @@
+# Mutex
+
+互斥锁（Mutex）用于确保异步任务在特定代码区域内一次只能执行一个。
+
+## 签名
+
+```typescript
+class Mutex {
+  isLocked: boolean;
+
+  acquire(): Promise<void>;
+  release(): void;
+}
+```
+
+## 属性
+
+- `isLocked` (`boolean`): 当前互斥锁是否被使用。`true` 表示已经有正在执行的异步任务。
+
+## 方法
+
+- `acquire` (`() => Promise<void>`): 获取互斥锁，执行异步任务，或者等待获取互斥锁。
+- `release` (`() => void`): 释放互斥锁，允许下一个等待的任务执行。
+
+## 示例
+
+```typescript
+const mutex = new Mutex();
+
+async function criticalSection() {
+  await mutex.acquire();
+  try {
+    // This code section cannot be executed simultaneously
+  } finally {
+    mutex.release();
+  }
+}
+
+criticalSection();
+criticalSection(); // This call will wait until the first call releases the mutex.
+```

docs/zh_hans/reference/promise/Semaphore.md

@@ -0,0 +1,51 @@
+# Semaphore
+
+信号量可以用来限制同时执行的异步任务的数量。
+
+- 执行 `acquire` 方法时，会获取许可并执行异步任务，或者等待直到获得许可。
+- 执行 `release` 方法时，会允许下一个等待中的任务执行。
+
+此信号量按照 `acquire` 执行的顺序，先到先得地执行异步任务。
+
+## 签名
+
+```typescript
+class Semaphore {
+  public capacity: number;
+  public available: number;
+
+  constructor(capacity: number);
+
+  acquire(): Promise<void>;
+  release(): void;
+}
+```
+
+## 属性
+
+- `capacity` (`number`): 同时可以执行的最大任务数。
+- `available` (`number`): 当前剩余的可执行任务数。
+
+## 方法
+
+- `acquire` (`() => Promise<void>`): 获取许可并执行异步任务，或者等待直到获得许可。
+- `release` (`() => void`): 允许下一个等待中的任务执行。
+
+## 示例
+
+```typescript
+const sema = new Semaphore(2);
+
+async function task() {
+  await sema.acquire();
+  try {
+    // This code can only be executed by two tasks at the same time
+  } finally {
+    sema.release();
+  }
+}
+
+task();
+task();
+task(); // This task will wait until one of the previous tasks releases the semaphore.
+```

src/promise/index.ts

@@ -1,3 +1,5 @@
 export { delay } from './delay.ts';
+export { Mutex } from './mutex.ts';
+export { Semaphore } from './semaphore.ts';
 export { timeout } from './timeout.ts';
 export { withTimeout } from './withTimeout.ts';