@saber-usa/node-common 1.7.18-alpha.1 → 1.7.19

package/src/wasmProp/runtime.js

@@ -1,147 +1,147 @@
-import {createSingleThreadRuntime, BulkPropagator} from "satellite.js";
-
-// Module-local state. In Node, ES module instances are per Realm/per worker
-// thread, so this state is naturally per-thread when consumed inside
-// `worker_threads` (e.g. node-pub-sub's workerpool workers).
-//
-// See docs/BULK_PROPAGATION.md sections 6, 7, and 8 for the consumer model,
-// lifecycle, and registry design.
-let runtimePromise = null;
-let registry = new Map();
-
-/**
- * Lazily creates (or returns) the per-thread WASM runtime.
- *
- * On first call within a thread, triggers `createSingleThreadRuntime()`
- * (the v7 successor to the blog's `createWasmModule()`) and caches the
- * resulting promise. All subsequent callers in that thread reuse it.
- *
- * Safe to await concurrently: every caller awaits the same in-flight
- * promise, so only one WASM compile + instantiate ever happens.
- *
- * @return {Promise<import("satellite.js").SingleThreadRuntime>}
- */
-const getBulkRuntime = () => {
-    if (runtimePromise === null) {
-        runtimePromise = createSingleThreadRuntime();
-    }
-    return runtimePromise;
-};
-
-/**
- * Eager bootstrap. Equivalent to `await getBulkRuntime()` but named for the
- * explicit warm-up call site (e.g. top of `dedicated_worker.js`).
- *
- * @return {Promise<import("satellite.js").SingleThreadRuntime>}
- */
-const initBulkRuntime = () => getBulkRuntime();
-
-/**
- * Returns true if the runtime has been requested in this thread (regardless
- * of whether it has finished initializing). Used by tests and by the
- * disposal path to decide whether dispose work is necessary.
- *
- * @return {boolean}
- */
-const isBulkRuntimeInitialized = () => runtimePromise !== null;
-
-/**
- * Acquires (or lazily constructs) the per-thread, per-pipeline singleton
- * `BulkPropagator` for the given pipeline key.
- *
- * Reuse rules:
- * - The same instance is returned on every call with the same `key`.
- * - If the caller's `satRecsCount` or `datesCount` exceed the current
- *   allocation, the propagator's own `setSatRecs` / `setDates` will perform
- *   a single `free` + `malloc` grow-realloc internally on the next set.
- *   The initial allocation here is sized to the first caller's request, so
- *   "warm" subsequent calls of the same shape pay zero allocation cost.
- *
- * Caller responsibilities:
- * - `setSatRecs`, `setDates`, then `run()` between `acquire` and using
- *   results. Within a single thread these are synchronous so no other
- *   pipeline consumer can interleave (per docs/BULK_PROPAGATION.md §9).
- * - **Do not call `dispose()` on the returned propagator.** Lifecycle is
- *   owned by the registry; `disposeBulkRuntime()` is the only sanctioned
- *   teardown path.
- *
- * @param {Object} params
- * @param {import("satellite.js").SingleThreadRuntime} params.runtime
- * @param {string} params.key Pipeline signature, e.g. `"eci"`.
- * @param {() => readonly any[]} params.makeCalculators Factory invoked once
- *   per (key, thread) to build fresh calculator instances. A factory is
- *   required because calculator instances are stateful and bound to a
- *   propagator at construction time; they cannot be shared across keys.
- * @param {number} params.satRecsCount Initial satellite-record allocation
- *   hint. Used only on first construction for this key in this thread.
- * @param {number} params.datesCount Initial dates allocation hint. Same
- *   first-call-only semantics.
- * @return {import("satellite.js").BulkPropagator<any, any>}
- */
-const getOrCreateBulkPropagator = ({
-    runtime,
-    key,
-    makeCalculators,
-    satRecsCount,
-    datesCount,
-}) => {
-    const cached = registry.get(key);
-    if (cached) {
-        return cached;
-    }
-
-    const propagator = new BulkPropagator({
-        runtime,
-        calculators: makeCalculators(),
-        satRecsCount: Math.max(1, satRecsCount),
-        datesCount: Math.max(1, datesCount),
-    });
-    registry.set(key, propagator);
-    return propagator;
-};
-
-/**
- * Releases all WASM memory owned by this thread: every registry-held
- * `BulkPropagator` is disposed and the runtime itself is torn down.
- *
- * Idempotent: safe to call when nothing was ever initialized. After this
- * returns, the next `getBulkRuntime()` will lazily re-initialize from
- * scratch.
- */
-const disposeBulkRuntime = async () => {
-    for (const propagator of registry.values()) {
-        try {
-            propagator.dispose();
-        } catch (e) {
-            // Disposal must never throw out of teardown; we surface the
-            // failure to stderr but continue cleaning up the rest of the
-            // registry to minimize the leak surface.
-            console.error("disposeBulkRuntime: failed to dispose propagator", e);
-        }
-    }
-    registry = new Map();
-
-    if (runtimePromise !== null) {
-        const pending = runtimePromise;
-        runtimePromise = null;
-        try {
-            const runtime = await pending;
-            runtime.dispose();
-        } catch (e) {
-            // Emscripten's `_exit_runtime` (with EXIT_RUNTIME=1) signals clean
-            // shutdown by throwing an `ExitStatus` object with `status === 0`.
-            // That is the documented success path, not a failure to log.
-            if (e?.name !== "ExitStatus" || e?.status !== 0) {
-                console.error("disposeBulkRuntime: failed to dispose runtime", e);
-            }
-        }
-    }
-};
-
-export {
-    getBulkRuntime,
-    initBulkRuntime,
-    isBulkRuntimeInitialized,
-    getOrCreateBulkPropagator,
-    disposeBulkRuntime,
-};
+import {createSingleThreadRuntime, BulkPropagator} from "satellite.js";
+
+// Module-local state. In Node, ES module instances are per Realm/per worker
+// thread, so this state is naturally per-thread when consumed inside
+// `worker_threads` (e.g. node-pub-sub's workerpool workers).
+//
+// See docs/BULK_PROPAGATION.md sections 6, 7, and 8 for the consumer model,
+// lifecycle, and registry design.
+let runtimePromise = null;
+let registry = new Map();
+
+/**
+ * Lazily creates (or returns) the per-thread WASM runtime.
+ *
+ * On first call within a thread, triggers `createSingleThreadRuntime()`
+ * (the v7 successor to the blog's `createWasmModule()`) and caches the
+ * resulting promise. All subsequent callers in that thread reuse it.
+ *
+ * Safe to await concurrently: every caller awaits the same in-flight
+ * promise, so only one WASM compile + instantiate ever happens.
+ *
+ * @return {Promise<import("satellite.js").SingleThreadRuntime>}
+ */
+const getBulkRuntime = () => {
+    if (runtimePromise === null) {
+        runtimePromise = createSingleThreadRuntime();
+    }
+    return runtimePromise;
+};
+
+/**
+ * Eager bootstrap. Equivalent to `await getBulkRuntime()` but named for the
+ * explicit warm-up call site (e.g. top of `dedicated_worker.js`).
+ *
+ * @return {Promise<import("satellite.js").SingleThreadRuntime>}
+ */
+const initBulkRuntime = () => getBulkRuntime();
+
+/**
+ * Returns true if the runtime has been requested in this thread (regardless
+ * of whether it has finished initializing). Used by tests and by the
+ * disposal path to decide whether dispose work is necessary.
+ *
+ * @return {boolean}
+ */
+const isBulkRuntimeInitialized = () => runtimePromise !== null;
+
+/**
+ * Acquires (or lazily constructs) the per-thread, per-pipeline singleton
+ * `BulkPropagator` for the given pipeline key.
+ *
+ * Reuse rules:
+ * - The same instance is returned on every call with the same `key`.
+ * - If the caller's `satRecsCount` or `datesCount` exceed the current
+ *   allocation, the propagator's own `setSatRecs` / `setDates` will perform
+ *   a single `free` + `malloc` grow-realloc internally on the next set.
+ *   The initial allocation here is sized to the first caller's request, so
+ *   "warm" subsequent calls of the same shape pay zero allocation cost.
+ *
+ * Caller responsibilities:
+ * - `setSatRecs`, `setDates`, then `run()` between `acquire` and using
+ *   results. Within a single thread these are synchronous so no other
+ *   pipeline consumer can interleave (per docs/BULK_PROPAGATION.md §9).
+ * - **Do not call `dispose()` on the returned propagator.** Lifecycle is
+ *   owned by the registry; `disposeBulkRuntime()` is the only sanctioned
+ *   teardown path.
+ *
+ * @param {Object} params
+ * @param {import("satellite.js").SingleThreadRuntime} params.runtime
+ * @param {string} params.key Pipeline signature, e.g. `"eci"`.
+ * @param {() => readonly any[]} params.makeCalculators Factory invoked once
+ *   per (key, thread) to build fresh calculator instances. A factory is
+ *   required because calculator instances are stateful and bound to a
+ *   propagator at construction time; they cannot be shared across keys.
+ * @param {number} params.satRecsCount Initial satellite-record allocation
+ *   hint. Used only on first construction for this key in this thread.
+ * @param {number} params.datesCount Initial dates allocation hint. Same
+ *   first-call-only semantics.
+ * @return {import("satellite.js").BulkPropagator<any, any>}
+ */
+const getOrCreateBulkPropagator = ({
+    runtime,
+    key,
+    makeCalculators,
+    satRecsCount,
+    datesCount,
+}) => {
+    const cached = registry.get(key);
+    if (cached) {
+        return cached;
+    }
+
+    const propagator = new BulkPropagator({
+        runtime,
+        calculators: makeCalculators(),
+        satRecsCount: Math.max(1, satRecsCount),
+        datesCount: Math.max(1, datesCount),
+    });
+    registry.set(key, propagator);
+    return propagator;
+};
+
+/**
+ * Releases all WASM memory owned by this thread: every registry-held
+ * `BulkPropagator` is disposed and the runtime itself is torn down.
+ *
+ * Idempotent: safe to call when nothing was ever initialized. After this
+ * returns, the next `getBulkRuntime()` will lazily re-initialize from
+ * scratch.
+ */
+const disposeBulkRuntime = async () => {
+    for (const propagator of registry.values()) {
+        try {
+            propagator.dispose();
+        } catch (e) {
+            // Disposal must never throw out of teardown; we surface the
+            // failure to stderr but continue cleaning up the rest of the
+            // registry to minimize the leak surface.
+            console.error("disposeBulkRuntime: failed to dispose propagator", e);
+        }
+    }
+    registry = new Map();
+
+    if (runtimePromise !== null) {
+        const pending = runtimePromise;
+        runtimePromise = null;
+        try {
+            const runtime = await pending;
+            runtime.dispose();
+        } catch (e) {
+            // Emscripten's `_exit_runtime` (with EXIT_RUNTIME=1) signals clean
+            // shutdown by throwing an `ExitStatus` object with `status === 0`.
+            // That is the documented success path, not a failure to log.
+            if (e?.name !== "ExitStatus" || e?.status !== 0) {
+                console.error("disposeBulkRuntime: failed to dispose runtime", e);
+            }
+        }
+    }
+};
+
+export {
+    getBulkRuntime,
+    initBulkRuntime,
+    isBulkRuntimeInitialized,
+    getOrCreateBulkPropagator,
+    disposeBulkRuntime,
+};