@xylabs/threads 4.8.0-rc.2 → 4.8.0

package/src/master/pool-node.ts

@@ -0,0 +1,399 @@
+/* eslint-disable import-x/export */
+/* eslint-disable unicorn/no-thenable */
+
+/* eslint-disable @typescript-eslint/member-ordering */
+/* eslint-disable unicorn/no-array-reduce */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-namespace */
+
+/// <reference lib="esnext" />
+
+import DebugLogger from 'debug'
+import {
+  multicast, Observable, Subject,
+} from 'observable-fns'
+
+import { defaultPoolSize } from './implementation.node.ts'
+import type {
+  PoolEvent, QueuedTask, TaskRunFunction, WorkerDescriptor,
+} from './pool-types.ts'
+import { PoolEventType } from './pool-types.ts'
+import { Thread } from './thread.ts'
+
+export declare namespace Pool {
+  type Event<ThreadType extends Thread = any> = PoolEvent<ThreadType>
+  type EventType = PoolEventType
+}
+
+let nextPoolID = 1
+
+function createArray(size: number): number[] {
+  const array: number[] = []
+  for (let index = 0; index < size; index++) {
+    array.push(index)
+  }
+  return array
+}
+
+function delay(ms: number) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+function flatMap<In, Out>(array: In[], mapper: (element: In) => Out[]): Out[] {
+  return array.reduce<Out[]>((flattened, element) => [...flattened, ...mapper(element)], [])
+}
+
+function slugify(text: string) {
+  return text.replaceAll(/\W/g, ' ').trim().replaceAll(/\s+/g, '-')
+}
+
+function spawnWorkers<ThreadType extends Thread>(spawnWorker: () => Promise<ThreadType>, count: number): Array<WorkerDescriptor<ThreadType>> {
+  return createArray(count).map(
+    (): WorkerDescriptor<ThreadType> => ({
+      init: spawnWorker(),
+      runningTasks: [],
+    }),
+  )
+}
+
+/**
+ * Thread pool managing a set of worker threads.
+ * Use it to queue tasks that are run on those threads with limited
+ * concurrency.
+ */
+export interface Pool<ThreadType extends Thread> {
+  /**
+   * Returns a promise that resolves once the task queue is emptied.
+   * Promise will be rejected if any task fails.
+   *
+   * @param allowResolvingImmediately Set to `true` to resolve immediately if task queue is currently empty.
+   */
+  completed(allowResolvingImmediately?: boolean): Promise<any>
+
+  /**
+   * Returns a promise that resolves once the task queue is emptied.
+   * Failing tasks will not cause the promise to be rejected.
+   *
+   * @param allowResolvingImmediately Set to `true` to resolve immediately if task queue is currently empty.
+   */
+  settled(allowResolvingImmediately?: boolean): Promise<Error[]>
+
+  /**
+   * Returns an observable that yields pool events.
+   */
+  events(): Observable<PoolEvent<ThreadType>>
+
+  /**
+   * Queue a task and return a promise that resolves once the task has been dequeued,
+   * started and finished.
+   *
+   * @param task An async function that takes a thread instance and invokes it.
+   */
+  queue<Return>(task: TaskRunFunction<ThreadType, Return>): QueuedTask<ThreadType, Return>
+
+  /**
+   * Terminate all pool threads.
+   *
+   * @param force Set to `true` to kill the thread even if it cannot be stopped gracefully.
+   */
+  terminate(force?: boolean): Promise<void>
+}
+
+interface PoolOptions {
+  /** Maximum no. of tasks to run on one worker thread at a time. Defaults to one. */
+  concurrency?: number
+
+  /** Maximum no. of jobs to be queued for execution before throwing an error. */
+  maxQueuedJobs?: number
+
+  /** Gives that pool a name to be used for debug logging, letting you distinguish between log output of different pools. */
+  name?: string
+
+  /** No. of worker threads to spawn and to be managed by the pool. */
+  size?: number
+}
+
+class WorkerPool<ThreadType extends Thread> implements Pool<ThreadType> {
+  static EventType = PoolEventType
+
+  private readonly debug: DebugLogger.Debugger
+  private readonly eventObservable: Observable<PoolEvent<ThreadType>>
+  private readonly options: PoolOptions
+  private readonly workers: Array<WorkerDescriptor<ThreadType>>
+
+  private readonly eventSubject = new Subject<PoolEvent<ThreadType>>()
+  private initErrors: Error[] = []
+  private isClosing = false
+  private nextTaskID = 1
+  private taskQueue: Array<QueuedTask<ThreadType, any>> = []
+
+  constructor(spawnWorker: () => Promise<ThreadType>, optionsOrSize?: number | PoolOptions) {
+    const options: PoolOptions = typeof optionsOrSize === 'number' ? { size: optionsOrSize } : optionsOrSize || {}
+
+    const { size = defaultPoolSize } = options
+
+    this.debug = DebugLogger(`threads:pool:${slugify(options.name || String(nextPoolID++))}`)
+    this.options = options
+    this.workers = spawnWorkers(spawnWorker, size)
+
+    this.eventObservable = multicast(Observable.from(this.eventSubject))
+
+    Promise.all(this.workers.map(worker => worker.init)).then(
+      () =>
+        this.eventSubject.next({
+          size: this.workers.length,
+          type: PoolEventType.initialized,
+        }),
+      (error) => {
+        this.debug('Error while initializing pool worker:', error)
+        this.eventSubject.error(error)
+        this.initErrors.push(error)
+      },
+    )
+  }
+
+  private findIdlingWorker(): WorkerDescriptor<ThreadType> | undefined {
+    const { concurrency = 1 } = this.options
+    return this.workers.find(worker => worker.runningTasks.length < concurrency)
+  }
+
+  private async runPoolTask(worker: WorkerDescriptor<ThreadType>, task: QueuedTask<ThreadType, any>) {
+    const workerID = this.workers.indexOf(worker) + 1
+
+    this.debug(`Running task #${task.id} on worker #${workerID}...`)
+    this.eventSubject.next({
+      taskID: task.id,
+      type: PoolEventType.taskStart,
+      workerID,
+    })
+
+    try {
+      const returnValue = await task.run(await worker.init)
+
+      this.debug(`Task #${task.id} completed successfully`)
+      this.eventSubject.next({
+        returnValue,
+        taskID: task.id,
+        type: PoolEventType.taskCompleted,
+        workerID,
+      })
+    } catch (ex) {
+      const error = ex as Error
+      this.debug(`Task #${task.id} failed`)
+      this.eventSubject.next({
+        error,
+        taskID: task.id,
+        type: PoolEventType.taskFailed,
+        workerID,
+      })
+    }
+  }
+
+  private run(worker: WorkerDescriptor<ThreadType>, task: QueuedTask<ThreadType, any>) {
+    const runPromise = (async () => {
+      const removeTaskFromWorkersRunningTasks = () => {
+        worker.runningTasks = worker.runningTasks.filter(someRunPromise => someRunPromise !== runPromise)
+      }
+
+      // Defer task execution by one tick to give handlers time to subscribe
+      await delay(0)
+
+      try {
+        await this.runPoolTask(worker, task)
+      } finally {
+        removeTaskFromWorkersRunningTasks()
+
+        if (!this.isClosing) {
+          this.scheduleWork()
+        }
+      }
+    })()
+
+    worker.runningTasks.push(runPromise)
+  }
+
+  private scheduleWork() {
+    this.debug('Attempt de-queueing a task in order to run it...')
+
+    const availableWorker = this.findIdlingWorker()
+    if (!availableWorker) return
+
+    const nextTask = this.taskQueue.shift()
+    if (!nextTask) {
+      this.debug('Task queue is empty')
+      this.eventSubject.next({ type: PoolEventType.taskQueueDrained })
+      return
+    }
+
+    this.run(availableWorker, nextTask)
+  }
+
+  private taskCompletion(taskID: number) {
+    return new Promise<any>((resolve, reject) => {
+      const eventSubscription = this.events().subscribe((event) => {
+        if (event.type === PoolEventType.taskCompleted && event.taskID === taskID) {
+          eventSubscription.unsubscribe()
+          resolve(event.returnValue)
+        } else if (event.type === PoolEventType.taskFailed && event.taskID === taskID) {
+          eventSubscription.unsubscribe()
+          reject(event.error)
+        } else if (event.type === PoolEventType.terminated) {
+          eventSubscription.unsubscribe()
+          reject(new Error('Pool has been terminated before task was run.'))
+        }
+      })
+    })
+  }
+
+  async settled(allowResolvingImmediately: boolean = false): Promise<Error[]> {
+    const getCurrentlyRunningTasks = () => flatMap(this.workers, worker => worker.runningTasks)
+
+    const taskFailures: Error[] = []
+
+    const failureSubscription = this.eventObservable.subscribe((event) => {
+      if (event.type === PoolEventType.taskFailed) {
+        taskFailures.push(event.error)
+      }
+    })
+
+    if (this.initErrors.length > 0) {
+      throw this.initErrors[0]
+    }
+    if (allowResolvingImmediately && this.taskQueue.length === 0) {
+      await Promise.allSettled(getCurrentlyRunningTasks())
+      return taskFailures
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      const subscription = this.eventObservable.subscribe({
+        error: reject,
+        next(event) {
+          if (event.type === PoolEventType.taskQueueDrained) {
+            subscription.unsubscribe()
+            resolve(void 0)
+          }
+        }, // make a pool-wide error reject the completed() result promise
+      })
+    })
+
+    await Promise.allSettled(getCurrentlyRunningTasks())
+    failureSubscription.unsubscribe()
+
+    return taskFailures
+  }
+
+  async completed(allowResolvingImmediately: boolean = false) {
+    const settlementPromise = this.settled(allowResolvingImmediately)
+
+    const earlyExitPromise = new Promise<Error[]>((resolve, reject) => {
+      const subscription = this.eventObservable.subscribe({
+        error: reject,
+        next(event) {
+          if (event.type === PoolEventType.taskQueueDrained) {
+            subscription.unsubscribe()
+            resolve(settlementPromise)
+          } else if (event.type === PoolEventType.taskFailed) {
+            subscription.unsubscribe()
+            reject(event.error)
+          }
+        }, // make a pool-wide error reject the completed() result promise
+      })
+    })
+
+    const errors = await Promise.race([settlementPromise, earlyExitPromise])
+
+    if (errors.length > 0) {
+      throw errors[0]
+    }
+  }
+
+  events() {
+    return this.eventObservable
+  }
+
+  queue(taskFunction: TaskRunFunction<ThreadType, any>) {
+    const { maxQueuedJobs = Number.POSITIVE_INFINITY } = this.options
+
+    if (this.isClosing) {
+      throw new Error('Cannot schedule pool tasks after terminate() has been called.')
+    }
+    if (this.initErrors.length > 0) {
+      throw this.initErrors[0]
+    }
+
+    const taskID = this.nextTaskID++
+    const taskCompletion = this.taskCompletion(taskID)
+
+    taskCompletion.catch((error) => {
+      // Prevent unhandled rejections here as we assume the user will use
+      // `pool.completed()`, `pool.settled()` or `task.catch()` to handle errors
+      this.debug(`Task #${taskID} errored:`, error)
+    })
+
+    const task: QueuedTask<ThreadType, any> = {
+      cancel: () => {
+        if (!this.taskQueue.includes(task)) return
+        this.taskQueue = this.taskQueue.filter(someTask => someTask !== task)
+        this.eventSubject.next({
+          taskID: task.id,
+          type: PoolEventType.taskCanceled,
+        })
+      },
+      id: taskID,
+      run: taskFunction,
+      then: taskCompletion.then.bind(taskCompletion),
+    }
+
+    if (this.taskQueue.length >= maxQueuedJobs) {
+      throw new Error(
+        'Maximum number of pool tasks queued. Refusing to queue another one.\n'
+        + 'This usually happens for one of two reasons: We are either at peak '
+        + "workload right now or some tasks just won't finish, thus blocking the pool.",
+      )
+    }
+
+    this.debug(`Queueing task #${task.id}...`)
+    this.taskQueue.push(task)
+
+    this.eventSubject.next({
+      taskID: task.id,
+      type: PoolEventType.taskQueued,
+    })
+
+    this.scheduleWork()
+    return task
+  }
+
+  async terminate(force?: boolean) {
+    this.isClosing = true
+    if (!force) {
+      await this.completed(true)
+    }
+    this.eventSubject.next({
+      remainingQueue: [...this.taskQueue],
+      type: PoolEventType.terminated,
+    })
+    this.eventSubject.complete()
+    await Promise.all(this.workers.map(async worker => Thread.terminate(await worker.init)))
+  }
+}
+
+/**
+ * Thread pool constructor. Creates a new pool and spawns its worker threads.
+ */
+function PoolConstructor<ThreadType extends Thread>(spawnWorker: () => Promise<ThreadType>, optionsOrSize?: number | PoolOptions) {
+  // The function exists only so we don't need to use `new` to create a pool (we still can, though).
+  // If the Pool is a class or not is an implementation detail that should not concern the user.
+  return new WorkerPool(spawnWorker, optionsOrSize)
+}
+
+;(PoolConstructor as any).EventType = PoolEventType
+
+/**
+ * Thread pool constructor. Creates a new pool and spawns its worker threads.
+ */
+export const Pool = PoolConstructor as typeof PoolConstructor & { EventType: typeof PoolEventType }
+
+export type { PoolEvent, QueuedTask } from './pool-types.ts'
+export { PoolEventType } from './pool-types.ts'
+export { Thread } from './thread.ts'

package/src/master/pool-types.ts

@@ -0,0 +1,83 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/member-ordering */
+import type { Thread } from './thread.ts'
+
+/** Pool event type. Specifies the type of each `PoolEvent`. */
+export enum PoolEventType {
+  initialized = 'initialized',
+  taskCanceled = 'taskCanceled',
+  taskCompleted = 'taskCompleted',
+  taskFailed = 'taskFailed',
+  taskQueued = 'taskQueued',
+  taskQueueDrained = 'taskQueueDrained',
+  taskStart = 'taskStart',
+  terminated = 'terminated',
+}
+
+export type TaskRunFunction<ThreadType extends Thread, Return> = (worker: ThreadType) => Promise<Return>
+
+/** Pool event. Subscribe to those events using `pool.events()`. Useful for debugging. */
+export type PoolEvent<ThreadType extends Thread> =
+  | {
+    type: PoolEventType.initialized
+    size: number
+  }
+  | {
+    type: PoolEventType.taskQueued
+    taskID: number
+  }
+  | {
+    type: PoolEventType.taskQueueDrained
+  }
+  | {
+    type: PoolEventType.taskStart
+    taskID: number
+    workerID: number
+  }
+  | {
+    type: PoolEventType.taskCompleted
+    returnValue: any
+    taskID: number
+    workerID: number
+  }
+  | {
+    type: PoolEventType.taskFailed
+    error: Error
+    taskID: number
+    workerID: number
+  }
+  | {
+    type: PoolEventType.taskCanceled
+    taskID: number
+  }
+  | {
+    type: PoolEventType.terminated
+    remainingQueue: Array<QueuedTask<ThreadType, any>>
+  }
+
+export interface WorkerDescriptor<ThreadType extends Thread> {
+  init: Promise<ThreadType>
+  runningTasks: Array<Promise<any>>
+}
+
+/**
+ * Task that has been `pool.queued()`-ed.
+ */
+export interface QueuedTask<ThreadType extends Thread, Return> {
+  /** @private */
+  id: number
+
+  /** @private */
+  run: TaskRunFunction<ThreadType, Return>
+
+  /**
+   * Queued tasks can be cancelled until the pool starts running them on a worker thread.
+   */
+  cancel(): void
+
+  /**
+   * `QueuedTask` is thenable, so you can `await` it.
+   * Resolves when the task has successfully been executed. Rejects if the task fails.
+   */
+  then: Promise<Return>['then']
+}

package/src/master/register.ts

@@ -0,0 +1,11 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { Worker as WorkerImplementation } from './index-node.ts'
+
+declare const window: any
+
+if (typeof globalThis !== 'undefined') {
+  ;(globalThis as any).Worker = WorkerImplementation
+} else if (window !== undefined) {
+  ;(window as any).Worker = WorkerImplementation
+}

package/src/master/spawn.ts

@@ -0,0 +1,172 @@
+/* eslint-disable import-x/no-internal-modules */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-floating-promises */
+import DebugLogger from 'debug'
+import { Observable } from 'observable-fns'
+
+import { deserialize } from '../common.ts'
+import { createPromiseWithResolver } from '../promise.ts'
+import {
+  $errors, $events, $terminate, $worker,
+} from '../symbols.ts'
+import type {
+  FunctionThread,
+  ModuleThread,
+  PrivateThreadProps,
+  StripAsync,
+  Worker as WorkerType,
+  WorkerEvent,
+  WorkerInternalErrorEvent,
+  WorkerMessageEvent,
+  WorkerTerminationEvent,
+} from '../types/master.ts'
+import { WorkerEventType } from '../types/master.ts'
+import type { WorkerInitMessage, WorkerUncaughtErrorMessage } from '../types/messages.ts'
+import type { WorkerFunction, WorkerModule } from '../types/worker.ts'
+import { createProxyFunction, createProxyModule } from './invocation-proxy.ts'
+
+type ArbitraryWorkerInterface = WorkerFunction & WorkerModule<string> & { somekeythatisneverusedinproductioncode123: 'magicmarker123' }
+type ArbitraryThreadType = FunctionThread<any, any> & ModuleThread<any>
+
+export type ExposedToThreadType<Exposed extends WorkerFunction | WorkerModule<any>> =
+  Exposed extends ArbitraryWorkerInterface ? ArbitraryThreadType
+    : Exposed extends WorkerFunction ? FunctionThread<Parameters<Exposed>, StripAsync<ReturnType<Exposed>>>
+      : Exposed extends WorkerModule<any> ? ModuleThread<Exposed>
+        : never
+
+const debugMessages = DebugLogger('threads:master:messages')
+const debugSpawn = DebugLogger('threads:master:spawn')
+const debugThreadUtils = DebugLogger('threads:master:thread-utils')
+
+const isInitMessage = (data: any): data is WorkerInitMessage => data && data.type === ('init' as const)
+const isUncaughtErrorMessage = (data: any): data is WorkerUncaughtErrorMessage => data && data.type === ('uncaughtError' as const)
+
+const initMessageTimeout
+  = typeof process !== 'undefined' && process.env !== undefined && process.env.THREADS_WORKER_INIT_TIMEOUT
+    ? Number.parseInt(process.env.THREADS_WORKER_INIT_TIMEOUT, 10)
+    : 10_000
+
+async function withTimeout<T>(promise: Promise<T>, timeoutInMs: number, errorMessage: string): Promise<T> {
+  let timeoutHandle: any
+
+  const timeout = new Promise<never>((resolve, reject) => {
+    timeoutHandle = setTimeout(() => reject(new Error(errorMessage)), timeoutInMs)
+  })
+  const result = await Promise.race([promise, timeout])
+
+  clearTimeout(timeoutHandle)
+  return result
+}
+
+function receiveInitMessage(worker: WorkerType): Promise<WorkerInitMessage> {
+  return new Promise((resolve, reject) => {
+    const messageHandler = ((event: MessageEvent) => {
+      debugMessages('Message from worker before finishing initialization:', event.data)
+      if (isInitMessage(event.data)) {
+        worker.removeEventListener('message', messageHandler)
+        resolve(event.data)
+      } else if (isUncaughtErrorMessage(event.data)) {
+        worker.removeEventListener('message', messageHandler)
+        reject(deserialize(event.data.error))
+      }
+    }) as EventListener
+    worker.addEventListener('message', messageHandler)
+  })
+}
+
+function createEventObservable(worker: WorkerType, workerTermination: Promise<any>): Observable<WorkerEvent> {
+  return new Observable<WorkerEvent>((observer) => {
+    const messageHandler = ((messageEvent: MessageEvent) => {
+      const workerEvent: WorkerMessageEvent<any> = {
+        data: messageEvent.data,
+        type: WorkerEventType.message,
+      }
+      observer.next(workerEvent)
+    }) as EventListener
+    const rejectionHandler = ((errorEvent: PromiseRejectionEvent) => {
+      debugThreadUtils('Unhandled promise rejection event in thread:', errorEvent)
+      const workerEvent: WorkerInternalErrorEvent = {
+        error: new Error(errorEvent.reason),
+        type: WorkerEventType.internalError,
+      }
+      observer.next(workerEvent)
+    }) as EventListener
+    worker.addEventListener('message', messageHandler)
+    worker.addEventListener('unhandledrejection', rejectionHandler)
+
+    workerTermination.then(() => {
+      const terminationEvent: WorkerTerminationEvent = { type: WorkerEventType.termination }
+      worker.removeEventListener('message', messageHandler)
+      worker.removeEventListener('unhandledrejection', rejectionHandler)
+      observer.next(terminationEvent)
+      observer.complete()
+    })
+  })
+}
+
+function createTerminator(worker: WorkerType): { terminate: () => Promise<void>; termination: Promise<void> } {
+  const [termination, resolver] = createPromiseWithResolver<void>()
+  const terminate = async () => {
+    debugThreadUtils('Terminating worker')
+    // Newer versions of worker_threads workers return a promise
+    await worker.terminate()
+    resolver()
+  }
+  return { terminate, termination }
+}
+
+function setPrivateThreadProps<T>(
+  raw: T,
+  worker: WorkerType,
+  workerEvents: Observable<WorkerEvent>,
+  terminate: () => Promise<void>,
+): T & PrivateThreadProps {
+  const workerErrors = workerEvents
+    .filter(event => event.type === WorkerEventType.internalError)
+    .map(errorEvent => (errorEvent as WorkerInternalErrorEvent).error)
+
+  return Object.assign(raw as any, {
+    [$errors]: workerErrors,
+    [$events]: workerEvents,
+    [$terminate]: terminate,
+    [$worker]: worker,
+  })
+}
+
+/**
+ * Spawn a new thread. Takes a fresh worker instance, wraps it in a thin
+ * abstraction layer to provide the transparent API and verifies that
+ * the worker has initialized successfully.
+ *
+ * @param worker Instance of `Worker`. Either a web worker, `worker_threads` worker or `tiny-worker` worker.
+ * @param [options]
+ * @param [options.timeout] Init message timeout. Default: 10000 or set by environment variable.
+ */
+export async function spawn<Exposed extends WorkerFunction | WorkerModule<any> = ArbitraryWorkerInterface>(
+  worker: WorkerType,
+  options?: { timeout?: number },
+): Promise<ExposedToThreadType<Exposed>> {
+  debugSpawn('Initializing new thread')
+
+  const timeout = options && options.timeout ? options.timeout : initMessageTimeout
+  const initMessage = await withTimeout(
+    receiveInitMessage(worker),
+    timeout,
+    `Timeout: Did not receive an init message from worker after ${timeout}ms. Make sure the worker calls expose().`,
+  )
+  const exposed = initMessage.exposed
+
+  const { termination, terminate } = createTerminator(worker)
+  const events = createEventObservable(worker, termination)
+
+  if (exposed.type === 'function') {
+    const proxy = createProxyFunction(worker)
+    return setPrivateThreadProps(proxy, worker, events, terminate) as ExposedToThreadType<Exposed>
+  } else if (exposed.type === 'module') {
+    const proxy = createProxyModule(worker, exposed.methods)
+    return setPrivateThreadProps(proxy, worker, events, terminate) as ExposedToThreadType<Exposed>
+  } else {
+    const type = (exposed as WorkerInitMessage['exposed']).type
+    throw new Error(`Worker init message states unexpected type of expose(): ${type}`)
+  }
+}

package/src/master/thread.ts

@@ -0,0 +1,29 @@
+/* eslint-disable import-x/no-internal-modules */
+import type { Observable } from 'observable-fns'
+
+import {
+  $errors, $events, $terminate,
+} from '../symbols.ts'
+import type { Thread as ThreadType, WorkerEvent } from '../types/master.ts'
+
+function fail(message: string): never {
+  throw new Error(message)
+}
+
+export type Thread = ThreadType
+
+/** Thread utility functions. Use them to manage or inspect a `spawn()`-ed thread. */
+export const Thread = {
+  /** Return an observable that can be used to subscribe to all errors happening in the thread. */
+  errors<ThreadT extends ThreadType>(thread: ThreadT): Observable<Error> {
+    return thread[$errors] || fail('Error observable not found. Make sure to pass a thread instance as returned by the spawn() promise.')
+  },
+  /** Return an observable that can be used to subscribe to internal events happening in the thread. Useful for debugging. */
+  events<ThreadT extends ThreadType>(thread: ThreadT): Observable<WorkerEvent> {
+    return thread[$events] || fail('Events observable not found. Make sure to pass a thread instance as returned by the spawn() promise.')
+  },
+  /** Terminate a thread. Remember to terminate every thread when you are done using it. */
+  terminate<ThreadT extends ThreadType>(thread: ThreadT) {
+    return thread[$terminate]()
+  },
+}