src/pools/selection-strategies/selection-strategies-types.ts

   1 /**
   2  * Enumeration of worker choice strategies.
   3  */
   4 export const WorkerChoiceStrategies = Object.freeze({
   5   /**
   6    * Round robin worker selection strategy.
   7    */
   8   ROUND_ROBIN: 'ROUND_ROBIN',
   9   /**
  10    * Least used worker selection strategy.
  11    */
  12   LEAST_USED: 'LEAST_USED',
  13   /**
  14    * Least busy worker selection strategy.
  15    */
  16   LEAST_BUSY: 'LEAST_BUSY',
  17   /**
  18    * Least ELU worker selection strategy.
  19    */
  20   LEAST_ELU: 'LEAST_ELU',
  21   /**
  22    * Fair share worker selection strategy.
  23    */
  24   FAIR_SHARE: 'FAIR_SHARE',
  25   /**
  26    * Weighted round robin worker selection strategy.
  27    */
  28   WEIGHTED_ROUND_ROBIN: 'WEIGHTED_ROUND_ROBIN',
  29   /**
  30    * Interleaved weighted round robin worker selection strategy.
  31    *
  32    * @experimental
  33    */
  34   INTERLEAVED_WEIGHTED_ROUND_ROBIN: 'INTERLEAVED_WEIGHTED_ROUND_ROBIN'
  35 } as const)
  36
  37 /**
  38  * Worker choice strategy.
  39  */
  40 export type WorkerChoiceStrategy = keyof typeof WorkerChoiceStrategies
  41
  42 /**
  43  * Enumeration of measurements.
  44  */
  45 export const Measurements = Object.freeze({
  46   runTime: 'runTime',
  47   waitTime: 'waitTime',
  48   elu: 'elu'
  49 } as const)
  50
  51 /**
  52  * Measurement.
  53  */
  54 export type Measurement = keyof typeof Measurements
  55
  56 /**
  57  * Measurement options.
  58  */
  59 export interface MeasurementOptions {
  60   /**
  61    * Set measurement median.
  62    */
  63   readonly median: boolean
  64 }
  65
  66 /**
  67  * Worker choice strategy options.
  68  */
  69 export interface WorkerChoiceStrategyOptions {
  70   /**
  71    * Measurement to use in worker choice strategy supporting it.
  72    */
  73   readonly measurement?: Measurement
  74   /**
  75    * Runtime options.
  76    *
  77    * @defaultValue \{ median: false \}
  78    */
  79   readonly runTime?: MeasurementOptions
  80   /**
  81    * Wait time options.
  82    *
  83    * @defaultValue \{ median: false \}
  84    */
  85   readonly waitTime?: MeasurementOptions
  86   /**
  87    * Event loop utilization options.
  88    *
  89    * @defaultValue \{ median: false \}
  90    */
  91   readonly elu?: MeasurementOptions
  92   /**
  93    * Worker weights to use for weighted round robin worker selection strategies.
  94    * A weight is tasks maximum execution time in milliseconds for a worker node.
  95    *
  96    * @defaultValue Weights computed automatically given the CPU performance.
  97    */
  98   weights?: Record<number, number>
  99 }
 100
 101 /**
 102  * Worker choice strategy internal options.
 103  *
 104  * @internal
 105  */
 106 export interface InternalWorkerChoiceStrategyOptions
 107   extends WorkerChoiceStrategyOptions {
 108   /**
 109    * Number of worker choice retries to perform if no worker is eligible.
 110    *
 111    * @defaultValue pool maximum size
 112    */
 113   readonly retries?: number
 114 }
 115
 116 /**
 117  * Measurement statistics requirements.
 118  *
 119  * @internal
 120  */
 121 export interface MeasurementStatisticsRequirements {
 122   /**
 123    * Requires measurement aggregate.
 124    */
 125   aggregate: boolean
 126   /**
 127    * Requires measurement average.
 128    */
 129   average: boolean
 130   /**
 131    * Requires measurement median.
 132    */
 133   median: boolean
 134 }
 135
 136 /**
 137  * Pool worker node worker usage statistics requirements.
 138  *
 139  * @internal
 140  */
 141 export interface TaskStatisticsRequirements {
 142   /**
 143    * Tasks runtime requirements.
 144    */
 145   readonly runTime: MeasurementStatisticsRequirements
 146   /**
 147    * Tasks wait time requirements.
 148    */
 149   readonly waitTime: MeasurementStatisticsRequirements
 150   /**
 151    * Tasks event loop utilization requirements.
 152    */
 153   readonly elu: MeasurementStatisticsRequirements
 154 }
 155
 156 /**
 157  * Strategy policy.
 158  *
 159  * @internal
 160  */
 161 export interface StrategyPolicy {
 162   /**
 163    * Expects tasks execution on the newly created dynamic worker.
 164    */
 165   readonly dynamicWorkerUsage: boolean
 166   /**
 167    * Expects the newly created dynamic worker to be flagged as ready.
 168    */
 169   readonly dynamicWorkerReady: boolean
 170 }
 171
 172 /**
 173  * Worker choice strategy interface.
 174  *
 175  * @internal
 176  */
 177 export interface IWorkerChoiceStrategy {
 178   /**
 179    * Strategy policy.
 180    */
 181   readonly strategyPolicy: StrategyPolicy
 182   /**
 183    * Tasks statistics requirements.
 184    */
 185   readonly taskStatisticsRequirements: TaskStatisticsRequirements
 186   /**
 187    * Resets strategy internals.
 188    *
 189    * @returns `true` if the reset is successful, `false` otherwise.
 190    */
 191   readonly reset: () => boolean
 192   /**
 193    * Updates the worker node key strategy internals.
 194    * This is called after a task has been executed on a worker node.
 195    *
 196    * @returns `true` if the update is successful, `false` otherwise.
 197    */
 198   readonly update: (workerNodeKey: number) => boolean
 199   /**
 200    * Chooses a worker node in the pool and returns its key.
 201    * If no worker nodes are not eligible, `undefined` is returned.
 202    * If `undefined` is returned, the caller retry.
 203    *
 204    * @returns The worker node key or `undefined`.
 205    */
 206   readonly choose: () => number | undefined
 207   /**
 208    * Removes the worker node key from strategy internals.
 209    *
 210    * @param workerNodeKey - The worker node key.
 211    * @returns `true` if the worker node key is removed, `false` otherwise.
 212    */
 213   readonly remove: (workerNodeKey: number) => boolean
 214   /**
 215    * Sets the worker choice strategy options.
 216    *
 217    * @param opts - The worker choice strategy options.
 218    */
 219   readonly setOptions: (opts: WorkerChoiceStrategyOptions) => void
 220   /**
 221    * Whether the pool has worker nodes ready or not.
 222    *
 223    * @returns Whether the pool has worker nodes ready or not.
 224    */
 225   readonly hasPoolWorkerNodesReady: () => boolean
 226 }