@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/src/orchestration/coordination/barrier.ts

@@ -0,0 +1,214 @@
+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 { BrokenBarrierError, CoordinationAbortError } from "./errors.ts"
+import { internalAssertTimeoutOption, internalBindWaitConstraints, internalCleanupWaitConstraints } from "./internal/wait-constraints.ts"
+
+/**
+ * 断言栅栏的参与者数量是一个有效的正整数。
+ */
+const internalAssertParticipantCount = (participantCount: number): void => {
+  if (
+    Number.isFinite(participantCount) === false
+    || Number.isInteger(participantCount) === false
+    || participantCount <= 0
+  ) {
+    throw new RangeError("Barrier participantCount must be a finite integer greater than 0.")
+  }
+}
+
+/**
+ * 表示某一代栅栏中单个等待者对应的内部节点。
+ *
+ * 每个节点既要能挂入等待队列，也要能绑定超时与中止约束，最终在整代完成或整代破坏时统一结算。
+ */
+interface InternalBarrierQueueEntry extends InternalWaitQueueEntry<InternalBarrierQueueEntry>, InternalWaitConstraintsEntry {
+  resolve: (generation: number) => void
+  reject: (reason: unknown) => void
+  isSettled: boolean
+}
+
+/**
+ * 表示调用 `Barrier.signalAndWait()` 时可选的等待约束。
+ */
+export interface BarrierWaitOptions extends InternalWaitConstraintsOptions {
+  /**
+   * 单次等待允许持续的最长时间，单位为毫秒。
+   */
+  timeout?: number | undefined
+
+  /**
+   * 用于主动中止当前等待的信号。
+   */
+  abortSignal?: AbortSignal | undefined
+}
+
+/**
+ * 表示一个循环栅栏，用于让固定数量的参与者在同一同步点会合。
+ *
+ * 每次当所有参与者都调用 `signalAndWait()` 后，当前这一代会被一次性完成，
+ * 所有等待者都会收到相同的代号，然后栅栏自动进入下一代继续复用。
+ */
+export class Barrier {
+  private readonly queue: InternalWaitQueue<InternalBarrierQueueEntry>
+
+  private internalArrivedCount: number
+
+  private internalGeneration: number
+
+  private readonly participantCount: number
+
+  /**
+   * 创建一个需要固定参与者数量才能完成一代的栅栏。
+   */
+  constructor(participantCount: number) {
+    internalAssertParticipantCount(participantCount)
+
+    this.queue = new InternalWaitQueue<InternalBarrierQueueEntry>()
+    this.internalArrivedCount = 0
+    this.internalGeneration = 0
+    this.participantCount = participantCount
+  }
+
+  /**
+   * 读取每一代完成所需的参与者总数。
+   */
+  getParticipantCount(): number {
+    return this.participantCount
+  }
+
+  /**
+   * 读取当前所处的代号。
+   *
+   * 该值会在一代正常完成或被破坏后递增。
+   */
+  getGeneration(): number {
+    return this.internalGeneration
+  }
+
+  /**
+   * 读取当前这一代中仍在等待其余参与者的任务数量。
+   */
+  getPendingCount(): number {
+    return this.queue.getCount()
+  }
+
+  /**
+   * 读取当前这一代距离完成还差多少参与者。
+   */
+  getRemainingCount(): number {
+    return this.participantCount - this.internalArrivedCount
+  }
+
+  /**
+   * 以成功状态完成当前代。
+   *
+   * 完成时会先重置计数并推进代号，再唤醒所有尚未结算的等待者，确保下一代可以立即开始接收新的参与者。
+   */
+  private completeGeneration(completedGeneration: number): void {
+    this.internalArrivedCount = 0
+    this.internalGeneration = this.internalGeneration + 1
+
+    while (this.queue.isEmpty() === false) {
+      const entry = this.queue.shift()
+      if (entry === undefined) {
+        return
+      }
+
+      if (entry.isSettled === true) {
+        continue
+      }
+
+      entry.isSettled = true
+      internalCleanupWaitConstraints(entry)
+      entry.resolve(completedGeneration)
+    }
+  }
+
+  /**
+   * 以失败状态破坏当前代。
+   *
+   * 触发 abort 或 timeout 的参与者收到其原始错误，其余同代等待者统一收到 `BrokenBarrierError`，
+   * 这样调用方可以区分“我自己失败了”与“别人导致这一代失效”。
+   */
+  private breakGeneration(failingEntry: InternalBarrierQueueEntry, reason: unknown): void {
+    if (failingEntry.isSettled === true) {
+      return
+    }
+
+    const brokenReason = new BrokenBarrierError(reason)
+    this.internalArrivedCount = 0
+    this.internalGeneration = this.internalGeneration + 1
+
+    while (this.queue.isEmpty() === false) {
+      const entry = this.queue.shift()
+      if (entry === undefined) {
+        return
+      }
+
+      if (entry.isSettled === true) {
+        continue
+      }
+
+      entry.isSettled = true
+      internalCleanupWaitConstraints(entry)
+
+      if (entry === failingEntry) {
+        entry.reject(reason)
+      }
+      else {
+        entry.reject(brokenReason)
+      }
+    }
+  }
+
+  /**
+   * 声明当前参与者已经到达同步点，并等待整代完成。
+   *
+   * 返回值是本次完成时对应的代号；如果本调用导致最后一个参与者到达，则会立即完成整代并同步返回。
+   */
+  async signalAndWait(options: BarrierWaitOptions = {}): Promise<number> {
+    internalAssertTimeoutOption("Barrier wait", options.timeout)
+
+    if (options.abortSignal?.aborted === true) {
+      throw new CoordinationAbortError("Barrier wait", options.abortSignal.reason)
+    }
+
+    const currentGeneration = this.internalGeneration
+    this.internalArrivedCount = this.internalArrivedCount + 1
+
+    if (this.internalArrivedCount === this.participantCount) {
+      this.completeGeneration(currentGeneration)
+      return currentGeneration
+    }
+
+    const generation = await new Promise<number>((resolve, reject) => {
+      const entry: InternalBarrierQueueEntry = {
+        resolve,
+        reject,
+        isSettled: false,
+        isQueued: false,
+        previous: undefined,
+        next: undefined,
+        timeoutId: undefined,
+        abortSignal: undefined,
+        abortListener: undefined,
+      }
+
+      internalBindWaitConstraints(entry, options, {
+        abortOperation: "Barrier wait",
+        timeoutOperation: "Barrier wait",
+        onAbort: error => {
+          this.breakGeneration(entry, error)
+        },
+        onTimeout: error => {
+          this.breakGeneration(entry, error)
+        },
+      })
+      this.queue.enqueue(entry)
+    })
+
+    return generation
+  }
+}

package/src/orchestration/coordination/count-down-latch.ts

@@ -0,0 +1,215 @@
+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 {
+  internalAssertTimeoutOption,
+  internalBindWaitConstraints,
+  internalCleanupWaitConstraints,
+  internalThrowIfAborted,
+} from "./internal/wait-constraints.ts"
+
+/**
+ * 断言闭锁初始计数为合法的非负整数。
+ */
+const internalAssertInitialCount = (count: number): void => {
+  if (
+    Number.isFinite(count) === false
+    || Number.isInteger(count) === false
+    || count < 0
+  ) {
+    throw new RangeError("CountDownLatch initialCount must be a finite integer greater than or equal to 0.")
+  }
+}
+
+/**
+ * 断言单次递减步长为合法的正整数。
+ */
+const internalAssertDelta = (count: number): void => {
+  if (
+    Number.isFinite(count) === false
+    || Number.isInteger(count) === false
+    || count <= 0
+  ) {
+    throw new RangeError("CountDownLatch count must be a finite integer greater than 0.")
+  }
+}
+
+/**
+ * 表示 `CountDownLatch` 等待者在内部队列中的节点。
+ */
+interface InternalCountDownLatchQueueEntry extends InternalWaitQueueEntry<InternalCountDownLatchQueueEntry>, InternalWaitConstraintsEntry {
+  resolve: () => void
+  reject: (reason: unknown) => void
+  isSettled: boolean
+}
+
+/**
+ * 表示调用 `CountDownLatch.wait()` 时可选的等待约束。
+ */
+export interface CountDownLatchWaitOptions extends InternalWaitConstraintsOptions {
+  /**
+   * 等待闭锁打开的最长时间，单位为毫秒。
+   */
+  timeout?: number | undefined
+
+  /**
+   * 用于主动取消等待的信号。
+   */
+  abortSignal?: AbortSignal | undefined
+}
+
+/**
+ * 表示一个倒计时闭锁。
+ *
+ * 闭锁在剩余计数降到 0 前保持关闭，所有等待者都会被挂起；
+ * 一旦打开，当前及后续等待都会立即通过，且该实例不会再次关闭。
+ */
+export class CountDownLatch {
+  private readonly queue: InternalWaitQueue<InternalCountDownLatchQueueEntry>
+
+  private internalRemainingCount: number
+
+  /**
+   * 使用给定初始计数创建闭锁。
+   */
+  constructor(initialCount: number) {
+    internalAssertInitialCount(initialCount)
+
+    this.queue = new InternalWaitQueue<InternalCountDownLatchQueueEntry>()
+    this.internalRemainingCount = initialCount
+  }
+
+  /**
+   * 判断闭锁是否已经打开。
+   */
+  isOpen(): boolean {
+    return this.internalRemainingCount === 0
+  }
+
+  /**
+   * 以同步方式检测当前是否可以继续执行而无需等待。
+   */
+  tryWait(): boolean {
+    return this.internalRemainingCount === 0
+  }
+
+  /**
+   * 读取距离打开闭锁还差多少次 `countDown()`。
+   */
+  getRemainingCount(): number {
+    return this.internalRemainingCount
+  }
+
+  /**
+   * 读取当前挂起的等待者数量。
+   */
+  getPendingCount(): number {
+    return this.queue.getCount()
+  }
+
+  /**
+   * 在闭锁打开时一次性唤醒全部等待者。
+   */
+  private resolveAll(): void {
+    while (this.queue.isEmpty() === false) {
+      const entry = this.queue.shift()
+      if (entry === undefined) {
+        return
+      }
+
+      if (entry.isSettled === true) {
+        continue
+      }
+
+      entry.isSettled = true
+      internalCleanupWaitConstraints(entry)
+      entry.resolve()
+    }
+  }
+
+  /**
+   * 以失败状态结束指定等待者，并从队列中摘除。
+   */
+  private rejectEntry(entry: InternalCountDownLatchQueueEntry, reason: unknown): void {
+    if (entry.isSettled === true) {
+      return
+    }
+
+    entry.isSettled = true
+    internalCleanupWaitConstraints(entry)
+    this.queue.remove(entry)
+    entry.reject(reason)
+  }
+
+  /**
+   * 将闭锁剩余计数减少指定值。
+   *
+   * 当剩余计数降到 0 时，所有等待者会立即被放行。
+   */
+  countDown(count: number = 1): number {
+    internalAssertDelta(count)
+
+    if (this.internalRemainingCount === 0) {
+      return 0
+    }
+
+    this.internalRemainingCount = Math.max(0, this.internalRemainingCount - count)
+
+    if (this.internalRemainingCount === 0) {
+      this.resolveAll()
+    }
+
+    return this.internalRemainingCount
+  }
+
+  /**
+   * `countDown()` 的语义化别名，用于强调“到达一次事件”。
+   */
+  arrive(count: number = 1): number {
+    return this.countDown(count)
+  }
+
+  /**
+   * 等待直到闭锁打开。
+   */
+  async wait(options: CountDownLatchWaitOptions = {}): Promise<void> {
+    internalAssertTimeoutOption("CountDownLatch wait", options.timeout)
+
+    internalThrowIfAborted("CountDownLatch wait", options.abortSignal)
+
+    if (this.internalRemainingCount === 0) {
+      return
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      const entry: InternalCountDownLatchQueueEntry = {
+        resolve,
+        reject,
+        isSettled: false,
+        isQueued: false,
+        previous: undefined,
+        next: undefined,
+        timeoutId: undefined,
+        abortSignal: undefined,
+        abortListener: undefined,
+      }
+
+      internalBindWaitConstraints(entry, options, {
+        abortOperation: "CountDownLatch wait",
+        timeoutOperation: "CountDownLatch wait",
+        onAbort: error => {
+          this.rejectEntry(entry, error)
+        },
+        onTimeout: error => {
+          this.rejectEntry(entry, error)
+        },
+      })
+      this.queue.enqueue(entry)
+
+      if (this.internalRemainingCount === 0) {
+        this.resolveAll()
+      }
+    })
+  }
+}

package/src/orchestration/coordination/errors.ts

@@ -0,0 +1,98 @@
+/**
+ * 把可读的失败原因拼接到错误消息中。
+ *
+ * 这里尽量保留基础类型与 `Error.message`，避免把复杂对象直接序列化成噪音文本。
+ */
+const internalAppendReasonMessage = (message: string, reason: unknown): string => {
+  if (reason === undefined) {
+    return message
+  }
+
+  if (reason instanceof Error && reason.message !== "") {
+    return `${message} ${reason.message}`
+  }
+
+  if (
+    typeof reason === "string"
+    || typeof reason === "number"
+    || typeof reason === "boolean"
+    || typeof reason === "bigint"
+    || typeof reason === "symbol"
+  ) {
+    return `${message} ${String(reason)}`
+  }
+
+  return message
+}
+
+/**
+ * 表示协调原语等待过程中的中止错误。
+ */
+export class CoordinationAbortError extends Error {
+  /**
+   * 触发中止的操作名称。
+   */
+  readonly operation: string
+
+  /**
+   * 中止信号携带的原始原因。
+   */
+  readonly reason: unknown
+
+  /**
+   * 创建一个表示等待被主动中止的错误。
+   */
+  constructor(operation: string, reason: unknown) {
+    super(internalAppendReasonMessage(`${operation} aborted.`, reason))
+    this.name = "CoordinationAbortError"
+    Object.setPrototypeOf(this, new.target.prototype)
+    this.operation = operation
+    this.reason = reason
+  }
+}
+
+/**
+ * 表示协调原语等待过程中的超时错误。
+ */
+export class CoordinationTimeoutError extends Error {
+  /**
+   * 发生超时的操作名称。
+   */
+  readonly operation: string
+
+  /**
+   * 触发超时时等待的毫秒数。
+   */
+  readonly timeout: number
+
+  /**
+   * 创建一个表示等待超时的错误。
+   */
+  constructor(operation: string, timeout: number) {
+    super(`${operation} timeout after ${timeout}ms.`)
+    this.name = "CoordinationTimeoutError"
+    Object.setPrototypeOf(this, new.target.prototype)
+    this.operation = operation
+    this.timeout = timeout
+  }
+}
+
+/**
+ * 表示栅栏某一代被参与者破坏后的错误。
+ */
+export class BrokenBarrierError extends Error {
+  /**
+   * 导致当前栅栏代失效的原始原因。
+   */
+  readonly reason: unknown
+
+  /**
+   * 创建一个表示“当前代已被其他参与者破坏”的错误。
+   */
+  constructor(reason: unknown) {
+    super(internalAppendReasonMessage("Barrier generation was broken by another participant.", reason))
+    this.name = "BrokenBarrierError"
+    Object.setPrototypeOf(this, new.target.prototype)
+    this.reason = reason
+  }
+}

package/src/orchestration/coordination/index.ts

@@ -0,0 +1,16 @@
+export * from "./errors.ts"
+
+/**
+ * 栅栏与闭锁类原语。
+ */
+export * from "./barrier.ts"
+export * from "./count-down-latch.ts"
+
+/**
+ * permit 与各类锁/信号量原语。
+ */
+export * from "./permit.ts"
+export * from "./mutex.ts"
+export * from "./semaphore.ts"
+export * from "./keyed-lock.ts"
+export * from "./read-write-lock.ts"

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

@@ -0,0 +1,95 @@
+import { CoordinationAbortError, CoordinationTimeoutError } from "../errors.ts"
+
+/**
+ * 表示等待节点上与 timeout / abort 绑定相关的内部状态。
+ */
+export interface InternalWaitConstraintsEntry {
+  timeoutId: ReturnType<typeof setTimeout> | undefined
+  abortSignal: AbortSignal | undefined
+  abortListener: (() => void) | undefined
+}
+
+/**
+ * 表示等待约束的输入参数。
+ */
+export interface InternalWaitConstraintsOptions {
+  timeout?: number | undefined
+  abortSignal?: AbortSignal | undefined
+}
+
+/**
+ * 表示将等待约束绑定到某个节点时需要提供的回调集合。
+ */
+export interface InternalWaitConstraintBindings {
+  abortOperation: string
+  timeoutOperation: string
+  onAbort: (error: CoordinationAbortError) => void
+  onTimeout: (error: CoordinationTimeoutError) => void
+}
+
+/**
+ * 断言 timeout 参数是合法的非负有限数值。
+ */
+export const internalAssertTimeoutOption = (operation: string, timeout: number | undefined): void => {
+  if (timeout === undefined) {
+    return
+  }
+
+  if (Number.isFinite(timeout) === false || timeout < 0) {
+    throw new RangeError(`${operation} timeout must be a finite number greater than or equal to 0.`)
+  }
+}
+
+/**
+ * 如果传入的 `AbortSignal` 已经处于中止状态，则立即抛出中止错误。
+ */
+export const internalThrowIfAborted = (operation: string, abortSignal: AbortSignal | undefined): void => {
+  if (abortSignal?.aborted === true) {
+    throw new CoordinationAbortError(operation, abortSignal.reason)
+  }
+}
+
+/**
+ * 清理已经绑定到等待节点上的超时器与中止监听器。
+ *
+ * 该函数应当在节点成功结算或失败结算时都被调用，以避免悬挂的定时器与事件监听器泄漏。
+ */
+export const internalCleanupWaitConstraints = (entry: InternalWaitConstraintsEntry): void => {
+  if (entry.timeoutId !== undefined) {
+    clearTimeout(entry.timeoutId)
+    entry.timeoutId = undefined
+  }
+
+  if (entry.abortSignal !== undefined && entry.abortListener !== undefined) {
+    entry.abortSignal.removeEventListener("abort", entry.abortListener)
+    entry.abortSignal = undefined
+    entry.abortListener = undefined
+  }
+}
+
+/**
+ * 把 timeout 与 abort 约束绑定到某个等待节点。
+ *
+ * 绑定本身只负责注册外部约束，真正如何让节点失败由调用方通过 `bindings` 中的回调决定。
+ */
+export const internalBindWaitConstraints = (
+  entry: InternalWaitConstraintsEntry,
+  options: InternalWaitConstraintsOptions,
+  bindings: InternalWaitConstraintBindings,
+): void => {
+  const { abortSignal, timeout } = options
+
+  if (abortSignal !== undefined) {
+    entry.abortSignal = abortSignal
+    entry.abortListener = (): void => {
+      bindings.onAbort(new CoordinationAbortError(bindings.abortOperation, abortSignal.reason))
+    }
+    abortSignal.addEventListener("abort", entry.abortListener, { once: true })
+  }
+
+  if (timeout !== undefined) {
+    entry.timeoutId = setTimeout(() => {
+      bindings.onTimeout(new CoordinationTimeoutError(bindings.timeoutOperation, timeout))
+    }, timeout)
+  }
+}