feat(mutex): set the mutex definition and tests

Author: HugoMendes98

src/index.ts

@@ -1,2 +1,4 @@
 export * from "./exceptions";
+export * from "./mutex";
 export * from "./semaphore";
+export * from "./synchronizer.interface";

src/mutex/index.ts

@@ -0,0 +1 @@
+export * from "./mutex";

src/mutex/mutex.spec.ts

@@ -0,0 +1,168 @@
+import { Mutex } from "./mutex";
+import { timeFunction } from "../../support/time-function";
+import {
+	ConcurrencyExceedTimeoutException,
+	ConcurrencyInterruptedException,
+	ConcurrencyInvalidTimeoutException
+} from "../exceptions";
+
+describe("Mutex", () => {
+	describe("Input validation", () => {
+		const mutex = new Mutex();
+
+		it("should throw a timeout exception when try-locking negative timeout", async () => {
+			for (const timeout of [-1, -10, -100]) {
+				await expect(() => mutex.tryLock(timeout)).rejects.toThrow(
+					ConcurrencyInvalidTimeoutException
+				);
+			}
+		});
+	});
+
+	describe("`lock` usage", () => {
+		const delay = 50;
+		const offset = 3;
+
+		it("should work with a basic usage", async () => {
+			// semaphore as a mutex
+			const mutex = new Mutex();
+
+			expect(mutex.isLocked).toBeFalse();
+			expect(mutex.queueLength).toBe(0);
+
+			const [elapsed] = await timeFunction(async () => {
+				setTimeout(() => {
+					expect(mutex.isLocked).toBeTrue();
+					expect(mutex.queueLength).toBe(1);
+					mutex.unlock();
+					expect(mutex.isLocked).toBeFalse();
+					expect(mutex.queueLength).toBe(0);
+				}, delay);
+
+				// Will wait until the end of the `setTimeout`
+				await mutex.lock();
+			});
+
+			expect(elapsed).toBeGreaterThanOrEqual(delay - offset);
+			expect(elapsed).toBeLessThanOrEqual(delay + offset);
+		});
+
+		it("should work with many lock", async () => {
+			const mutex = new Mutex();
+
+			const min = delay / 2;
+			const med = delay;
+			const max = delay * 2;
+
+			setTimeout(() => {
+				expect(mutex.isLocked).toBeTrue();
+				expect(mutex.queueLength).toBe(3);
+				mutex.unlock();
+				expect(mutex.isLocked).toBeTrue();
+				expect(mutex.queueLength).toBe(2);
+			}, min);
+
+			setTimeout(() => {
+				expect(mutex.isLocked).toBeTrue();
+				expect(mutex.queueLength).toBe(2);
+				mutex.unlock();
+				expect(mutex.isLocked).toBeTrue();
+				expect(mutex.queueLength).toBe(1);
+			}, med);
+
+			setTimeout(() => {
+				expect(mutex.isLocked).toBeTrue();
+				expect(mutex.queueLength).toBe(1);
+				mutex.unlock();
+				expect(mutex.isLocked).toBeFalse();
+				expect(mutex.queueLength).toBe(0);
+			}, max);
+
+			const [elapsed, times] = await timeFunction(() =>
+				Promise.all([
+					timeFunction(() => mutex.lock()),
+					timeFunction(() => mutex.lock()),
+					timeFunction(() => mutex.lock())
+				])
+			);
+
+			const [elapsed1, elapsed2, elapsed3] = times
+				.map(([elapsed]) => elapsed)
+				.sort((a, b) => a - b);
+
+			expect(elapsed1).toBeGreaterThanOrEqual(min - offset);
+			expect(elapsed1).toBeLessThanOrEqual(min + offset);
+			expect(elapsed2).toBeGreaterThanOrEqual(med - offset);
+			expect(elapsed2).toBeLessThanOrEqual(med + offset);
+			expect(elapsed3).toBeGreaterThanOrEqual(max - offset);
+			expect(elapsed3).toBeLessThanOrEqual(max + offset);
+
+			// The global elapsed time is very close to the slowest timeout
+			expect(elapsed).toBeGreaterThanOrEqual(max - offset);
+			expect(elapsed).toBeLessThanOrEqual(max + offset);
+
+			expect(mutex.isLocked).toBeFalse();
+			expect(mutex.queueLength).toBe(0);
+		});
+	});
+
+	describe("`tryLock` usage", () => {
+		const delay = 50;
+		const offset = 3;
+
+		it("should work with tryLock/unlock", async () => {
+			const mutex = new Mutex();
+
+			const [elapsed] = await timeFunction(async () => {
+				setTimeout(() => mutex.unlock(), delay);
+				await mutex.tryLock(delay * 5);
+			});
+
+			expect(elapsed).toBeGreaterThanOrEqual(delay - offset);
+			expect(elapsed).toBeLessThanOrEqual(delay + offset);
+		});
+
+		it("should thrown an error when the time exceeds", async () => {
+			const mutex = new Mutex();
+
+			setTimeout(() => {
+				expect(mutex.queueLength).toBe(1);
+				expect(mutex.isLocked).toBeTrue();
+			}, delay / 2);
+
+			await expect(() => mutex.tryLock(delay)).rejects.toThrow(
+				ConcurrencyExceedTimeoutException
+			);
+
+			// The queue is reset, since the `tryAcquire` failed
+			expect(mutex.queueLength).toBe(0);
+			expect(mutex.isLocked).toBeFalse();
+		});
+	});
+
+	it("should interrupt all", async () => {
+		const delay = 100;
+		const mutex = new Mutex();
+		const reason = "test";
+
+		setTimeout(() => {
+			expect(mutex.isLocked).toBeTrue();
+			expect(mutex.queueLength).toBe(3);
+			mutex.interrupt(reason);
+		}, delay);
+
+		const errors = await Promise.all([
+			mutex.lock().catch((err: unknown) => err),
+			mutex.tryLock(delay * 2).catch((err: unknown) => err),
+			mutex.lock().catch((err: unknown) => err)
+		]);
+
+		for (const error of errors) {
+			expect(error).toBeInstanceOf(ConcurrencyInterruptedException);
+			expect((error as ConcurrencyInterruptedException).getReason()).toBe(reason);
+		}
+
+		expect(mutex.isLocked).toBeFalse();
+		expect(mutex.queueLength).toBe(0);
+	});
+});

src/mutex/mutex.ts

@@ -0,0 +1,52 @@
+import { Synchronizer } from "../synchronizer.interface";
+
+export class Mutex implements Synchronizer {
+	/**
+	 * @returns if the current mutex is currently locked
+	 */
+	public get isLocked(): boolean {
+		throw new Error("Not implemented yet");
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public get queueLength(): number {
+		throw new Error("Not implemented yet");
+	}
+
+	/**
+	 * Locks this mutex
+	 *
+	 * @returns a promise when the lock has been set
+	 */
+	public lock(): Promise<void> {
+		throw new Error("Not implemented yet");
+	}
+
+	/**
+	 * Locks this mutex within a time limit.
+	 *
+	 * Throws an error if the given time exceeds.
+	 *
+	 * @param timeout maximum time (in ms) to lock
+	 * @returns a promise when the lock has been set
+	 */
+	public tryLock(timeout: number): Promise<void> {
+		throw new Error("Not implemented yet");
+	}
+
+	/**
+	 * Unlocks this mutex
+	 */
+	public unlock() {
+		throw new Error("Not implemented yet");
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public interrupt(reason: unknown) {
+		throw new Error("Not implemented yet");
+	}
+}

src/semaphore/semaphore.spec.ts

@@ -150,9 +150,9 @@ describe("Semaphore", () => {
 			const med = delay;
 			const max = delay * 2;
 
-			setTimeout(() => semaphore.release(), delay);
-			setTimeout(() => semaphore.release(), delay / 2);
-			setTimeout(() => semaphore.release(), delay * 2);
+			setTimeout(() => semaphore.release(), med);
+			setTimeout(() => semaphore.release(), min);
+			setTimeout(() => semaphore.release(), max);
 
 			// global elapsed of the operation and the times of the individual acquires
 			const [elapsed, times] = await timeFunction(() =>

src/semaphore/semaphore.ts

@@ -4,6 +4,7 @@ import {
 	ConcurrencyInvalidTimeoutException
 } from "../exceptions";
 import { ConcurrencyInterruptedException } from "../exceptions";
+import { Synchronizer } from "../synchronizer.interface";
 
 type Resolver = () => void;
 
@@ -28,7 +29,7 @@ interface QueueItem {
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#promise_concurrency
  */
-export class Semaphore {
+export class Semaphore implements Synchronizer {
 	/**
 	 * Queue of the "threads"
 	 */

src/synchronizer.interface.ts

@@ -0,0 +1,13 @@
+export interface Synchronizer {
+	/**
+	 * Interrupts all awaiting "Threads" with an [exception]{@link ConcurrencyInterruptedException}.
+	 *
+	 * @param reason The reason why this semaphore is being interrupted
+	 */
+	interrupt: (reason: unknown) => void;
+
+	/**
+	 * @returns the number of waiting "Threads" on a locking statement
+	 */
+	queueLength: number;
+}