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    * @experimental
  40    */
  41   INTERLEAVED_WEIGHTED_ROUND_ROBIN: 'INTERLEAVED_WEIGHTED_ROUND_ROBIN',
  42 } as const)
  43
  44 /**
  45  * Worker choice strategy.
  46  */
  47 export type WorkerChoiceStrategy = keyof typeof WorkerChoiceStrategies
  48
  49 /**
  50  * Enumeration of measurements.
  51  */
  52 export const Measurements: Readonly<{
  53   runTime: 'runTime'
  54   waitTime: 'waitTime'
  55   elu: 'elu'
  56 }> = Object.freeze({
  57   runTime: 'runTime',
  58   waitTime: 'waitTime',
  59   elu: 'elu',
  60 } as const)
  61
  62 /**
  63  * Measurement.
  64  */
  65 export type Measurement = keyof typeof Measurements
  66
  67 /**
  68  * Measurement options.
  69  */
  70 export interface MeasurementOptions {
  71   /**
  72    * Set measurement median.
  73    */
  74   readonly median: boolean
  75 }
  76
  77 /**
  78  * Worker choice strategy options.
  79  */
  80 export interface WorkerChoiceStrategyOptions {
  81   /**
  82    * Measurement to use in worker choice strategy supporting it.
  83    */
  84   readonly measurement?: Measurement
  85   /**
  86    * Runtime options.
  87    * @defaultValue \{ median: false \}
  88    */
  89   readonly runTime?: MeasurementOptions
  90   /**
  91    * Wait time options.
  92    * @defaultValue \{ median: false \}
  93    */
  94   readonly waitTime?: MeasurementOptions
  95   /**
  96    * Event loop utilization options.
  97    * @defaultValue \{ median: false \}
  98    */
  99   readonly elu?: MeasurementOptions
 100   /**
 101    * Worker weights to use for weighted round robin worker selection strategies.
 102    * A weight is tasks maximum execution time in milliseconds for a worker node.
 103    * @defaultValue Weights computed automatically given the CPU performance.
 104    */
 105   weights?: Record<number, number>
 106 }
 107
 108 /**
 109  * Measurement statistics requirements.
 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  * @internal
 130  */
 131 export interface TaskStatisticsRequirements {
 132   /**
 133    * Tasks runtime requirements.
 134    */
 135   readonly runTime: MeasurementStatisticsRequirements
 136   /**
 137    * Tasks wait time requirements.
 138    */
 139   readonly waitTime: MeasurementStatisticsRequirements
 140   /**
 141    * Tasks event loop utilization requirements.
 142    */
 143   readonly elu: MeasurementStatisticsRequirements
 144 }
 145
 146 /**
 147  * Strategy policy.
 148  * @internal
 149  */
 150 export interface StrategyPolicy {
 151   /**
 152    * Expects tasks execution on the newly created dynamic worker.
 153    */
 154   readonly dynamicWorkerUsage: boolean
 155   /**
 156    * Expects the newly created dynamic worker to be flagged as ready.
 157    */
 158   readonly dynamicWorkerReady: boolean
 159 }
 160
 161 /**
 162  * Worker choice strategy interface.
 163  * @internal
 164  */
 165 export interface IWorkerChoiceStrategy {
 166   /**
 167    * Strategy policy.
 168    */
 169   readonly strategyPolicy: StrategyPolicy
 170   /**
 171    * Tasks statistics requirements.
 172    */
 173   readonly taskStatisticsRequirements: TaskStatisticsRequirements
 174   /**
 175    * Resets strategy internals.
 176    * @returns `true` if the reset is successful, `false` otherwise.
 177    */
 178   readonly reset: () => boolean
 179   /**
 180    * Updates the worker node key strategy internals.
 181    * This is called after a task has been executed on a worker node.
 182    * @returns `true` if the update is successful, `false` otherwise.
 183    */
 184   readonly update: (workerNodeKey: number) => boolean
 185   /**
 186    * Chooses a worker node in the pool and returns its key.
 187    * If no worker nodes are not eligible, `undefined` is returned.
 188    * If `undefined` is returned, the caller retry.
 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    * @param workerNodeKey - The worker node key.
 195    * @returns `true` if the worker node key is removed, `false` otherwise.
 196    */
 197   readonly remove: (workerNodeKey: number) => boolean
 198   /**
 199    * Sets the worker choice strategy options.
 200    * @param opts - The worker choice strategy options.
 201    */
 202   readonly setOptions: (opts: WorkerChoiceStrategyOptions | undefined) => void
 203 }