From 756f62ba0afcb5c5441bf1fd1c3ac73d76f2dad2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 01:24:49 -0700 Subject: [PATCH 1/6] chore(quest): claim quest/m2/performance-survey/hang-buffered.md Quest-Claim: 0dc8ec22c270d5a2 From 93d108f542025f6d1fba22fd8774b5bff42bae5b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 01:45:22 -0700 Subject: [PATCH 2/6] perf(hang): keep a bulk max-delay skip linear in buffered groups Add a buffered-group benchmark sweeping groups x frames per group and publishers x players across steady, lookahead, sparse out-of-order and burst-skip arrivals, in Bun nightly and the Chromium micro lane. #checkMaxDelay rescanned every buffered group for each group it skipped, so a bulk skip of G groups visited ~G^2/2 groups. After the first skip it now reads suffix extrema from one backward pass. Co-Authored-By: Claude Opus 5.5 --- bench/README.md | 17 +- bench/browser/micro.ts | 19 +- bench/browser/run.sh | 2 +- js/hang/bench/buffered.ts | 217 +++++++++++++++++++ js/hang/src/container/consumer.skips.test.ts | 42 ++++ js/hang/src/container/consumer.ts | 46 +++- js/justfile | 5 + sh/gh/nightly.sh | 1 + 8 files changed, 333 insertions(+), 16 deletions(-) create mode 100644 js/hang/bench/buffered.ts diff --git a/bench/README.md b/bench/README.md index 82427ba0cb9..09b39efe808 100644 --- a/bench/README.md +++ b/bench/README.md @@ -409,12 +409,13 @@ Crashes, wrong bytes, missing frames, a window that presents nothing, or an unavailable CPU clock fail the run; timing never does. The nightly runs `--smoke` and keeps its run directory as the `bench-browser` artifact. -The in-memory frame, retained-history, and gap ledger paths also run directly in Chromium: +The in-memory frame, retained-history, gap ledger, and buffered-group paths also run directly in Chromium: ```bash nix develop --command bun bench/browser/micro.ts --bench frames --out .tmp/frames.json base=/path/to/release current=. aa=. nix develop --command bun bench/browser/micro.ts --bench drift --out .tmp/drift.json before=/path/to/main current=. aa=. nix develop --command bun bench/browser/micro.ts --bench ledger --out .tmp/ledger.json before=/path/to/main current=. aa=. +nix develop --command bun bench/browser/micro.ts --bench buffered --out .tmp/buffered.json before=/path/to/main current=. aa=. ``` Each variant uses its own workspace source and a persistent page, with one full @@ -431,9 +432,17 @@ B-frames, independently varying publisher and reader counts and retained history Its `time_mode` column is 0 for untimed, 1 for millisecond timestamps, and 2 for mixed millisecond/microsecond timestamps, which exercise exact cross-scale comparison. - -The browser smoke lane preserves one measured round of all three fixtures, and drift -and ledger also run in the nightly JS benchmark leg. Timing is +`buffered` drives every checkout's `@moq/hang` container consumer with one fixture, +sweeping buffered groups against frames per group, then publishers against players. +`steady` reads each frame as it lands (its `ns_per_op` is the frame delay); +`lookahead` and `sparse` decode every group before draining them, in order or +shuffled with a missing sequence between groups; `burst` times only the arrival +that skips every buffered group once the max delay drops to zero, per skipped group. +Each case checks its exact buffered ranges, timestamp order and payloads, and that +skipped groups are closed; `gaps` and `warnings` must match between variants. + +The browser smoke lane preserves one measured round of all four fixtures, and drift, +ledger and buffered also run in the nightly JS benchmark leg. Timing is observational, with the A/A spread showing the host's noise floor. ## Pattern and container coverage diff --git a/bench/browser/micro.ts b/bench/browser/micro.ts index 1bf4d138034..8401853f27c 100644 --- a/bench/browser/micro.ts +++ b/bench/browser/micro.ts @@ -14,8 +14,9 @@ const { values, positionals } = parseArgs({ }, }); const benchmark = values.bench; -if (benchmark !== "frames" && benchmark !== "drift" && benchmark !== "ledger") - throw new Error("--bench must be frames, drift, or ledger"); +const benchmarks = { frames: 26, drift: 36, ledger: 12, buffered: 36 } as const; +if (!Object.hasOwn(benchmarks, benchmark)) throw new Error("--bench must be frames, drift, ledger, or buffered"); +const expected = benchmarks[benchmark as keyof typeof benchmarks]; const rounds = Number(values.rounds); if (!Number.isSafeInteger(rounds) || rounds < 1) throw new Error("--rounds must be a positive integer"); const roots = new Map(); @@ -30,7 +31,9 @@ for (const [name, root] of roots) { const entry = benchmark === "frames" ? resolve(root, "js/net/bench/frames.ts") - : resolve(import.meta.dir, `../../js/net/bench/${benchmark}.ts`); + : benchmark === "buffered" + ? resolve(import.meta.dir, "../../js/hang/bench/buffered.ts") + : resolve(import.meta.dir, `../../js/net/bench/${benchmark}.ts`); const result = await Bun.build({ entrypoints: [entry], target: "browser", @@ -43,7 +46,11 @@ for (const [name, root] of roots) { build.onResolve({ filter: /^\.\.\/src\/ledger\.ts$/ }, () => ({ path: resolve(root, "js/net/src/ledger.ts"), })); - build.onLoad({ filter: /\/bench\/(frames|drift|ledger)\.ts$/ }, async ({ path }) => { + // So is the container consumer, which the buffered fixture drives directly. + build.onResolve({ filter: /^\.\.\/src\/container\/(consumer|legacy)\.ts$/ }, ({ path }) => ({ + path: resolve(root, "js/hang/src", path.slice("../src/".length)), + })); + build.onLoad({ filter: /\/bench\/(frames|drift|ledger|buffered)\.ts$/ }, async ({ path }) => { const source = await Bun.file(path).text(); if (benchmark !== "frames") return { loader: "ts", contents: `${source}\nglobalThis.measure = run;` }; @@ -91,7 +98,7 @@ try { pages.set(name, page); rows.set(name, []); page.on("console", (message) => { - if (/^(lite|ietf|\d+),/.test(message.text())) rows.get(name)?.push(message.text()); + if (/^(lite|ietf|steady|lookahead|sparse|burst|\d+),/.test(message.text())) rows.get(name)?.push(message.text()); }); page.on("pageerror", (error) => { console.error(error); @@ -109,7 +116,7 @@ try { rows.set(variant, []); await pages.get(variant)?.evaluate("globalThis.measure()"); const measured = rows.get(variant); - if (measured?.length !== (benchmark === "frames" ? 26 : benchmark === "drift" ? 36 : 12)) + if (measured?.length !== expected) throw new Error(`incomplete rows: ${variant}`); samples.push({ round, variant, rows: measured }); await Bun.write( diff --git a/bench/browser/run.sh b/bench/browser/run.sh index 6c16ba98a76..c1f40b8941f 100755 --- a/bench/browser/run.sh +++ b/bench/browser/run.sh @@ -88,7 +88,7 @@ bun install --frozen-lockfile cd "$HERE" # The in-memory paths share Chromium installation and artifact retention with this lane. -for benchmark in frames drift ledger; do +for benchmark in frames drift ledger buffered; do bun micro.ts --bench "$benchmark" --rounds 1 --out "$HARNESS_RUN/$benchmark.json" \ current="$WORKSPACE" aa="$WORKSPACE" done diff --git a/js/hang/bench/buffered.ts b/js/hang/bench/buffered.ts new file mode 100644 index 00000000000..2821b6ddb2c --- /dev/null +++ b/js/hang/bench/buffered.ts @@ -0,0 +1,217 @@ +/** Sweep buffered groups, frames per group, publishers and players through the container consumer. */ +import { Milli } from "@moq/clock"; +import { type Group, Time, Track, Varint } from "@moq/net"; +import { Signal } from "@moq/signals"; +import { Consumer } from "../src/container/consumer.ts"; +import { Format } from "../src/container/legacy.ts"; + +// Far past every fixture's span, so only the burst case skips anything. +const HOLD = Milli(1_000_000_000); +// One group per second at 30 fps. +const FRAME_US = 33_333; +const GROUP_US = 1_000_000; +const PAYLOAD = new Uint8Array([7]); +// Measured operations per case, repeating smaller ones. +const MIN_OPS = 8192; + +type Scenario = "steady" | "lookahead" | "sparse" | "burst"; + +interface Player { + track: Track.Producer; + consumer: Consumer; + // Every group the consumer received, to check that what it skipped is closed. + received: Group.Consumer[]; +} + +function timestamp(group: number, frame: number): number { + return group * GROUP_US + frame * FRAME_US; +} + +function payload(group: number, frame: number): Uint8Array { + const prefix = Varint.encode(timestamp(group, frame)); + const data = new Uint8Array(prefix.byteLength + PAYLOAD.byteLength); + data.set(prefix, 0); + data.set(PAYLOAD, prefix.byteLength); + return data; +} + +function wire(group: number, frame: number): Group.Frame { + return { payload: payload(group, frame), timestamp: Time.Timestamp.fromMicros(timestamp(group, frame)) }; +} + +function open(track: Track.Producer, maxDelay: Signal): Player { + const subscriber = track.subscribe({ maxDelay: HOLD }); + const received: Group.Consumer[] = []; + const recv = subscriber.recvGroup.bind(subscriber); + subscriber.recvGroup = async () => { + const group = await recv(); + if (group) received.push(group); + return group; + }; + return { track, consumer: new Consumer(subscriber, { format: new Format("video"), maxDelay }), received }; +} + +// The deterministic arrival order of the sparse case: every group exactly once, shuffled. +function shuffled(count: number): number[] { + const order = Array.from({ length: count }, (_, i) => i); + let seed = 42; + for (let i = count - 1; i > 0; i--) { + seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0; + const j = seed % (i + 1); + [order[i], order[j]] = [order[j], order[i]]; + } + return order; +} + +// Write one frame to every publisher, then wait until every player decoded it, as each arrival would +// be decoded before the next lands. A decoded frame always changes some buffered range. +async function arrive(groups: Group.Producer[], players: Player[], index: number, frame: number): Promise { + const changed = players.map((player) => player.consumer.buffered.changed()); + for (const group of groups) group.writeFrame(wire(index, frame)); + await Promise.all(changed); +} + +// Read every buffered frame, checking timestamp order, and count the gaps between them. +async function drain(player: Player, expected: number[]): Promise { + let gaps = 0; + for (const want of expected) { + for (;;) { + const read = await player.consumer.next(); + if (!read) throw new Error("frame missing"); + if (read.kind === "gap") { + gaps++; + continue; + } + if (read.kind !== "frame" || read.frame.timestamp !== want || read.frame.payload[0] !== PAYLOAD[0]) + throw new Error("frame missing or reordered"); + break; + } + } + return gaps; +} + +function ranges(player: Player): string { + return JSON.stringify(player.consumer.buffered.peek()); +} + +/** Return elapsed ns, the measured operations, gaps and warnings for one case. */ +async function measure( + scenario: Scenario, + groups: number, + frames: number, + publishers: number, + readers: number, +): Promise<{ ns: number; ops: number; gaps: number; warnings: number }> { + const maxDelay = new Signal(HOLD); + // Stamped like a hang publisher's media, so the transport finds its live edge at the newest group. + const tracks = Array.from({ length: publishers }, (_, i) => + new Track.Producer(`p${i}`).accept({ timescale: Time.Timescale.MICRO }), + ); + const players = tracks.flatMap((track) => Array.from({ length: readers }, () => open(track, maxDelay))); + let warnings = 0; + const warn = console.warn; + console.warn = () => { + warnings++; + }; + try { + const sequence = (i: number) => (scenario === "sparse" ? i * 2 : i); + const order = scenario === "sparse" ? shuffled(groups) : Array.from({ length: groups }, (_, i) => i); + const expected = Array.from({ length: groups * frames }, (_, i) => + timestamp(sequence(Math.floor(i / frames)), i % frames), + ); + let gaps = 0; + let start = performance.now(); + if (scenario === "steady") { + // The player reads each frame as it lands, so nothing builds up behind it. + for (const i of order) { + const sources = tracks.map((track) => track.createGroup(i)); + for (let frame = 0; frame < frames; frame++) { + const reads = players.map((player) => player.consumer.next()); + for (const source of sources) source.writeFrame(wire(i, frame)); + for (const read of await Promise.all(reads)) + if (read?.kind !== "frame" || read.frame.timestamp !== timestamp(i, frame)) + throw new Error("frame missing or reordered"); + } + for (const source of sources) source.finish(); + } + return { ns: (performance.now() - start) * 1e6, ops: groups * frames * players.length, gaps, warnings }; + } + + // Everything arrives before the player reads: a stalled reader, or history after a join. + for (const i of order) { + const sources = tracks.map((track) => track.createGroup(sequence(i))); + for (let frame = 0; frame < frames; frame++) await arrive(sources, players, sequence(i), frame); + for (const source of sources) source.finish(); + } + // A finished track proves no missing group can still arrive. + if (scenario === "sparse") for (const track of tracks) track.finish(); + await Promise.resolve(); + + for (const player of players) { + // Finished adjacent groups merge into one range; sparse ones stay one range per group. + const want = + scenario === "sparse" + ? Array.from({ length: groups }, (_, i) => ({ + start: timestamp(sequence(i), 0) / 1000, + end: timestamp(sequence(i), frames - 1) / 1000, + })) + : [{ start: 0, end: timestamp(groups - 1, frames - 1) / 1000 }]; + if (ranges(player) !== JSON.stringify(want)) throw new Error(`wrong buffered ranges: ${ranges(player)}`); + } + + if (scenario === "burst") { + // The budget drops to nothing, so the next arrival makes every older group too stale to keep. + maxDelay.set(Milli.zero); + start = performance.now(); + const sources = tracks.map((track) => track.createGroup(groups)); + await arrive(sources, players, groups, 0); + const elapsed = (performance.now() - start) * 1e6; + const newest = timestamp(groups, 0) / 1000; + for (const player of players) { + if (ranges(player) !== JSON.stringify([{ start: newest, end: newest }])) + throw new Error(`skip left ${ranges(player)}`); + if (player.received.slice(0, groups).some((group) => !group.isClosed)) + throw new Error("skipped group left open"); + const read = await player.consumer.next(); + if (read?.kind !== "frame" || read.frame.timestamp !== timestamp(groups, 0)) + throw new Error("newest frame missing"); + } + return { ns: elapsed, ops: groups * players.length, gaps, warnings }; + } + + for (const player of players) gaps += await drain(player, expected); + return { ns: (performance.now() - start) * 1e6, ops: groups * frames * players.length, gaps, warnings }; + } finally { + console.warn = warn; + for (const player of players) player.consumer.close(); + for (const track of tracks) track.close(); + } +} + +/** + * Print one CSV row per case. `ns_per_op` is per frame and player, except for a burst, where it is per + * skipped group and player and covers only the arrival that skips them. + */ +export async function run(): Promise { + console.log("scenario,groups,frames,publishers,players,ops,gaps,warnings,ns_per_op"); + const cases: [Scenario, number, number, number, number][] = []; + for (const scenario of ["steady", "lookahead", "sparse", "burst"] as const) + for (const groups of [1, 16, 256, 1024]) for (const frames of [1, 30]) cases.push([scenario, groups, frames, 1, 1]); + for (const publishers of [1, 4]) for (const players of [1, 8]) cases.push(["lookahead", 64, 30, publishers, players]); + for (const [scenario, groups, frames, publishers, players] of cases) { + // Small cases repeat, so a coarse browser clock still resolves them. + const total = { ns: 0, ops: 0, gaps: 0, warnings: 0 }; + while (total.ops < MIN_OPS) { + const { ns, ops, gaps, warnings } = await measure(scenario, groups, frames, publishers, players); + total.ns += ns; + total.ops += ops; + total.gaps += gaps; + total.warnings += warnings; + } + console.log( + `${scenario},${groups},${frames},${publishers},${players},${total.ops},${total.gaps},${total.warnings},${(total.ns / total.ops).toFixed(0)}`, + ); + } +} + +if (import.meta.main) await run(); diff --git a/js/hang/src/container/consumer.skips.test.ts b/js/hang/src/container/consumer.skips.test.ts index 3592cfbd6dd..76db7b1b392 100644 --- a/js/hang/src/container/consumer.skips.test.ts +++ b/js/hang/src/container/consumer.skips.test.ts @@ -50,3 +50,45 @@ for (const count of [1, 16, 256]) { } }); } + +test("Consumer measures each skip's span over every group left, not just the new oldest", async () => { + const warn = spyOn(console, "warn").mockImplementation(() => {}); + const track = new Track.Producer("tone"); + const maxDelay = new Signal(Milli(30_000)); + const consumer = new Consumer(track.subscribe({ maxDelay: Milli(30_000) }), { + format: new Format("data"), + maxDelay, + }); + const write = (sequence: number, timestamp: number) => { + const group = track.createGroup(sequence); + group.writeFrame({ payload: Varint.encode(timestamp), timestamp: Time.Timestamp.now() }); + }; + const buffered = async (timestamp: number) => { + while (consumer.buffered.peek().at(-1)?.end !== timestamp) await consumer.buffered.changed(); + }; + try { + // Group 2 starts below group 1, so the span after skipping group 0 still reaches back to it. + for (const [sequence, timestamp] of [ + [0, 0], + [1, 10_000], + [2, 1_000], + [3, 12_000], + ]) + write(sequence, timestamp); + await buffered(12); + maxDelay.set(Milli(5)); + write(4, 13_000); + await buffered(13); + expect(warn).toHaveBeenLastCalledWith("skipping slow groups: track=tone 0 -> 3 count=3"); + expect(consumer.buffered.peek()).toEqual([ + { start: Milli(12), end: Milli(12) }, + { start: Milli(13), end: Milli(13) }, + ]); + expect(await consumer.next()).toMatchObject({ kind: "frame", group: 3 }); + } finally { + consumer.close(); + track.finish(); + track.close(); + warn.mockRestore(); + } +}); diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index d38796a1f44..50458320400 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -90,6 +90,12 @@ interface Group { released?: boolean; // Dropped from #groups, with what it held refunded } +// The earliest and latest known frame timestamps of the buffered groups from each index on. +interface Spans { + min: (number | undefined)[]; + max: (number | undefined)[]; +} + // Two adjacent groups are treated as timeline-contiguous when the next group's first PTS is within // this slack of the current group's end. Per-sample durations and base-decode-times are each rounded // to microseconds independently, so a genuinely contiguous boundary can be off by ~1µs (seen on 48kHz @@ -436,6 +442,8 @@ export class Consumer { let skipped = 0; const start = this.#groups[0]?.consumer.sequence; + // The span left after each further skip, computed once the first skip shows more may follow. + let spans: Spans | undefined; // Keep skipping the oldest group while the buffered span exceeds the max delay. // This also handles gaps in group sequence numbers: if #active points to a missing @@ -448,12 +456,20 @@ export class Consumer { let min: number | undefined; let max: number | undefined; - for (const group of this.#groups) { - if (group.latest === undefined) continue; + if (skipped === 0) { + for (const group of this.#groups) { + if (group.latest === undefined) continue; - const frame = group.frames.at(0)?.timestamp ?? group.latest; - if (min === undefined || frame < min) min = frame; - if (max === undefined || group.latest > max) max = group.latest; + const frame = group.frames.at(0)?.timestamp ?? group.latest; + if (min === undefined || frame < min) min = frame; + if (max === undefined || group.latest > max) max = group.latest; + } + } else { + // A skip removes only the oldest group, so one pass over what the first skip left gives + // the span after every later one, and a bulk skip stays linear in the buffered groups. + spans ??= this.#spans(); + min = spans.min[skipped - 1]; + max = spans.max[skipped - 1]; } if (min === undefined || max === undefined) break; @@ -490,6 +506,26 @@ export class Consumer { return skipped > 0; } + // The earliest and latest known frames of the buffered groups from each index on: the span left + // once that many of the oldest groups are skipped, undefined where none of them has a frame. + #spans(): Spans { + const count = this.#groups.length; + const spans: Spans = { min: new Array(count), max: new Array(count) }; + let min: number | undefined; + let max: number | undefined; + for (let i = count - 1; i >= 0; i--) { + const group = this.#groups[i]; + if (group.latest !== undefined) { + const frame = group.frames.at(0)?.timestamp ?? group.latest; + if (min === undefined || frame < min) min = frame; + if (max === undefined || group.latest > max) max = group.latest; + } + spans.min[i] = min; + spans.max[i] = max; + } + return spans; + } + // Skip the stalled active group once it has presented up to where the next group // begins (its furthest frame end reaches the next group's first timestamp). Only // fires when the active group is fully consumed and still open, so we never drop diff --git a/js/justfile b/js/justfile index 5f4bcb5691f..dee88500d0e 100644 --- a/js/justfile +++ b/js/justfile @@ -145,6 +145,11 @@ slow-group-bench: bun install --frozen-lockfile bun hang/bench/slow-group.ts +# Sweep a hang consumer's buffered groups, frames per group, publishers and players across arrival orders. +buffered-bench: + bun install --frozen-lockfile + bun hang/bench/buffered.ts + # Sweep the audio jitter estimator's held history against in-order and reordered frames. jitter-bench: bun install --frozen-lockfile diff --git a/sh/gh/nightly.sh b/sh/gh/nightly.sh index ae8312bc9dd..10d060d67ba 100755 --- a/sh/gh/nightly.sh +++ b/sh/gh/nightly.sh @@ -151,6 +151,7 @@ case "$1" in javascript json-codec just js json-codec-bench javascript json-parse just js json-parse-bench javascript slow-group just js slow-group-bench + javascript buffered just js buffered-bench javascript jitter just js jitter-bench javascript audio-warmup just js audio-warmup-bench javascript clock just js clock-bench From a715a81aaa84bd9ffd32ce7bb715f10be524d58c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 01:48:45 -0700 Subject: [PATCH 3/6] chore(quest): finish the buffered browser groups quest The bulk skip is linear; the per-frame range and decode scans stay O(buffered groups), measured below any realistic consumer cost. Co-Authored-By: Claude Opus 5.5 --- bench/browser/micro.ts | 6 ++-- js/hang/bench/buffered.ts | 6 ++-- quest/m2/audit-perf.md | 24 +++++++--------- quest/m2/performance-survey/README.md | 1 - quest/m2/performance-survey/hang-buffered.md | 30 -------------------- 5 files changed, 18 insertions(+), 49 deletions(-) delete mode 100644 quest/m2/performance-survey/hang-buffered.md diff --git a/bench/browser/micro.ts b/bench/browser/micro.ts index 8401853f27c..b343315ed09 100644 --- a/bench/browser/micro.ts +++ b/bench/browser/micro.ts @@ -98,7 +98,8 @@ try { pages.set(name, page); rows.set(name, []); page.on("console", (message) => { - if (/^(lite|ietf|steady|lookahead|sparse|burst|\d+),/.test(message.text())) rows.get(name)?.push(message.text()); + if (/^(lite|ietf|steady|lookahead|sparse|burst|\d+),/.test(message.text())) + rows.get(name)?.push(message.text()); }); page.on("pageerror", (error) => { console.error(error); @@ -116,8 +117,7 @@ try { rows.set(variant, []); await pages.get(variant)?.evaluate("globalThis.measure()"); const measured = rows.get(variant); - if (measured?.length !== expected) - throw new Error(`incomplete rows: ${variant}`); + if (measured?.length !== expected) throw new Error(`incomplete rows: ${variant}`); samples.push({ round, variant, rows: measured }); await Bun.write( values.out, diff --git a/js/hang/bench/buffered.ts b/js/hang/bench/buffered.ts index 2821b6ddb2c..a590060ad36 100644 --- a/js/hang/bench/buffered.ts +++ b/js/hang/bench/buffered.ts @@ -196,8 +196,10 @@ export async function run(): Promise { console.log("scenario,groups,frames,publishers,players,ops,gaps,warnings,ns_per_op"); const cases: [Scenario, number, number, number, number][] = []; for (const scenario of ["steady", "lookahead", "sparse", "burst"] as const) - for (const groups of [1, 16, 256, 1024]) for (const frames of [1, 30]) cases.push([scenario, groups, frames, 1, 1]); - for (const publishers of [1, 4]) for (const players of [1, 8]) cases.push(["lookahead", 64, 30, publishers, players]); + for (const groups of [1, 16, 256, 1024]) + for (const frames of [1, 30]) cases.push([scenario, groups, frames, 1, 1]); + for (const publishers of [1, 4]) + for (const players of [1, 8]) cases.push(["lookahead", 64, 30, publishers, players]); for (const [scenario, groups, frames, publishers, players] of cases) { // Small cases repeat, so a coarse browser clock still resolves them. const total = { ns: 0, ops: 0, gaps: 0, warnings: 0 }; diff --git a/quest/m2/audit-perf.md b/quest/m2/audit-perf.md index b0313979e76..bff8a131582 100644 --- a/quest/m2/audit-perf.md +++ b/quest/m2/audit-perf.md @@ -167,30 +167,28 @@ follow-up quest. The m1 run added none of these: complete adapter delivery across publishers and viewers. 3. LOC and CMAF wire containers in moq-mux: `containers` and `export` only use `Container::Legacy`; sweep container x frame size x frames. -4. [Buffered browser groups](/quest/m2/performance-survey/hang-buffered.md) - owns per-frame scans and bulk skip work in the Hang consumer. -5. [Browser media copies](/quest/m2/performance-survey/browser-media-copies.md) +4. [Browser media copies](/quest/m2/performance-survey/browser-media-copies.md) owns CMAF sample copies and LOC encode allocation. Generic `js/msf` and `js/flate` benchmark coverage remains here. -6. moq-quic loss recovery and real congestion controllers: every bench pins +5. moq-quic loss recovery and real congestion controllers: every bench pins `Unlimited`; sweep controller x flight x loss x streams. -7. [Announcement snapshots](/quest/m2/performance-survey/announced-snapshots.md) +6. [Announcement snapshots](/quest/m2/performance-survey/announced-snapshots.md) owns HTTP snapshot/rendering costs across routes and pollers. -8. [JWT verification](/quest/m2/performance-survey/jwt-verification.md) owns +7. [JWT verification](/quest/m2/performance-survey/jwt-verification.md) owns key-source I/O, import, lookup, parsing and crypto attribution. -9. MPEG-TS import with real repeated media (the CLI bench mostly skips null +8. MPEG-TS import with real repeated media (the CLI bench mostly skips null padding), and MKV, FLV, H.265, AV1 importers. -10. JS watch audio ring buffer and publish `Fanout` (lower impact). Include - capture-to-encoder staging: `audio/framer.ts` copies planes before - `audio/encoder.ts` joins them. AudioData already uses a transfer list; - do not count that transfer as another mandatory copy. Sweep publishers - x renditions, channels and frame duration in a browser. +9. JS watch audio ring buffer and publish `Fanout` (lower impact). Include + capture-to-encoder staging: `audio/framer.ts` copies planes before + `audio/encoder.ts` joins them. AudioData already uses a transfer list; + do not count that transfer as another mandatory copy. Sweep publishers + x renditions, channels and frame duration in a browser. The [2026-10-22 source survey](/quest/m2/performance-survey/README.md) owns the extracted items above and additional algorithmic hypotheses, with paired benchmarks required before optimization. This audit still owns nightly regression attribution and the remaining coverage. Its fragmented-MKV child -specializes item 9's MKV work. +specializes item 8's MKV work. Single-axis fan-out benches to widen: `session_delivery_paced` (viewers only), `track_fanout_*` (subscribers only), `memory` (lite-06 only), and diff --git a/quest/m2/performance-survey/README.md b/quest/m2/performance-survey/README.md index c25cce3d3b9..e4856e55ec1 100644 --- a/quest/m2/performance-survey/README.md +++ b/quest/m2/performance-survey/README.md @@ -183,7 +183,6 @@ No duplicate quest or workflow edit belongs here. - [Fragmented MKV import](/quest/m2/performance-survey/mkv-fragments.md) - accumulated-buffer copies and parser replay - [QUIC scheduling churn](/quest/m2/performance-survey/quic-schedule-churn.md) - priority and retirement work across unrelated groups - [HLS request fan-out](/quest/m2/performance-survey/hls-serving.md) - repeated fetch, remux and playlist construction per viewer -- [Buffered browser groups](/quest/m2/performance-survey/hang-buffered.md) - per-frame scans and bulk skip work - [Idle browser stats](/quest/m2/performance-survey/browser-idle-stats.md) - local transport polling without active publishing demand - [Transport preference history](/quest/m2/performance-survey/transport-history.md) - full URL retention across retired sessions - [Resume identity history](/quest/m2/performance-survey/resume-history.md) - historical source graphs held by first-seen track metadata diff --git a/quest/m2/performance-survey/hang-buffered.md b/quest/m2/performance-survey/hang-buffered.md deleted file mode 100644 index 59baf68ad66..00000000000 --- a/quest/m2/performance-survey/hang-buffered.md +++ /dev/null @@ -1,30 +0,0 @@ -# [M] Browser buffered-group bookkeeping scales with changed data - -## Goal - -Playing or skipping buffered groups avoids avoidable repeated backlog scans -without changing the buffering and max-delay contract. - -## Plan - -[Hang Consumer](/js/hang/src/container/consumer.ts) rebuilds buffered ranges -by walking groups in `#updateBuffered` (line 696). `#checkMaxDelay` scans -all groups inside a loop that shifts old groups (line 377), so bulk skipping -can repeat the scan. These paths execute while frames arrive and are read. - -Add real-browser cases sweeping buffered groups × frames per group, then -players × independent publishers. Compare ordinary steady playback, sparse -out-of-order groups, large lookahead and a burst that must be skipped. -Measure operation counts, main-thread CPU, allocations/GC and frame delay. -Verify exact buffered ranges, gaps, timestamp order, skip decisions and closure -of discarded frames. Incremental extrema/ranges are candidates only if their -maintenance is cheaper across normal and adversarial arrival orders. - -This extracts the recurring audit's buffered-consumer finding. -[Watch worker planning](/quest/m2/plan-watch-worker.md) owns main-thread -isolation; moving the work does not discharge this algorithmic measurement. - -Follow the [survey's benchmark contract](/quest/m2/performance-survey/README.md): -measure the baseline before optimizing, retain paired evidence, verify equivalent -work, schedule coverage nightly, and accept a measured no-win. Expected public -API and wire impact: none; report the actual impact in the implementation PR. From 671d2cf8f4a13ceab0132b520bcdbd4660352cf3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 14:30:36 -0800 Subject: [PATCH 4/6] fix(hang): move the buffered bench and skip test to the Delay prop Main's Delay { min, max } replaced the maxDelay prop. The span test now reads one frame first, so the age skip runs past the start's warming guard, and expects the gap the skipped media leaves before the retained group. Co-Authored-By: Claude Opus 5.5 --- js/hang/bench/buffered.ts | 12 ++++++------ js/hang/src/container/consumer.skips.test.ts | 10 +++++++--- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/js/hang/bench/buffered.ts b/js/hang/bench/buffered.ts index a590060ad36..54b2a6aca8c 100644 --- a/js/hang/bench/buffered.ts +++ b/js/hang/bench/buffered.ts @@ -2,7 +2,7 @@ import { Milli } from "@moq/clock"; import { type Group, Time, Track, Varint } from "@moq/net"; import { Signal } from "@moq/signals"; -import { Consumer } from "../src/container/consumer.ts"; +import { Consumer, type Delay } from "../src/container/consumer.ts"; import { Format } from "../src/container/legacy.ts"; // Far past every fixture's span, so only the burst case skips anything. @@ -39,7 +39,7 @@ function wire(group: number, frame: number): Group.Frame { return { payload: payload(group, frame), timestamp: Time.Timestamp.fromMicros(timestamp(group, frame)) }; } -function open(track: Track.Producer, maxDelay: Signal): Player { +function open(track: Track.Producer, delay: Signal): Player { const subscriber = track.subscribe({ maxDelay: HOLD }); const received: Group.Consumer[] = []; const recv = subscriber.recvGroup.bind(subscriber); @@ -48,7 +48,7 @@ function open(track: Track.Producer, maxDelay: Signal): Player { if (group) received.push(group); return group; }; - return { track, consumer: new Consumer(subscriber, { format: new Format("video"), maxDelay }), received }; + return { track, consumer: new Consumer(subscriber, { format: new Format("video"), delay }), received }; } // The deterministic arrival order of the sparse case: every group exactly once, shuffled. @@ -102,12 +102,12 @@ async function measure( publishers: number, readers: number, ): Promise<{ ns: number; ops: number; gaps: number; warnings: number }> { - const maxDelay = new Signal(HOLD); + const delay = new Signal({ max: HOLD }); // Stamped like a hang publisher's media, so the transport finds its live edge at the newest group. const tracks = Array.from({ length: publishers }, (_, i) => new Track.Producer(`p${i}`).accept({ timescale: Time.Timescale.MICRO }), ); - const players = tracks.flatMap((track) => Array.from({ length: readers }, () => open(track, maxDelay))); + const players = tracks.flatMap((track) => Array.from({ length: readers }, () => open(track, delay))); let warnings = 0; const warn = console.warn; console.warn = () => { @@ -161,7 +161,7 @@ async function measure( if (scenario === "burst") { // The budget drops to nothing, so the next arrival makes every older group too stale to keep. - maxDelay.set(Milli.zero); + delay.set({ max: Milli.zero }); start = performance.now(); const sources = tracks.map((track) => track.createGroup(groups)); await arrive(sources, players, groups, 0); diff --git a/js/hang/src/container/consumer.skips.test.ts b/js/hang/src/container/consumer.skips.test.ts index 236baf7377c..d120b774d63 100644 --- a/js/hang/src/container/consumer.skips.test.ts +++ b/js/hang/src/container/consumer.skips.test.ts @@ -54,10 +54,10 @@ for (const count of [1, 16, 256]) { test("Consumer measures each skip's span over every group left, not just the new oldest", async () => { const warn = spyOn(console, "warn").mockImplementation(() => {}); const track = new Track.Producer("tone"); - const maxDelay = new Signal(Milli(30_000)); + const delay = new Signal({ max: Milli(30_000) }); const consumer = new Consumer(track.subscribe({ maxDelay: Milli(30_000) }), { format: new Format("data"), - maxDelay, + delay, }); const write = (sequence: number, timestamp: number) => { const group = track.createGroup(sequence); @@ -76,7 +76,9 @@ test("Consumer measures each skip's span over every group left, not just the new ]) write(sequence, timestamp); await buffered(12); - maxDelay.set(Milli(5)); + // Reading the first frame warms the reader, so the age skip runs on the max delay alone. + expect(await consumer.next()).toMatchObject({ kind: "frame", group: 0 }); + delay.set({ max: Milli(5) }); write(4, 13_000); await buffered(13); expect(warn).toHaveBeenLastCalledWith("skipping slow groups: track=tone 0 -> 3 count=3"); @@ -84,6 +86,8 @@ test("Consumer measures each skip's span over every group left, not just the new { start: Milli(12), end: Milli(12) }, { start: Milli(13), end: Milli(13) }, ]); + // The skipped groups held media past the first frame, so their span reads as a gap first. + expect(await consumer.next()).toMatchObject({ kind: "gap", timestamp: 0, duration: 12_000 }); expect(await consumer.next()).toMatchObject({ kind: "frame", group: 3 }); } finally { consumer.close(); From dcd097983326189c6d6bb5435c6d8049740369cf Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 22:24:05 -0800 Subject: [PATCH 5/6] perf(hang): keep a warming bulk skip linear too #7518's backlog-start check recomputed the live edge over every buffered group on each skip, making a bulk skip before the first read quadratic again. The loop already holds that edge as the span's max, so pass it in. Co-Authored-By: Claude Opus 5.5 --- js/hang/src/container/consumer.ts | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index 107ada2ec56..39db92fb250 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -526,7 +526,8 @@ export class Consumer { // Before the first item, a backlog that landed whole starts within the budget, so only // the group covering the live edge less the reach is kept: one whose successor starts // past that point. Rust's start skip, in `Consumer::poll_event_once`, measures the same. - const target = this.#startTarget(this.#reach(this.#delay.peek())); + // `max` is the live edge of the groups left, so this stays O(1) per skip. + const target = this.#startTarget(this.#reach(this.#delay.peek()), max); if (target !== undefined && nextStart > target) break; } else if (max - nextStart < threshold) { // Once reading began, it is stale only once its successor starts a whole budget behind @@ -980,14 +981,21 @@ export class Consumer { // The point the start reaches back to: the live edge (the newest content) less `reach`. Undefined // for a zero reach, which the newest group covers, and before any timed content, since untimed // content such as a marker has no edge to reach back from. - #startTarget(reach: number): number | undefined { + // A caller that already knows the live edge passes it, sparing a scan of every group. + #startTarget(reach: number, known?: number): number | undefined { if (reach === 0) return undefined; + const edge = known ?? this.#liveEdge(); + // Media starts at zero, so a reach past it is covered there. + return edge === undefined ? undefined : Math.max(0, edge - reach); + } + + // The newest known frame timestamp across the buffered groups. + #liveEdge(): number | undefined { let edge: number | undefined; for (const group of this.#groups) { if (group.latest !== undefined && (edge === undefined || group.latest > edge)) edge = group.latest; } - // Media starts at zero, so a reach past it is covered there. - return edge === undefined ? undefined : Math.max(0, edge - reach); + return edge; } // How stale the buffered span may get before the age skip drops its oldest group, in microseconds: From 39673ed339707876575e4e62866e81f91a676049 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 2 Nov 2026 22:29:34 -0800 Subject: [PATCH 6/6] fix(hang): type the bench and span test with Track.Delay; find smoke benches in any package #7597 moved the delay type to `Track.Delay`. The nightly coverage test read every browser smoke bench from `js/net/bench`, but `buffered` lives in `js/hang/bench`. Co-Authored-By: Claude Opus 5.5 --- js/hang/bench/buffered.ts | 6 +++--- js/hang/src/container/consumer.skips.test.ts | 2 +- sh/gh/nightly.test.py | 7 +++++-- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/js/hang/bench/buffered.ts b/js/hang/bench/buffered.ts index 742bca80783..25eaad8d607 100644 --- a/js/hang/bench/buffered.ts +++ b/js/hang/bench/buffered.ts @@ -2,7 +2,7 @@ import { Milli } from "@moq/clock"; import { type Group, Time, Track, Varint } from "@moq/net"; import { Signal } from "@moq/signals"; -import { Consumer, type Delay } from "../src/container/consumer.ts"; +import { Consumer } from "../src/container/consumer.ts"; import { Format } from "../src/container/legacy.ts"; // Far past every fixture's span, so only the burst case skips anything. @@ -39,7 +39,7 @@ function wire(group: number, frame: number): Group.Frame { return { payload: payload(group, frame), timestamp: Time.Timestamp.fromMicros(timestamp(group, frame)) }; } -function open(track: Track.Producer, delay: Signal): Player { +function open(track: Track.Producer, delay: Signal): Player { const subscriber = track.subscribe({ delay: { max: HOLD } }); const received: Group.Consumer[] = []; const recv = subscriber.recvGroup.bind(subscriber); @@ -102,7 +102,7 @@ async function measure( publishers: number, readers: number, ): Promise<{ ns: number; ops: number; gaps: number; warnings: number }> { - const delay = new Signal({ max: HOLD }); + const delay = new Signal({ max: HOLD }); // Stamped like a hang publisher's media, so the transport finds its live edge at the newest group. const tracks = Array.from({ length: publishers }, (_, i) => new Track.Producer(`p${i}`).accept({ timescale: Time.Timescale.MICRO }), diff --git a/js/hang/src/container/consumer.skips.test.ts b/js/hang/src/container/consumer.skips.test.ts index cd6b54dc423..9bb0075244a 100644 --- a/js/hang/src/container/consumer.skips.test.ts +++ b/js/hang/src/container/consumer.skips.test.ts @@ -143,7 +143,7 @@ test("a backlog start waits on a successor without frames", async () => { test("Consumer measures each skip's span over every group left, not just the new oldest", async () => { const warn = spyOn(console, "warn").mockImplementation(() => {}); const track = new Track.Producer("tone"); - const delay = new Signal({ max: Milli(30_000) }); + const delay = new Signal({ max: Milli(30_000) }); const consumer = new Consumer(track.subscribe({ delay: { max: Milli(30_000) } }), { format: new Format("data"), delay, diff --git a/sh/gh/nightly.test.py b/sh/gh/nightly.test.py index a3e88f90fe2..c0076dc4e1c 100644 --- a/sh/gh/nightly.test.py +++ b/sh/gh/nightly.test.py @@ -193,13 +193,16 @@ def test_every_js_bench_runs_nightly(self): continue for path in recipes[args[2]]: entries.add(ROOT / "js" / path.replace("{{ name }}", args[-1])) - # The browser smoke lane runs the in-memory net fixtures in Chromium. + # The browser smoke lane runs the in-memory fixtures in Chromium. self.assertIn("recipe: bench-browser --smoke", workflow) smoke = re.search( r"^for benchmark in (.+); do\n\s+bun micro\.ts ", (ROOT / "bench/browser/run.sh").read_text(), re.M ) self.assertIsNotNone(smoke) - entries |= {ROOT / "js/net/bench" / f"{name}.ts" for name in smoke[1].split()} + for name in smoke[1].split(): + fixtures = list((ROOT / "js").glob(f"*/bench/{name}.ts")) + self.assertEqual(len(fixtures), 1, f"browser smoke bench {name}") + entries |= set(fixtures) # Bundled helpers only run through the entry that names them. helpers = { path for entry in entries for path in entry.parent.glob("*.ts") if f"/{path.name}" in entry.read_text()