@xylabs/threads 4.6.3 → 4.7.0-rc.1

package/src/master/pool.ts

@@ -1,399 +0,0 @@
-/* eslint-disable import-x/export */
-/* eslint-disable unicorn/no-thenable */
-
-/* eslint-disable require-await */
-/* 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 */
-/* eslint-disable @typescript-eslint/no-floating-promises */
-import DebugLogger from 'debug'
-import {
-  multicast, Observable, Subject,
-} from 'observable-fns'
-
-import { allSettled } from '../ponyfills'
-import { defaultPoolSize } from './implementation'
-import type {
-  PoolEvent, QueuedTask, TaskRunFunction, WorkerDescriptor,
-} from './pool-types'
-import { PoolEventType } from './pool-types'
-import { Thread } from './thread'
-
-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 (error) {
-      this.debug(`Task #${task.id} failed`)
-      this.eventSubject.next({
-        error,
-        taskID: task.id,
-        type: PoolEventType.taskFailed,
-        workerID,
-      })
-    }
-  }
-
-  private async 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 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 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 {
-  PoolEvent, PoolEventType, QueuedTask,
-} from './pool-types'
-export { Thread } from './thread'

package/src/master/register.ts

@@ -1,10 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { Worker as WorkerImplementation } from './index'
-
-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

@@ -1,172 +0,0 @@
-/* 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'
-import { createPromiseWithResolver } from '../promise'
-import {
-  $errors, $events, $terminate, $worker,
-} from '../symbols'
-import type {
-  FunctionThread,
-  ModuleThread,
-  PrivateThreadProps,
-  StripAsync,
-  Worker as WorkerType,
-  WorkerEvent,
-  WorkerInternalErrorEvent,
-  WorkerMessageEvent,
-  WorkerTerminationEvent,
-} from '../types/master'
-import { WorkerEventType } from '../types/master'
-import type { WorkerInitMessage, WorkerUncaughtErrorMessage } from '../types/messages'
-import type { WorkerFunction, WorkerModule } from '../types/worker'
-import { createProxyFunction, createProxyModule } from './invocation-proxy'
-
-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

@@ -1,29 +0,0 @@
-/* eslint-disable import-x/no-internal-modules */
-import type { Observable } from 'observable-fns'
-
-import {
-  $errors, $events, $terminate,
-} from '../symbols'
-import type { Thread as ThreadType, WorkerEvent } from '../types/master'
-
-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]()
-  },
-}