Semaphore: Add timeout option (#1300)

Adds an optional `timeout` option to the Semaphore class that throws an
error when the Semaphore cannot be acquired for `timeout` milliseconds.

Related to #1287

 ## Testing instructions

Confirm the unit tests pass

Author: adamziel

packages/php-wasm/util/src/lib/semaphore.spec.ts

@@ -1,4 +1,4 @@
-import Semaphore from './semaphore';
+import Semaphore, { AcquireTimeoutError } from './semaphore';
 
 describe('RequestsPerIntervaledSemaphore', () => {
 	it('should limit the number of concurrent lock holders', async () => {
@@ -40,4 +40,13 @@ describe('RequestsPerIntervaledSemaphore', () => {
 
 		expect(semaphore.running).toBe(1);
 	});
+	it('should wait for the lock no longer than the timeout', async () => {
+		const semaphore = new Semaphore({
+			concurrency: 1,
+			timeout: 1,
+		});
+
+		await semaphore.acquire();
+		expect(() => semaphore.acquire()).rejects.toThrow(AcquireTimeoutError);
+	});
 });

packages/php-wasm/util/src/lib/semaphore.ts

@@ -1,17 +1,38 @@
+import { SleepFinished, sleep } from './sleep';
+
 export interface SemaphoreOptions {
+	/**
+	 * The maximum number of concurrent locks.
+	 */
 	concurrency: number;
+	/**
+	 * The maximum time to wait for a lock to become available.
+	 */
+	timeout?: number;
+}
+
+export class AcquireTimeoutError extends Error {
+	constructor() {
+		super('Acquiring lock timed out');
+	}
 }
 
 export default class Semaphore {
 	private _running = 0;
 	private concurrency: number;
+	private timeout?: number;
 	private queue: (() => void)[];
 
-	constructor({ concurrency }: SemaphoreOptions) {
+	constructor({ concurrency, timeout }: SemaphoreOptions) {
 		this.concurrency = concurrency;
+		this.timeout = timeout;
 		this.queue = [];
 	}
 
+	get remaining(): number {
+		return this.concurrency - this.running;
+	}
+
 	get running(): number {
 		return this._running;
 	}
@@ -20,7 +41,20 @@ export default class Semaphore {
 		while (true) {
 			if (this._running >= this.concurrency) {
 				// Concurrency exhausted – wait until a lock is released:
-				await new Promise<void>((resolve) => this.queue.push(resolve));
+				const acquired = new Promise<void>((resolve) => {
+					this.queue.push(resolve);
+				});
+				if (this.timeout !== undefined) {
+					await Promise.race([acquired, sleep(this.timeout)]).then(
+						(value) => {
+							if (value === SleepFinished) {
+								throw new AcquireTimeoutError();
+							}
+						}
+					);
+				} else {
+					await acquired;
+				}
 			} else {
 				// Acquire the lock:
 				this._running++;

packages/php-wasm/util/src/lib/sleep.ts

@@ -0,0 +1,7 @@
+export const SleepFinished = Symbol('SleepFinished');
+
+export function sleep(ms: number): Promise<typeof SleepFinished> {
+	return new Promise((resolve) => {
+		setTimeout(() => resolve(SleepFinished), ms);
+	});
+}