@loaders.gl/core 5.0.0-alpha.13 → 5.0.0-alpha.14

package/src/worker-utils/lib/worker-api/process-on-worker.ts

@@ -16,6 +16,7 @@ import WorkerFarm from '../worker-farm/worker-farm';
 import type {WorkerPoolTarget} from '../worker-farm/worker-pool';
 import {
   getCustomWorkerURL,
+  getConfiguredWorkerURL,
   getDefaultWorkerURL,
   getWorkerURL,
   getWorkerName
@@ -55,6 +56,22 @@ export function canProcessOnWorker(worker: WorkerObject, options?: WorkerOptions
   );
 }
 
+/**
+ * Checks whether a worker supports stateful batch processing.
+ * @param worker Worker descriptor declaring built-in batch support.
+ * @param options Worker options, including an explicit capability for custom URLs or source.
+ */
+export function canProcessOnWorkerInBatches(
+  worker: WorkerObject,
+  options: WorkerOptions = {}
+): boolean {
+  if (!canProcessOnWorker(worker, options)) return false;
+  if (options.workerInBatches !== undefined) return options.workerInBatches;
+  return Boolean(
+    worker.workerInBatches && !options.source && !getConfiguredWorkerURL(worker, options)
+  );
+}
+
 /**
  * This function expects that the worker thread sends certain messages,
  * Creating such a worker can be automated if the worker is wrapper by a call to
@@ -77,18 +94,15 @@ export async function processOnWorker(
   const job = await workerPool.startJob(
     jobName,
     // eslint-disable-next-line
-    onMessage.bind(null, context)
+    onMessage.bind(null, context, options),
+    undefined,
+    options.signal
   );
 
-  const abortJob = (): void => job.abort(getAbortReason(options.signal));
-  options.signal?.addEventListener('abort', abortJob, {once: true});
-  if (options.signal?.aborted) {
-    abortJob();
-  }
-
   try {
+    if (options.signal?.aborted) job.abort(getAbortReason(options.signal));
     // AbortSignal cannot be structured-cloned. It controls the job on this thread only.
-    const {signal: _signal, ...workerOptions} = options;
+    const {signal: _signal, onProgress: _onProgress, ...workerOptions} = options;
     const transferableOptions = getTransferListForWriter(workerOptions);
     const transferableContext = getTransferListForWriter(jobContext);
     if (job.isRunning) {
@@ -101,8 +115,9 @@ export async function processOnWorker(
 
     const result = await job.result;
     return result.result;
-  } finally {
-    options.signal?.removeEventListener('abort', abortJob);
+  } catch (error) {
+    job.abort(error);
+    throw error;
   }
 }
 
@@ -140,9 +155,18 @@ async function* processOnWorkerInBatchesIterator<InputBatch, OutputBatch>(
   const inputIterator = getAsyncIterator(input);
   let outputFinished = false;
   let inputFinished = false;
+  let inputCleanupRequested = false;
   let inputRequest = Promise.resolve();
   const batchJobFailed = new Error('Worker batch job failed');
 
+  /** Requests cleanup even when the output consumer is paused after yielding a batch. */
+  const closeJobInput = (): void => {
+    if (!inputFinished && !inputCleanupRequested) {
+      inputCleanupRequested = true;
+      closeInputIterator(inputIterator);
+    }
+  };
+
   const finishOutput = (): void => {
     if (!outputFinished) {
       outputFinished = true;
@@ -157,66 +181,76 @@ async function* processOnWorkerInBatchesIterator<InputBatch, OutputBatch>(
     }
   };
 
-  const job = await workerPool.startJob(
-    options.jobName || worker.name,
-    (activeJob, type, payload) => {
-      switch (type) {
-        case 'input-request':
-          inputRequest = inputRequest
-            .then(async () => {
-              const nextBatch = await inputIterator.next();
-              if (!activeJob.isRunning) {
-                return;
-              }
-              if (nextBatch.done) {
-                inputFinished = true;
-                activeJob.postMessage('input-done', {});
-              } else {
-                activeJob.postMessage('input-batch', {input: nextBatch.value});
-              }
-            })
-            .catch(error => activeJob.abort(error));
-          break;
-
-        case 'output-batch':
-          outputBatches.push(payload.result as OutputBatch);
-          break;
-
-        case 'done':
-          activeJob.done(payload);
-          finishOutput();
-          break;
-
-        case 'error': {
-          const error = new Error(payload.error || 'Worker batch processing failed');
-          activeJob.error(error);
-          failOutput(error);
-          break;
-        }
-
-        case 'process':
-          void onMessage(context, activeJob, type, payload);
-          break;
-
-        default: {
-          const error = new Error(`Unexpected worker batch message: ${type}`);
-          activeJob.error(error);
-          failOutput(error);
-          break;
+  const job = await workerPool
+    .startJob(
+      options.jobName || worker.name,
+      (activeJob, type, payload) => {
+        switch (type) {
+          case 'progress':
+            reportProgress(activeJob, options, payload);
+            break;
+
+          case 'input-request':
+            inputRequest = inputRequest
+              .then(async () => {
+                if (!activeJob.isRunning) return;
+                const nextBatch = await inputIterator.next();
+                if (!activeJob.isRunning) {
+                  return;
+                }
+                if (nextBatch.done) {
+                  inputFinished = true;
+                  activeJob.postMessage('input-done', {});
+                } else {
+                  activeJob.postMessage('input-batch', {input: nextBatch.value});
+                }
+              })
+              .catch(error => activeJob.abort(error));
+            break;
+
+          case 'output-batch':
+            outputBatches.push(payload.result as OutputBatch);
+            break;
+
+          case 'done':
+            activeJob.done(payload);
+            finishOutput();
+            break;
+
+          case 'error': {
+            const error = new Error(payload.error || 'Worker batch processing failed');
+            activeJob.error(error);
+            failOutput(error);
+            break;
+          }
+
+          case 'process':
+            void onMessage(context, options, activeJob, type, payload);
+            break;
+
+          default: {
+            const error = new Error(`Unexpected worker batch message: ${type}`);
+            activeJob.error(error);
+            failOutput(error);
+            break;
+          }
         }
-      }
-    }
-  );
+      },
+      undefined,
+      options.signal
+    )
+    .catch(error => {
+      closeJobInput();
+      throw error;
+    });
 
-  const abortJob = (): void => job.abort(getAbortReason(options.signal));
-  options.signal?.addEventListener('abort', abortJob, {once: true});
-  if (options.signal?.aborted) {
-    abortJob();
-  }
-  void job.result.catch(failOutput);
+  void job.result.catch(error => {
+    failOutput(error);
+    closeJobInput();
+  });
 
   try {
-    const {signal: _signal, ...workerOptions} = options;
+    const {signal: _signal, onProgress: _onProgress, ...workerOptions} = options;
     if (job.isRunning) {
       job.postMessage('process-in-batches', {
         options: getTransferListForWriter(workerOptions),
@@ -239,13 +273,10 @@ async function* processOnWorkerInBatchesIterator<InputBatch, OutputBatch>(
     }
     await job.result;
   } finally {
-    options.signal?.removeEventListener('abort', abortJob);
     if (job.isRunning) {
       job.abort(createAbortError('Worker batch iterator was closed'));
     }
-    if (!inputFinished) {
-      closeInputIterator(inputIterator);
-    }
+    closeJobInput();
   }
 }
 
@@ -259,7 +290,7 @@ function throwIfAborted(signal?: AbortSignal): void {
 
 /** Returns a caller-provided abort reason or a cross-runtime `AbortError`. */
 function getAbortReason(signal?: AbortSignal): unknown {
-  return signal?.reason ?? createAbortError('Worker job was aborted');
+  return signal ? signal.reason : createAbortError('Worker job was aborted');
 }
 
 /** Creates an abort error without requiring the DOMException global. */
@@ -353,11 +384,16 @@ function getWorkerPoolTarget(
  */
 async function onMessage(
   context: WorkerContext,
+  options: ProcessOnWorkerOptions,
   job: WorkerJob,
   type: WorkerMessageType,
   payload: WorkerMessagePayload
 ) {
   switch (type) {
+    case 'progress':
+      reportProgress(job, options, payload);
+      break;
+
     case 'done':
       // Worker is done
       job.done(payload);
@@ -370,13 +406,18 @@ async function onMessage(
 
     case 'process':
       // Worker is asking for us (main thread) to process something
-      const {id, input, options} = payload;
+      const {id, input, options: processOptions} = payload;
       try {
         if (!context.process) {
           job.postMessage('error', {id, error: 'Worker not set up to process on main thread'});
           return;
         }
-        const result = await context.process(input, options, undefined, payload.context || {});
+        const result = await context.process(
+          input,
+          {...processOptions, signal: options.signal, onProgress: options.onProgress},
+          undefined,
+          payload.context || {}
+        );
         job.postMessage('done', {id, result});
       } catch (error) {
         const message = error instanceof Error ? error.message : 'unknown error';
@@ -411,3 +452,17 @@ function onPreloadMessage(job: WorkerJob, type: WorkerMessageType, payload: Work
       console.warn(`process-on-worker: unknown preload message ${type}`);
   }
 }
+
+/** Delivers progress; callback failures terminate the job and settle its caller. */
+function reportProgress(
+  job: WorkerJob,
+  options: ProcessOnWorkerOptions,
+  payload: WorkerMessagePayload
+): void {
+  if (!job.isRunning || !payload.progress) return;
+  try {
+    options.onProgress?.(payload.progress);
+  } catch (error) {
+    job.abort(error);
+  }
+}

package/src/worker-utils/lib/worker-farm/worker-job.ts

@@ -32,6 +32,7 @@ export default class WorkerJob {
    * @param data any data structure, ideally consisting mostly of transferrable objects
    */
   postMessage(type: WorkerMessageType, payload: WorkerMessagePayload): void {
+    if (!this.isRunning) return;
     this.workerThread.postMessage({
       source: 'loaders.gl', // Lets worker ignore unrelated messages
       type,
@@ -69,9 +70,10 @@ export default class WorkerJob {
     if (!this.isRunning) {
       return;
     }
-    const error = reason ?? createAbortError(`Worker job "${this.name}" was aborted`);
     this.workerThread.destroy();
-    this.error(error);
+    this.error(
+      arguments.length ? reason : createAbortError(`Worker job "${this.name}" was aborted`)
+    );
   }
 }
 

package/src/worker-utils/lib/worker-farm/worker-pool.ts

@@ -50,6 +50,10 @@ type QueuedJob = {
   onError: OnError;
   onStart: (value: any) => void; // Resolve job start promise
   onReject: (reason: unknown) => void; // Reject job start promise
+  /** Removes the queued cancellation listener when the job leaves the queue. */
+  removeAbortListener: () => void;
+  /** Cancels this queued or active job. */
+  signal?: AbortSignal;
 };
 
 /**
@@ -99,9 +103,13 @@ export default class WorkerPool {
    */
   destroy(reason: unknown = new Error('Worker pool was destroyed')): void {
     // Abort active jobs so callers receive an error when a development worker is invalidated.
+    this.isDestroyed = true;
     this.activeJobs.forEach(job => job.abort(reason));
     const queuedJobs = this.jobQueue.splice(0);
-    queuedJobs.forEach(queuedJob => queuedJob.onReject(reason));
+    queuedJobs.forEach(queuedJob => {
+      queuedJob.removeAbortListener();
+      queuedJob.onReject(reason);
+    });
     this.idleQueue.forEach(worker => worker.destroy());
     this.isDestroyed = true;
   }
@@ -129,15 +137,37 @@ export default class WorkerPool {
   async startJob(
     name: string,
     onMessage: OnMessage = (job, type, data) => job.done(data),
-    onError: OnError = (job, error) => job.error(error)
+    onError: OnError = (job, error) => job.error(error),
+    signal?: AbortSignal
   ): Promise<WorkerJob> {
+    if (signal?.aborted) {
+      throw signal.reason;
+    }
     if (this.isDestroyed) {
       return Promise.reject(new Error('Worker pool was destroyed'));
     }
     // Promise resolves when thread starts working on this job
     const startPromise = new Promise<WorkerJob>((onStart, onReject) => {
       // Promise resolves when thread completes or fails working on this job
-      this.jobQueue.push({name, onMessage, onError, onStart, onReject});
+      const abortQueuedJob = (): void => {
+        const index = this.jobQueue.indexOf(queuedJob);
+        if (index >= 0) {
+          this.jobQueue.splice(index, 1);
+          queuedJob.removeAbortListener();
+          onReject(signal?.reason);
+        }
+      };
+      const queuedJob: QueuedJob = {
+        name,
+        onMessage,
+        onError,
+        onStart,
+        onReject,
+        signal,
+        removeAbortListener: () => signal?.removeEventListener('abort', abortQueuedJob)
+      };
+      this.jobQueue.push(queuedJob);
+      signal?.addEventListener('abort', abortQueuedJob, {once: true});
       return this;
     });
     this._startQueuedJob(); // eslint-disable-line @typescript-eslint/no-floating-promises
@@ -155,7 +185,16 @@ export default class WorkerPool {
       return;
     }
 
-    const workerThread = this._getAvailableWorker();
+    let workerThread: WorkerThread | null;
+    try {
+      workerThread = this._getAvailableWorker();
+    } catch (error) {
+      const queuedJob = this.jobQueue.shift();
+      queuedJob?.removeAbortListener();
+      queuedJob?.onReject(error);
+      void this._startQueuedJob();
+      return;
+    }
     if (!workerThread) {
       return;
     }
@@ -174,11 +213,17 @@ export default class WorkerPool {
 
       // Create a worker job to let the app access thread and manage job completion
       const job = new WorkerJob(queuedJob.name, workerThread);
+      queuedJob.removeAbortListener();
+      const abortJob = (): void => job.abort(queuedJob.signal?.reason);
+      queuedJob.signal?.addEventListener('abort', abortJob, {once: true});
+      if (queuedJob.signal?.aborted) abortJob();
       this.activeJobs.add(job);
       workerThread.ref();
 
       // Set the worker thread's message handlers
-      workerThread.onMessage = data => queuedJob.onMessage(job, data.type, data.payload);
+      workerThread.onMessage = data => {
+        if (job.isRunning) queuedJob.onMessage(job, data.type, data.payload);
+      };
       workerThread.onError = error => queuedJob.onError(job, error);
 
       // Resolve the start promise so that the app can start sending messages to worker
@@ -191,9 +236,12 @@ export default class WorkerPool {
         // The job result promise carries worker errors back to the caller; do not duplicate-log
         // handled rejections here.
       } finally {
+        queuedJob.signal?.removeEventListener('abort', abortJob);
         this.activeJobs.delete(job);
         this.returnWorkerToQueue(workerThread);
       }
+    } else {
+      this.returnWorkerToQueue(workerThread);
     }
   }
 
@@ -244,13 +292,18 @@ export default class WorkerPool {
     if (this.count < this._getMaxConcurrency()) {
       this.count++;
       const name = `${this.name.toLowerCase()} (#${this.count} of ${this.maxConcurrency})`;
-      return new WorkerThread({
-        name,
-        source: this.source,
-        url: this.url,
-        getUrl: this.getUrl,
-        loadWorker: this.loadWorker
-      });
+      try {
+        return new WorkerThread({
+          name,
+          source: this.source,
+          url: this.url,
+          getUrl: this.getUrl,
+          loadWorker: this.loadWorker
+        });
+      } catch (error) {
+        this.count--;
+        throw error;
+      }
     }
 
     // No worker available, have to wait

package/src/worker-utils/types.ts

@@ -2,13 +2,29 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-/**
- * Worker Options
- */
+/** Progress measured independently within a named phase. */
+export type WorkerProgress = {
+  /** Operation being measured. */
+  phase: string;
+  /** Work completed in this phase. */
+  completed: number;
+  /** Expected work, when known. */
+  total?: number;
+  /** Measurement unit, such as bytes, rows, or tasks. */
+  unit: string;
+};
+
+/** Shared worker execution options. */
 export type WorkerOptions = {
+  /** Cancels queued or running work. */
+  signal?: AbortSignal;
+  /** Receives phase progress. Throwing aborts the job with that error. */
+  onProgress?: (progress: WorkerProgress) => void;
   // Worker farm options
   CDN?: string | null;
   worker?: boolean;
+  /** Declares batch-protocol support for a custom worker, or disables batch offloading. */
+  workerInBatches?: boolean;
   maxConcurrency?: number;
   maxMobileConcurrency?: number;
   reuseWorkers?: boolean;
@@ -26,6 +42,8 @@ export type WorkerOptions = {
 export type LoadWorker = () => Worker | null;
 
 export type WorkerContext = {
+  /** Reports progress from the active worker job. */
+  reportProgress?: (progress: WorkerProgress) => void;
   process?: Process;
   processInBatches?: ProcessInBatches;
 };
@@ -58,6 +76,8 @@ export type WorkerObject = {
   module: string;
   version: string;
   worker?: string | boolean;
+  /** Whether the built-in worker accepts stateful batch requests. */
+  workerInBatches?: boolean;
   /** Browser worker filename when it differs from the worker id. */
   workerFile?: string;
   /** Creates a built-in browser worker, typically using `type: 'module'`. */
@@ -93,6 +113,7 @@ export type WorkerObject = {
               <= error
  */
 export type WorkerMessageType =
+  | 'progress'
   | 'preload'
   | 'process'
   | 'done'
@@ -105,6 +126,8 @@ export type WorkerMessageType =
   | 'output-ack';
 
 export type WorkerMessagePayload = {
+  /** Phase progress from the worker. */
+  progress?: WorkerProgress;
   id?: number;
   options?: {[key: string]: any};
   context?: WorkerJobContext;