@isdk/util 0.3.9 → 0.3.10

package/docs/classes/IntSet.md

@@ -6,7 +6,7 @@
 
 # Class: IntSet
 
-Defined in: [src/intset.ts:6](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/intset.ts#L6)
+Defined in: [src/intset.ts:6](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/intset.ts#L6)
 
 Represents a set of integers using a bit field.
 Each bit in the bit field represents an integer starting from 0,
@@ -18,7 +18,7 @@ where the flag value 0 represents the 0th bit, 1 represents the 1st bit, and so
 
 > **new IntSet**(`bitField?`): `IntSet`
 
-Defined in: [src/intset.ts:20](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/intset.ts#L20)
+Defined in: [src/intset.ts:20](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/intset.ts#L20)
 
 #### Parameters
 
@@ -36,7 +36,7 @@ Defined in: [src/intset.ts:20](https://github.com/isdk/util.js/blob/30c54a8a455a
 
 > **add**(`flag`): `IntSet`
 
-Defined in: [src/intset.ts:28](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/intset.ts#L28)
+Defined in: [src/intset.ts:28](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/intset.ts#L28)
 
 Adds an element to the set.
 
@@ -59,7 +59,7 @@ The flag value representing the bit position to set.
 
 > **clear**(): `IntSet`
 
-Defined in: [src/intset.ts:56](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/intset.ts#L56)
+Defined in: [src/intset.ts:56](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/intset.ts#L56)
 
 Clears all elements from the set.
 
@@ -73,7 +73,7 @@ Clears all elements from the set.
 
 > **delete**(`flag`): `IntSet`
 
-Defined in: [src/intset.ts:38](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/intset.ts#L38)
+Defined in: [src/intset.ts:38](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/intset.ts#L38)
 
 Removes an element from the set.
 
@@ -95,7 +95,7 @@ The flag value representing the bit position to set. 0 represents the 0th bit
 
 > **has**(`flag`): `boolean`
 
-Defined in: [src/intset.ts:49](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/intset.ts#L49)
+Defined in: [src/intset.ts:49](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/intset.ts#L49)
 
 Determines whether an element is in the set.
 
@@ -119,7 +119,7 @@ true if the element is in the set; otherwise, false.
 
 > **toJSON**(): `number`
 
-Defined in: [src/intset.ts:69](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/intset.ts#L69)
+Defined in: [src/intset.ts:69](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/intset.ts#L69)
 
 #### Returns
 
@@ -131,7 +131,7 @@ Defined in: [src/intset.ts:69](https://github.com/isdk/util.js/blob/30c54a8a455a
 
 > **toString**(): `string`
 
-Defined in: [src/intset.ts:65](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/intset.ts#L65)
+Defined in: [src/intset.ts:65](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/intset.ts#L65)
 
 #### Returns
 
@@ -143,7 +143,7 @@ Defined in: [src/intset.ts:65](https://github.com/isdk/util.js/blob/30c54a8a455a
 
 > **valueOf**(): `number`
 
-Defined in: [src/intset.ts:61](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/intset.ts#L61)
+Defined in: [src/intset.ts:61](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/intset.ts#L61)
 
 #### Returns
 
@@ -155,7 +155,7 @@ Defined in: [src/intset.ts:61](https://github.com/isdk/util.js/blob/30c54a8a455a
 
 > `static` **add**(`bitField`, `flag`): `number`
 
-Defined in: [src/intset.ts:11](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/intset.ts#L11)
+Defined in: [src/intset.ts:11](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/intset.ts#L11)
 
 #### Parameters
 
@@ -177,7 +177,7 @@ Defined in: [src/intset.ts:11](https://github.com/isdk/util.js/blob/30c54a8a455a
 
 > `static` **delete**(`bitField`, `flag`): `number`
 
-Defined in: [src/intset.ts:15](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/intset.ts#L15)
+Defined in: [src/intset.ts:15](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/intset.ts#L15)
 
 #### Parameters
 
@@ -199,7 +199,7 @@ Defined in: [src/intset.ts:15](https://github.com/isdk/util.js/blob/30c54a8a455a
 
 > `static` **has**(`bitField`, `flag`): `boolean`
 
-Defined in: [src/intset.ts:7](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/intset.ts#L7)
+Defined in: [src/intset.ts:7](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/intset.ts#L7)
 
 #### Parameters
 

package/docs/classes/Semaphore.md

@@ -6,45 +6,26 @@
 
 # Class: Semaphore
 
-Defined in: [src/async-semaphore.ts:377](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L377)
+Defined in: [src/async-semaphore.ts:465](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L465)
 
-A Semaphore implementation for managing concurrency in asynchronous operations.
-Semaphores allow a fixed number of resources to be accessed concurrently.
-This class extends BinarySemaphore and adds support for a maximum concurrency limit and an optional readiness check.
+计数信号量（Semaphore）实现。
+扩展自二进制信号量，允许指定最大并发数（`maxConcurrency`）。
+支持可选的就绪检查（`isReadyFn`）。
 
-Example usage:
+示例用法：
 
 ```typescript
-const semaphore = new Semaphore(5); // Allows 5 concurrent operations.
-
-const semaphore = new Semaphore(
-  4, // Allow 4 concurrent async calls
-  {
-    capacity: 100, // Prealloc space for 100 tokens
-    isReadyFn: async () => {
-      // Check if the system is ready to handle more requests
-      return true;
-    },
-    pauseFn: () => {
-      console.log('Pausing the stream');
-    },
-    resumeFn: () => {
-      console.log('Resuming the stream');
-    }
-  }
-);
+const semaphore = new Semaphore(5); // 允许 5 个并发操作
 
-async function fetchData(x) {
-  await semaphore.acquire()
+async function fetchData(id) {
+  const release = await semaphore.acquire();
   try {
-    console.log(semaphore.pendingCount() + ' calls to fetch are waiting')
-    // ... do some async stuff with x
+    console.log(`正在获取数据 ${id}, 等待中: ${semaphore.pendingCount}`);
+    // ... 异步操作
   } finally {
-    semaphore.release();
+    release();
   }
 }
-
-const data = await Promise.all(array.map(fetchData));
 ```
 
 ## Extends
@@ -57,26 +38,32 @@ const data = await Promise.all(array.map(fetchData));
 
 > **new Semaphore**(`maxConcurrency`, `options?`): `Semaphore`
 
-Defined in: [src/async-semaphore.ts:395](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L395)
+Defined in: [src/async-semaphore.ts:480](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L480)
 
-Creates a semaphore object. The first argument is the maximum concurrently number and the second argument is optional.
+创建一个计数信号量实例。
 
 #### Parameters
 
 ##### maxConcurrency
 
-The maximum number of callers allowed to acquire the semaphore concurrently.
+`number` \| [`SemaphoreOptions`](../interfaces/SemaphoreOptions.md)
 
-`number` | [`SemaphoreOptions`](../interfaces/SemaphoreOptions.md)
+最大并发数，或者包含并发设置的配置对象。
 
 ##### options?
 
 [`SemaphoreOptions`](../interfaces/SemaphoreOptions.md)
 
+配置选项。
+
 #### Returns
 
 `Semaphore`
 
+#### Throws
+
+如果未指定有效并发数则抛出错误。
+
 #### Overrides
 
 [`BinarySemaphore`](BinarySemaphore.md).[`constructor`](BinarySemaphore.md#constructor)
@@ -87,7 +74,9 @@ The maximum number of callers allowed to acquire the semaphore concurrently.
 
 > `protected` **\_activeCount**: `number`
 
-Defined in: [src/async-semaphore.ts:97](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L97)
+Defined in: [src/async-semaphore.ts:180](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L180)
+
+记录当前活跃的（已获取但未释放）操作总数。
 
 #### Inherited from
 
@@ -99,7 +88,9 @@ Defined in: [src/async-semaphore.ts:97](https://github.com/isdk/util.js/blob/30c
 
 > `protected` **emitter**: `EventEmitter`
 
-Defined in: [src/async-semaphore.ts:91](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L91)
+Defined in: [src/async-semaphore.ts:168](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L168)
+
+内部事件触发器，用于协调释放和分发逻辑。
 
 #### Inherited from
 
@@ -111,7 +102,9 @@ Defined in: [src/async-semaphore.ts:91](https://github.com/isdk/util.js/blob/30c
 
 > `protected` **free**: [`Deque`](Deque.md)\<`any`\>
 
-Defined in: [src/async-semaphore.ts:379](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L379)
+Defined in: [src/async-semaphore.ts:469](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L469)
+
+存储空闲令牌的队列。
 
 #### Overrides
 
@@ -119,11 +112,13 @@ Defined in: [src/async-semaphore.ts:379](https://github.com/isdk/util.js/blob/30
 
 ***
 
-### initTokenFn()
+### initTokenFn
 
 > `protected` **initTokenFn**: (`token?`) => `void`
 
-Defined in: [src/async-semaphore.ts:95](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L95)
+Defined in: [src/async-semaphore.ts:176](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L176)
+
+令牌初始化函数。
 
 #### Parameters
 
@@ -145,7 +140,9 @@ Defined in: [src/async-semaphore.ts:95](https://github.com/isdk/util.js/blob/30c
 
 > `readonly` **maxConcurrency**: `number`
 
-Defined in: [src/async-semaphore.ts:378](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L378)
+Defined in: [src/async-semaphore.ts:467](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L467)
+
+最大并发限制。
 
 ***
 
@@ -153,7 +150,9 @@ Defined in: [src/async-semaphore.ts:378](https://github.com/isdk/util.js/blob/30
 
 > `protected` **paused**: `boolean`
 
-Defined in: [src/async-semaphore.ts:96](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L96)
+Defined in: [src/async-semaphore.ts:178](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L178)
+
+记录当前是否处于暂停状态。
 
 #### Inherited from
 
@@ -161,11 +160,13 @@ Defined in: [src/async-semaphore.ts:96](https://github.com/isdk/util.js/blob/30c
 
 ***
 
-### pauseFn()?
+### pauseFn?
 
-> `protected` `optional` **pauseFn**: () => `void`
+> `protected` `optional` **pauseFn?**: () => `void`
 
-Defined in: [src/async-semaphore.ts:93](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L93)
+Defined in: [src/async-semaphore.ts:172](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L172)
+
+获取积压时的暂停回调。
 
 #### Returns
 
@@ -177,11 +178,13 @@ Defined in: [src/async-semaphore.ts:93](https://github.com/isdk/util.js/blob/30c
 
 ***
 
-### resumeFn()?
+### resumeFn?
+
+> `protected` `optional` **resumeFn?**: () => `void`
 
-> `protected` `optional` **resumeFn**: () => `void`
+Defined in: [src/async-semaphore.ts:174](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L174)
 
-Defined in: [src/async-semaphore.ts:94](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L94)
+恢复处理的回调。
 
 #### Returns
 
@@ -197,7 +200,9 @@ Defined in: [src/async-semaphore.ts:94](https://github.com/isdk/util.js/blob/30c
 
 > `protected` **useDefaultTokens**: `boolean`
 
-Defined in: [src/async-semaphore.ts:92](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L92)
+Defined in: [src/async-semaphore.ts:170](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L170)
+
+标记是否使用默认的令牌初始化函数。
 
 #### Inherited from
 
@@ -209,7 +214,9 @@ Defined in: [src/async-semaphore.ts:92](https://github.com/isdk/util.js/blob/30c
 
 > `readonly` **waiting**: [`Deque`](Deque.md)\<[`SemaphoreTaskItem`](../interfaces/SemaphoreTaskItem.md) \| `undefined`\>
 
-Defined in: [src/async-semaphore.ts:89](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L89)
+Defined in: [src/async-semaphore.ts:164](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L164)
+
+存储等待获取令牌的任务队列。
 
 #### Inherited from
 
@@ -223,19 +230,18 @@ Defined in: [src/async-semaphore.ts:89](https://github.com/isdk/util.js/blob/30c
 
 > **get** **activeCount**(): `number`
 
-Defined in: [src/async-semaphore.ts:323](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L323)
-
-Get the total count of all active operations.
+Defined in: [src/async-semaphore.ts:430](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L430)
 
-This method returns the number of operations that are either:
-- Waiting in the queue to acquire the semaphore (`pendingCount`).
-- Already acquired the semaphore but have not yet released it.
+获取所有活跃操作的总数。
+包含：
+- 正在队列中等待获取信号量的操作（`pendingCount`）。
+- 已经成功获取信号量但尚未释放的操作。
 
 ##### Returns
 
 `number`
 
-The total count of active operations, including both waiting and ongoing tasks.
+活跃操作的总数。
 
 #### Inherited from
 
@@ -249,15 +255,15 @@ The total count of active operations, including both waiting and ongoing tasks.
 
 > **get** **pendingCount**(): `number`
 
-Defined in: [src/async-semaphore.ts:332](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L332)
+Defined in: [src/async-semaphore.ts:439](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L439)
 
-Get the number of callers waiting on the semaphore, i.e. the number of pending promises.
+获取当前在等待队列中的调用方数量。
 
 ##### Returns
 
 `number`
 
-The number of waiters in the waiting list.
+等待中的 Promise 数量。
 
 #### Inherited from
 
@@ -269,7 +275,11 @@ The number of waiters in the waiting list.
 
 > **\_dispatchTask**(`task`, `options?`): `void`
 
-Defined in: [src/async-semaphore.ts:210](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L210)
+Defined in: [src/async-semaphore.ts:282](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L282)
+
+**`Internal`**
+
+将令牌分发给等待的任务。
 
 #### Parameters
 
@@ -277,10 +287,14 @@ Defined in: [src/async-semaphore.ts:210](https://github.com/isdk/util.js/blob/30
 
 [`SemaphoreTaskItem`](../interfaces/SemaphoreTaskItem.md)
 
+等待中的任务项。
+
 ##### options?
 
 [`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
 
+释放时传递的选项。
+
 #### Returns
 
 `void`
@@ -295,7 +309,12 @@ Defined in: [src/async-semaphore.ts:210](https://github.com/isdk/util.js/blob/30
 
 > **\_newReleaser**(`options?`): [`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)
 
-Defined in: [src/async-semaphore.ts:195](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L195)
+Defined in: [src/async-semaphore.ts:260](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L260)
+
+**`Internal`**
+
+创建一个新的释放函数。
+确保释放逻辑只被执行一次，并携带相关的释放选项。
 
 #### Parameters
 
@@ -303,10 +322,14 @@ Defined in: [src/async-semaphore.ts:195](https://github.com/isdk/util.js/blob/30
 
 [`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
 
+释放选项。
+
 #### Returns
 
 [`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)
 
+返回一个可调用的释放函数。
+
 #### Inherited from
 
 [`BinarySemaphore`](BinarySemaphore.md).[`_newReleaser`](BinarySemaphore.md#_newreleaser)
@@ -317,7 +340,10 @@ Defined in: [src/async-semaphore.ts:195](https://github.com/isdk/util.js/blob/30
 
 > **abort**(`reason?`): `void`
 
-Defined in: [src/async-semaphore.ts:306](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L306)
+Defined in: [src/async-semaphore.ts:414](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L414)
+
+中止所有正在等待的任务。
+所有在等待队列中的 Promise 将被拒绝并抛出 `AbortError`。
 
 #### Parameters
 
@@ -325,6 +351,8 @@ Defined in: [src/async-semaphore.ts:306](https://github.com/isdk/util.js/blob/30
 
 `any`
 
+中止的原因。
+
 #### Returns
 
 `void`
@@ -339,9 +367,18 @@ Defined in: [src/async-semaphore.ts:306](https://github.com/isdk/util.js/blob/30
 
 > **acquire**(`options?`): `Promise`\<[`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)\>
 
-Defined in: [src/async-semaphore.ts:244](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L244)
+Defined in: [src/async-semaphore.ts:339](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L339)
+
+获取信号量。
+如果信号量当前可用，将立即解析。否则，调用方将被加入等待队列，
+直到有令牌被释放。
 
-Acquire a token from the semaphore, thus decrement the number of available execution slots. If initFn is not used then the return value of the function can be discarded.
+逻辑流程：
+1. 增加活跃计数。
+2. 尝试通过 `tryAcquire` 立即获取令牌。
+3. 如果 `tryAcquire` 返回的是异步结果（通过 `isAsync` 判断），则等待其解析。
+4. 如果最终未获得令牌，则将任务推入 `waiting` 队列，并处理可选的 `AbortSignal`。
+5. 如果此时是队列中的第一个任务且定义了 `pauseFn`，则触发暂停回调。
 
 #### Parameters
 
@@ -349,11 +386,13 @@ Acquire a token from the semaphore, thus decrement the number of available execu
 
 [`BinarySemaphoreAcquireOptions`](../interfaces/BinarySemaphoreAcquireOptions.md)
 
+获取选项，可包含 `signal` 用于取消。
+
 #### Returns
 
 `Promise`\<[`BinarySemaphoreReleaserFunc`](../interfaces/BinarySemaphoreReleaserFunc.md)\>
 
-A promise that resolves to a release function when a token is acquired. If the semaphore is full, the caller will be added to a waiting queue.
+解析为释放函数（`BinarySemaphoreReleaserFunc`）的 Promise。
 
 #### Inherited from
 
@@ -365,14 +404,17 @@ A promise that resolves to a release function when a token is acquired. If the s
 
 > **drain**(): `Promise`\<`any`[]\>
 
-Defined in: [src/async-semaphore.ts:451](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L451)
+Defined in: [src/async-semaphore.ts:563](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L563)
 
-Drains the semaphore and returns all the initialized tokens in an array. Draining is an ideal way to ensure there are no pending async tasks, for example before a process will terminate.
+消耗掉所有并发槽位，确保当前没有其他操作正在运行。
+常用于在关键操作前清空并发环境。
 
 #### Returns
 
 `Promise`\<`any`[]\>
 
+解析为包含所有令牌数组的 Promise。
+
 #### Overrides
 
 [`BinarySemaphore`](BinarySemaphore.md).[`drain`](BinarySemaphore.md#drain)
@@ -383,7 +425,9 @@ Drains the semaphore and returns all the initialized tokens in an array. Drainin
 
 > **init**(`options`): `void`
 
-Defined in: [src/async-semaphore.ts:189](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L189)
+Defined in: [src/async-semaphore.ts:246](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L246)
+
+初始化事件监听。在构造函数中被调用。
 
 #### Parameters
 
@@ -391,6 +435,8 @@ Defined in: [src/async-semaphore.ts:189](https://github.com/isdk/util.js/blob/30
 
 [`BinarySemaphoreOptions`](../interfaces/BinarySemaphoreOptions.md)
 
+配置选项。
+
 #### Returns
 
 `void`
@@ -405,7 +451,9 @@ Defined in: [src/async-semaphore.ts:189](https://github.com/isdk/util.js/blob/30
 
 > **initFree**(`options`): `void`
 
-Defined in: [src/async-semaphore.ts:413](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L413)
+Defined in: [src/async-semaphore.ts:503](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L503)
+
+初始化令牌池，填充至最大并发数。
 
 #### Parameters
 
@@ -413,6 +461,8 @@ Defined in: [src/async-semaphore.ts:413](https://github.com/isdk/util.js/blob/30
 
 [`SemaphoreOptions`](../interfaces/SemaphoreOptions.md)
 
+配置选项。
+
 #### Returns
 
 `void`
@@ -427,7 +477,9 @@ Defined in: [src/async-semaphore.ts:413](https://github.com/isdk/util.js/blob/30
 
 > **lock**(`options?`): `any`
 
-Defined in: [src/async-semaphore.ts:447](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L447)
+Defined in: [src/async-semaphore.ts:553](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L553)
+
+从空闲令牌池中取出一个令牌。
 
 #### Parameters
 
@@ -435,10 +487,14 @@ Defined in: [src/async-semaphore.ts:447](https://github.com/isdk/util.js/blob/30
 
 [`BinarySemaphoreAcquireOptions`](../interfaces/BinarySemaphoreAcquireOptions.md)
 
+获取选项。
+
 #### Returns
 
 `any`
 
+如果池中不为空则返回一个令牌，否则返回 undefined。
+
 #### Overrides
 
 [`BinarySemaphore`](BinarySemaphore.md).[`lock`](BinarySemaphore.md#lock)
@@ -449,7 +505,10 @@ Defined in: [src/async-semaphore.ts:447](https://github.com/isdk/util.js/blob/30
 
 > **onReleased**(`options?`): `void`
 
-Defined in: [src/async-semaphore.ts:173](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L173)
+Defined in: [src/async-semaphore.ts:226](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L226)
+
+当信号量被释放时执行的内部处理逻辑。
+检查等待队列，如果有任务则分发令牌；否则将令牌归还至空闲池，并视情况调用 `resumeFn`。
 
 #### Parameters
 
@@ -457,6 +516,8 @@ Defined in: [src/async-semaphore.ts:173](https://github.com/isdk/util.js/blob/30
 
 [`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
 
+释放选项，可能包含令牌。
+
 #### Returns
 
 `void`
@@ -471,9 +532,11 @@ Defined in: [src/async-semaphore.ts:173](https://github.com/isdk/util.js/blob/30
 
 > **release**(`options?`): `void`
 
-Defined in: [src/async-semaphore.ts:293](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L293)
+Defined in: [src/async-semaphore.ts:391](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L391)
 
-Releases the semaphore, incrementing the number of free execution slots. If there are tasks in the waiting queue, the next task will be dispatched.
+释放信号量，增加可用执行槽位。
+如果等待队列中有任务，将触发下一个任务的执行。
+此方法会减少 `activeCount` 并发出 'release' 事件。
 
 #### Parameters
 
@@ -481,6 +544,8 @@ Releases the semaphore, incrementing the number of free execution slots. If ther
 
 [`BinarySemaphoreReleaseOptions`](../interfaces/BinarySemaphoreReleaseOptions.md)
 
+释放选项。
+
 #### Returns
 
 `void`
@@ -495,9 +560,10 @@ Releases the semaphore, incrementing the number of free execution slots. If ther
 
 > **tryAcquire**(`options?`): `any`
 
-Defined in: [src/async-semaphore.ts:424](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L424)
+Defined in: [src/async-semaphore.ts:521](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L521)
 
-Attempt to acquire a token from the semaphore, if one is available immediately. Otherwise, return undefined.
+尝试获取令牌，包含就绪状态检查。
+如果定义了 `isReadyFn`，将先调用它。
 
 #### Parameters
 
@@ -505,11 +571,13 @@ Attempt to acquire a token from the semaphore, if one is available immediately.
 
 [`BinarySemaphoreAcquireOptions`](../interfaces/BinarySemaphoreAcquireOptions.md)
 
+获取选项。
+
 #### Returns
 
 `any`
 
-Returns a token if the semaphore is not full; otherwise, returns `undefined`.
+可能返回令牌、Promise（当就绪检查为异步时）或 undefined。
 
 #### Overrides
 
@@ -521,7 +589,9 @@ Returns a token if the semaphore is not full; otherwise, returns `undefined`.
 
 > **unlock**(`token?`): `void`
 
-Defined in: [src/async-semaphore.ts:443](https://github.com/isdk/util.js/blob/30c54a8a455a9593000448de2a45f94a197d73de/src/async-semaphore.ts#L443)
+Defined in: [src/async-semaphore.ts:544](https://github.com/isdk/util.js/blob/c98bd1bf94d1b1dc8d01c6b9a6fc50b4beec5c62/src/async-semaphore.ts#L544)
+
+将令牌归还至空闲令牌池。
 
 #### Parameters
 
@@ -529,6 +599,8 @@ Defined in: [src/async-semaphore.ts:443](https://github.com/isdk/util.js/blob/30
 
 `any`
 
+要归还的令牌。
+
 #### Returns
 
 `void`