@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/src/orchestration/coordination/internal/wait-queue.ts

@@ -0,0 +1,109 @@
+/**
+ * 表示可挂入等待队列的节点最小结构。
+ *
+ * 队列本身不关心节点承载的业务数据，只要求节点能记录自己是否在队列中，以及前后相邻节点。
+ */
+export interface InternalWaitQueueEntry<Entry extends InternalWaitQueueEntry<Entry>> {
+  isQueued: boolean
+  previous: Entry | undefined
+  next: Entry | undefined
+}
+
+/**
+ * 表示面向等待者节点的双向链表队列。
+ */
+export class InternalWaitQueue<Entry extends InternalWaitQueueEntry<Entry>> {
+  private head: Entry | undefined
+  private tail: Entry | undefined
+
+  private count: number
+
+  constructor() {
+    this.head = undefined
+    this.tail = undefined
+    this.count = 0
+  }
+
+  /**
+   * 查看当前队头节点但不移除。
+   */
+  peek(): Entry | undefined {
+    return this.head
+  }
+
+  /**
+   * 读取队列中的节点数量。
+   */
+  getCount(): number {
+    return this.count
+  }
+
+  /**
+   * 判断队列是否为空。
+   */
+  isEmpty(): boolean {
+    return this.head === undefined
+  }
+
+  /**
+   * 把节点追加到队尾。
+   */
+  enqueue(entry: Entry): void {
+    entry.previous = this.tail
+    entry.next = undefined
+    entry.isQueued = true
+
+    if (this.tail === undefined) {
+      this.head = entry
+    }
+    else {
+      this.tail.next = entry
+    }
+
+    this.tail = entry
+    this.count = this.count + 1
+  }
+
+  /**
+   * 从队列中移除指定节点。
+   *
+   * 该操作不要求节点位于队头，因此适合被 timeout 或 abort 的等待者直接自移除。
+   */
+  remove(entry: Entry): void {
+    if (entry.isQueued === false) {
+      return
+    }
+
+    if (entry.previous === undefined) {
+      this.head = entry.next
+    }
+    else {
+      entry.previous.next = entry.next
+    }
+
+    if (entry.next === undefined) {
+      this.tail = entry.previous
+    }
+    else {
+      entry.next.previous = entry.previous
+    }
+
+    entry.previous = undefined
+    entry.next = undefined
+    entry.isQueued = false
+    this.count = this.count - 1
+  }
+
+  /**
+   * 取出并返回队头节点。
+   */
+  shift(): Entry | undefined {
+    const head = this.head
+    if (head === undefined) {
+      return undefined
+    }
+
+    this.remove(head)
+    return head
+  }
+}

package/src/orchestration/coordination/keyed-lock.ts

@@ -0,0 +1,168 @@
+import type { MutexAcquireOptions, MutexOptions, MutexPermit } from "./mutex.ts"
+import type { KeyedPermitDetails } from "./permit.ts"
+
+import { Mutex } from "./mutex.ts"
+import { Permit } from "./permit.ts"
+
+/**
+ * 表示 `KeyedLock` 成功获取后的释放句柄。
+ *
+ * 句柄中会保留当前命中的 key，便于调试或上层记录持锁对象。
+ */
+export type KeyedLockPermit<Key> = Permit<KeyedPermitDetails<"keyed-lock", Key>>
+
+/**
+ * 表示单个 key 对应的内部状态。
+ *
+ * 每个 key 都维护一个独立的 `Mutex`，并通过引用计数判断是否可以从状态表中清理。
+ */
+interface InternalKeyedLockState<Key> {
+  key: Key
+  mutex: Mutex
+  referenceCount: number
+}
+
+/**
+ * 表示构造 `KeyedLock` 时支持的配置。
+ *
+ * 当前直接复用 `Mutex` 的配置项，以保证每个 key 下的锁行为一致。
+ */
+export interface KeyedLockOptions extends MutexOptions {
+}
+
+/**
+ * 表示按 key 维度拆分互斥域的锁。
+ *
+ * 相同 key 的任务会串行执行，不同 key 之间则互不影响，适合做资源 ID、租户 ID、文件路径等粒度的独占控制。
+ */
+export class KeyedLock<Key> {
+  private readonly stateMap: Map<Key, InternalKeyedLockState<Key>>
+
+  private readonly mutexOptions: MutexOptions
+
+  /**
+   * 创建一个按 key 分桶的互斥锁管理器。
+   */
+  constructor(options: KeyedLockOptions = {}) {
+    this.stateMap = new Map<Key, InternalKeyedLockState<Key>>()
+    this.mutexOptions = options
+  }
+
+  /**
+   * 判断当前是否已经为指定 key 建立内部状态。
+   */
+  hasKey(key: Key): boolean {
+    return this.stateMap.has(key)
+  }
+
+  /**
+   * 读取当前仍被追踪的 key 数量。
+   */
+  getKeyCount(): number {
+    return this.stateMap.size
+  }
+
+  /**
+   * 取得指定 key 的状态；若不存在则惰性创建。
+   */
+  private getOrCreateState(key: Key): InternalKeyedLockState<Key> {
+    const existingState = this.stateMap.get(key)
+    if (existingState !== undefined) {
+      return existingState
+    }
+
+    const state: InternalKeyedLockState<Key> = {
+      key,
+      mutex: new Mutex(this.mutexOptions),
+      referenceCount: 0,
+    }
+    this.stateMap.set(key, state)
+    return state
+  }
+
+  /**
+   * 在某个 key 不再被持有且没有等待者时回收对应状态。
+   */
+  private cleanupState(state: InternalKeyedLockState<Key>): void {
+    if (state.referenceCount !== 0) {
+      return
+    }
+
+    if (state.mutex.isLocked() === true || state.mutex.getPendingCount() !== 0) {
+      return
+    }
+
+    const currentState = this.stateMap.get(state.key)
+    if (currentState === state) {
+      this.stateMap.delete(state.key)
+    }
+  }
+
+  /**
+   * 基于底层 `Mutex` permit 构造带 key 元信息的释放句柄。
+   */
+  private buildPermit(state: InternalKeyedLockState<Key>, permit: MutexPermit): KeyedLockPermit<Key> {
+    return new Permit<KeyedPermitDetails<"keyed-lock", Key>>({
+      details: {
+        coordination: "keyed-lock",
+        key: state.key,
+      },
+      duplicateReleaseMessage: "KeyedLock permit release was called more than once.",
+      onDuplicateRelease: this.mutexOptions.onDuplicateRelease,
+      onRelease: (): void => {
+        permit.release()
+        state.referenceCount = state.referenceCount - 1
+        this.cleanupState(state)
+      },
+    })
+  }
+
+  /**
+   * 尝试立即获取指定 key 的独占锁。
+   */
+  tryAcquire(key: Key): KeyedLockPermit<Key> | undefined {
+    const state = this.getOrCreateState(key)
+    const permit = state.mutex.tryAcquire()
+
+    if (permit === undefined) {
+      this.cleanupState(state)
+      return undefined
+    }
+
+    state.referenceCount = state.referenceCount + 1
+    return this.buildPermit(state, permit)
+  }
+
+  /**
+   * 等待直到成功获取指定 key 的独占锁。
+   */
+  async acquire(key: Key, options: MutexAcquireOptions = {}): Promise<KeyedLockPermit<Key>> {
+    const state = this.getOrCreateState(key)
+    state.referenceCount = state.referenceCount + 1
+
+    try {
+      const permit = await state.mutex.acquire(options)
+      return this.buildPermit(state, permit)
+    }
+    catch (error) {
+      state.referenceCount = state.referenceCount - 1
+      this.cleanupState(state)
+      throw error
+    }
+  }
+
+  /**
+   * 在指定 key 的独占锁保护下执行回调。
+   */
+  async runExclusive<T>(key: Key, callback: () => Promise<T>, options?: MutexAcquireOptions): Promise<T>
+  async runExclusive<T>(key: Key, callback: () => T, options?: MutexAcquireOptions): Promise<T>
+  async runExclusive<T>(key: Key, callback: () => Promise<T> | T, options: MutexAcquireOptions = {}): Promise<T> {
+    const permit = await this.acquire(key, options)
+    try {
+      return await callback()
+    }
+    finally {
+      permit.release()
+    }
+  }
+}

package/src/orchestration/coordination/mutex.ts

@@ -0,0 +1,257 @@
+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"
+
+/**
+ * 链表形式的等待节点。
+ *
+ * 之所以不使用数组，是因为等待中的任务可能会被 timeout 或 abort 主动取消。
+ * 使用双向链表后，任意节点都可以在 O(1) 时间内从等待队列中移除，不需要做
+ * `indexOf + splice` 这样的线性扫描。
+ */
+interface InternalMutexQueueEntry extends InternalWaitQueueEntry<InternalMutexQueueEntry>, InternalWaitConstraintsEntry {
+  resolve: (permit: MutexPermit) => void
+  reject: (reason: unknown) => void
+  isSettled: boolean
+}
+
+/**
+ * 表示获取互斥锁时可选的等待控制参数。
+ */
+export interface MutexAcquireOptions extends InternalWaitConstraintsOptions {
+  /**
+   * 等待锁的超时时间，单位为毫秒。
+   */
+  timeout?: number | undefined
+
+  /**
+   * 等待期间使用的中止信号；一旦中止，会将本次等待从队列中移除并拒绝。
+   */
+  abortSignal?: AbortSignal | undefined
+}
+
+/**
+ * 表示 `Mutex` 成功获取后的占用句柄。
+ */
+export type MutexPermit = Permit<CoordinationPermitDetails<"mutex">>
+
+const INTERNAL_MUTEX_DUPLICATE_RELEASE_MESSAGE = "Mutex permit release was called more than once."
+/**
+ * 表示 `Mutex` 在检测到重复 `release()` 误用时使用的处理函数。
+ */
+export type MutexDuplicateReleaseHandler = (message: string) => void
+/**
+ * 表示构造 `Mutex` 时可选的运行时配置。
+ */
+export interface MutexOptions {
+  /**
+   * 重复调用同一个 `release()` 时的可选处理器。
+   *
+   * 未提供时，`Mutex` 会保持静默；提供后，每个 `Mutex` 实例最多调用一次。
+   */
+  onDuplicateRelease?: MutexDuplicateReleaseHandler | undefined
+}
+
+/**
+ * 表示用于串行化异步临界区的互斥锁。
+ *
+ * @example
+ * ```
+ * const mutex = new Mutex()
+ * let counter = 0
+ *
+ * await Promise.all([
+ *   mutex.runExclusive(async () => {
+ *     const current = counter
+ *     await Promise.resolve()
+ *     counter = current + 1
+ *   }),
+ *   mutex.runExclusive(async () => {
+ *     const current = counter
+ *     await Promise.resolve()
+ *     counter = current + 1
+ *   }),
+ * ])
+ *
+ * // Expect: 2
+ * const example1 = counter
+ * ```
+ */
+export class Mutex {
+  /**
+   * 等待队列中的每个节点都代表一个尚未拿到锁的等待者。
+   */
+  private readonly queue: InternalWaitQueue<InternalMutexQueueEntry>
+
+  /**
+   * 当前是否已有持锁者进入临界区。
+   */
+  private internalIsLocked: boolean
+
+  /**
+   * 重复 release 误用的可选处理器。
+   */
+  private readonly onDuplicateRelease: MutexDuplicateReleaseHandler | undefined
+
+  constructor(options: MutexOptions = {}) {
+    this.queue = new InternalWaitQueue<InternalMutexQueueEntry>()
+    this.internalIsLocked = false
+    this.onDuplicateRelease = options.onDuplicateRelease
+  }
+
+  /**
+   * 读取当前锁是否已经被持有。
+   */
+  isLocked(): boolean {
+    return this.internalIsLocked
+  }
+
+  /**
+   * 读取当前等待队列中的任务数量。
+   */
+  getPendingCount(): number {
+    return this.queue.getCount()
+  }
+
+  /**
+   * 尝试把锁交给下一个可运行的等待者。
+   *
+   * 这里始终从队头取任务，保持 FIFO；若遇到已失效节点，则跳过直到找到下一个有效等待者。
+   */
+  private dispatch(): void {
+    if (this.internalIsLocked === true) {
+      return
+    }
+
+    while (this.queue.isEmpty() === false) {
+      const nextEntry = this.queue.shift()
+      if (nextEntry === undefined) {
+        return
+      }
+
+      if (nextEntry.isSettled === true) {
+        continue
+      }
+
+      this.internalIsLocked = true
+      nextEntry.isSettled = true
+      internalCleanupWaitConstraints(nextEntry)
+      nextEntry.resolve(this.buildPermit())
+      return
+    }
+  }
+
+  /**
+   * 为当前持锁者构造一个 permit。
+   */
+  private buildPermit(): MutexPermit {
+    return new Permit<CoordinationPermitDetails<"mutex">>({
+      details: { coordination: "mutex" },
+      duplicateReleaseMessage: INTERNAL_MUTEX_DUPLICATE_RELEASE_MESSAGE,
+      onDuplicateRelease: this.onDuplicateRelease,
+      onRelease: (): void => {
+        this.internalIsLocked = false
+        this.dispatch()
+      },
+    })
+  }
+
+  /**
+   * 以失败状态结束一个等待节点。
+   *
+   * 该逻辑会统一处理：标记结束、清理约束、从队列摘除、拒绝 Promise，最后尝试继续调度后继等待者。
+   */
+  private rejectEntry(entry: InternalMutexQueueEntry, reason: unknown): void {
+    if (entry.isSettled === true) {
+      return
+    }
+
+    entry.isSettled = true
+    internalCleanupWaitConstraints(entry)
+    this.queue.remove(entry)
+    entry.reject(reason)
+    this.dispatch()
+  }
+
+  /**
+   * 尝试立即获取锁；若当前不可用则返回 `undefined`。
+   */
+  tryAcquire(): MutexPermit | undefined {
+    if (this.internalIsLocked === true || this.queue.isEmpty() === false) {
+      return undefined
+    }
+
+    this.internalIsLocked = true
+    return this.buildPermit()
+  }
+
+  /**
+   * 等待直到成功获取锁。
+    *
+    * 当锁暂时不可用时，调用方会进入 FIFO 等待队列；一旦前面的持锁者释放，队头等待者会被唤醒。
+   */
+  async acquire(options: MutexAcquireOptions = {}): Promise<MutexPermit> {
+    internalAssertTimeoutOption("Mutex acquire", options.timeout)
+
+    internalThrowIfAborted("Mutex acquire", options.abortSignal)
+
+    const immediatePermit = this.tryAcquire()
+    if (immediatePermit !== undefined) {
+      return immediatePermit
+    }
+
+    const permit = await new Promise<MutexPermit>((resolve, reject) => {
+      const entry: InternalMutexQueueEntry = {
+        resolve,
+        reject,
+        isSettled: false,
+        isQueued: false,
+        previous: undefined,
+        next: undefined,
+        timeoutId: undefined,
+        abortSignal: undefined,
+        abortListener: undefined,
+      }
+
+      internalBindWaitConstraints(entry, options, {
+        abortOperation: "Mutex acquire",
+        timeoutOperation: "Mutex acquire",
+        onAbort: error => {
+          this.rejectEntry(entry, error)
+        },
+        onTimeout: error => {
+          this.rejectEntry(entry, error)
+        },
+      })
+      this.queue.enqueue(entry)
+      this.dispatch()
+    })
+    return permit
+  }
+
+  /**
+   * 在独占锁保护下执行回调。
+    *
+    * 无论回调成功还是抛错，permit 都会在 `finally` 中释放，避免把锁永久占住。
+   */
+  async runExclusive<T>(callback: () => Promise<T>, options?: MutexAcquireOptions): Promise<T>
+  async runExclusive<T>(callback: () => T, options?: MutexAcquireOptions): Promise<T>
+  async runExclusive<T>(callback: () => Promise<T> | T, options: MutexAcquireOptions = {}): Promise<T> {
+    const permit = await this.acquire(options)
+    try {
+      return await callback()
+    }
+    finally {
+      permit.release()
+    }
+  }
+}

package/src/orchestration/coordination/permit.ts

@@ -0,0 +1,127 @@
+const INTERNAL_DEFAULT_DUPLICATE_RELEASE_MESSAGE = "Permit release was called more than once."
+
+/**
+ * 表示 `Permit` 在检测到重复 `release()` 误用时使用的处理函数。
+ */
+export type PermitDuplicateReleaseHandler = (message: string) => void
+
+/**
+ * 表示构造 `Permit` 时的可选元信息。
+ */
+export interface PermitOptions<Details> {
+  /**
+   * `Permit` 被正常释放时的回调。
+   */
+  onRelease: () => void
+
+  /**
+   * 释放句柄附带的只读细节。
+   */
+  details?: Details | undefined
+
+  /**
+   * 重复释放时的可选处理器。
+   */
+  onDuplicateRelease?: PermitDuplicateReleaseHandler | undefined
+
+  /**
+   * 重复释放时的提示信息。
+   */
+  duplicateReleaseMessage?: string | undefined
+}
+
+/**
+ * 表示与某个协调原语关联的 permit 细节。
+ */
+export interface CoordinationPermitDetails<Coordination extends string = string> {
+  coordination: Coordination
+}
+
+/**
+ * 表示带有模式信息的 permit 细节。
+ */
+export interface ModePermitDetails<Coordination extends string, Mode extends string>
+  extends CoordinationPermitDetails<Coordination> {
+  mode: Mode
+}
+
+/**
+ * 表示带有 key 信息的 permit 细节。
+ */
+export interface KeyedPermitDetails<Coordination extends string, Key>
+  extends CoordinationPermitDetails<Coordination> {
+  key: Key
+}
+
+/**
+ * 表示一次已成功获取的协调资源占用句柄。
+ *
+ * `Permit` 本身不负责排队或调度，它只是对“当前持有一次资源”的显式表达，
+ * 并把释放动作和调试元信息封装在一起。
+ */
+export class Permit<Details = undefined> implements Disposable {
+  /**
+   * 创建该 permit 时附带的只读元信息。
+   */
+  readonly details: Details | undefined
+
+  private isReleasedValue: boolean
+
+  private readonly onRelease: () => void
+
+  private readonly onDuplicateRelease: PermitDuplicateReleaseHandler | undefined
+
+  private readonly duplicateReleaseMessage: string
+
+  /**
+   * 创建一个 permit，并绑定释放时需要执行的回调。
+   */
+  constructor(options: PermitOptions<Details>) {
+    this.details = options.details
+    this.isReleasedValue = false
+    this.onRelease = options.onRelease
+    this.onDuplicateRelease = options.onDuplicateRelease
+    this.duplicateReleaseMessage = options.duplicateReleaseMessage ?? INTERNAL_DEFAULT_DUPLICATE_RELEASE_MESSAGE
+  }
+
+  /**
+   * 读取当前 `Permit` 是否已经释放。
+   */
+  isReleased(): boolean {
+    return this.isReleasedValue
+  }
+
+  /**
+   * 读取当前 `Permit` 是否仍然有效。
+   */
+  isActive(): boolean {
+    return this.isReleasedValue === false
+  }
+
+  /**
+   * 主动释放本次占用。
+   */
+  release(): void {
+    if (this.isReleasedValue === true) {
+      this.onDuplicateRelease?.(this.duplicateReleaseMessage)
+      return
+    }
+
+    this.isReleasedValue = true
+    this.onRelease()
+  }
+
+  /**
+   * 与其他模块保持一致的显式释放别名。
+   */
+  dispose(): void {
+    this.release()
+  }
+
+  /**
+   * 支持 `using` 语法自动释放。
+   */
+  [Symbol.dispose](): void {
+    this.release()
+  }
+}