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