@math.gl/tasks 0.0.0-stage → 5.0.0-beta.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (212) hide show
  1. package/LICENSE +147 -0
  2. package/LOADERS-GL-LICENSE.txt +52 -0
  3. package/README.md +26 -2
  4. package/THIRD-PARTY-NOTICES.md +5 -0
  5. package/dist/index.cjs +3454 -0
  6. package/dist/index.cjs.map +6 -0
  7. package/dist/index.d.ts +2 -0
  8. package/dist/index.d.ts.map +1 -0
  9. package/dist/index.js +5 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/tasks/index.d.ts +9 -0
  12. package/dist/tasks/index.d.ts.map +1 -0
  13. package/dist/tasks/index.js +9 -0
  14. package/dist/tasks/index.js.map +1 -0
  15. package/dist/tasks/task-channel.d.ts +48 -0
  16. package/dist/tasks/task-channel.d.ts.map +1 -0
  17. package/dist/tasks/task-channel.js +166 -0
  18. package/dist/tasks/task-channel.js.map +1 -0
  19. package/dist/tasks/task-operation-queue.d.ts +26 -0
  20. package/dist/tasks/task-operation-queue.d.ts.map +1 -0
  21. package/dist/tasks/task-operation-queue.js +106 -0
  22. package/dist/tasks/task-operation-queue.js.map +1 -0
  23. package/dist/tasks/task-preload.d.ts +13 -0
  24. package/dist/tasks/task-preload.d.ts.map +1 -0
  25. package/dist/tasks/task-preload.js +96 -0
  26. package/dist/tasks/task-preload.js.map +1 -0
  27. package/dist/tasks/task-runner.d.ts +74 -0
  28. package/dist/tasks/task-runner.d.ts.map +1 -0
  29. package/dist/tasks/task-runner.js +811 -0
  30. package/dist/tasks/task-runner.js.map +1 -0
  31. package/dist/tasks/task-runtime.d.ts +27 -0
  32. package/dist/tasks/task-runtime.d.ts.map +1 -0
  33. package/dist/tasks/task-runtime.js +216 -0
  34. package/dist/tasks/task-runtime.js.map +1 -0
  35. package/dist/tasks/task-sync.d.ts +4 -0
  36. package/dist/tasks/task-sync.d.ts.map +1 -0
  37. package/dist/tasks/task-sync.js +95 -0
  38. package/dist/tasks/task-sync.js.map +1 -0
  39. package/dist/tasks/task-worker-channel.d.ts +11 -0
  40. package/dist/tasks/task-worker-channel.d.ts.map +1 -0
  41. package/dist/tasks/task-worker-channel.js +34 -0
  42. package/dist/tasks/task-worker-channel.js.map +1 -0
  43. package/dist/tasks/task.d.ts +132 -0
  44. package/dist/tasks/task.d.ts.map +1 -0
  45. package/dist/tasks/task.js +5 -0
  46. package/dist/tasks/task.js.map +1 -0
  47. package/dist/tasks/typed-task-dispatch.d.ts +30 -0
  48. package/dist/tasks/typed-task-dispatch.d.ts.map +1 -0
  49. package/dist/tasks/typed-task-dispatch.js +12 -0
  50. package/dist/tasks/typed-task-dispatch.js.map +1 -0
  51. package/dist/worker-utils/index.d.ts +25 -0
  52. package/dist/worker-utils/index.d.ts.map +1 -0
  53. package/dist/worker-utils/index.js +46 -0
  54. package/dist/worker-utils/index.js.map +1 -0
  55. package/dist/worker-utils/lib/async-queue/async-queue.d.ts +32 -0
  56. package/dist/worker-utils/lib/async-queue/async-queue.d.ts.map +1 -0
  57. package/dist/worker-utils/lib/async-queue/async-queue.js +88 -0
  58. package/dist/worker-utils/lib/async-queue/async-queue.js.map +1 -0
  59. package/dist/worker-utils/lib/env-utils/assert.d.ts +3 -0
  60. package/dist/worker-utils/lib/env-utils/assert.d.ts.map +1 -0
  61. package/dist/worker-utils/lib/env-utils/assert.js +13 -0
  62. package/dist/worker-utils/lib/env-utils/assert.js.map +1 -0
  63. package/dist/worker-utils/lib/env-utils/globals.d.ts +22 -0
  64. package/dist/worker-utils/lib/env-utils/globals.d.ts.map +1 -0
  65. package/dist/worker-utils/lib/env-utils/globals.js +30 -0
  66. package/dist/worker-utils/lib/env-utils/globals.js.map +1 -0
  67. package/dist/worker-utils/lib/env-utils/version.d.ts +3 -0
  68. package/dist/worker-utils/lib/env-utils/version.d.ts.map +1 -0
  69. package/dist/worker-utils/lib/env-utils/version.js +11 -0
  70. package/dist/worker-utils/lib/env-utils/version.js.map +1 -0
  71. package/dist/worker-utils/lib/library-utils/library-utils.d.ts +42 -0
  72. package/dist/worker-utils/lib/library-utils/library-utils.d.ts.map +1 -0
  73. package/dist/worker-utils/lib/library-utils/library-utils.js +251 -0
  74. package/dist/worker-utils/lib/library-utils/library-utils.js.map +1 -0
  75. package/dist/worker-utils/lib/node/worker_threads-browser.d.ts +15 -0
  76. package/dist/worker-utils/lib/node/worker_threads-browser.d.ts.map +1 -0
  77. package/dist/worker-utils/lib/node/worker_threads-browser.js +23 -0
  78. package/dist/worker-utils/lib/node/worker_threads-browser.js.map +1 -0
  79. package/dist/worker-utils/lib/node/worker_threads.d.ts +16 -0
  80. package/dist/worker-utils/lib/node/worker_threads.d.ts.map +1 -0
  81. package/dist/worker-utils/lib/node/worker_threads.js +7 -0
  82. package/dist/worker-utils/lib/node/worker_threads.js.map +1 -0
  83. package/dist/worker-utils/lib/npm-tag.d.ts +2 -0
  84. package/dist/worker-utils/lib/npm-tag.d.ts.map +1 -0
  85. package/dist/worker-utils/lib/npm-tag.js +5 -0
  86. package/dist/worker-utils/lib/npm-tag.js.map +1 -0
  87. package/dist/worker-utils/lib/process-utils/child-process-proxy.browser.d.ts +8 -0
  88. package/dist/worker-utils/lib/process-utils/child-process-proxy.browser.d.ts.map +1 -0
  89. package/dist/worker-utils/lib/process-utils/child-process-proxy.browser.js +18 -0
  90. package/dist/worker-utils/lib/process-utils/child-process-proxy.browser.js.map +1 -0
  91. package/dist/worker-utils/lib/process-utils/child-process-proxy.d.ts +45 -0
  92. package/dist/worker-utils/lib/process-utils/child-process-proxy.d.ts.map +1 -0
  93. package/dist/worker-utils/lib/process-utils/child-process-proxy.js +128 -0
  94. package/dist/worker-utils/lib/process-utils/child-process-proxy.js.map +1 -0
  95. package/dist/worker-utils/lib/process-utils/process-utils.d.ts +2 -0
  96. package/dist/worker-utils/lib/process-utils/process-utils.d.ts.map +1 -0
  97. package/dist/worker-utils/lib/process-utils/process-utils.js +32 -0
  98. package/dist/worker-utils/lib/process-utils/process-utils.js.map +1 -0
  99. package/dist/worker-utils/lib/worker-api/create-worker.d.ts +9 -0
  100. package/dist/worker-utils/lib/worker-api/create-worker.d.ts.map +1 -0
  101. package/dist/worker-utils/lib/worker-api/create-worker.js +229 -0
  102. package/dist/worker-utils/lib/worker-api/create-worker.js.map +1 -0
  103. package/dist/worker-utils/lib/worker-api/get-worker-url.d.ts +29 -0
  104. package/dist/worker-utils/lib/worker-api/get-worker-url.d.ts.map +1 -0
  105. package/dist/worker-utils/lib/worker-api/get-worker-url.js +101 -0
  106. package/dist/worker-utils/lib/worker-api/get-worker-url.js.map +1 -0
  107. package/dist/worker-utils/lib/worker-api/process-on-worker.d.ts +67 -0
  108. package/dist/worker-utils/lib/worker-api/process-on-worker.d.ts.map +1 -0
  109. package/dist/worker-utils/lib/worker-api/process-on-worker.js +429 -0
  110. package/dist/worker-utils/lib/worker-api/process-on-worker.js.map +1 -0
  111. package/dist/worker-utils/lib/worker-api/shared-state.d.ts +34 -0
  112. package/dist/worker-utils/lib/worker-api/shared-state.d.ts.map +1 -0
  113. package/dist/worker-utils/lib/worker-api/shared-state.js +105 -0
  114. package/dist/worker-utils/lib/worker-api/shared-state.js.map +1 -0
  115. package/dist/worker-utils/lib/worker-api/validate-output-ownership.d.ts +3 -0
  116. package/dist/worker-utils/lib/worker-api/validate-output-ownership.d.ts.map +1 -0
  117. package/dist/worker-utils/lib/worker-api/validate-output-ownership.js +10 -0
  118. package/dist/worker-utils/lib/worker-api/validate-output-ownership.js.map +1 -0
  119. package/dist/worker-utils/lib/worker-api/validate-worker-version.d.ts +9 -0
  120. package/dist/worker-utils/lib/worker-api/validate-worker-version.d.ts.map +1 -0
  121. package/dist/worker-utils/lib/worker-api/validate-worker-version.js +35 -0
  122. package/dist/worker-utils/lib/worker-api/validate-worker-version.js.map +1 -0
  123. package/dist/worker-utils/lib/worker-api/worker-resource.d.ts +33 -0
  124. package/dist/worker-utils/lib/worker-api/worker-resource.d.ts.map +1 -0
  125. package/dist/worker-utils/lib/worker-api/worker-resource.js +156 -0
  126. package/dist/worker-utils/lib/worker-api/worker-resource.js.map +1 -0
  127. package/dist/worker-utils/lib/worker-farm/worker-body.d.ts +20 -0
  128. package/dist/worker-utils/lib/worker-farm/worker-body.d.ts.map +1 -0
  129. package/dist/worker-utils/lib/worker-farm/worker-body.js +134 -0
  130. package/dist/worker-utils/lib/worker-farm/worker-body.js.map +1 -0
  131. package/dist/worker-utils/lib/worker-farm/worker-farm.d.ts +73 -0
  132. package/dist/worker-utils/lib/worker-farm/worker-farm.d.ts.map +1 -0
  133. package/dist/worker-utils/lib/worker-farm/worker-farm.js +135 -0
  134. package/dist/worker-utils/lib/worker-farm/worker-farm.js.map +1 -0
  135. package/dist/worker-utils/lib/worker-farm/worker-job.d.ts +47 -0
  136. package/dist/worker-utils/lib/worker-farm/worker-job.d.ts.map +1 -0
  137. package/dist/worker-utils/lib/worker-farm/worker-job.js +124 -0
  138. package/dist/worker-utils/lib/worker-farm/worker-job.js.map +1 -0
  139. package/dist/worker-utils/lib/worker-farm/worker-pool.d.ts +152 -0
  140. package/dist/worker-utils/lib/worker-farm/worker-pool.d.ts.map +1 -0
  141. package/dist/worker-utils/lib/worker-farm/worker-pool.js +584 -0
  142. package/dist/worker-utils/lib/worker-farm/worker-pool.js.map +1 -0
  143. package/dist/worker-utils/lib/worker-farm/worker-thread.d.ts +77 -0
  144. package/dist/worker-utils/lib/worker-farm/worker-thread.d.ts.map +1 -0
  145. package/dist/worker-utils/lib/worker-farm/worker-thread.js +215 -0
  146. package/dist/worker-utils/lib/worker-farm/worker-thread.js.map +1 -0
  147. package/dist/worker-utils/lib/worker-utils/get-input-byte-length.d.ts +5 -0
  148. package/dist/worker-utils/lib/worker-utils/get-input-byte-length.d.ts.map +1 -0
  149. package/dist/worker-utils/lib/worker-utils/get-input-byte-length.js +39 -0
  150. package/dist/worker-utils/lib/worker-utils/get-input-byte-length.js.map +1 -0
  151. package/dist/worker-utils/lib/worker-utils/get-loadable-worker-url.d.ts +15 -0
  152. package/dist/worker-utils/lib/worker-utils/get-loadable-worker-url.d.ts.map +1 -0
  153. package/dist/worker-utils/lib/worker-utils/get-loadable-worker-url.js +84 -0
  154. package/dist/worker-utils/lib/worker-utils/get-loadable-worker-url.js.map +1 -0
  155. package/dist/worker-utils/lib/worker-utils/get-transfer-list.d.ts +16 -0
  156. package/dist/worker-utils/lib/worker-utils/get-transfer-list.d.ts.map +1 -0
  157. package/dist/worker-utils/lib/worker-utils/get-transfer-list.js +127 -0
  158. package/dist/worker-utils/lib/worker-utils/get-transfer-list.js.map +1 -0
  159. package/dist/worker-utils/lib/worker-utils/remove-nontransferable-options.d.ts +6 -0
  160. package/dist/worker-utils/lib/worker-utils/remove-nontransferable-options.d.ts.map +1 -0
  161. package/dist/worker-utils/lib/worker-utils/remove-nontransferable-options.js +27 -0
  162. package/dist/worker-utils/lib/worker-utils/remove-nontransferable-options.js.map +1 -0
  163. package/dist/worker-utils/types.d.ts +165 -0
  164. package/dist/worker-utils/types.d.ts.map +1 -0
  165. package/dist/worker-utils/types.js +5 -0
  166. package/dist/worker-utils/types.js.map +1 -0
  167. package/dist/worker-utils/workers/null-worker.d.ts +2 -0
  168. package/dist/worker-utils/workers/null-worker.d.ts.map +1 -0
  169. package/dist/worker-utils/workers/null-worker.js +17 -0
  170. package/dist/worker-utils/workers/null-worker.js.map +1 -0
  171. package/package.json +43 -4
  172. package/src/index.ts +5 -0
  173. package/src/tasks/index.ts +33 -0
  174. package/src/tasks/task-channel.ts +191 -0
  175. package/src/tasks/task-operation-queue.ts +109 -0
  176. package/src/tasks/task-preload.ts +107 -0
  177. package/src/tasks/task-runner.ts +933 -0
  178. package/src/tasks/task-runtime.ts +244 -0
  179. package/src/tasks/task-sync.ts +100 -0
  180. package/src/tasks/task-worker-channel.ts +44 -0
  181. package/src/tasks/task.ts +168 -0
  182. package/src/tasks/typed-task-dispatch.ts +44 -0
  183. package/src/worker-utils/index.ts +105 -0
  184. package/src/worker-utils/lib/async-queue/async-queue.ts +100 -0
  185. package/src/worker-utils/lib/env-utils/assert.ts +14 -0
  186. package/src/worker-utils/lib/env-utils/globals.ts +40 -0
  187. package/src/worker-utils/lib/env-utils/version.ts +15 -0
  188. package/src/worker-utils/lib/library-utils/library-utils.ts +305 -0
  189. package/src/worker-utils/lib/node/worker_threads-browser.ts +44 -0
  190. package/src/worker-utils/lib/node/worker_threads.ts +21 -0
  191. package/src/worker-utils/lib/npm-tag.ts +5 -0
  192. package/src/worker-utils/lib/process-utils/child-process-proxy.browser.ts +23 -0
  193. package/src/worker-utils/lib/process-utils/child-process-proxy.ts +172 -0
  194. package/src/worker-utils/lib/process-utils/process-utils.ts +34 -0
  195. package/src/worker-utils/lib/worker-api/create-worker.ts +271 -0
  196. package/src/worker-utils/lib/worker-api/get-worker-url.ts +130 -0
  197. package/src/worker-utils/lib/worker-api/process-on-worker.ts +596 -0
  198. package/src/worker-utils/lib/worker-api/shared-state.ts +135 -0
  199. package/src/worker-utils/lib/worker-api/validate-output-ownership.ts +10 -0
  200. package/src/worker-utils/lib/worker-api/validate-worker-version.ts +44 -0
  201. package/src/worker-utils/lib/worker-api/worker-resource.ts +203 -0
  202. package/src/worker-utils/lib/worker-farm/worker-body.ts +154 -0
  203. package/src/worker-utils/lib/worker-farm/worker-farm.ts +172 -0
  204. package/src/worker-utils/lib/worker-farm/worker-job.ts +148 -0
  205. package/src/worker-utils/lib/worker-farm/worker-pool.ts +719 -0
  206. package/src/worker-utils/lib/worker-farm/worker-thread.ts +260 -0
  207. package/src/worker-utils/lib/worker-utils/get-input-byte-length.ts +34 -0
  208. package/src/worker-utils/lib/worker-utils/get-loadable-worker-url.ts +96 -0
  209. package/src/worker-utils/lib/worker-utils/get-transfer-list.ts +125 -0
  210. package/src/worker-utils/lib/worker-utils/remove-nontransferable-options.ts +27 -0
  211. package/src/worker-utils/types.ts +224 -0
  212. package/src/worker-utils/workers/null-worker.ts +20 -0
@@ -0,0 +1,719 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import type {LoadWorker, WorkerMessageType, WorkerMessagePayload} from '../../types';
6
+ import {isMobile} from '../env-utils/globals';
7
+ import WorkerThread from './worker-thread';
8
+ import WorkerJob from './worker-job';
9
+ import type {SharedWorkerState} from '../worker-api/shared-state';
10
+ import type {WorkerJobMetrics, WorkerPoolStats} from '../../types';
11
+
12
+ /** WorkerPool onDebug Callback Parameters */
13
+ type OnDebugParameters = {
14
+ message: string;
15
+ worker: string;
16
+ name: string;
17
+ job: string;
18
+ backlog: number;
19
+ workerThread: WorkerThread;
20
+ };
21
+
22
+ /** WorkerPool Properties */
23
+ export type WorkerPoolProps = {
24
+ name?: string;
25
+ source?: string; // | Function;
26
+ url?: string;
27
+ /** Browser worker script type; ignored for Node workers. */
28
+ workerType?: 'classic' | 'module';
29
+ /** Lazily resolves a classic worker fallback URL. */
30
+ getUrl?: () => string;
31
+ /** Creates a browser Worker directly. */
32
+ loadWorker?: LoadWorker;
33
+ /** Maximum retained input bytes waiting for a worker; overflow rejects before transfer. */
34
+ maxQueuedJobs?: number;
35
+ maxPendingAdmissions?: number;
36
+ /** Each interval increases a waiting job's effective priority by one. */
37
+ priorityAgingMs?: number;
38
+ onMetrics?: (metrics: WorkerJobMetrics) => void;
39
+ performanceMarks?: boolean;
40
+ maxQueuedBytes?: number;
41
+ /** Maximum reserved input bytes across running jobs. */
42
+ maxInFlightBytes?: number;
43
+ maxConcurrency?: number;
44
+ maxMobileConcurrency?: number;
45
+ onDebug?: (options: OnDebugParameters) => any;
46
+ reuseWorkers?: boolean;
47
+ };
48
+
49
+ /** Worker-pool target, including values used only to distinguish cached pools. */
50
+ export type WorkerPoolTarget = WorkerPoolProps & {
51
+ /** Worker name used as the base pool identity. */
52
+ name: string;
53
+ /** Stable identity for a lazily resolved URL. */
54
+ urlKey?: string;
55
+ };
56
+
57
+ /** Private helper types */
58
+ type OnMessage = (job: WorkerJob, type: WorkerMessageType, payload: WorkerMessagePayload) => void;
59
+ type OnError = (job: WorkerJob, error: Error) => void;
60
+
61
+ type QueuedJob = {
62
+ name: string;
63
+ inputBytes: number;
64
+ priority: number;
65
+ queuedAt: number;
66
+ sharedState?: SharedWorkerState;
67
+ cancellationMode?: 'terminate' | 'cooperative';
68
+ cancellationTimeout?: number;
69
+ onMessage: OnMessage;
70
+ onError: OnError;
71
+ onStart: (value: any) => void; // Resolve job start promise
72
+ onReject: (reason: unknown) => void; // Reject job start promise
73
+ /** Removes the queued cancellation listener when the job leaves the queue. */
74
+ removeAbortListener: () => void;
75
+ /** Cancels this queued or active job. */
76
+ signal?: AbortSignal;
77
+ };
78
+
79
+ /** A byte reservation obtained before constructing a large input. */
80
+ export type WorkerAdmission = {
81
+ readonly inputBytes: number;
82
+ release(): void;
83
+ };
84
+ type AdmissionWaiter = {
85
+ inputBytes: number;
86
+ resolve: (admission: WorkerAdmission) => void;
87
+ reject: (error: unknown) => void;
88
+ cleanup: () => void;
89
+ };
90
+
91
+ /**
92
+ * Process multiple data messages with small pool of identical workers
93
+ */
94
+ export default class WorkerPool {
95
+ name: string = 'unnamed';
96
+ source?: string; // | Function;
97
+ url?: string;
98
+ workerType?: 'classic' | 'module';
99
+ /** Lazily resolves a classic worker fallback URL. */
100
+ getUrl?: () => string;
101
+ /** Creates a browser Worker directly. */
102
+ loadWorker?: LoadWorker;
103
+ maxConcurrency: number = 1;
104
+ maxMobileConcurrency: number = 1;
105
+ onDebug: (options: OnDebugParameters) => any = () => {};
106
+ reuseWorkers: boolean = true;
107
+
108
+ private props: WorkerPoolProps = {};
109
+ private jobQueue: QueuedJob[] = [];
110
+ private idleQueue: WorkerThread[] = [];
111
+ private activeJobs = new Set<WorkerJob>();
112
+ private startingJobs = 0;
113
+ private count = 0;
114
+ private workers = new Set<WorkerThread>();
115
+ private queuedBytes = 0;
116
+ private inFlightBytes = 0;
117
+ private maxQueuedBytes = Infinity;
118
+ private maxInFlightBytes = Infinity;
119
+ private isDestroyed = false;
120
+ private isClosing = false;
121
+ private closing?: Promise<void>;
122
+ private onDrained?: () => void;
123
+ private destruction?: Promise<void>;
124
+ private maxQueuedJobs = Infinity;
125
+ private maxPendingAdmissions = 128;
126
+ private priorityAgingMs = 1000;
127
+ private reservations = new Set<WorkerAdmission>();
128
+ private admissions: AdmissionWaiter[] = [];
129
+ private reservedBytes = 0;
130
+ private totals = {
131
+ peakQueuedBytes: 0,
132
+ peakInFlightBytes: 0,
133
+ workersCreated: 0,
134
+ workerRestarts: 0,
135
+ completed: 0,
136
+ failed: 0,
137
+ cancelled: 0
138
+ };
139
+
140
+ /** Snapshot; byte figures describe input buffers, not total heap memory. */
141
+ get stats(): WorkerPoolStats {
142
+ return {
143
+ ...this.totals,
144
+ queuedJobs: this.jobQueue.length,
145
+ activeJobs: this.activeJobs.size,
146
+ queuedBytes: this.queuedBytes + this.reservedBytes,
147
+ inFlightBytes: this.inFlightBytes,
148
+ pendingAdmissions: this.admissions.length,
149
+ reservations: this.reservations.size
150
+ };
151
+ }
152
+
153
+ /** Wait for an atomic queue reservation before allocating input. Waiting metadata is bounded. */
154
+ reserve(inputBytes: number, options: {signal?: AbortSignal} = {}): Promise<WorkerAdmission> {
155
+ const {signal} = options;
156
+ if (signal?.aborted) return Promise.reject(signal.reason);
157
+ if (this.isDestroyed) return Promise.reject(new Error('Worker pool was destroyed'));
158
+ if (this.isClosing) return Promise.reject(new Error('Worker pool is closing'));
159
+ if (
160
+ !Number.isSafeInteger(inputBytes) ||
161
+ inputBytes < 0 ||
162
+ inputBytes > this.maxQueuedBytes ||
163
+ inputBytes > this.maxInFlightBytes
164
+ ) {
165
+ return Promise.reject(new RangeError('Reservation exceeds worker byte budgets'));
166
+ }
167
+ if (this.maxQueuedJobs < 1 || this.admissions.length >= this.maxPendingAdmissions) {
168
+ return Promise.reject(new RangeError('Worker admission queue is full'));
169
+ }
170
+ return new Promise((resolve, reject) => {
171
+ const abort = () => {
172
+ const index = this.admissions.indexOf(waiter);
173
+ if (index >= 0) this.admissions.splice(index, 1);
174
+ waiter.cleanup();
175
+ reject(signal?.reason);
176
+ this._admit();
177
+ };
178
+ const waiter: AdmissionWaiter = {
179
+ inputBytes,
180
+ resolve,
181
+ reject,
182
+ cleanup: () => signal?.removeEventListener('abort', abort)
183
+ };
184
+ this.admissions.push(waiter);
185
+ signal?.addEventListener('abort', abort, {once: true});
186
+ this._admit();
187
+ });
188
+ }
189
+
190
+ private _admit(): void {
191
+ while (!this.isDestroyed && !this.isClosing && this.admissions.length) {
192
+ const waiter = this.admissions[0];
193
+ if (waiter.inputBytes > this.maxQueuedBytes || waiter.inputBytes > this.maxInFlightBytes) {
194
+ this.admissions.shift();
195
+ waiter.cleanup();
196
+ waiter.reject(new RangeError('Reservation exceeds worker byte budgets'));
197
+ continue;
198
+ }
199
+ if (
200
+ this.jobQueue.length + this.reservations.size >= this.maxQueuedJobs ||
201
+ waiter.inputBytes > this.maxQueuedBytes - this.queuedBytes - this.reservedBytes
202
+ )
203
+ return;
204
+ this.admissions.shift();
205
+ waiter.cleanup();
206
+ const admission: WorkerAdmission = {
207
+ inputBytes: waiter.inputBytes,
208
+ release: () => {
209
+ if (this.reservations.delete(admission)) {
210
+ this.reservedBytes -= admission.inputBytes;
211
+ this._admit();
212
+ }
213
+ }
214
+ };
215
+ this.reservations.add(admission);
216
+ this.reservedBytes += admission.inputBytes;
217
+ this.totals.peakQueuedBytes = Math.max(
218
+ this.totals.peakQueuedBytes,
219
+ this.queuedBytes + this.reservedBytes
220
+ );
221
+ waiter.resolve(admission);
222
+ }
223
+ }
224
+
225
+ /** Checks if workers are supported on this platform */
226
+ static isSupported(): boolean {
227
+ return WorkerThread.isSupported();
228
+ }
229
+
230
+ /**
231
+ * @param processor - worker function
232
+ * @param maxConcurrency - max count of workers
233
+ */
234
+ constructor(props: WorkerPoolProps) {
235
+ this.source = props.source;
236
+ this.url = props.url;
237
+ this.workerType = props.workerType;
238
+ this.getUrl = props.getUrl;
239
+ this.loadWorker = props.loadWorker;
240
+ this.setProps(props);
241
+ }
242
+
243
+ /** Reject new work, drain submitted jobs, and terminate workers; optionally force termination after a deadline. */
244
+ close(options: {timeout?: number} = {}): Promise<void> {
245
+ if (this.closing) return this.closing;
246
+ if (this.isDestroyed) return this.destroy();
247
+ if (
248
+ options.timeout !== undefined &&
249
+ (!Number.isFinite(options.timeout) || options.timeout < 0 || options.timeout > 0x7fffffff)
250
+ ) {
251
+ return Promise.reject(new RangeError('Close timeout must be between 0 and 2147483647 ms'));
252
+ }
253
+ this.isClosing = true;
254
+ const reason = new Error('Worker pool is closing');
255
+ this.admissions.splice(0).forEach(waiter => {
256
+ waiter.cleanup();
257
+ waiter.reject(reason);
258
+ });
259
+ this.reservations.clear();
260
+ this.reservedBytes = 0;
261
+ let timer: ReturnType<typeof setTimeout> | undefined;
262
+ const drained = new Promise<void>(resolve => {
263
+ this.onDrained = resolve;
264
+ });
265
+ const deadline =
266
+ options.timeout === undefined
267
+ ? drained
268
+ : Promise.race([
269
+ drained,
270
+ new Promise<void>(resolve => {
271
+ timer = setTimeout(resolve, options.timeout);
272
+ })
273
+ ]);
274
+ this.closing = deadline.then(async () => {
275
+ clearTimeout(timer);
276
+ await this.destroy();
277
+ });
278
+ this._checkDrained();
279
+ return this.closing;
280
+ }
281
+
282
+ private _checkDrained(): void {
283
+ if (this.isClosing && !this.jobQueue.length && !this.activeJobs.size && !this.startingJobs)
284
+ this.onDrained?.();
285
+ }
286
+
287
+ /**
288
+ * Terminates all workers in the pool and aborts active jobs.
289
+ * @param reason Optional error delivered to active jobs.
290
+ * @note Can free up significant memory
291
+ */
292
+ destroy(reason: unknown = new Error('Worker pool was destroyed')): Promise<void> {
293
+ if (this.destruction) return this.destruction;
294
+ const workers = [...this.workers];
295
+ // Abort active jobs so callers receive an error when a development worker is invalidated.
296
+ this.isDestroyed = true;
297
+ this.onDrained?.();
298
+ this.activeJobs.forEach(job => job.abort(reason));
299
+ this.admissions.splice(0).forEach(waiter => {
300
+ waiter.cleanup();
301
+ waiter.reject(reason);
302
+ });
303
+ this.reservations.clear();
304
+ this.reservedBytes = 0;
305
+ const queuedJobs = this.jobQueue.splice(0);
306
+ this.queuedBytes = 0;
307
+ queuedJobs.forEach(queuedJob => {
308
+ queuedJob.removeAbortListener();
309
+ queuedJob.onReject(reason);
310
+ });
311
+ this.idleQueue.splice(0).forEach(worker => {
312
+ worker.destroy();
313
+ this.count--;
314
+ });
315
+ this.isDestroyed = true;
316
+ this.destruction = Promise.all(workers.map(worker => worker.destroy())).then(() => {
317
+ this.workers.clear();
318
+ });
319
+ void this.destruction.catch(() => undefined);
320
+ return this.destruction;
321
+ }
322
+
323
+ setProps(props: WorkerPoolProps) {
324
+ for (const key of [
325
+ 'maxQueuedBytes',
326
+ 'maxInFlightBytes',
327
+ 'maxQueuedJobs',
328
+ 'maxPendingAdmissions'
329
+ ] as const) {
330
+ const value = props[key];
331
+ if (
332
+ value !== undefined &&
333
+ (!(value >= 0) || (value !== Infinity && !Number.isSafeInteger(value)))
334
+ ) {
335
+ throw new RangeError(`${key} must be a nonnegative safe integer or Infinity`);
336
+ }
337
+ }
338
+ if (
339
+ props.priorityAgingMs !== undefined &&
340
+ (!Number.isFinite(props.priorityAgingMs) || props.priorityAgingMs <= 0)
341
+ ) {
342
+ throw new RangeError('priorityAgingMs must be positive and finite');
343
+ }
344
+ this.maxQueuedJobs = props.maxQueuedJobs ?? this.maxQueuedJobs;
345
+ this.maxPendingAdmissions = props.maxPendingAdmissions ?? this.maxPendingAdmissions;
346
+ this.priorityAgingMs = props.priorityAgingMs ?? this.priorityAgingMs;
347
+ this.maxQueuedBytes = props.maxQueuedBytes ?? this.maxQueuedBytes;
348
+ this.maxInFlightBytes = props.maxInFlightBytes ?? this.maxInFlightBytes;
349
+ this.props = {...this.props, ...props};
350
+
351
+ if (props.name !== undefined) {
352
+ this.name = props.name;
353
+ }
354
+ if (props.maxConcurrency !== undefined) {
355
+ this.maxConcurrency = props.maxConcurrency;
356
+ }
357
+ if (props.maxMobileConcurrency !== undefined) {
358
+ this.maxMobileConcurrency = props.maxMobileConcurrency;
359
+ }
360
+ if (props.reuseWorkers !== undefined) {
361
+ this.reuseWorkers = props.reuseWorkers;
362
+ }
363
+ if (props.onDebug !== undefined) {
364
+ this.onDebug = props.onDebug;
365
+ }
366
+ for (const queuedJob of [...this.jobQueue]) {
367
+ if (queuedJob.inputBytes > this.maxInFlightBytes) {
368
+ this.jobQueue.splice(this.jobQueue.indexOf(queuedJob), 1);
369
+ this.queuedBytes -= queuedJob.inputBytes;
370
+ queuedJob.removeAbortListener();
371
+ queuedJob.onReject(new RangeError('Worker job exceeds maxInFlightBytes'));
372
+ }
373
+ }
374
+ this._admit();
375
+ void this._startQueuedJob();
376
+ this._checkDrained();
377
+ }
378
+
379
+ /** Whether batch callers must declare a retained-input reservation. */
380
+ get requiresInputBytes(): boolean {
381
+ return this.maxQueuedBytes !== Infinity || this.maxInFlightBytes !== Infinity;
382
+ }
383
+
384
+ async startJob(
385
+ name: string,
386
+ onMessage: OnMessage = (job, type, data) => job.done(data),
387
+ onError: OnError = (job, error) => job.error(error),
388
+ signal?: AbortSignal,
389
+ scheduling: {
390
+ inputBytes?: number;
391
+ priority?: number;
392
+ admission?: WorkerAdmission;
393
+ sharedState?: SharedWorkerState;
394
+ cancellationMode?: 'terminate' | 'cooperative';
395
+ cancellationTimeout?: number;
396
+ } = {}
397
+ ): Promise<WorkerJob> {
398
+ if (
399
+ scheduling.cancellationMode !== undefined &&
400
+ !['terminate', 'cooperative'].includes(scheduling.cancellationMode)
401
+ ) {
402
+ throw new Error('Invalid worker cancellation mode');
403
+ }
404
+ if (
405
+ scheduling.cancellationTimeout !== undefined &&
406
+ (!Number.isFinite(scheduling.cancellationTimeout) || scheduling.cancellationTimeout < 0)
407
+ ) {
408
+ throw new RangeError('cancellationTimeout must be finite and nonnegative');
409
+ }
410
+ if (signal?.aborted) {
411
+ throw signal.reason;
412
+ }
413
+ if (this.isDestroyed) {
414
+ return Promise.reject(new Error('Worker pool was destroyed'));
415
+ }
416
+ if (this.isClosing) return Promise.reject(new Error('Worker pool is closing'));
417
+ const {inputBytes = 0, priority = 0} = scheduling;
418
+ if (!Number.isSafeInteger(inputBytes) || inputBytes < 0 || !Number.isFinite(priority)) {
419
+ throw new RangeError('Invalid worker scheduling inputBytes or priority');
420
+ }
421
+ if (inputBytes > this.maxInFlightBytes) {
422
+ throw new RangeError('Worker job exceeds maxInFlightBytes');
423
+ }
424
+ const admission = scheduling.admission;
425
+ if (admission && (!this.reservations.has(admission) || admission.inputBytes !== inputBytes)) {
426
+ throw new Error('Invalid or consumed worker admission');
427
+ }
428
+ // A job that can start immediately need not fit the waiting queue budget.
429
+ const canStart =
430
+ !this.jobQueue.length &&
431
+ this.activeJobs.size < this._getMaxConcurrency() &&
432
+ this.inFlightBytes + inputBytes <= this.maxInFlightBytes;
433
+ if (
434
+ !admission &&
435
+ !canStart &&
436
+ (this.jobQueue.length + this.reservations.size >= this.maxQueuedJobs ||
437
+ inputBytes > this.maxQueuedBytes - this.queuedBytes - this.reservedBytes)
438
+ ) {
439
+ throw new RangeError('Worker queue exceeds maxQueuedBytes or maxQueuedJobs');
440
+ }
441
+ if (admission) {
442
+ this.reservations.delete(admission);
443
+ this.reservedBytes -= admission.inputBytes;
444
+ }
445
+ // Promise resolves when thread starts working on this job
446
+ const startPromise = new Promise<WorkerJob>((onStart, onReject) => {
447
+ // Promise resolves when thread completes or fails working on this job
448
+ const abortQueuedJob = (): void => {
449
+ const index = this.jobQueue.indexOf(queuedJob);
450
+ if (index >= 0) {
451
+ this.jobQueue.splice(index, 1);
452
+ this.queuedBytes -= queuedJob.inputBytes;
453
+ this._admit();
454
+ void this._startQueuedJob();
455
+ queuedJob.removeAbortListener();
456
+ onReject(signal?.reason);
457
+ this._checkDrained();
458
+ }
459
+ };
460
+ const queuedJob: QueuedJob = {
461
+ name,
462
+ inputBytes,
463
+ priority,
464
+ queuedAt: performance.now(),
465
+ sharedState: scheduling.sharedState,
466
+ cancellationMode: scheduling.cancellationMode,
467
+ cancellationTimeout: scheduling.cancellationTimeout,
468
+ onMessage,
469
+ onError,
470
+ onStart,
471
+ onReject,
472
+ signal,
473
+ removeAbortListener: () => signal?.removeEventListener('abort', abortQueuedJob)
474
+ };
475
+ // Stable priority order: larger values first, FIFO for equal priorities.
476
+ const index = this.jobQueue.findIndex(job => job.priority < priority);
477
+ this.jobQueue.splice(index < 0 ? this.jobQueue.length : index, 0, queuedJob);
478
+ this.queuedBytes += inputBytes;
479
+ if (!canStart)
480
+ this.totals.peakQueuedBytes = Math.max(
481
+ this.totals.peakQueuedBytes,
482
+ this.queuedBytes + this.reservedBytes
483
+ );
484
+ signal?.addEventListener('abort', abortQueuedJob, {once: true});
485
+ return this;
486
+ });
487
+ this._startQueuedJob(); // eslint-disable-line @typescript-eslint/no-floating-promises
488
+ return await startPromise;
489
+ }
490
+
491
+ // PRIVATE
492
+
493
+ /**
494
+ * Starts first queued job if worker is available or can be created
495
+ * Called when job is started and whenever a worker returns to the idleQueue
496
+ */
497
+ async _startQueuedJob(): Promise<void> {
498
+ if (!this.jobQueue.length) {
499
+ return;
500
+ }
501
+
502
+ const now = performance.now();
503
+ this.jobQueue.sort(
504
+ (a, b) =>
505
+ b.priority +
506
+ Math.floor((now - b.queuedAt) / this.priorityAgingMs) -
507
+ (a.priority + Math.floor((now - a.queuedAt) / this.priorityAgingMs))
508
+ );
509
+ // Strict priority order deliberately prevents smaller jobs bypassing the head job.
510
+ if (this.jobQueue[0].inputBytes > this.maxInFlightBytes - this.inFlightBytes) return;
511
+
512
+ let workerThread: WorkerThread | null;
513
+ try {
514
+ workerThread = this._getAvailableWorker();
515
+ } catch (error) {
516
+ const queuedJob = this.jobQueue.shift();
517
+ if (queuedJob) this.queuedBytes -= queuedJob.inputBytes;
518
+ this._admit();
519
+ queuedJob?.removeAbortListener();
520
+ queuedJob?.onReject(error);
521
+ void this._startQueuedJob();
522
+ this._checkDrained();
523
+ return;
524
+ }
525
+ if (!workerThread) {
526
+ return;
527
+ }
528
+
529
+ // We have a worker, dequeue and start the job
530
+ const queuedJob = this.jobQueue.shift();
531
+ if (queuedJob) {
532
+ this.startingJobs++;
533
+ this.queuedBytes -= queuedJob.inputBytes;
534
+ this.inFlightBytes += queuedJob.inputBytes;
535
+ this.totals.peakInFlightBytes = Math.max(this.totals.peakInFlightBytes, this.inFlightBytes);
536
+ this._admit();
537
+ const startedAt = performance.now();
538
+ try {
539
+ // @ts-ignore Legacy diagnostic callback shape.
540
+ this.onDebug({
541
+ message: 'Starting job',
542
+ name: queuedJob.name,
543
+ workerThread,
544
+ backlog: this.jobQueue.length
545
+ });
546
+ } catch {
547
+ /* Diagnostics must never affect scheduling. */
548
+ }
549
+
550
+ if (this.isDestroyed || workerThread.terminated) {
551
+ this.startingJobs--;
552
+ this.inFlightBytes -= queuedJob.inputBytes;
553
+ queuedJob.removeAbortListener();
554
+ queuedJob.onReject(new Error('Worker pool was destroyed before job start'));
555
+ this.returnWorkerToQueue(workerThread);
556
+ return;
557
+ }
558
+ // Create a worker job to let the app access thread and manage job completion
559
+ const job = new WorkerJob(queuedJob.name, workerThread);
560
+ job.sharedState = queuedJob.sharedState;
561
+ queuedJob.removeAbortListener();
562
+ const abortJob = (): void => {
563
+ if (queuedJob.cancellationMode === 'cooperative') {
564
+ job.cancel(queuedJob.signal?.reason, queuedJob.cancellationTimeout);
565
+ } else job.abort(queuedJob.signal?.reason);
566
+ };
567
+ queuedJob.signal?.addEventListener('abort', abortJob, {once: true});
568
+ if (queuedJob.signal?.aborted) abortJob();
569
+ this.activeJobs.add(job);
570
+ this.startingJobs--;
571
+ workerThread.ref();
572
+
573
+ // Set the worker thread's message handlers
574
+ workerThread.onMessage = data => {
575
+ try {
576
+ if (job.isRunning) queuedJob.onMessage(job, data.type, data.payload);
577
+ } catch (error) {
578
+ job.abort(error);
579
+ }
580
+ };
581
+ workerThread.onError = error => {
582
+ try {
583
+ queuedJob.onError(job, error);
584
+ } catch (callbackError) {
585
+ job.abort(callbackError);
586
+ }
587
+ };
588
+
589
+ void job.result.catch(() => undefined);
590
+ // Resolve the start promise so that the app can start sending messages to worker
591
+ queuedJob.onStart(job);
592
+ void this._startQueuedJob();
593
+
594
+ // Wait for the app to signal that the job is complete, then return worker to queue
595
+ try {
596
+ await job.completion;
597
+ } catch {
598
+ // The job result promise carries worker errors back to the caller; do not duplicate-log
599
+ // handled rejections here.
600
+ } finally {
601
+ queuedJob.signal?.removeEventListener('abort', abortJob);
602
+ this.activeJobs.delete(job);
603
+ this.inFlightBytes -= queuedJob.inputBytes;
604
+ const outcome = job.isCancelled ? 'cancelled' : job.failed ? 'failed' : 'completed';
605
+ this.totals[outcome]++;
606
+ const metrics: WorkerJobMetrics = {
607
+ name: job.name,
608
+ outcome,
609
+ queueWaitMs: startedAt - queuedJob.queuedAt,
610
+ durationMs: performance.now() - startedAt,
611
+ workerCreationMs: workerThread.creationTimeMs,
612
+ workerStartupMs: workerThread.startupTimeMs,
613
+ postMessageMs: job.postMessageMs,
614
+ executionMs: job.executionMs,
615
+ inputBytes: queuedJob.inputBytes
616
+ };
617
+ try {
618
+ this.props.onMetrics?.(metrics);
619
+ if (this.props.performanceMarks && typeof performance.measure === 'function') {
620
+ performance.measure(`math.gl.worker:${job.name}`, {
621
+ start: queuedJob.queuedAt,
622
+ end: performance.now(),
623
+ detail: metrics
624
+ });
625
+ }
626
+ } catch {
627
+ /* Instrumentation must not break worker release. */
628
+ }
629
+ this._admit();
630
+ this.returnWorkerToQueue(workerThread);
631
+ }
632
+ } else {
633
+ this.returnWorkerToQueue(workerThread);
634
+ }
635
+ }
636
+
637
+ /**
638
+ * Returns a worker to the idle queue
639
+ * Destroys the worker if
640
+ * - pool is destroyed
641
+ * - if this pool doesn't reuse workers
642
+ * - if maxConcurrency has been lowered
643
+ * @param worker
644
+ */
645
+ returnWorkerToQueue(worker: WorkerThread) {
646
+ const shouldDestroyWorker =
647
+ // Aborted jobs terminate their worker immediately.
648
+ worker.terminated ||
649
+ // If the pool is destroyed, there is no reason to keep the worker around
650
+ this.isDestroyed ||
651
+ // If the app has disabled worker reuse, any completed workers should be destroyed
652
+ !this.reuseWorkers ||
653
+ // If concurrency has been lowered, this worker might be surplus to requirements
654
+ this.count > this._getMaxConcurrency();
655
+
656
+ if (shouldDestroyWorker) {
657
+ if (worker.terminated && !this.isDestroyed) this.totals.workerRestarts++;
658
+ if (!worker.terminated) {
659
+ worker.destroy();
660
+ }
661
+ void worker.destroy().then(() => this.workers.delete(worker));
662
+ this.count--;
663
+ } else {
664
+ worker.unref();
665
+ this.idleQueue.push(worker);
666
+ }
667
+
668
+ if (!this.isDestroyed) {
669
+ this._startQueuedJob(); // eslint-disable-line @typescript-eslint/no-floating-promises
670
+ }
671
+ this._checkDrained();
672
+ }
673
+
674
+ /**
675
+ * Returns idle worker or creates new worker if maxConcurrency has not been reached
676
+ */
677
+ _getAvailableWorker(): WorkerThread | null {
678
+ // If a worker has completed and returned to the queue, it can be used
679
+ while (this.idleQueue.length > 0) {
680
+ const worker = this.idleQueue.shift();
681
+ if (worker && (worker.terminated || this.count > this._getMaxConcurrency())) {
682
+ if (worker.terminated) this.totals.workerRestarts++;
683
+ void worker.destroy().then(() => this.workers.delete(worker));
684
+ this.count--;
685
+ } else if (worker) {
686
+ return worker;
687
+ }
688
+ }
689
+
690
+ // Create fresh worker if we haven't yet created the max amount of worker threads for this worker source
691
+ if (this.count < this._getMaxConcurrency()) {
692
+ this.count++;
693
+ const name = `${this.name.toLowerCase()} (#${this.count} of ${this.maxConcurrency})`;
694
+ try {
695
+ const worker = new WorkerThread({
696
+ name,
697
+ source: this.source,
698
+ url: this.url,
699
+ workerType: this.workerType,
700
+ getUrl: this.getUrl,
701
+ loadWorker: this.loadWorker
702
+ });
703
+ this.totals.workersCreated++;
704
+ this.workers.add(worker);
705
+ return worker;
706
+ } catch (error) {
707
+ this.count--;
708
+ throw error;
709
+ }
710
+ }
711
+
712
+ // No worker available, have to wait
713
+ return null;
714
+ }
715
+
716
+ _getMaxConcurrency() {
717
+ return isMobile ? this.maxMobileConcurrency : this.maxConcurrency;
718
+ }
719
+ }