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    * Number of worker choice retries to perform if no worker is eligible.
  72    *
  73    * @defaultValue 6
  74    */
  75   readonly choiceRetries?: number
  76   /**
  77    * Measurement to use in worker choice strategy supporting it.
  78    */
  79   readonly measurement?: Measurement
  80   /**
  81    * Runtime options.
  82    *
  83    * @defaultValue \{ median: false \}
  84    */
  85   readonly runTime?: MeasurementOptions
  86   /**
  87    * Wait time options.
  88    *
  89    * @defaultValue \{ median: false \}
  90    */
  91   readonly waitTime?: MeasurementOptions
  92   /**
  93    * Event loop utilization options.
  94    *
  95    * @defaultValue \{ median: false \}
  96    */
  97   readonly elu?: MeasurementOptions
  98   /**
  99    * Worker weights to use for weighted round robin worker selection strategy.
 100    * Weight is the tasks maximum average or median runtime in milliseconds.
 101    *
 102    * @defaultValue Computed worker weights automatically given the CPU performance.
 103    */
 104   readonly weights?: Record<number, number>
 105 }
 106
 107 /**
 108  * Measurement statistics requirements.
 109  *
 110  * @internal
 111  */
 112 export interface MeasurementStatisticsRequirements {
 113   /**
 114    * Requires measurement aggregate.
 115    */
 116   aggregate: boolean
 117   /**
 118    * Requires measurement average.
 119    */
 120   average: boolean
 121   /**
 122    * Requires measurement median.
 123    */
 124   median: boolean
 125 }
 126
 127 /**
 128  * Pool worker node worker usage statistics requirements.
 129  *
 130  * @internal
 131  */
 132 export interface TaskStatisticsRequirements {
 133   /**
 134    * Tasks runtime requirements.
 135    */
 136   readonly runTime: MeasurementStatisticsRequirements
 137   /**
 138    * Tasks wait time requirements.
 139    */
 140   readonly waitTime: MeasurementStatisticsRequirements
 141   /**
 142    * Tasks event loop utilization requirements.
 143    */
 144   readonly elu: MeasurementStatisticsRequirements
 145 }
 146
 147 /**
 148  * Strategy policy.
 149  *
 150  * @internal
 151  */
 152 export interface StrategyPolicy {
 153   /**
 154    * Expects tasks execution on the newly created dynamic worker.
 155    */
 156   readonly dynamicWorkerUsage: boolean
 157   /**
 158    * Expects the newly created dynamic worker to be flagged as ready.
 159    */
 160   readonly dynamicWorkerReady: boolean
 161 }
 162
 163 /**
 164  * Worker choice strategy interface.
 165  *
 166  * @internal
 167  */
 168 export interface IWorkerChoiceStrategy {
 169   /**
 170    * Strategy policy.
 171    */
 172   readonly strategyPolicy: StrategyPolicy
 173   /**
 174    * Tasks statistics requirements.
 175    */
 176   readonly taskStatisticsRequirements: TaskStatisticsRequirements
 177   /**
 178    * Resets strategy internals.
 179    *
 180    * @returns `true` if the reset is successful, `false` otherwise.
 181    */
 182   readonly reset: () => boolean
 183   /**
 184    * Updates the worker node key strategy internals.
 185    *
 186    * @returns `true` if the update is successful, `false` otherwise.
 187    */
 188   readonly update: (workerNodeKey: number) => boolean
 189   /**
 190    * Chooses a worker node in the pool and returns its key.
 191    * If the worker node is not eligible, `undefined` is returned.
 192    *
 193    * @returns The worker node key or `undefined`.
 194    */
 195   readonly choose: () => number | undefined
 196   /**
 197    * Removes the worker node key from strategy internals.
 198    *
 199    * @param workerNodeKey - The worker node key.
 200    * @returns `true` if the worker node key is removed, `false` otherwise.
 201    */
 202   readonly remove: (workerNodeKey: number) => boolean
 203   /**
 204    * Sets the worker choice strategy options.
 205    *
 206    * @param opts - The worker choice strategy options.
 207    */
 208   readonly setOptions: (opts: WorkerChoiceStrategyOptions) => void
 209 }