@zk-tech/bedrock 0.0.1

package/src/launch/job-scheduler.test.ts

@@ -0,0 +1,122 @@
+import { JobScheduler } from './job-scheduler';
+import { AbstractJob } from './abstract-job';
+import { InstantiationService } from '@/di';
+
+enum Lifecycle {
+  A,
+  B,
+  C,
+}
+
+class Job1 extends AbstractJob<Lifecycle> {
+  protected _name = 'job1';
+
+  constructor(private readonly _fn: () => void) {
+    super();
+  }
+
+  protected _executePhase(phase: Lifecycle) {
+    switch (phase) {
+      case Lifecycle.A:
+      case Lifecycle.B:
+        this._fn();
+        break;
+      default:
+        return;
+    }
+  }
+}
+
+class Job2 extends AbstractJob<Lifecycle> {
+  protected _name = 'job2';
+
+  constructor(private readonly _fn: () => void) {
+    super();
+  }
+
+  protected _executePhase(phase: Lifecycle) {
+    switch (phase) {
+      case Lifecycle.C:
+        this._fn();
+        break;
+      default:
+        return;
+    }
+  }
+}
+
+class Job3 extends AbstractJob<Lifecycle> {
+  protected _name = 'job3';
+
+  constructor(private readonly _fn: () => void) {
+    super();
+    this._fn();
+  }
+
+  protected _executePhase(phase: Lifecycle) {
+    // donothing
+  }
+}
+
+describe('jobscheduler', () => {
+  it('addJob', async () => {
+    const fn1 = vi.fn();
+    const fn2 = vi.fn();
+    const instantiationService = new InstantiationService();
+    const jobScheduler = instantiationService.createInstance(JobScheduler, Lifecycle.A);
+    jobScheduler.addJob(new Job1(fn1));
+    jobScheduler.addJob(new Job2(fn2));
+
+    jobScheduler.prepare(Lifecycle.A);
+    await jobScheduler.wait(Lifecycle.A);
+
+    jobScheduler.prepare(Lifecycle.B);
+    await jobScheduler.wait(Lifecycle.B);
+
+    jobScheduler.prepare(Lifecycle.C);
+    await jobScheduler.wait(Lifecycle.C);
+
+    expect(fn1).toBeCalledTimes(2);
+    expect(fn2).toBeCalledTimes(1);
+  });
+
+  it('registerJob', async () => {
+    const fn1 = vi.fn();
+    const fn2 = vi.fn();
+    const instantiationService = new InstantiationService();
+    const jobScheduler = instantiationService.createInstance(JobScheduler, Lifecycle.A);
+    jobScheduler.registerJob(Lifecycle.A, Job1, fn1);
+    jobScheduler.registerJob(Lifecycle.B, Job2, fn2);
+
+    jobScheduler.prepare(Lifecycle.A);
+    await jobScheduler.wait(Lifecycle.A);
+
+    jobScheduler.prepare(Lifecycle.B);
+    await jobScheduler.wait(Lifecycle.B);
+
+    jobScheduler.prepare(Lifecycle.C);
+    await jobScheduler.wait(Lifecycle.C);
+
+    expect(fn1).toBeCalledTimes(2);
+    expect(fn2).toBeCalledTimes(1);
+  });
+
+  it('delayConstructJob', async () => {
+    const fn = vi.fn();
+    const instantiationService = new InstantiationService();
+    const jobScheduler = instantiationService.createInstance(JobScheduler, Lifecycle.A);
+    jobScheduler.registerJob(Lifecycle.C, Job3, fn);
+
+    jobScheduler.prepare(Lifecycle.A);
+    await jobScheduler.wait(Lifecycle.A);
+    expect(fn).not.toBeCalled();
+
+    jobScheduler.prepare(Lifecycle.B);
+    await jobScheduler.wait(Lifecycle.B);
+    expect(fn).not.toBeCalled();
+
+    jobScheduler.prepare(Lifecycle.C);
+    await jobScheduler.wait(Lifecycle.C);
+    expect(fn).toBeCalled();
+  });
+});

package/src/launch/job-scheduler.ts

@@ -0,0 +1,118 @@
+import { IInstantiationService, type GetLeadingNonServiceArgs } from '@/di';
+import { lvAssert, lvAssertNotHere } from '@/assert';
+import type { AbstractJob } from './abstract-job';
+import { CostRecorder } from './cost-recorder';
+
+class JobDescriptor<T, K extends T> {
+  readonly ctor: new (...args: any[]) => AbstractJob<T, K>;
+  readonly staticArguments: any[];
+
+  constructor(ctor: new (...args: any[]) => AbstractJob<T, K>, args: any[]) {
+    this.ctor = ctor;
+    this.staticArguments = args;
+  }
+}
+
+export class JobScheduler<T, K extends T = T> {
+  private readonly _jobPools: Map<string, AbstractJob<T, K>> = new Map();
+  private readonly _costRecorder = new CostRecorder();
+  private readonly _unconstructedJobs: Map<K, JobDescriptor<AbstractJob<T, K>, any>[]> = new Map();
+
+  constructor(
+    private _currentPhase: K,
+    @IInstantiationService private readonly _instantiationService: IInstantiationService,
+  ) {}
+
+  get currentPhase() {
+    return this._currentPhase;
+  }
+
+  /**
+   * 按需添加一个job，job会在phase时刻才进行实例化
+   * @param phase job实例化时机
+   * @param ctor job构造函数
+   * @param args job构造静态参数
+   */
+  registerJob<Ctor extends new (...args: any[]) => AbstractJob<T, K>>(
+    phase: K,
+    ctor: Ctor,
+    ...args: GetLeadingNonServiceArgs<ConstructorParameters<Ctor>>
+  ) {
+    if (!this._unconstructedJobs.has(phase)) {
+      this._unconstructedJobs.set(phase, [new JobDescriptor(ctor, args)]);
+    } else {
+      this._unconstructedJobs.get(phase)!.push(new JobDescriptor(ctor, args));
+    }
+  }
+
+  /**
+   * 添加一个构造好的job
+   * @param job 任务
+   */
+  addJob(job: AbstractJob<T, K>) {
+    lvAssert(!this._jobPools.has(job.name), 'cant duplicate add job.');
+    this._jobPools.set(job.name, job);
+  }
+
+  removeJob(jobName: string) {
+    this._jobPools.delete(jobName);
+  }
+
+  prepare(phase: K) {
+    const descriptors = this._unconstructedJobs.get(phase) ?? [];
+    for (const d of descriptors) {
+      this.addJob(this._instantiationService.createInstance(d.ctor, ...d.staticArguments));
+    }
+    let shouldWait = false;
+    this._unconstructedJobs.delete(phase);
+    for (const [, job] of this._jobPools) {
+      const start = Date.now();
+      job.prepare(phase);
+      this._costRecorder.record(job.name, phase as number | string, Date.now() - start);
+
+      if (job.shouldWait(phase)) {
+        shouldWait = true;
+      }
+    }
+
+    return shouldWait;
+  }
+
+  getCost() {
+    return this._costRecorder.toString();
+  }
+
+  /**
+   * 推进到目标阶段，要求目标阶段没有需要等待的任务
+   * @param phase 目标阶段
+   */
+  advanceToPhase(phase: K) {
+    for (const [, job] of this._jobPools) {
+      if (job.shouldWait(phase)) {
+        lvAssertNotHere(`exists job should wait, job name: ${job.name}, phase: ${phase}`);
+      }
+    }
+
+    this._currentPhase = phase;
+  }
+
+  async wait(phase: K) {
+    const jobPromises: Promise<void>[] = [];
+    for (const [, job] of this._jobPools) {
+      if (!job.shouldWait(phase)) {
+        continue;
+      }
+      jobPromises.push(
+        (() => {
+          const start = Date.now();
+          return job.wait(phase).then(() => {
+            this._costRecorder.record(job.name, phase as number | string, Date.now() - start);
+          });
+        })(),
+      );
+    }
+
+    await Promise.all(jobPromises);
+    this._currentPhase = phase;
+  }
+}

package/src/launch/node_modules/.vitest/deps/_metadata.json

@@ -0,0 +1,8 @@
+{
+  "hash": "ec1fa8f3",
+  "configHash": "a2dd8394",
+  "lockfileHash": "d75a6bc5",
+  "browserHash": "cb29fc16",
+  "optimized": {},
+  "chunks": {}
+}

package/src/launch/node_modules/.vitest/deps/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/src/launch/node_modules/.vitest/results.json

@@ -0,0 +1 @@
+{"version":"1.0.1","results":[[":job-scheduler.test.ts",{"duration":2,"failed":false}]]}

package/src/lock/README.md

@@ -0,0 +1,11 @@
+# 读写锁
+TODO(niurouwan): 补上
+
+## 核心
+- 写写互斥、读写互斥，读读可重入  
+- 写者优先于读者  
+- 写者唤醒顺序按调用顺序来  
+
+## 实现原理
+
+## 使用举例

package/src/lock/capability.test.ts

@@ -0,0 +1,110 @@
+import { CapabilityStatus, Capability, SharedCapability } from './capability';
+
+describe('Capability', () => {
+  // 初始化
+  it('init', () => {
+    const capability = new Capability();
+    // 初始化完成，默认是没有锁状态
+    expect(capability.status).toBe(CapabilityStatus.Unlocked);
+  });
+
+  // 获取控制权成功
+  it('acquire success', () => {
+    const capability = new Capability();
+    expect(capability.status).toBe(CapabilityStatus.Unlocked);
+    capability.acquire();
+    expect(capability.status).toBe(CapabilityStatus.Locked);
+  });
+
+  // 获取控制权失败
+  it('acquire fail', () => {
+    const capability = new Capability();
+    capability.acquire();
+    expect(() => {
+      capability.acquire();
+    }).toThrowError();
+  });
+
+  // 释放控制权成功
+  it('release success', () => {
+    let locked = false;
+    const capability = new Capability();
+    capability.onUnlocked(() => {
+      locked = false;
+    });
+    expect(capability.status).toBe(CapabilityStatus.Unlocked);
+    capability.acquire();
+    locked = true;
+    expect(capability.status).toBe(CapabilityStatus.Locked);
+    expect(locked).toBeTruthy();
+
+    capability.release();
+    expect(capability.status).toBe(CapabilityStatus.Unlocked);
+    expect(locked).toBeFalsy();
+  });
+
+  // 直接释放控制权失败
+  it('release fail1', () => {
+    const capability = new Capability();
+    expect(() => {
+      capability.release();
+    }).toThrowError();
+  });
+
+  // 重复释放控制权失败
+  it('release fail2', () => {
+    const capability = new Capability();
+    capability.acquire();
+    capability.release();
+    expect(() => {
+      capability.release();
+    }).toThrowError();
+  });
+});
+
+describe('SharedCapability', () => {
+  // 初始化
+  it('init', () => {
+    const capability = new SharedCapability();
+    // 初始化完成，默认是没有锁状态
+    expect(capability.status).toBe(CapabilityStatus.Unlocked);
+  });
+
+  // 获取控制权成功
+  it('acquire success', () => {
+    const capability = new SharedCapability();
+    capability.acquire();
+    expect(capability.status).toBe(CapabilityStatus.Locked);
+    expect(() => {
+      capability.acquire();
+    }).not.toThrowError();
+  });
+
+  // 释放控制权成功
+  it('release success', () => {
+    const capability = new SharedCapability();
+    capability.acquire();
+    expect(capability.status).toBe(CapabilityStatus.Locked);
+    capability.acquire();
+    expect(() => {
+      capability.release();
+      capability.release();
+    }).not.toThrowError();
+    expect(capability.status).toBe(CapabilityStatus.Unlocked);
+  });
+
+  // 释放控制权失败
+  it('release fail', () => {
+    const capability = new SharedCapability();
+    capability.acquire();
+    expect(capability.status).toBe(CapabilityStatus.Locked);
+    capability.acquire();
+    expect(() => {
+      capability.release();
+      capability.release();
+    }).not.toThrowError();
+    expect(() => {
+      capability.release();
+    }).toThrowError();
+  });
+});

package/src/lock/capability.ts

@@ -0,0 +1,89 @@
+import { lvAssert } from '@/assert';
+import { Emitter, type Event } from '@/event';
+
+//
+// 资源对应的是标准库中的 unsigned state 以及相关的位运算
+// 我们用两个具体的Capability结构实现（Capability命名来源于标准库）
+//
+
+/**
+ * 资源状态
+ */
+export enum CapabilityStatus {
+  Unlocked,
+  Locked,
+}
+
+/**
+ * 独享的资源
+ *
+ * acquire 获取控制权
+ * release 释放控制权
+ */
+export class Capability {
+  public onUnlocked: Event<[]>;
+
+  private readonly _onUnlocked = new Emitter<[]>();
+  private _status = CapabilityStatus.Unlocked;
+
+  constructor() {
+    this.onUnlocked = this._onUnlocked.event;
+  }
+
+  get status(): CapabilityStatus {
+    return this._status;
+  }
+
+  public acquire(): void {
+    lvAssert(this._status === CapabilityStatus.Unlocked);
+    this._status = CapabilityStatus.Locked;
+  }
+
+  public release(): void {
+    lvAssert(this._status === CapabilityStatus.Locked);
+    this._status = CapabilityStatus.Unlocked;
+    this._onUnlocked.fire();
+  }
+}
+
+/**
+ * 共享的资源
+ *
+ * acquire 获取控制权
+ * release 释放控制权
+ */
+export class SharedCapability {
+  public onUnlocked: Event<[]>;
+
+  private readonly _onUnlocked = new Emitter<[]>();
+  private _status = CapabilityStatus.Unlocked;
+  private _counter = 0;
+
+  constructor() {
+    this.onUnlocked = this._onUnlocked.event;
+  }
+
+  get status(): CapabilityStatus {
+    return this._status;
+  }
+
+  get counter(): number {
+    return this._counter;
+  }
+
+  public acquire() {
+    if (this._status === CapabilityStatus.Unlocked) {
+      this._status = CapabilityStatus.Locked;
+    }
+    this._counter++;
+  }
+
+  public release() {
+    lvAssert(this._counter > 0);
+    this._counter--;
+    if (this._counter === 0) {
+      this._status = CapabilityStatus.Unlocked;
+      this._onUnlocked.fire();
+    }
+  }
+}

package/src/lock/index.ts

@@ -0,0 +1,15 @@
+// 读写能力的互斥量，实现读写锁的能力
+export { SharedMutex } from './shared-mutex';
+
+// 可解锁的句柄
+export type { IUnlockable } from './utils';
+
+// 转移独享锁控制权
+export { transferLock } from './utils';
+// 尝试转移独享锁控制权
+export { tryTransferLock } from './utils';
+
+// 转移共享锁控制权
+export { transferSharedLock } from './utils';
+// 尝试转移共享锁控制权
+export { tryTransferSharedLock } from './utils';

package/src/lock/node_modules/.vitest/results.json

@@ -0,0 +1 @@
+{"version":"1.0.1","results":[]}

package/src/lock/semaphore.ts

@@ -0,0 +1,21 @@
+import type { Event } from '@/event';
+import { Emitter } from '@/event';
+
+/**
+ * 信号
+ *
+ * 用来模拟标准库的condition_variable
+ * 提供监听某个信号被激活的能力
+ */
+export class Semaphore {
+  public onActive: Event<[]>;
+  private readonly _onActive = new Emitter<[]>();
+
+  constructor() {
+    this.onActive = this._onActive.event;
+  }
+
+  public notify(): void {
+    this._onActive.fire();
+  }
+}