@navaramap/worker 0.0.0

package/src/helpers/transferReturnedConstructedTerrainMesh.ts

@@ -0,0 +1,21 @@
+import { ReturnedConstructedTerrainMeshLike } from "@navaramap/core";
+import type { ReturnedConstructedTerrainMesh } from "@navaramap/engine-worker";
+
+export function transferReturnedConstructedTerrainMesh(
+  r: ReturnedConstructedTerrainMesh,
+) {
+  const like = new ReturnedConstructedTerrainMeshLike(r);
+  const transfers: ArrayBufferLike[] = [
+    like.vertices.buffer,
+    like.uvs.buffer,
+    like.indices.buffer,
+    like.heights.buffer,
+  ];
+  if (like.normals) transfers.push(like.normals.buffer);
+  if (like.skirt_vertices) transfers.push(like.skirt_vertices.buffer);
+  if (like.skirt_uvs) transfers.push(like.skirt_uvs.buffer);
+  if (like.skirt_indices) transfers.push(like.skirt_indices.buffer);
+  if (like.skirt_normals) transfers.push(like.skirt_normals.buffer);
+  if (like.watermask) transfers.push(like.watermask.buffer);
+  return { result: like, transfers };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./pool";
+export * from "./worker";
+export * from "./manager";
+export type { ParsedMvtTileResultLike } from "./tasks/parseMvtTile";

package/src/manager.test.ts

@@ -0,0 +1,45 @@
+import { expect, it } from "vitest";
+
+import { createConcurrencyManager } from "./manager";
+
+it("should get correct concurrency states", () => {
+  const manager = createConcurrencyManager(1);
+
+  // Initialize
+  expect(manager.actives()).toBe(0);
+  expect(manager.idles()).toBe(1);
+  expect(manager.total).toBe(1);
+
+  // Increment
+
+  expect(manager.canIncrement()).toBeTruthy();
+
+  manager.increment();
+  expect(manager.actives()).toBe(1);
+  expect(manager.idles()).toBe(0);
+
+  expect(manager.canIncrement()).toBeFalsy();
+  manager.increment();
+  expect(manager.actives()).toBe(1);
+  expect(manager.idles()).toBe(0);
+
+  // Decrement
+
+  expect(manager.canDecrement()).toBeTruthy();
+
+  manager.decrement();
+  expect(manager.actives()).toBe(0);
+  expect(manager.idles()).toBe(1);
+
+  expect(manager.canDecrement()).toBeFalsy();
+  manager.decrement();
+  expect(manager.actives()).toBe(0);
+  expect(manager.idles()).toBe(1);
+
+  // Reset
+
+  manager.increment();
+  manager.reset();
+  expect(manager.actives()).toBe(0);
+  expect(manager.idles()).toBe(1);
+});

package/src/manager.ts

@@ -0,0 +1,43 @@
+export type ConcurrencyManager = {
+  /** Total concurrency */
+  total: number;
+  /** Increment the count according to the activated process */
+  increment: () => void;
+  /** Decrement the count according to the deactivated process */
+  decrement: () => void;
+  /** Reset the count */
+  reset: () => void;
+  /** The number of activated processes */
+  actives: () => number;
+  /** The number of idle processes */
+  idles: () => number;
+  /** Whether it can activate the process */
+  canIncrement: () => boolean;
+  /** Whether there is an activated process */
+  canDecrement: () => boolean;
+};
+export const createConcurrencyManager = (total: number): ConcurrencyManager => {
+  let actives = 0;
+
+  const canIncrement = () => actives !== total;
+  const canDecrement = () => actives !== 0;
+
+  return {
+    total,
+    actives: () => actives,
+    idles: () => total - actives,
+    increment: () => {
+      if (!canIncrement()) return;
+      actives++;
+    },
+    decrement: () => {
+      if (!canDecrement()) return;
+      actives--;
+    },
+    canIncrement,
+    canDecrement,
+    reset: () => {
+      actives = 0;
+    },
+  };
+};

package/src/pool.test.ts

@@ -0,0 +1,87 @@
+import { beforeEach, expect, it, vi } from "vitest";
+import workerpool from "workerpool";
+import type Pool from "workerpool/types/Pool";
+
+import { createConcurrencyManager } from "./manager";
+import { initializeWorkerPool, queueTask } from "./pool";
+
+const workPoolExecStates = (() => {
+  const states = {
+    resolve: false,
+    reject: false,
+    rejectBeforePromise: false,
+  };
+  const reset = () => {
+    states.rejectBeforePromise = false;
+    states.resolve = false;
+    states.reject = false;
+  };
+
+  return { states, reset };
+})();
+
+vi.spyOn(workerpool, "pool").mockImplementation(
+  () =>
+    ({
+      exec: (_method: string, _params?: unknown, _options?: unknown) => {
+        if (workPoolExecStates.states.rejectBeforePromise) {
+          throw new Error();
+        }
+        return new workerpool.Promise(
+          (resolve: () => void, reject: () => void) => {
+            if (workPoolExecStates.states.resolve) {
+              resolve();
+            }
+            if (workPoolExecStates.states.reject) {
+              reject();
+            }
+          },
+        );
+      },
+      terminate: () => undefined,
+    }) as unknown as Pool,
+);
+
+// Worker pool is initialized globally.
+const manager = createConcurrencyManager(1);
+const incrementFnMock = vi.spyOn(manager, "increment");
+initializeWorkerPool("https://example.com", manager);
+
+beforeEach(() => {
+  workPoolExecStates.reset();
+  incrementFnMock.mockClear();
+});
+
+it("should increment and decrement concurrency when the promise is resolved", async () => {
+  workPoolExecStates.states.resolve = true;
+
+  const promise = queueTask("test" as any);
+  await promise;
+  expect(incrementFnMock).toHaveBeenCalledOnce();
+  expect(manager.actives()).toBe(0);
+});
+
+it("should increment and decrement concurrency when the promise is rejected", async () => {
+  workPoolExecStates.states.reject = true;
+
+  const promise = queueTask("test" as any);
+  try {
+    await promise;
+    expect.fail("Expect that this case throws an error");
+  } catch {
+    expect(incrementFnMock).toHaveBeenCalledOnce();
+    expect(manager.actives()).toBe(0);
+  }
+});
+
+it("should increment and decrement concurrency when the function throws an error before returning the promise", async () => {
+  workPoolExecStates.states.rejectBeforePromise = true;
+
+  try {
+    queueTask("test" as any);
+    expect.fail("Expect that this case throws an error");
+  } catch {
+    expect(incrementFnMock).toHaveBeenCalledOnce();
+    expect(manager.actives()).toBe(0);
+  }
+});

package/src/pool.ts

@@ -0,0 +1,150 @@
+import invariant from "tiny-invariant";
+import type { Promise } from "workerpool";
+import type { ExecOptions } from "workerpool/types/types";
+
+import type { ConcurrencyManager } from "./manager";
+import {
+  RecyclingWorkerPool,
+  type RecyclingWorkerPoolOptions,
+} from "./recyclingPool";
+import { type CommonTasks } from "./worker";
+
+export type { Promise } from "workerpool";
+export type {
+  RecyclingWorkerPoolOptions,
+  WorkerPoolHeapStats,
+  WorkerPoolStats,
+} from "./recyclingPool";
+
+const {
+  initializeWorkerPool,
+  terminateWorkerPool,
+  warmUpWorkerPool,
+  worker,
+  workerPoolStats,
+  workerPoolHeapStats,
+  probeWorkerPoolHeap,
+} = (() => {
+  // Restrict access to this object.
+  let worker:
+    | {
+        pool: RecyclingWorkerPool;
+        manager: ConcurrencyManager;
+      }
+    | undefined;
+
+  return {
+    initializeWorkerPool: (
+      url: string,
+      manager: ConcurrencyManager,
+      options?: RecyclingWorkerPoolOptions,
+    ) => {
+      if (worker) {
+        throw new Error("Worker pool has already been initialized.");
+      }
+
+      worker = {
+        // Recycles worker threads to bound WASM linear memory growth; see
+        // recyclingPool.ts for the policy.
+        pool: new RecyclingWorkerPool(url, manager.total, options),
+        manager,
+      };
+    },
+    terminateWorkerPool: () => {
+      if (worker) {
+        worker.pool.terminate();
+        worker = undefined;
+      }
+    },
+    /**
+     * Pre-initializes WASM on the workers so that upcoming tasks don't pay
+     * the initialization latency. Warms a single worker and resolves once
+     * it is ready; the rest warm in the background.
+     */
+    warmUpWorkerPool: () => {
+      invariant(worker, "initializeWorkerPool() must be invoked first.");
+      return worker.pool.warmUp();
+    },
+    worker: () => {
+      invariant(worker, "initializeWorkerPool() must be invoked first.");
+      return {
+        pool: worker.pool,
+        manager: worker.manager,
+      };
+    },
+    workerPoolStats: () => worker?.pool.stats(),
+    /** Last-probed WASM heap per worker; see RecyclingWorkerPool.heapStats. */
+    workerPoolHeapStats: () => worker?.pool.heapStats(),
+    /** Requests fresh heap probes (coalesced per worker; display-rate safe). */
+    probeWorkerPoolHeap: () => worker?.pool.probeHeap(),
+  };
+})();
+
+export {
+  initializeWorkerPool,
+  terminateWorkerPool,
+  warmUpWorkerPool,
+  workerPoolStats,
+  workerPoolHeapStats,
+  probeWorkerPoolHeap,
+};
+
+export const canWorkerProcessImmediately = () => {
+  const { pool, manager } = worker();
+  // Also pauses intake while every worker is over its WASM heap budget
+  // (draining); a recycled worker restores capacity moments later.
+  return manager.canIncrement() && pool.canAcceptTasks();
+};
+
+export type { ExecOptions } from "workerpool/types/types";
+
+type GetTaskName<Task> =
+  Task extends Record<string, unknown> ? keyof Task : string;
+
+type AnyFunction = (...args: any) => any;
+
+export type WorkerTask<T extends Record<string, AnyFunction>> = T & CommonTasks;
+
+export type TaskParams<
+  Task extends CommonTasks,
+  Name extends keyof Task,
+> = Parameters<
+  Task[Name] extends AnyFunction ? Task[Name] : (...args: unknown[]) => unknown
+>;
+type MethodReturnType<
+  Task extends CommonTasks,
+  Name extends GetTaskName<Task>,
+  R = Awaited<ReturnType<Task[Name]>>,
+> = R extends infer U ? U : R;
+
+export function queueTask<
+  Task extends CommonTasks,
+  Name extends GetTaskName<Task>,
+>(
+  method: Name,
+  params?: TaskParams<Task, Name>,
+  options?: ExecOptions,
+): Promise<MethodReturnType<Task, Name>> {
+  const { pool, manager } = worker();
+
+  manager.increment();
+
+  try {
+    return (
+      pool
+        .exec(method, params, options)
+        // `finally` doesn't work, so use `then()` and `catch()` to ensure that `manager.decrement()` is invoked.
+        .then((p) => {
+          manager.decrement();
+          return p;
+        })
+        .catch((e) => {
+          manager.decrement();
+          throw e;
+        })
+    );
+  } catch (e) {
+    manager.decrement();
+    throw e;
+  }
+}