@swf2es/player-hosts 0.0.0-stage → 0.1.0

package/dist/thread/player/scripting/timers.js

@@ -0,0 +1,434 @@
+import { SpinClock } from "../clock.js";
+export class Timers {
+    s;
+    /**
+     * The frame clock, in ms since the start, moved by the frame step alone;
+     * Timer fires by it without a real clock, and sounds go by it with one.
+     */
+    clock = 0;
+    /**
+     * By the frame clock, the time getTimer tells and a timer started now
+     * counts from (sounds go by it with either clock): the clock,
+     * except while a timer's closure runs, when it is the time the timer fell
+     * due, as Flash fires timers between frames at their own times, so that
+     * one timer set from another keeps the first's pace, not the frame's.
+     */
+    now = 0;
+    realTime;
+    /** The timers started, by their Timer objects, and a heap of them by when they fall due. */
+    running = new Map();
+    timers = new TimerHeap();
+    /** Timers started so far: a pass of the real clock fires those due in start order. */
+    starts = 0;
+    /** Set by updateAfterEvent: a timer fired between frames has the stage render after it. */
+    renderAsked = false;
+    /**
+     * The timers' time with a real clock: the host's, the sum of what it
+     * passed to advance() since the first call, which started it at the
+     * real clock's; NaN until then. Frames lie on an exact grid by it, where
+     * the real clock read as each runs wobbles with the host's latency, and
+     * a timer as long as a frame would miss frames by a fraction of a ms.
+     */
+    host = Number.NaN;
+    /** elapsed() when `host` last moved, to tell the time between calls. */
+    hostReal = 0;
+    /**
+     * The time of the frame or the between-frames pass that runs, which a
+     * timer started in it counts from; NaN outside. A frame's is the call's
+     * time, less the frame interval for each frame the call plays after it.
+     */
+    at = Number.NaN;
+    /**
+     * The running frame's time on the frame grid: the time it fell due,
+     * which the timers as long as a frame or longer go by, so that one of
+     * the frame's length fires every frame however the host's calls fall
+     * (a 25 fps SWF's frames are 33 and 50 ms apart at 60 Hz). Those shorter
+     * go by `at`, so as not to wait for a between-frames check's time plus
+     * their delay while the frame runs late.
+     */
+    grid = Number.NaN;
+    /**
+     * While a frame waits for a load from bytes, the host's time of the
+     * frame's slot: no timer due after it fires until release(); Infinity
+     * otherwise (Player.advance).
+     */
+    cap = Number.POSITIVE_INFINITY;
+    /** The last pass's time: none goes back before it. */
+    lastPass = Number.NEGATIVE_INFINITY;
+    /** The real clock's last finite reading, and the sum of its forward steps since the start. */
+    lastRaw = Number.NaN;
+    sum = 0;
+    /** getTimer on the real clock, skipping a spin on it (clock.ts). */
+    spin;
+    constructor(s, options) {
+        this.s = s;
+        this.realTime = options.realTime === undefined ? defaultClock() : options.realTime;
+        this.spin = new SpinClock(() => this.elapsed());
+        // getTimer's zero: when the player is made, as Flash's is when it starts.
+        if (this.realTime) {
+            this.elapsed();
+        }
+    }
+    /**
+     * What getTimer tells: whole milliseconds since the start, by the real
+     * clock, truncated as Flash's are, or by the frame clock's now, rounded
+     * as it always has been, so that the traces recorded by it stay.
+     */
+    timer() {
+        if (!this.realTime) {
+            return Math.round(this.now);
+        }
+        return Math.floor(this.spin.read());
+    }
+    /**
+     * How far getTimer and the timers run ahead of the real clock, in ms,
+     * since a spin had the clock skip to the time it waited for: the frames
+     * wait for the real clock (Player.advance). Ends the pass that ran.
+     */
+    ahead() {
+        return this.realTime ? this.spin.ahead() : 0;
+    }
+    /** What the clock tells beyond the real clock at `real`: the timers' time keeps to getTimer's. */
+    lead(real) {
+        return this.spin.lead(real);
+    }
+    /**
+     * Milliseconds since the start by the real clock, unrounded: the sum of
+     * its forward steps, so that a reading that is not finite is skipped and
+     * one that jumps back neither goes back nor stops the time after it.
+     */
+    elapsed() {
+        const raw = this.realTime();
+        if (Number.isFinite(raw)) {
+            if (raw > this.lastRaw) {
+                this.sum += raw - this.lastRaw;
+            }
+            this.lastRaw = raw;
+        }
+        return this.sum;
+    }
+    /** The timers' time now with a real clock: the host's, run on by the real clock since. */
+    current() {
+        const real = this.elapsed();
+        const time = Number.isNaN(this.host) ? real : this.host + (real - this.hostReal);
+        return time + this.lead(real);
+    }
+    /** advance() was called with `passed` ms: the host's time moves on. */
+    hostPassed(passed) {
+        if (!this.realTime) {
+            return;
+        }
+        const real = this.elapsed();
+        this.host = Number.isNaN(this.host) ? real : this.host + passed;
+        this.hostReal = real;
+    }
+    /**
+     * The next frame of the call runs `slot` ms of frames before its last,
+     * and fell due on the grid `rest` ms before that; both NaN once the
+     * call's frames are over.
+     */
+    frameAt(slot, rest) {
+        const off = Number.isNaN(slot) || Number.isNaN(this.host);
+        const lead = off ? 0 : this.lead(this.elapsed());
+        this.at = off ? Number.NaN : this.host - slot + lead;
+        this.grid = off ? Number.NaN : this.host - slot - rest + lead;
+    }
+    /**
+     * A frame waits for a load from bytes `ms` before its slot, from the
+     * host's time now: timers due after the slot wait for release(), then
+     * fire once each, the ticks they lost dropped. Already waiting, nothing.
+     */
+    holdAfter(ms) {
+        if (this.realTime && this.cap === Number.POSITIVE_INFINITY && !Number.isNaN(this.host)) {
+            this.cap = this.host + this.lead(this.elapsed()) + ms;
+        }
+    }
+    /** The frame that waited has played: the timers fire as they fall due again. */
+    release() {
+        this.cap = Number.POSITIVE_INFINITY;
+    }
+    /** A frame begins: the frame clock moves on by `ms`; its timers fire after ENTER_FRAME. */
+    beginFrame(ms) {
+        if (this.realTime) {
+            this.spin.settle();
+        }
+        this.clock += ms;
+        this.now = this.clock;
+    }
+    /**
+     * By the frame clock, the timers that fall due by the frame's time, each
+     * firing the earliest due, so that two timers interleave as their times
+     * do and one started from another with time to spare fires in the same
+     * pass.
+     */
+    fireByClock() {
+        try {
+            for (;;) {
+                const next = this.timers.pop(this.clock);
+                if (!next) {
+                    break;
+                }
+                this.now = next.due;
+                next.due += next.delay;
+                try {
+                    this.s.rt.call(next.closure, next.object);
+                }
+                catch (error) {
+                    // Reported, and the timers after it and the frame still run.
+                    this.s.reportUncaught(error);
+                }
+                finally {
+                    // Pushed back whatever the call did, unless it stopped the timer or
+                    // started it anew: one whose closure throws still has its next time.
+                    if (!next.stopped) {
+                        this.timers.push(next);
+                    }
+                }
+            }
+        }
+        finally {
+            this.now = this.clock;
+        }
+    }
+    /**
+     * The frame's timers, after ENTER_FRAME and before the frame's
+     * construction, as Flash fires them: by the real clock every timer due
+     * fires once; by the frame clock every due time in the frame fires.
+     */
+    frameTimers() {
+        if (this.realTime) {
+            // A frame run by tick() alone, not advance(), goes by the time now.
+            const now = Number.isNaN(this.at) ? this.current() : this.at;
+            const grid = Number.isNaN(this.grid) ? now : this.grid;
+            this.fireDue(now, grid, 1000 / this.s.frameRate, false);
+        }
+        else {
+            this.fireByClock();
+        }
+    }
+    /**
+     * A check between frames by the real clock: the timers due whose delay
+     * is shorter than the frame fire once each. Flash fires those between
+     * frames at their times and holds a longer one for the next frame, a
+     * 45 ms timer at 24 fps firing every other frame though the player
+     * checks between (measured in adl, docs/architecture/input.md).
+     */
+    betweenFrames(frameMs) {
+        if (!this.realTime) {
+            return;
+        }
+        this.spin.settle();
+        const real = this.elapsed();
+        this.at = (Number.isNaN(this.host) ? real : this.host) + this.lead(real);
+        try {
+            this.fireDue(this.at, Number.NaN, frameMs, true);
+        }
+        finally {
+            this.at = Number.NaN;
+        }
+    }
+    /**
+     * A pass: each timer due fires once, in the order the timers were
+     * started, and next falls due its delay after the frame's time on the
+     * grid, or after `time` between frames (`frameGrid` NaN), so the ticks a long
+     * frame or a stall lost are dropped, not caught up with, as in Flash.
+     * Those shorter than `frameMs` are due by `time`; the others by `frameGrid`,
+     * and wait for a frame.
+     */
+    fireDue(time, frameGrid, frameMs, between) {
+        // While a frame waits for a load, none due after its slot.
+        const now = Math.max(Math.min(time, this.cap), this.lastPass);
+        const grid = Math.min(frameGrid, this.cap);
+        this.lastPass = now;
+        const due = [];
+        const held = [];
+        for (;;) {
+            // The grid's time is never after the call's. Sums of a host's
+            // intervals land a hair off the grid: due then is due.
+            const next = this.timers.pop(now + GRID_SLACK);
+            if (!next) {
+                break;
+            }
+            // A short timer is due by the call's time, so as not to wait for a
+            // between-frames check's time plus its delay while the frame runs
+            // late; a longer one by the grid's. Either next falls due from the
+            // grid's, which frames keep to, as Flash's keep to its own.
+            // Between frames, a short one also waits its whole delay since it
+            // last fired, as Flash's do: due from the grid, it is a little early.
+            const short = next.delay < frameMs;
+            const ready = !between || next.fired + next.delay <= now + GRID_SLACK;
+            if (ready && next.due <= (short ? now : grid) + GRID_SLACK) {
+                next.due = Number.isNaN(grid) ? now : grid;
+                next.fired = now;
+                due.push(next);
+            }
+            else {
+                held.push(next);
+            }
+        }
+        for (const record of held) {
+            this.timers.push(record);
+        }
+        if (!due.length) {
+            return;
+        }
+        due.sort((a, b) => a.order - b.order);
+        try {
+            for (const record of due) {
+                // Stopped by a closure before it in the pass; one started anew has a record of its own.
+                if (record.stopped) {
+                    continue;
+                }
+                // `due` holds the time it fired by, set above.
+                record.due += record.delay;
+                this.renderAsked = false;
+                try {
+                    this.s.rt.call(record.closure, record.object);
+                }
+                catch (error) {
+                    this.s.reportUncaught(error);
+                }
+                finally {
+                    if (!record.stopped) {
+                        this.timers.push(record);
+                    }
+                }
+                // updateAfterEvent between frames: the stage renders now, RENDER and all, as in Flash.
+                if (between && this.renderAsked) {
+                    this.s.render();
+                }
+            }
+        }
+        finally {
+            this.renderAsked = false;
+        }
+    }
+    /** Timer._start: `closure` is called every `delay` ms from now, until stopped; a timer running already is started anew. */
+    startTimer(object, delay, closure) {
+        this.stopTimer(object);
+        // Whole milliseconds, as Flash's: Timer(1000 / 24) is 41 ms, shorter than the frame.
+        const ms = Math.max(Math.trunc(delay) || 0, 1);
+        // In a frame, one as long as a frame counts from the frame's time on
+        // the grid, which it fires by; others from the frame's or the pass's.
+        let from = this.now;
+        if (this.realTime) {
+            const long = ms >= 1000 / this.s.frameRate && !Number.isNaN(this.grid);
+            from = long ? this.grid : Number.isNaN(this.at) ? this.current() : this.at;
+        }
+        const record = {
+            object,
+            delay: ms,
+            closure,
+            due: from + ms,
+            fired: Number.NEGATIVE_INFINITY,
+            seq: 0,
+            order: this.starts++,
+            stopped: false,
+        };
+        this.running.set(object, record);
+        this.timers.push(record);
+    }
+    stopTimer(object) {
+        const record = this.running.get(object);
+        if (record) {
+            record.stopped = true;
+            this.running.delete(object);
+            this.timers.stopped();
+        }
+    }
+    timerRunning(object) {
+        return this.running.has(object);
+    }
+}
+/** How far past a pass's time a timer still counts as due, in ms: far below a whole one. */
+const GRID_SLACK = 1e-6;
+/** The real clock where the host has one, browsers and node alike; else none, and the frame clock. */
+function defaultClock() {
+    return typeof performance !== "undefined" ? () => performance.now() : null;
+}
+/**
+ * The started timers by due time, a binary min-heap as asyncio keeps its
+ * scheduled callbacks: the next due is found and rescheduled in O(log n)
+ * where a scan of all timers is O(n) per firing, which at a thousand
+ * timers is the difference between 0.3 and 2.5 ms a frame. A stopped
+ * timer stays until it surfaces, and the heap is rebuilt without the
+ * stopped when they are more than half of it.
+ */
+class TimerHeap {
+    heap = [];
+    seq = 0;
+    stoppedCount = 0;
+    push(record) {
+        record.seq = this.seq++;
+        this.insert(record);
+    }
+    /** `record` in its place by due time and the sequence it has. */
+    insert(record) {
+        const h = this.heap;
+        h.push(record);
+        let i = h.length - 1;
+        while (i > 0) {
+            const parent = (i - 1) >> 1;
+            if (!before(h[i], h[parent])) {
+                break;
+            }
+            [h[i], h[parent]] = [h[parent], h[i]];
+            i = parent;
+        }
+    }
+    /** The earliest due timer at or before `clock`, taken out; stopped ones in the way are dropped. */
+    pop(clock) {
+        for (;;) {
+            const top = this.heap[0];
+            if (!top || top.due > clock) {
+                return null;
+            }
+            this.remove();
+            if (top.stopped) {
+                this.stoppedCount--;
+                continue;
+            }
+            return top;
+        }
+    }
+    stopped() {
+        this.stoppedCount++;
+        if (this.stoppedCount > this.heap.length / 2) {
+            // Rebuilt with each record's own sequence: the order of two due at once must not change.
+            const live = this.heap.filter((r) => !r.stopped);
+            this.heap = [];
+            this.stoppedCount = 0;
+            for (const record of live) {
+                this.insert(record);
+            }
+        }
+    }
+    remove() {
+        const h = this.heap;
+        const last = h.pop();
+        if (!h.length) {
+            return;
+        }
+        h[0] = last;
+        let i = 0;
+        for (;;) {
+            const left = 2 * i + 1;
+            const right = left + 1;
+            let least = i;
+            if (left < h.length && before(h[left], h[least])) {
+                least = left;
+            }
+            if (right < h.length && before(h[right], h[least])) {
+                least = right;
+            }
+            if (least === i) {
+                break;
+            }
+            [h[i], h[least]] = [h[least], h[i]];
+            i = least;
+        }
+    }
+}
+function before(a, b) {
+    return a.due < b.due || (a.due === b.due && a.seq < b.seq);
+}