@woosh/meep-engine 3.26.0 → 3.27.0

package/src/shade/renderer/geometry/virtual/runtime/VGeoPageFetcher.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @typedef {import("../format/read/VGeoContainerReader.js").VGeoContainerReader} VGeoContainerReader
+ * @typedef {import("../format/read/VGeoPage.js").VGeoPage} VGeoPage
+ */
+/**
+ * Pages fetched, verified and decoded off the main thread, for every container a residency holds.
+ *
+ * A pool of module workers, each serving `vgeo_page_worker_serve`, and an in-process fall-back that
+ * is the same core on this thread. A container goes to the workers when its byte source carries a
+ * `descriptor` — a URL, a `Blob`, bytes in memory — and stays here when it does not, which is what
+ * a source built by hand in a spec is. Requests round-robin; a container's descriptor is sent to a
+ * worker once, with the first request that names it there.
+ *
+ * What comes back is a `VGeoPage` with its buffers transferred, not copied, and what the residency
+ * does with it is `reader.adopt(page)` — the reader's page map is still the RAM tier's store, and
+ * the reader still owns quarantine; the fetch just no longer runs inside it
+ * (RUNTIME_PLAN_2026_09_14 §4.6).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoPageFetcher {
+    /**
+     * @param {Object} [options]
+     * @param {number} [options.worker_count] zero runs everything in-process
+     * @param {function(): Worker} [options.make_worker] how a worker is spawned —
+     *     `make_vgeo_page_worker` in a browser, a loopback in a spec, nothing under a runner with no
+     *     `Worker`, in which case everything runs in-process
+     */
+    constructor({ worker_count, make_worker }?: {
+        worker_count?: number;
+        make_worker?: () => Worker;
+    });
+    /**
+     * @returns {number}
+     */
+    get worker_count(): number;
+    /**
+     * Fetches answered by a worker.
+     * @returns {number}
+     */
+    get worker_fetch_count(): number;
+    /**
+     * Fetches answered on this thread.
+     * @returns {number}
+     */
+    get in_process_fetch_count(): number;
+    /**
+     * @returns {number}
+     */
+    get pending_count(): number;
+    /**
+     * Bytes fetched by the workers — a source's own `bytes_read` counts only this thread's reads.
+     * @returns {number}
+     */
+    get worker_bytes_read(): number;
+    /**
+     * @param {VGeoContainerReader} reader open, so its header and options are known
+     * @param {number} page_index
+     * @param {number} frame_offset
+     * @param {number} fetch_size
+     * @param {AbortSignal} [signal]
+     * @returns {Promise<VGeoPage>} rejects with a {@link VGeoFetchError}
+     */
+    fetch(reader: VGeoContainerReader, page_index: number, frame_offset: number, fetch_size: number, signal?: AbortSignal): Promise<VGeoPage>;
+    /**
+     * Give up on every fetch of one container: what is on the wire in a worker is cancelled, and
+     * every promise for it rejects as cancelled rather than quarantined.
+     *
+     * @param {VGeoContainerReader} reader
+     * @returns {number} fetches cancelled
+     */
+    cancel(reader: VGeoContainerReader): number;
+    /**
+     * Terminate the workers and reject what they were doing.
+     *
+     * @returns {void}
+     */
+    destroy(): void;
+    #private;
+}
+export type VGeoContainerReader = import("../format/read/VGeoContainerReader.js").VGeoContainerReader;
+export type VGeoPage = import("../format/read/VGeoPage.js").VGeoPage;
+//# sourceMappingURL=VGeoPageFetcher.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/VGeoPageFetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoPageFetcher.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/VGeoPageFetcher.js"],"names":[],"mappings":"AAIA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;IA0EI;;;;;;OAMG;IACH;QAL4B,YAAY,GAA7B,MAAM;QACuB,WAAW,SAA5B,MAAM;OAS5B;IAED;;OAEG;IACH,2BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,qCAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;OAGG;IACH,gCAEC;IAED;;;;;;;OAOG;IACH,cAPW,mBAAmB,cACnB,MAAM,gBACN,MAAM,cACN,MAAM,WACN,WAAW,GACT,QAAQ,QAAQ,CAAC,CAc7B;IAED;;;;;;OAMG;IACH,eAHW,mBAAmB,GACjB,MAAM,CAuBlB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAiBhB;;CAwKJ;kCAnYY,OAAO,uCAAuC,EAAE,mBAAmB;uBACnE,OAAO,4BAA4B,EAAE,QAAQ"}

package/src/shade/renderer/geometry/virtual/runtime/VGeoPageFetcher.js

@@ -0,0 +1,393 @@
+import { assert } from "../../../../../core/assert.js";
+import { VGeoFetchError, VGeoPageFetcherCore } from "../format/read/VGeoPageFetcherCore.js";
+import { vgeo_page_from_transfer } from "../format/read/vgeo_page_transfer.js";
+
+/**
+ * @typedef {import("../format/read/VGeoContainerReader.js").VGeoContainerReader} VGeoContainerReader
+ * @typedef {import("../format/read/VGeoPage.js").VGeoPage} VGeoPage
+ */
+
+/**
+ * Pages fetched, verified and decoded off the main thread, for every container a residency holds.
+ *
+ * A pool of module workers, each serving `vgeo_page_worker_serve`, and an in-process fall-back that
+ * is the same core on this thread. A container goes to the workers when its byte source carries a
+ * `descriptor` — a URL, a `Blob`, bytes in memory — and stays here when it does not, which is what
+ * a source built by hand in a spec is. Requests round-robin; a container's descriptor is sent to a
+ * worker once, with the first request that names it there.
+ *
+ * What comes back is a `VGeoPage` with its buffers transferred, not copied, and what the residency
+ * does with it is `reader.adopt(page)` — the reader's page map is still the RAM tier's store, and
+ * the reader still owns quarantine; the fetch just no longer runs inside it
+ * (RUNTIME_PLAN_2026_09_14 §4.6).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoPageFetcher {
+    /**
+     * @type {number}
+     */
+    #worker_count;
+
+    /**
+     * @type {function(): Worker}
+     */
+    #make_worker;
+
+    /**
+     * @type {(Worker|MessagePort|object)[]}
+     */
+    #workers = [];
+
+    /**
+     * Per worker, the source ids it has been given a descriptor for.
+     * @type {Set<number>[]}
+     */
+    #known = [];
+
+    /**
+     * @type {number}
+     */
+    #next_worker = 0;
+
+    /**
+     * Whether spawning failed, after which everything runs in-process for good.
+     * @type {boolean}
+     */
+    #no_workers = false;
+
+    /**
+     * @type {number}
+     */
+    #next_id = 1;
+
+    /**
+     * @type {Map<number, {resolve: function, reject: function, reader: VGeoContainerReader, worker: number}>}
+     */
+    #pending = new Map();
+
+    /**
+     * @type {Map<VGeoContainerReader, number>}
+     */
+    #source_ids = new Map();
+
+    /**
+     * @type {number}
+     */
+    #next_source_id = 1;
+
+    /**
+     * @type {Map<VGeoContainerReader, VGeoPageFetcherCore>}
+     */
+    #cores = new Map();
+
+    /**
+     * @type {number}
+     */
+    #worker_fetch_count = 0;
+
+    /**
+     * @type {number}
+     */
+    #in_process_fetch_count = 0;
+
+    /**
+     * Bytes the workers read, which this thread's byte sources never see.
+     * @type {number}
+     */
+    #worker_bytes_read = 0;
+
+    /**
+     * @param {Object} [options]
+     * @param {number} [options.worker_count] zero runs everything in-process
+     * @param {function(): Worker} [options.make_worker] how a worker is spawned —
+     *     `make_vgeo_page_worker` in a browser, a loopback in a spec, nothing under a runner with no
+     *     `Worker`, in which case everything runs in-process
+     */
+    constructor({ worker_count = 0, make_worker = undefined } = {}) {
+        assert.isNonNegativeInteger(worker_count, 'worker_count');
+
+        this.#worker_count = worker_count;
+        this.#make_worker = make_worker;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get worker_count() {
+        return this.#worker_count;
+    }
+
+    /**
+     * Fetches answered by a worker.
+     * @returns {number}
+     */
+    get worker_fetch_count() {
+        return this.#worker_fetch_count;
+    }
+
+    /**
+     * Fetches answered on this thread.
+     * @returns {number}
+     */
+    get in_process_fetch_count() {
+        return this.#in_process_fetch_count;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get pending_count() {
+        return this.#pending.size;
+    }
+
+    /**
+     * Bytes fetched by the workers — a source's own `bytes_read` counts only this thread's reads.
+     * @returns {number}
+     */
+    get worker_bytes_read() {
+        return this.#worker_bytes_read;
+    }
+
+    /**
+     * @param {VGeoContainerReader} reader open, so its header and options are known
+     * @param {number} page_index
+     * @param {number} frame_offset
+     * @param {number} fetch_size
+     * @param {AbortSignal} [signal]
+     * @returns {Promise<VGeoPage>} rejects with a {@link VGeoFetchError}
+     */
+    fetch(reader, page_index, frame_offset, fetch_size, signal = undefined) {
+        assert.defined(reader, 'reader');
+
+        if (this.#worker_count > 0 && !this.#no_workers && reader.source.descriptor !== undefined) {
+            const worker = this.#worker_for();
+
+            if (worker !== -1) {
+                return this.#fetch_in_worker(worker, reader, page_index, frame_offset, fetch_size, signal);
+            }
+        }
+
+        return this.#fetch_in_process(reader, page_index, frame_offset, fetch_size, signal);
+    }
+
+    /**
+     * Give up on every fetch of one container: what is on the wire in a worker is cancelled, and
+     * every promise for it rejects as cancelled rather than quarantined.
+     *
+     * @param {VGeoContainerReader} reader
+     * @returns {number} fetches cancelled
+     */
+    cancel(reader) {
+        let cancelled = 0;
+
+        for (const [id, entry] of Array.from(this.#pending)) {
+            if (entry.reader !== reader) {
+                continue;
+            }
+
+            this.#pending.delete(id);
+
+            this.#workers[entry.worker].postMessage({ cancel: id });
+
+            entry.reject(new VGeoFetchError('the fetch was cancelled', false, 'cancelled'));
+
+            cancelled++;
+        }
+
+        this.#source_ids.delete(reader);
+        this.#cores.delete(reader);
+
+        return cancelled;
+    }
+
+    /**
+     * Terminate the workers and reject what they were doing.
+     *
+     * @returns {void}
+     */
+    destroy() {
+        for (const entry of this.#pending.values()) {
+            entry.reject(new VGeoFetchError('the fetcher was destroyed', false, 'destroyed'));
+        }
+
+        this.#pending.clear();
+
+        for (const worker of this.#workers) {
+            worker.terminate?.();
+        }
+
+        this.#workers.length = 0;
+        this.#known.length = 0;
+        this.#cores.clear();
+        this.#source_ids.clear();
+    }
+
+    /**
+     * The next worker in the round, spawning the pool on first use.
+     *
+     * @returns {number} index, or -1 when no worker can be had
+     */
+    #worker_for() {
+        if (this.#workers.length === 0) {
+            const make = this.#make_worker;
+
+            if (make === undefined) {
+                // nobody said how to spawn one: a runner with no Worker, or a host that did not
+                // wire `make_vgeo_page_worker`
+                this.#no_workers = true;
+
+                return -1;
+            }
+
+            try {
+                for (let i = 0; i < this.#worker_count; i++) {
+                    const worker = make();
+
+                    worker.onmessage = event => this.#on_message(event.data);
+
+                    this.#workers.push(worker);
+                    this.#known.push(new Set());
+                }
+            } catch (e) {
+                // no Worker here — a test runner, a host without one — so everything stays on this
+                // thread, and it is said once rather than once per page
+                console.warn('vgeo: page fetches will run in-process', e);
+
+                this.#no_workers = true;
+
+                for (const worker of this.#workers) {
+                    worker.terminate?.();
+                }
+
+                this.#workers.length = 0;
+                this.#known.length = 0;
+
+                return -1;
+            }
+        }
+
+        const worker = this.#next_worker;
+
+        this.#next_worker = (worker + 1) % this.#workers.length;
+
+        return worker;
+    }
+
+    /**
+     * @param {number} worker
+     * @param {VGeoContainerReader} reader
+     * @param {number} page_index
+     * @param {number} frame_offset
+     * @param {number} fetch_size
+     * @param {AbortSignal|undefined} signal
+     * @returns {Promise<VGeoPage>}
+     */
+    #fetch_in_worker(worker, reader, page_index, frame_offset, fetch_size, signal) {
+        let source_id = this.#source_ids.get(reader);
+
+        if (source_id === undefined) {
+            source_id = this.#next_source_id++;
+
+            this.#source_ids.set(reader, source_id);
+        }
+
+        const id = this.#next_id++;
+
+        const options = reader.options;
+
+        const request = {
+            id,
+            source_id,
+            asset_id_low64: reader.header.asset_id_low64,
+            verify_frames: options.verify_frames,
+            fetch_retries: options.fetch_retries,
+            fetch_retry_backoff_ms: options.fetch_retry_backoff_ms,
+            page_index,
+            frame_offset,
+            fetch_size,
+        };
+
+        const known = this.#known[worker];
+
+        if (!known.has(source_id)) {
+            request.descriptor = reader.source.descriptor;
+
+            known.add(source_id);
+        }
+
+        this.#worker_fetch_count++;
+
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, { resolve, reject, reader, worker, fetch_size });
+
+            if (signal !== undefined) {
+                signal.addEventListener('abort', () => {
+                    if (this.#pending.delete(id)) {
+                        this.#workers[worker].postMessage({ cancel: id });
+
+                        reject(new VGeoFetchError(`page ${page_index}: the fetch was cancelled`, false, 'cancelled'));
+                    }
+                }, { once: true });
+            }
+
+            this.#workers[worker].postMessage(request);
+        });
+    }
+
+    /**
+     * @param {object} data
+     */
+    #on_message(data) {
+        const entry = this.#pending.get(data.id);
+
+        if (entry === undefined) {
+            // cancelled, or the container left while this was on the wire
+            return;
+        }
+
+        this.#pending.delete(data.id);
+
+        if (data.error !== undefined) {
+            entry.reject(new VGeoFetchError(data.error.message, data.error.quarantine, data.error.reason));
+
+            return;
+        }
+
+        this.#worker_bytes_read += entry.fetch_size;
+
+        entry.resolve(vgeo_page_from_transfer(data.page));
+    }
+
+    /**
+     * @param {VGeoContainerReader} reader
+     * @param {number} page_index
+     * @param {number} frame_offset
+     * @param {number} fetch_size
+     * @param {AbortSignal|undefined} signal
+     * @returns {Promise<VGeoPage>}
+     */
+    #fetch_in_process(reader, page_index, frame_offset, fetch_size, signal) {
+        let core = this.#cores.get(reader);
+
+        if (core === undefined) {
+            const source = reader.source;
+            const options = reader.options;
+
+            core = new VGeoPageFetcherCore({
+                read: (offset, length, abort) => source.read(offset, length, abort),
+                asset_id_low64: () => reader.header.asset_id_low64,
+                verify_frames: options.verify_frames,
+                fetch_retries: options.fetch_retries,
+                fetch_retry_backoff_ms: options.fetch_retry_backoff_ms,
+            });
+
+            this.#cores.set(reader, core);
+        }
+
+        this.#in_process_fetch_count++;
+
+        return core.fetch(page_index, frame_offset, fetch_size, signal);
+    }
+}