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  * Measurement statistics requirements.
 103  *
 104  * @internal
 105  */
 106 export interface MeasurementStatisticsRequirements {
 107   /**
 108    * Requires measurement aggregate.
 109    */
 110   aggregate: boolean
 111   /**
 112    * Requires measurement average.
 113    */
 114   average: boolean
 115   /**
 116    * Requires measurement median.
 117    */
 118   median: boolean
 119 }
 120
 121 /**
 122  * Pool worker node worker usage statistics requirements.
 123  *
 124  * @internal
 125  */
 126 export interface TaskStatisticsRequirements {
 127   /**
 128    * Tasks runtime requirements.
 129    */
 130   readonly runTime: MeasurementStatisticsRequirements
 131   /**
 132    * Tasks wait time requirements.
 133    */
 134   readonly waitTime: MeasurementStatisticsRequirements
 135   /**
 136    * Tasks event loop utilization requirements.
 137    */
 138   readonly elu: MeasurementStatisticsRequirements
 139 }
 140
 141 /**
 142  * Strategy policy.
 143  *
 144  * @internal
 145  */
 146 export interface StrategyPolicy {
 147   /**
 148    * Expects tasks execution on the newly created dynamic worker.
 149    */
 150   readonly dynamicWorkerUsage: boolean
 151   /**
 152    * Expects the newly created dynamic worker to be flagged as ready.
 153    */
 154   readonly dynamicWorkerReady: boolean
 155 }
 156
 157 /**
 158  * Worker choice strategy interface.
 159  *
 160  * @internal
 161  */
 162 export interface IWorkerChoiceStrategy {
 163   /**
 164    * Strategy policy.
 165    */
 166   readonly strategyPolicy: StrategyPolicy
 167   /**
 168    * Tasks statistics requirements.
 169    */
 170   readonly taskStatisticsRequirements: TaskStatisticsRequirements
 171   /**
 172    * Resets strategy internals.
 173    *
 174    * @returns `true` if the reset is successful, `false` otherwise.
 175    */
 176   readonly reset: () => boolean
 177   /**
 178    * Updates the worker node key strategy internals.
 179    * This is called after a task has been executed on a worker node.
 180    *
 181    * @returns `true` if the update is successful, `false` otherwise.
 182    */
 183   readonly update: (workerNodeKey: number) => boolean
 184   /**
 185    * Chooses a worker node in the pool and returns its key.
 186    * If no worker nodes are not eligible, `undefined` is returned.
 187    * If `undefined` is returned, the caller retry.
 188    *
 189    * @returns The worker node key or `undefined`.
 190    */
 191   readonly choose: () => number | undefined
 192   /**
 193    * Removes the worker node key from strategy internals.
 194    *
 195    * @param workerNodeKey - The worker node key.
 196    * @returns `true` if the worker node key is removed, `false` otherwise.
 197    */
 198   readonly remove: (workerNodeKey: number) => boolean
 199   /**
 200    * Sets the worker choice strategy options.
 201    *
 202    * @param opts - The worker choice strategy options.
 203    */
 204   readonly setOptions: (opts: WorkerChoiceStrategyOptions | undefined) => void
 205 }