@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/src/orchestration/coordination/read-write-lock.ts

@@ -0,0 +1,444 @@
+import type { InternalWaitQueueEntry } from "./internal/wait-queue.ts"
+import type { ModePermitDetails } from "./permit.ts"
+import type { InternalWaitConstraintsEntry, InternalWaitConstraintsOptions } from "./internal/wait-constraints.ts"
+
+import { InternalWaitQueue } from "./internal/wait-queue.ts"
+import { Permit } from "./permit.ts"
+import {
+  internalAssertTimeoutOption,
+  internalBindWaitConstraints,
+  internalCleanupWaitConstraints,
+  internalThrowIfAborted,
+} from "./internal/wait-constraints.ts"
+
+/**
+ * 表示读写锁内部使用的两种获取模式。
+ */
+type InternalReadWriteLockAcquireMode = "read" | "write"
+
+/**
+ * 表示读写锁对外暴露的持锁模式。
+ */
+export type ReadWriteLockMode = InternalReadWriteLockAcquireMode
+
+/**
+ * 表示 `ReadWriteLock` 成功获取后的占用句柄。
+ */
+export type ReadWriteLockPermit = Permit<ModePermitDetails<"read-write-lock", ReadWriteLockMode>>
+
+/**
+ * 表示读写锁内部等待队列中的节点。
+ */
+interface InternalReadWriteLockQueueEntry extends InternalWaitQueueEntry<InternalReadWriteLockQueueEntry>, InternalWaitConstraintsEntry {
+  mode: InternalReadWriteLockAcquireMode
+  resolve: (permit: ReadWriteLockPermit) => void
+  reject: (reason: unknown) => void
+  isSettled: boolean
+}
+
+/**
+ * 表示调用读锁或写锁获取方法时可选的等待约束。
+ */
+export interface ReadWriteLockAcquireOptions extends InternalWaitConstraintsOptions {
+  /**
+   * 单次等待允许持续的最长时间，单位为毫秒。
+   */
+  timeout?: number | undefined
+
+  /**
+   * 用于主动中止本次等待的信号。
+   */
+  abortSignal?: AbortSignal | undefined
+}
+
+const INTERNAL_READ_WRITE_LOCK_DUPLICATE_RELEASE_MESSAGE = "ReadWriteLock permit release was called more than once."
+
+/**
+ * 表示读写锁在检测到重复释放时使用的处理函数。
+ */
+export type ReadWriteLockDuplicateReleaseHandler = (message: string) => void
+
+/**
+ * 表示构造 `ReadWriteLock` 时支持的配置。
+ */
+export interface ReadWriteLockOptions {
+  /**
+   * 重复调用同一个 permit 的 `release()` 时触发的可选处理器。
+   */
+  onDuplicateRelease?: ReadWriteLockDuplicateReleaseHandler | undefined
+}
+
+/**
+ * 表示一个读写锁。
+ *
+ * 读锁允许多个读取者并发进入，写锁则要求完全独占。
+ * 当前实现采用 FIFO 等待队列，并保证一旦队头出现写者，后续读者不会越过该写者插队。
+ */
+export class ReadWriteLock {
+  private readonly queue: InternalWaitQueue<InternalReadWriteLockQueueEntry>
+
+  private internalPendingReaderCount: number
+
+  private internalPendingWriterCount: number
+
+  private internalActiveReaderCount: number
+
+  private internalHasActiveWriter: boolean
+
+  private readonly onDuplicateRelease: ReadWriteLockDuplicateReleaseHandler | undefined
+
+  /**
+   * 创建一个读写锁实例。
+   */
+  constructor(options: ReadWriteLockOptions = {}) {
+    this.queue = new InternalWaitQueue<InternalReadWriteLockQueueEntry>()
+    this.internalPendingReaderCount = 0
+    this.internalPendingWriterCount = 0
+    this.internalActiveReaderCount = 0
+    this.internalHasActiveWriter = false
+    this.onDuplicateRelease = options.onDuplicateRelease
+  }
+
+  /**
+   * 判断当前是否至少存在一个活动中的读者。
+   */
+  isReadLocked(): boolean {
+    return this.internalActiveReaderCount !== 0
+  }
+
+  /**
+   * 判断当前是否存在活动中的写者。
+   */
+  isWriteLocked(): boolean {
+    return this.internalHasActiveWriter
+  }
+
+  /**
+   * 判断当前读写锁是否被任意模式占用。
+   */
+  isLocked(): boolean {
+    return this.internalHasActiveWriter || this.internalActiveReaderCount !== 0
+  }
+
+  /**
+   * 读取等待队列中的总任务数。
+   */
+  getPendingCount(): number {
+    return this.queue.getCount()
+  }
+
+  /**
+   * 读取等待中的读者数量。
+   */
+  getPendingReaderCount(): number {
+    return this.internalPendingReaderCount
+  }
+
+  /**
+   * 读取等待中的写者数量。
+   */
+  getPendingWriterCount(): number {
+    return this.internalPendingWriterCount
+  }
+
+  /**
+   * 读取当前已进入临界区的读者数量。
+   */
+  getActiveReaderCount(): number {
+    return this.internalActiveReaderCount
+  }
+
+  /**
+   * 把等待节点加入队列，并同步更新按模式拆分的统计计数。
+   */
+  private enqueueEntry(entry: InternalReadWriteLockQueueEntry): void {
+    this.queue.enqueue(entry)
+
+    if (entry.mode === "read") {
+      this.internalPendingReaderCount = this.internalPendingReaderCount + 1
+    }
+    else {
+      this.internalPendingWriterCount = this.internalPendingWriterCount + 1
+    }
+  }
+
+  /**
+   * 从等待队列中移除指定节点，并同步回收对应的统计计数。
+   */
+  private removeEntry(entry: InternalReadWriteLockQueueEntry): void {
+    if (entry.isQueued === false) {
+      return
+    }
+
+    this.queue.remove(entry)
+
+    if (entry.mode === "read") {
+      this.internalPendingReaderCount = this.internalPendingReaderCount - 1
+    }
+    else {
+      this.internalPendingWriterCount = this.internalPendingWriterCount - 1
+    }
+  }
+
+  /**
+   * 构造一个读锁 permit。
+   */
+  private buildReadPermit(): ReadWriteLockPermit {
+    return new Permit<ModePermitDetails<"read-write-lock", ReadWriteLockMode>>({
+      details: { coordination: "read-write-lock", mode: "read" },
+      duplicateReleaseMessage: INTERNAL_READ_WRITE_LOCK_DUPLICATE_RELEASE_MESSAGE,
+      onDuplicateRelease: this.onDuplicateRelease,
+      onRelease: (): void => {
+        this.internalActiveReaderCount = this.internalActiveReaderCount - 1
+        this.dispatch()
+      },
+    })
+  }
+
+  /**
+   * 构造一个写锁 permit。
+   */
+  private buildWritePermit(): ReadWriteLockPermit {
+    return new Permit<ModePermitDetails<"read-write-lock", ReadWriteLockMode>>({
+      details: { coordination: "read-write-lock", mode: "write" },
+      duplicateReleaseMessage: INTERNAL_READ_WRITE_LOCK_DUPLICATE_RELEASE_MESSAGE,
+      onDuplicateRelease: this.onDuplicateRelease,
+      onRelease: (): void => {
+        this.internalHasActiveWriter = false
+        this.dispatch()
+      },
+    })
+  }
+
+  /**
+   * 尝试按 FIFO 规则调度队头等待者。
+   *
+   * 规则如下：
+   * 1. 若已有活动写者，则任何人都不能继续进入。
+   * 2. 若队头是写者，则必须等到所有活动读者结束后才可授予写锁。
+   * 3. 若队头是读者，则会批量放行连续的读者，直到遇到写者或队列结束。
+   */
+  private dispatch(): void {
+    if (this.internalHasActiveWriter === true) {
+      return
+    }
+
+    while (true) {
+      const head = this.queue.peek()
+      if (head === undefined) {
+        return
+      }
+
+      if (head.mode === "write") {
+        if (this.internalActiveReaderCount !== 0) {
+          return
+        }
+
+        const writerEntry = this.queue.shift()
+        if (writerEntry === undefined) {
+          return
+        }
+
+        this.internalPendingWriterCount = this.internalPendingWriterCount - 1
+
+        if (writerEntry.isSettled === true) {
+          continue
+        }
+
+        this.internalHasActiveWriter = true
+        writerEntry.isSettled = true
+        internalCleanupWaitConstraints(writerEntry)
+        writerEntry.resolve(this.buildWritePermit())
+        return
+      }
+
+      while (true) {
+        const readerHead = this.queue.peek()
+        if (readerHead === undefined || readerHead.mode !== "read") {
+          break
+        }
+
+        const readerEntry = this.queue.shift()
+        if (readerEntry === undefined) {
+          return
+        }
+
+        this.internalPendingReaderCount = this.internalPendingReaderCount - 1
+
+        if (readerEntry.isSettled === true) {
+          continue
+        }
+
+        this.internalActiveReaderCount = this.internalActiveReaderCount + 1
+        readerEntry.isSettled = true
+        internalCleanupWaitConstraints(readerEntry)
+        readerEntry.resolve(this.buildReadPermit())
+      }
+
+      if (this.internalActiveReaderCount !== 0) {
+        return
+      }
+    }
+  }
+
+  /**
+   * 以失败状态结束一个等待节点，并尝试继续调度后继等待者。
+   */
+  private rejectEntry(entry: InternalReadWriteLockQueueEntry, reason: unknown): void {
+    if (entry.isSettled === true) {
+      return
+    }
+
+    entry.isSettled = true
+    internalCleanupWaitConstraints(entry)
+    this.removeEntry(entry)
+    entry.reject(reason)
+    this.dispatch()
+  }
+
+  /**
+   * 尝试立即获取读锁；若当前已有写者或队列中存在排队任务，则返回 `undefined`。
+   */
+  tryAcquireRead(): ReadWriteLockPermit | undefined {
+    if (this.internalHasActiveWriter === true || this.queue.isEmpty() === false) {
+      return undefined
+    }
+
+    this.internalActiveReaderCount = this.internalActiveReaderCount + 1
+    return this.buildReadPermit()
+  }
+
+  /**
+   * 尝试立即获取写锁；只有完全空闲时才会成功。
+   */
+  tryAcquireWrite(): ReadWriteLockPermit | undefined {
+    if (
+      this.internalHasActiveWriter === true
+      || this.internalActiveReaderCount !== 0
+      || this.queue.isEmpty() === false
+    ) {
+      return undefined
+    }
+
+    this.internalHasActiveWriter = true
+    return this.buildWritePermit()
+  }
+
+  /**
+   * 等待直到成功获取读锁。
+   */
+  async acquireRead(options: ReadWriteLockAcquireOptions = {}): Promise<ReadWriteLockPermit> {
+    internalAssertTimeoutOption("ReadWriteLock read acquire", options.timeout)
+
+    internalThrowIfAborted("ReadWriteLock read acquire", options.abortSignal)
+
+    const immediatePermit = this.tryAcquireRead()
+    if (immediatePermit !== undefined) {
+      return immediatePermit
+    }
+
+    const permit = await new Promise<ReadWriteLockPermit>((resolve, reject) => {
+      const entry: InternalReadWriteLockQueueEntry = {
+        mode: "read",
+        resolve,
+        reject,
+        isSettled: false,
+        isQueued: false,
+        previous: undefined,
+        next: undefined,
+        timeoutId: undefined,
+        abortSignal: undefined,
+        abortListener: undefined,
+      }
+
+      internalBindWaitConstraints(entry, options, {
+        abortOperation: "ReadWriteLock read acquire",
+        timeoutOperation: "ReadWriteLock read acquire",
+        onAbort: error => {
+          this.rejectEntry(entry, error)
+        },
+        onTimeout: error => {
+          this.rejectEntry(entry, error)
+        },
+      })
+      this.enqueueEntry(entry)
+      this.dispatch()
+    })
+
+    return permit
+  }
+
+  /**
+   * 等待直到成功获取写锁。
+   */
+  async acquireWrite(options: ReadWriteLockAcquireOptions = {}): Promise<ReadWriteLockPermit> {
+    internalAssertTimeoutOption("ReadWriteLock write acquire", options.timeout)
+
+    internalThrowIfAborted("ReadWriteLock write acquire", options.abortSignal)
+
+    const immediatePermit = this.tryAcquireWrite()
+    if (immediatePermit !== undefined) {
+      return immediatePermit
+    }
+
+    const permit = await new Promise<ReadWriteLockPermit>((resolve, reject) => {
+      const entry: InternalReadWriteLockQueueEntry = {
+        mode: "write",
+        resolve,
+        reject,
+        isSettled: false,
+        isQueued: false,
+        previous: undefined,
+        next: undefined,
+        timeoutId: undefined,
+        abortSignal: undefined,
+        abortListener: undefined,
+      }
+
+      internalBindWaitConstraints(entry, options, {
+        abortOperation: "ReadWriteLock write acquire",
+        timeoutOperation: "ReadWriteLock write acquire",
+        onAbort: error => {
+          this.rejectEntry(entry, error)
+        },
+        onTimeout: error => {
+          this.rejectEntry(entry, error)
+        },
+      })
+      this.enqueueEntry(entry)
+      this.dispatch()
+    })
+
+    return permit
+  }
+
+  /**
+   * 在读锁保护下执行回调。
+   */
+  async runExclusiveRead<T>(callback: () => Promise<T>, options?: ReadWriteLockAcquireOptions): Promise<T>
+  async runExclusiveRead<T>(callback: () => T, options?: ReadWriteLockAcquireOptions): Promise<T>
+  async runExclusiveRead<T>(callback: () => Promise<T> | T, options: ReadWriteLockAcquireOptions = {}): Promise<T> {
+    const permit = await this.acquireRead(options)
+    try {
+      return await callback()
+    }
+    finally {
+      permit.release()
+    }
+  }
+
+  /**
+   * 在写锁保护下执行回调。
+   */
+  async runExclusiveWrite<T>(callback: () => Promise<T>, options?: ReadWriteLockAcquireOptions): Promise<T>
+  async runExclusiveWrite<T>(callback: () => T, options?: ReadWriteLockAcquireOptions): Promise<T>
+  async runExclusiveWrite<T>(callback: () => Promise<T> | T, options: ReadWriteLockAcquireOptions = {}): Promise<T> {
+    const permit = await this.acquireWrite(options)
+    try {
+      return await callback()
+    }
+    finally {
+      permit.release()
+    }
+  }
+}

package/src/orchestration/coordination/semaphore.ts

@@ -0,0 +1,280 @@
+import type { CoordinationPermitDetails } from "./permit.ts"
+import type { InternalWaitQueueEntry } from "./internal/wait-queue.ts"
+import type { InternalWaitConstraintsEntry, InternalWaitConstraintsOptions } from "./internal/wait-constraints.ts"
+
+import { InternalWaitQueue } from "./internal/wait-queue.ts"
+import { Permit } from "./permit.ts"
+import {
+  internalAssertTimeoutOption,
+  internalBindWaitConstraints,
+  internalCleanupWaitConstraints,
+  internalThrowIfAborted,
+} from "./internal/wait-constraints.ts"
+
+const internalAssertMaxConcurrency = (maxConcurrency: number): void => {
+  if (
+    Number.isFinite(maxConcurrency) === false
+    || Number.isInteger(maxConcurrency) === false
+    || maxConcurrency <= 0
+  ) {
+    throw new RangeError("Semaphore maxConcurrency must be a finite integer greater than 0.")
+  }
+}
+
+/**
+ * 表示 `Semaphore` 成功获取后的占用句柄。
+ */
+export type SemaphorePermit = Permit<CoordinationPermitDetails<"semaphore">>
+
+/**
+ * 表示信号量等待队列中的单个节点。
+ */
+interface InternalSemaphoreQueueEntry extends InternalWaitQueueEntry<InternalSemaphoreQueueEntry>, InternalWaitConstraintsEntry {
+  resolve: (permit: SemaphorePermit) => void
+  reject: (reason: unknown) => void
+  isSettled: boolean
+}
+
+/**
+ * 表示调用 `Semaphore.acquire()` 时可选的等待约束。
+ */
+export interface SemaphoreAcquireOptions extends InternalWaitConstraintsOptions {
+  /**
+   * 单次等待允许持续的最长时间，单位为毫秒。
+   */
+  timeout?: number | undefined
+
+  /**
+   * 用于主动中止本次等待的信号。
+   */
+  abortSignal?: AbortSignal | undefined
+}
+
+const INTERNAL_SEMAPHORE_DUPLICATE_RELEASE_MESSAGE = "Semaphore permit release was called more than once."
+
+/**
+ * 表示信号量在检测到重复释放时使用的处理函数。
+ */
+export type SemaphoreDuplicateReleaseHandler = (message: string) => void
+
+/**
+ * 表示构造 `Semaphore` 时支持的配置。
+ */
+export interface SemaphoreOptions {
+  /**
+   * 重复调用同一个 permit 的 `release()` 时触发的可选处理器。
+   */
+  onDuplicateRelease?: SemaphoreDuplicateReleaseHandler | undefined
+}
+
+/**
+ * 表示用于限制并发进入数量的信号量。
+ *
+ * @example
+ * ```
+ * const semaphore = new Semaphore(2)
+ * let activeCount = 0
+ * let peakCount = 0
+ *
+ * await Promise.all([
+ *   semaphore.runExclusive(async () => {
+ *     activeCount = activeCount + 1
+ *     peakCount = Math.max(peakCount, activeCount)
+ *     await Promise.resolve()
+ *     activeCount = activeCount - 1
+ *   }),
+ *   semaphore.runExclusive(async () => {
+ *     activeCount = activeCount + 1
+ *     peakCount = Math.max(peakCount, activeCount)
+ *     await Promise.resolve()
+ *     activeCount = activeCount - 1
+ *   }),
+ *   semaphore.runExclusive(async () => {
+ *     activeCount = activeCount + 1
+ *     peakCount = Math.max(peakCount, activeCount)
+ *     await Promise.resolve()
+ *     activeCount = activeCount - 1
+ *   }),
+ * ])
+ *
+ * // Expect: 2
+ * const example1 = peakCount
+ * ```
+ */
+export class Semaphore {
+  private readonly queue: InternalWaitQueue<InternalSemaphoreQueueEntry>
+
+  private internalActiveCount: number
+
+  private readonly maxConcurrency: number
+
+  private readonly onDuplicateRelease: SemaphoreDuplicateReleaseHandler | undefined
+
+  /**
+   * 使用给定最大并发数创建信号量。
+   */
+  constructor(maxConcurrency: number, options: SemaphoreOptions = {}) {
+    internalAssertMaxConcurrency(maxConcurrency)
+
+    this.queue = new InternalWaitQueue<InternalSemaphoreQueueEntry>()
+    this.internalActiveCount = 0
+    this.maxConcurrency = maxConcurrency
+    this.onDuplicateRelease = options.onDuplicateRelease
+  }
+
+  /**
+   * 判断当前是否已经达到并发上限。
+   */
+  isSaturated(): boolean {
+    return this.internalActiveCount >= this.maxConcurrency
+  }
+
+  /**
+   * 读取当前正在占用中的数量。
+   */
+  getActiveCount(): number {
+    return this.internalActiveCount
+  }
+
+  /**
+   * 读取当前还剩多少可立即分配的许可。
+   */
+  getAvailableCount(): number {
+    return this.maxConcurrency - this.internalActiveCount
+  }
+
+  /**
+   * 读取当前等待中的任务数量。
+   */
+  getPendingCount(): number {
+    return this.queue.getCount()
+  }
+
+  /**
+   * 读取信号量的最大并发容量。
+   */
+  getMaxConcurrency(): number {
+    return this.maxConcurrency
+  }
+
+  /**
+   * 在仍有可用容量时，按 FIFO 顺序持续放行等待者。
+   */
+  private dispatch(): void {
+    while (this.internalActiveCount < this.maxConcurrency && this.queue.isEmpty() === false) {
+      const nextEntry = this.queue.shift()
+      if (nextEntry === undefined) {
+        return
+      }
+
+      if (nextEntry.isSettled === true) {
+        continue
+      }
+
+      this.internalActiveCount = this.internalActiveCount + 1
+      nextEntry.isSettled = true
+      internalCleanupWaitConstraints(nextEntry)
+      nextEntry.resolve(this.buildPermit())
+    }
+  }
+
+  /**
+   * 构造一个信号量 permit，并在释放时归还一个并发槽位。
+   */
+  private buildPermit(): SemaphorePermit {
+    return new Permit<CoordinationPermitDetails<"semaphore">>({
+      details: { coordination: "semaphore" },
+      duplicateReleaseMessage: INTERNAL_SEMAPHORE_DUPLICATE_RELEASE_MESSAGE,
+      onDuplicateRelease: this.onDuplicateRelease,
+      onRelease: (): void => {
+        this.internalActiveCount = this.internalActiveCount - 1
+        this.dispatch()
+      },
+    })
+  }
+
+  /**
+   * 以失败状态结束一个等待节点，并尝试继续调度后继等待者。
+   */
+  private rejectEntry(entry: InternalSemaphoreQueueEntry, reason: unknown): void {
+    if (entry.isSettled === true) {
+      return
+    }
+
+    entry.isSettled = true
+    internalCleanupWaitConstraints(entry)
+    this.queue.remove(entry)
+    entry.reject(reason)
+    this.dispatch()
+  }
+
+  /**
+   * 尝试立即获取一个许可；若没有剩余容量或前面已有排队任务，则返回 `undefined`。
+   */
+  tryAcquire(): SemaphorePermit | undefined {
+    if (this.internalActiveCount >= this.maxConcurrency || this.queue.isEmpty() === false) {
+      return undefined
+    }
+
+    this.internalActiveCount = this.internalActiveCount + 1
+    return this.buildPermit()
+  }
+
+  /**
+   * 等待直到成功获取一个许可。
+   */
+  async acquire(options: SemaphoreAcquireOptions = {}): Promise<SemaphorePermit> {
+    internalAssertTimeoutOption("Semaphore acquire", options.timeout)
+
+    internalThrowIfAborted("Semaphore acquire", options.abortSignal)
+
+    const immediatePermit = this.tryAcquire()
+    if (immediatePermit !== undefined) {
+      return immediatePermit
+    }
+
+    const permit = await new Promise<SemaphorePermit>((resolve, reject) => {
+      const entry: InternalSemaphoreQueueEntry = {
+        resolve,
+        reject,
+        isSettled: false,
+        isQueued: false,
+        previous: undefined,
+        next: undefined,
+        timeoutId: undefined,
+        abortSignal: undefined,
+        abortListener: undefined,
+      }
+
+      internalBindWaitConstraints(entry, options, {
+        abortOperation: "Semaphore acquire",
+        timeoutOperation: "Semaphore acquire",
+        onAbort: error => {
+          this.rejectEntry(entry, error)
+        },
+        onTimeout: error => {
+          this.rejectEntry(entry, error)
+        },
+      })
+      this.queue.enqueue(entry)
+      this.dispatch()
+    })
+
+    return permit
+  }
+
+  /**
+   * 在信号量许可保护下执行回调。
+   */
+  async runExclusive<T>(callback: () => Promise<T>, options?: SemaphoreAcquireOptions): Promise<T>
+  async runExclusive<T>(callback: () => T, options?: SemaphoreAcquireOptions): Promise<T>
+  async runExclusive<T>(callback: () => Promise<T> | T, options: SemaphoreAcquireOptions = {}): Promise<T> {
+    const permit = await this.acquire(options)
+    try {
+      return await callback()
+    }
+    finally {
+      permit.release()
+    }
+  }
+}