Add BasicLockable, Lockable and TimedLockable interfaces

src/index.ts

@@ -1,5 +1,8 @@
 // Types
+export { BasicLockable } from "./types/basicLockable";
 export { type CVStatus, CV_OK, CV_TIMED_OUT } from "./types/cvStatus";
+export { Lockable } from "./types/lockable";
+export { TimedLockable } from "./types/timedLockable";
 
 // Errors
 export { MutexError } from "./errors/mutexError";

src/mutex.ts

@@ -4,6 +4,7 @@ import { ERR_MUTEX_TIMEOUT } from "./errors/constants";
 import { MutexRelockError } from "./errors/mutexRelockError";
 import { MutexOwnershipError } from "./errors/mutexOwnershipError";
 import { TimeoutError } from "./errors/timeoutError";
+import { TimedLockable } from "./types/timedLockable";
 
 /**
  * Represents the mutex lock state.
@@ -36,7 +37,7 @@ const LOCK_BIT = 1;
  * @privateRemarks
  * 1. {@link https://en.cppreference.com/w/cpp/thread/unique_lock | C++ std::unique_lock}
  */
-export class Mutex {
+export class Mutex implements TimedLockable {
   /**
    * Indicates whether the current agent owns the lock.
    */

src/recursiveMutex.ts

@@ -3,6 +3,7 @@ import { ATOMICS_TIMED_OUT } from "./types/atomicsStatus";
 import { ERR_MUTEX_TIMEOUT, ERR_REC_MUTEX_OVERFLOW } from "./errors/constants";
 import { MutexOwnershipError } from "./errors/mutexOwnershipError";
 import { TimeoutError } from "./errors/timeoutError";
+import { TimedLockable } from "./types/timedLockable";
 
 /**
  * Represents the mutex lock state.
@@ -38,7 +39,7 @@ const LOCK_BIT = 1;
  * @privateRemarks
  * 1. {@link https://en.cppreference.com/w/cpp/thread/recursive_mutex | C++ std::recursive_mutex}
  */
-export class RecursiveMutex {
+export class RecursiveMutex implements TimedLockable {
   /**
    * The number of locks acquired by the agent.
    */

src/sharedMutex.ts

@@ -2,6 +2,7 @@ import { ConditionVariable } from "./conditionVariable";
 import { MutexOwnershipError } from "./errors/mutexOwnershipError";
 import { MutexRelockError } from "./errors/mutexRelockError";
 import { Mutex } from "./mutex";
+import { Lockable } from "./types/lockable";
 
 const WRITE_BIT = 1 << 31;
 const READ_BITS = ~WRITE_BIT;
@@ -23,7 +24,7 @@ const READ_BITS = ~WRITE_BIT;
  * 1. {@link https://en.cppreference.com/w/cpp/thread/shared_mutex | C++ std::shared_mutex}
  * 1. {@link https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2406.html | Alexander Terekhov, Howard Hinnant. (2007-09-09). Mutex, Lock, Condition Variable Rationale}
  */
-export class SharedMutex {
+export class SharedMutex implements Lockable {
   private _gate1: ConditionVariable;
   private _gate2: ConditionVariable;
   private _isReader: boolean;

src/types/basicLockable.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The base interface for types that provide exclusive
+ * blocking for agents (i.e. main thread, workers).
+ */
+export interface BasicLockable {
+  /**
+   * Blocks until a lock can be acquired for the current agent.
+   * If an exception is thrown, no lock is acquired.
+   */
+  lock(): Promise<void>;
+
+  /**
+   * Releases the lock held by the current agent.
+   */
+  unlock(): void | Promise<void>;
+}

src/types/cvStatus.ts → src/types/cvStatus.d.ts

@@ -5,12 +5,11 @@
 export type CVStatus = typeof CV_OK | typeof CV_TIMED_OUT;
 
 /**
- * Indicates the {@link ConditionVariable} operation completed successfully.
+ * The {@link ConditionVariable} was awakened via notification.
  */
 export const CV_OK = "ok";
 
 /**
- * Indicates the {@link ConditionVariable}
- * operation did not complete within the given time.
+ * The {@link ConditionVariable} was awakened by timeout expiration.
  */
 export const CV_TIMED_OUT = "timed-out";

src/types/lockable.d.ts

@@ -0,0 +1,15 @@
+import { BasicLockable } from "./basicLockable";
+
+/**
+ * Extends the {@link BasicLockable} interface to include attempted locking.
+ */
+export interface Lockable extends BasicLockable {
+  /**
+   * Attempts to acquire the lock for the current agent
+   * without blocking until acquired. If an exception
+   * is thrown, no lock is obtained.
+   *
+   * @returns `true` if the lock was acquired, `false` otherwise.
+   */
+  tryLock(): boolean | Promise<boolean>;
+}

src/types/timedLockable.d.ts

@@ -0,0 +1,20 @@
+import { Lockable } from "./lockable";
+
+/**
+ * Extends the {@link Lockable} interface to include timed blocking.
+ */
+export interface TimedLockable extends Lockable {
+  /**
+   * Blocks for the provided duration or until a lock is acquired.
+   *
+   * @returns `true` if the lock was acquired, `false` otherwise.
+   */
+  tryLockFor(timeout: number): Promise<boolean>;
+
+  /**
+   * Blocks until the provided timestamp is reached or a lock is acquired.
+   *
+   * @returns `true` if the lock was acquired, `false` otherwise.
+   */
+  tryLockUntil(timestamp: number): Promise<boolean>;
+}