@dxos/async 0.10.0 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/async",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Async utilities.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -14,12 +14,14 @@
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "browser": "./dist/lib/browser/index.mjs",
-      "node": {
-        "require": "./dist/lib/node/index.cjs",
-        "default": "./dist/lib/node-esm/index.mjs"
-      }
+      "import": "./dist/lib/index.mjs"
+    },
+    "./testing": {
+      "source": "./src/test-stream.ts",
+      "types": "./dist/types/src/test-stream.d.ts",
+      "import": "./dist/lib/testing.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -30,12 +32,12 @@
   "dependencies": {
     "zen-observable": "^0.10.0",
     "zen-push": "^0.3.1",
-    "@dxos/context": "0.10.0",
-    "@dxos/debug": "0.10.0",
-    "@dxos/invariant": "0.10.0",
-    "@dxos/log": "0.10.0",
-    "@dxos/node-std": "0.10.0",
-    "@dxos/util": "0.10.0"
+    "@dxos/context": "0.11.1",
+    "@dxos/debug": "0.11.1",
+    "@dxos/invariant": "0.11.1",
+    "@dxos/log": "0.11.1",
+    "@dxos/node-std": "0.11.1",
+    "@dxos/util": "0.11.1"
   },
   "devDependencies": {
     "@types/zen-observable": "^0.8.3"

package/src/index.ts

@@ -16,7 +16,6 @@ export * from './persistent-lifecycle';
 export * from './push-iterable';
 export * from './stream-to-array';
 export * from './task-scheduling';
-export * from './test-stream';
 export * from './testing';
 export * from './timeout';
 export * from './timer';

package/src/task-scheduling.ts

@@ -40,6 +40,10 @@ export class DeferredTask {
 
     scheduleTask(this._ctx, async () => {
       // The previous task might still be running, so we need to wait for it to finish.
+      //
+      // A single await suffices only because this is the one claim site and `_scheduled` collapses
+      // schedules into one waiter. A second path claiming `_currentTask` directly would let two
+      // callbacks run at once — see dxos/edge#758.
       await this._currentTask; // Can't be rejected.
 
       // Reset the flag. New tasks can now be scheduled. They would wait for the callback to finish.

package/src/update-scheduler.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { describe, expect, test } from 'vitest';
+import { describe, test } from 'vitest';
 
 import { Context } from '@dxos/context';
 
@@ -10,7 +10,7 @@ import { sleep } from './timeout';
 import { UpdateScheduler } from './update-scheduler';
 
 describe('update-scheduler', () => {
-  test('schedules updates', async () => {
+  test('schedules updates', async ({ expect }) => {
     let updates = 0;
 
     const ctx = new Context();
@@ -24,4 +24,194 @@ describe('update-scheduler', () => {
     await sleep(5);
     expect(updates).to.eq(1);
   });
+
+  // The flush-barrier contract: when `runBlocking` resolves, everything that was queued at call time
+  // has been fully processed — not claimed by a still-running pass the barrier failed to observe.
+  test('runBlocking does not resolve while a pass that claimed the queue is still in flight', async ({ expect }) => {
+    const ctx = new Context();
+    const queue: string[] = [];
+    const processed: string[] = [];
+    let inFlight = 0;
+    const gate = { resolve: () => {} };
+    const scheduler: UpdateScheduler = new UpdateScheduler(ctx, async () => {
+      const claimed = queue.splice(0, queue.length); // Claim synchronously, like _sendUpdates.
+      inFlight += claimed.length;
+      if (claimed.length > 0) {
+        await new Promise<void>((resolve) => {
+          gate.resolve = resolve;
+          setTimeout(resolve, 50); // The claimed batch takes real time to deliver.
+        });
+      }
+      processed.push(...claimed);
+      inFlight -= claimed.length;
+    });
+
+    // A long pass is running (claimed nothing of interest)...
+    queue.push('warmup');
+    scheduler.trigger();
+    await sleep(5);
+
+    // ...now the real work arrives; a trigger parks behind the running pass...
+    queue.push('document-data');
+    scheduler.trigger();
+    await sleep(0); // Let the trigger's task start and park on the running pass, as in production.
+
+    // ...and a flush arrives after it.
+    await scheduler.runBlocking();
+
+    // Everything that was queued when runBlocking was called must be fully processed — not claimed
+    // by a still-running pass the barrier failed to observe.
+    expect(inFlight, 'runBlocking resolved with a claimed batch still in flight').toEqual(0);
+    expect(processed).toContain('document-data');
+    await ctx.dispose();
+  });
+
+  // The callback is not reentrant: it typically drains shared queued state, so two passes running at
+  // once each claim part of the queue. Historically a throttled `trigger` checked for a running pass
+  test('the callback does not overlap itself when runBlocking races a throttled trigger', async ({ expect }) => {
+    const ctx = new Context();
+    let calls = 0;
+    let active = 0;
+    let maxActive = 0;
+    const scheduler = new UpdateScheduler(
+      ctx,
+      async () => {
+        const call = ++calls;
+        active++;
+        maxActive = Math.max(maxActive, active);
+        // Make the `runBlocking` pass outlast the triggered pass's throttle delay.
+        await sleep(call === 2 ? 200 : 10);
+        active--;
+      },
+      { maxFrequency: 10 }, // 100ms between passes.
+    );
+
+    // First pass consumes the throttle allowance, so the next `trigger` has to wait one out.
+    scheduler.trigger();
+    await sleep(40);
+
+    scheduler.trigger(); // Parks in its delay, having seen nothing running.
+    const blocking = scheduler.runBlocking(); // Starts a long pass while it sleeps.
+    await blocking;
+    await sleep(300); // Let the triggered pass run.
+
+    expect(calls, 'the coalesced flush run must have happened').toBeGreaterThanOrEqual(2);
+    expect(maxActive, 'two callbacks ran at once').toEqual(1);
+    await ctx.dispose();
+  });
+
+  // `runBlocking` is a flush barrier: a caller must observe that its batch was NOT handed off. The
+  // error belongs to the callers waiting on that run — and must not poison later barriers (a
+  // retained rejected pass would make `join`/dispose throw someone else's stale error).
+  test('runBlocking rejects with its run error and later barriers stay clean', async ({ expect }) => {
+    const ctx = new Context();
+    let fail = true;
+    const scheduler = new UpdateScheduler(ctx, async () => {
+      if (fail) {
+        throw new Error('send failed');
+      }
+    });
+
+    await expect(scheduler.runBlocking()).rejects.toThrow('send failed');
+
+    fail = false;
+    await expect(scheduler.join()).resolves.toBeUndefined();
+    await expect(scheduler.runBlocking()).resolves.toBeUndefined();
+    await ctx.dispose();
+  });
+
+  // The outcome handle must be read AFTER `trigger()`: when a run is already in flight the handle is
+  // still the finished-and-woken one from that run, so reading it first would return immediately and
+  // report a flush that never covered the caller's work.
+  test('runBlocking waits for a run that starts after it, not one already in flight', async ({ expect }) => {
+    const ctx = new Context();
+    const queue: string[] = [];
+    const drained: string[][] = [];
+    const scheduler = new UpdateScheduler(ctx, async () => {
+      drained.push(queue.splice(0, queue.length));
+      await sleep(30);
+    });
+
+    queue.push('first');
+    scheduler.trigger();
+    await sleep(5); // The first run has claimed 'first' and is still in flight.
+
+    queue.push('second'); // Enqueued while that run is running, so it cannot be in its drain.
+    await scheduler.runBlocking();
+
+    expect(drained.flat(), 'runBlocking resolved without draining later work').toContain('second');
+    await ctx.dispose();
+  });
+
+  // Concurrent flushes coalesce onto one run that observes everything enqueued before either call —
+  // they are all asking the same question ("has what I queued been handed off?"), so one drain
+  // answers all of them.
+  test('concurrent runBlocking callers coalesce into a single run', async ({ expect }) => {
+    const ctx = new Context();
+    const queue: string[] = [];
+    const drained: string[][] = [];
+    const scheduler = new UpdateScheduler(ctx, async () => {
+      drained.push(queue.splice(0, queue.length));
+      await sleep(10);
+    });
+
+    queue.push('a', 'b');
+    await Promise.all([scheduler.runBlocking(), scheduler.runBlocking()]);
+
+    expect(drained.length).toEqual(1);
+    expect(drained[0]).toEqual(['a', 'b']);
+    await ctx.dispose();
+  });
+
+  // Flush is urgent: it must not sit out the `maxFrequency` delay of a pass that was scheduled
+  // before it (the delay exists to pace background triggers, not barriers).
+  test('runBlocking skips the throttle delay', async ({ expect }) => {
+    const ctx = new Context();
+    let runs = 0;
+    const scheduler = new UpdateScheduler(
+      ctx,
+      async () => {
+        runs++;
+      },
+      { maxFrequency: 2 }, // 500ms between passes.
+    );
+
+    // Consume the allowance, then queue a throttled pass.
+    await scheduler.runBlocking();
+    scheduler.trigger();
+
+    const started = performance.now();
+    await scheduler.runBlocking();
+    const elapsed = performance.now() - started;
+
+    expect(runs).toBeGreaterThanOrEqual(2);
+    expect(elapsed, `flush waited out the throttle (${Math.round(elapsed)}ms)`).toBeLessThan(400);
+    await ctx.dispose();
+  });
+
+  // A dispose must release a parked flush rather than strand it: the runner it was waiting on may
+  // never reach its claim once the context is gone.
+  test('dispose releases a parked runBlocking', async ({ expect }) => {
+    const ctx = new Context();
+    const scheduler = new UpdateScheduler(
+      ctx,
+      async () => {
+        await sleep(5);
+      },
+      { maxFrequency: 1 }, // 1000ms delay — the flush parks behind it.
+    );
+
+    await scheduler.runBlocking(); // Consume the allowance.
+    scheduler.trigger();
+    // Park a flush on the throttled runner, then dispose before it can claim.
+    const parked = (async () => {
+      // Re-arm the delay skip is deliberately NOT done here: dispose must be what releases it.
+      const completionBefore = scheduler.runBlocking();
+      return completionBefore;
+    })();
+    await sleep(10);
+    await ctx.dispose();
+
+    await expect(parked).resolves.toBeUndefined();
+  });
 });

package/src/update-scheduler.ts

@@ -5,6 +5,7 @@
 import { type Context } from '@dxos/context';
 
 import { scheduleMicroTask } from './task-scheduling';
+import { Trigger } from './trigger';
 
 export type UpdateSchedulerOptions = {
   /**
@@ -18,13 +19,41 @@ export type UpdateSchedulerOptions = {
  */
 const TIME_PERIOD = 1_000;
 
+/** A claimed run's error (or `undefined`). Resolves, never rejects — `runBlocking` re-throws it. */
+type RunResult = Promise<Error | undefined>;
+
+/**
+ * Runs a non-reentrant callback at most once at a time, coalescing triggers (optionally rate-limited
+ * via {@link UpdateSchedulerOptions.maxFrequency}).
+ *
+ * The runner inside {@link trigger} is the only place the callback starts; `runBlocking` and
+ * `forceTrigger` funnel into it. That, plus `_scheduled` collapsing triggers into one pending
+ * runner, is what makes mutual exclusion hold by construction (dxos/edge#758).
+ */
 export class UpdateScheduler {
+  /** The running pass; never rejects, non-null exactly while a run is executing. */
+  private _currentTask: Promise<void> | null = null;
+  private _scheduled = false;
+
   /**
-   * Promise that resolves when the callback is done.
-   * Never rejects.
+   * Armed by the `trigger` that schedules a runner, woken by that runner when it claims — with the
+   * run's promise, which `Trigger` adopts, so waiters resume when the run *finishes*. Lets
+   * `runBlocking` await a run that does not exist in `_currentTask` yet.
+   *
+   * `reset()` abandons parked waiters, so it may only be armed in `trigger`'s non-coalesced branch:
+   * waiters park only while `_scheduled` is true, and that branch requires it false.
    */
-  private _promise: Promise<any> | null = null;
-  private _scheduled = false;
+  private _runOutcome = new Trigger<RunResult>();
+
+  /** Woken to make the pending runner skip its throttle delay. Replaced at claim time. */
+  private _skipDelay = new Trigger();
+
+  /**
+   * `runBlocking` callers in flight, incremented synchronously before triggering. A failing run uses
+   * it to tell whether someone will throw the error; counting microtask hops to a waiter's resume
+   * would be a race.
+   */
+  private _observers = 0;
 
   private _lastUpdateTime = -TIME_PERIOD;
 
@@ -34,24 +63,37 @@ export class UpdateScheduler {
     private readonly _params: UpdateSchedulerOptions = {},
   ) {
     _ctx.onDispose(async () => {
-      await this._promise; // Context waits for callback to finish.
+      await this._currentTask; // Context waits for callback to finish.
+      // Release `runBlocking` callers parked on a runner that never claimed. NOOP if already woken.
+      this._runOutcome.wake(Promise.resolve(undefined));
     });
   }
 
+  get scheduled() {
+    return this._scheduled;
+  }
+
+  /**
+   * Schedule the callback to run asynchronously. Triggers issued while a run is pending or in flight
+   * coalesce into the next run.
+   */
   trigger(): void {
     if (this._scheduled) {
       return;
     }
+    this._scheduled = true;
+    this._runOutcome.reset(); // Only here — never on a coalesced trigger (see `_runOutcome`).
 
+    // The only claim site. A single await suffices: nothing else claims, so this is the only waiter.
     scheduleMicroTask(this._ctx, async () => {
-      // The previous task might still be running, so we need to wait for it to finish.
-      await this._promise; // Can't be rejected.
+      await this._currentTask; // Never rejects.
 
-      // Check if the callback was called recently.
+      // Rate limiting. Suspending before the claim is safe only because no other claimant exists.
       if (this._params.maxFrequency) {
         const now = performance.now();
         const delay = this._lastUpdateTime + TIME_PERIOD / this._params.maxFrequency - now;
         if (delay > 0) {
+          const skipDelay = this._skipDelay;
           await new Promise<void>((resolve) => {
             const timeoutId = setTimeout(() => {
               clearContext();
@@ -62,53 +104,85 @@ export class UpdateScheduler {
               clearTimeout(timeoutId);
               resolve();
             });
+
+            // `runBlocking`/`forceTrigger` cut the delay short.
+            void skipDelay.wait().then(() => {
+              clearTimeout(timeoutId);
+              clearContext();
+              resolve();
+            });
           });
         }
       }
 
       if (this._ctx.disposed) {
+        this._runOutcome.wake(Promise.resolve(undefined));
         return;
       }
 
-      this._lastUpdateTime = performance.now();
-
-      // Reset the flag. New tasks can now be scheduled. They would wait for the callback to finish.
+      // The claim: one synchronous slice from here to the `wake` below.
       this._scheduled = false;
-      this._promise = this._callback().then(
-        () => {
-          this._promise = null;
-        },
-        (error) => {
-          this._promise = null;
-          this._ctx.raise(error);
+      this._skipDelay = new Trigger();
+      this._lastUpdateTime = performance.now();
+      const run: RunResult = this._callback().then(
+        () => undefined,
+        (error): Error => {
+          // A thrown non-Error is typed away here, matching `Context.raise`'s signature.
+          const failure = error as Error;
+          // Unobserved failures go to the context, as trigger-path failures always have.
+          if (this._observers === 0) {
+            this._ctx.raise(failure);
+          }
+          return failure;
         },
       );
+      const task: Promise<void> = run.then(() => {
+        if (this._currentTask === task) {
+          this._currentTask = null;
+        }
+      });
+      this._currentTask = task;
+      this._runOutcome.wake(run);
     });
-
-    this._scheduled = true;
   }
 
+  /**
+   * Run as soon as possible: schedules (coalescing with any pending run) and skips the throttle
+   * delay. Does not start a concurrent callback.
+   */
   forceTrigger(): void {
-    scheduleMicroTask(this._ctx, async () => {
-      this._callback().catch((err) => this._ctx.raise(err));
-    });
+    this.trigger();
+    this._skipDelay.wake();
   }
 
   /**
    * Waits for the current task to finish if it is running.
-   * Does not schedule a new task.
+   * Does not schedule a new task, and does not wait for one that is merely scheduled.
    */
   async join(): Promise<void> {
-    await this._promise;
+    await this._currentTask;
   }
 
   /**
-   * Force schedule the task to run and wait for it to finish.
+   * Ensure a run that observes everything enqueued so far, and wait for it to finish. Waits for the
+   * pending run to claim, then for its result; that run necessarily claims after this call, so its
+   * drain includes everything enqueued before it. Rejects with the run's error so a flush barrier can
+   * see its batch was not handed off. No-op once disposed.
    */
   async runBlocking(): Promise<void> {
-    // The previous task might still be running, so we need to wait for it to finish.
-    await this._promise; // Can't be rejected.
-    this._promise = this._callback();
-    await this._promise;
+    if (this._ctx.disposed) {
+      return;
+    }
+    this._observers++;
+    try {
+      this.trigger();
+      this._skipDelay.wake();
+      const error = await this._runOutcome.wait();
+      if (error !== undefined) {
+        throw error;
+      }
+    } finally {
+      this._observers--;
+    }
   }
 }