docs: update changelog entries
[poolifier.git] / src / pools / pool.ts
CommitLineData
fc3e6586 1import EventEmitter from 'node:events'
bdaf31cd
JB
2import type {
3 ErrorHandler,
4 ExitHandler,
5 MessageHandler,
6 OnlineHandler
f06e48d8 7} from './worker'
da309861
JB
8import type {
9 WorkerChoiceStrategy,
10 WorkerChoiceStrategyOptions
11} from './selection-strategies/selection-strategies-types'
bdaf31cd 12
b4904890
JB
13/**
14 * Pool events emitter.
15 */
16export class PoolEmitter extends EventEmitter {}
17
aee46736
JB
18/**
19 * Enumeration of pool events.
20 */
21export const PoolEvents = Object.freeze({
22 full: 'full',
23 busy: 'busy'
24} as const)
25
26/**
27 * Pool event.
28 */
29export type PoolEvent = keyof typeof PoolEvents
30
bdaf31cd
JB
31/**
32 * Options for a poolifier pool.
33 */
34export interface PoolOptions<Worker> {
35 /**
36 * A function that will listen for message event on each worker.
37 */
38 messageHandler?: MessageHandler<Worker>
39 /**
40 * A function that will listen for error event on each worker.
41 */
42 errorHandler?: ErrorHandler<Worker>
43 /**
44 * A function that will listen for online event on each worker.
45 */
46 onlineHandler?: OnlineHandler<Worker>
47 /**
48 * A function that will listen for exit event on each worker.
49 */
50 exitHandler?: ExitHandler<Worker>
51 /**
46e857ca 52 * The worker choice strategy to use in this pool.
bdaf31cd
JB
53 */
54 workerChoiceStrategy?: WorkerChoiceStrategy
da309861
JB
55 /**
56 * The worker choice strategy options.
57 */
58 workerChoiceStrategyOptions?: WorkerChoiceStrategyOptions
bdaf31cd
JB
59 /**
60 * Pool events emission.
61 *
38e795c1 62 * @defaultValue true
bdaf31cd
JB
63 */
64 enableEvents?: boolean
ff733df7
JB
65 /**
66 * Pool worker tasks queue.
67 *
68 * @experimental
69 * @defaultValue false
70 */
71 enableTasksQueue?: boolean
bdaf31cd 72}
a35560ba 73
729c563d
S
74/**
75 * Contract definition for a poolifier pool.
76 *
38e795c1
JB
77 * @typeParam Data - Type of data sent to the worker. This can only be serializable data.
78 * @typeParam Response - Type of response of execution. This can only be serializable data.
729c563d 79 */
d3c8a1a8 80export interface IPool<Data = unknown, Response = unknown> {
b4904890
JB
81 /**
82 * Emitter on which events can be listened to.
83 *
84 * Events that can currently be listened to:
85 *
164d950a
JB
86 * - `'full'`: Emitted when the pool is dynamic and full.
87 * - `'busy'`: Emitted when the pool is busy.
b4904890
JB
88 */
89 readonly emitter?: PoolEmitter
729c563d 90 /**
bdede008 91 * Performs the task specified in the constructor with the data parameter.
729c563d 92 *
38e795c1 93 * @param data - The input for the specified task. This can only be serializable data.
729c563d
S
94 * @returns Promise that will be resolved when the task is successfully completed.
95 */
78cea37e 96 execute: (data: Data) => Promise<Response>
280c2a77 97 /**
675bb809 98 * Shutdowns every current worker in this pool.
280c2a77 99 */
78cea37e 100 destroy: () => Promise<void>
a35560ba 101 /**
bdede008 102 * Sets the worker choice strategy in this pool.
a35560ba 103 *
38e795c1 104 * @param workerChoiceStrategy - The worker choice strategy.
a35560ba 105 */
78cea37e 106 setWorkerChoiceStrategy: (workerChoiceStrategy: WorkerChoiceStrategy) => void
c97c7edb 107}