feat(Semaphore): add waiterCount to reveal the number of lock waiters

Author: lambdalisue

_raw_semaphore.ts

@@ -29,6 +29,13 @@ export class RawSemaphore {
     return this.#value === 0;
   }
 
+  /**
+   * Returns the number of waiters that are waiting for lock release.
+   */
+  get waiterCount(): number {
+    return this.#resolves.length;
+  }
+
   /**
    * Acquires the semaphore, blocking until the semaphore is available.
    */

semaphore.ts

@@ -35,6 +35,13 @@ export class Semaphore {
     return this.#sem.locked;
   }
 
+  /**
+   * Returns the number of waiters that are waiting for lock release.
+   */
+  get waiterCount(): number {
+    return this.#sem.waiterCount;
+  }
+
   /**
    * Acquires a lock on the semaphore, and invokes the specified function.
    *

semaphore_test.ts

@@ -106,3 +106,56 @@ test(
     assertThrows(() => new Semaphore(0), RangeError);
   },
 );
+
+test(
+  "Semaphore.waiterCount returns the number of waiters (n=5)",
+  async () => {
+    const befores: number[] = [];
+    const afters: number[] = [];
+    const sem = new Semaphore(5);
+    const worker = (i: number) => {
+      return sem.lock(async () => {
+        befores.push(sem.waiterCount);
+        await new Promise((resolve) => setTimeout(resolve, 10 + i));
+        afters.push(sem.waiterCount);
+      });
+    };
+    await Promise.all([...Array(10)].map((_, i) => worker(i)));
+    /**
+     * Worker 0 |5========5
+     * Worker 1 |5=========4
+     * Worker 2 |5==========3
+     * Worker 3 |5===========2
+     * Worker 4 |5============1
+     * Worker 5 |----------4=============0
+     * Worker 6 |-----------3==============0
+     * Worker 7 |------------2===============0
+     * Worker 8 |-------------1================0
+     * Worker 9 |--------------0=================0
+     */
+    assertEquals(befores, [
+      5,
+      5,
+      5,
+      5,
+      5,
+      4,
+      3,
+      2,
+      1,
+      0,
+    ]);
+    assertEquals(afters, [
+      5,
+      4,
+      3,
+      2,
+      1,
+      0,
+      0,
+      0,
+      0,
+      0,
+    ]);
+  },
+);