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

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