@nxtedition/scheduler 2.0.3 → 3.0.0

package/lib/index.d.ts

@@ -1,24 +1,29 @@
+export type Priority = -3 | -2 | -1 | 0 | 1 | 2 | 3 | 'lowest' | 'lower' | 'low' | 'normal' | 'high' | 'higher' | 'highest';
+export declare function parsePriority(p: Priority | string | number): number;
 export declare class Scheduler {
     #private;
-    static LOW: 0;
-    static NORMAL: 1;
-    static HIGH: 2;
+    static LOWEST: Priority;
+    static LOWER: Priority;
+    static LOW: Priority;
+    static NORMAL: Priority;
+    static HIGH: Priority;
+    static HIGHER: Priority;
+    static HIGHEST: Priority;
     get concurrency(): number;
     get stats(): {
         deferred: number;
         running: number;
         pending: number;
-        lowCount: number;
-        normalCount: number;
-        highCount: number;
-        lowLimit: number;
-        normalLimit: number;
-        highLimit: number;
+        queues: {
+            count: number;
+            age: number;
+        }[];
     };
     static makeSharedState(concurrency: number): SharedArrayBuffer;
     constructor(opts: SharedArrayBuffer | {
         concurrency?: number;
     });
-    acquire(fn: (opaque?: any) => any, priority?: 0 | 1 | 2 | 'low' | 'normal' | 'high', opaque?: any): any;
+    run<T, U>(fn: (opaque?: U) => Promise<T> | T, priority?: Priority, opaque?: U): Promise<T>;
+    acquire<U>(fn: (opaque?: U) => unknown, priority?: Priority, opaque?: U): void;
     release(): void;
 }

package/lib/index.js

@@ -1,17 +1,76 @@
 const RUNNING_INDEX = 0
 const CONCURRENCY_INDEX = 1
 
+const maxInt = 2147483647
+
+let fastNow = Date.now()
+setInterval(() => {
+  fastNow = Date.now()
+}, 1e3).unref()
+
 class FastQueue {
   idx = 0
   cnt = 0
   arr                        = []
-  lim = 0
+  age = fastNow
+}
+
+                      
+      
+      
+      
+     
+     
+     
+     
+            
+           
+         
+            
+          
+            
+             
+
+export function parsePriority(p                            )         {
+  if (typeof p === 'number') {
+    // Do nothing...
+  } else if (p === 'lowest') {
+    return -3
+  } else if (p === 'lower') {
+    return -2
+  } else if (p === 'low') {
+    return -1
+  } else if (p === 'normal') {
+    return 0
+  } else if (p === 'high') {
+    return 1
+  } else if (p === 'higher') {
+    return 2
+  } else if (p === 'highest') {
+    return 3
+  } else {
+    p = Number(p)
+  }
+
+  if (typeof p !== 'number') {
+    return 0
+  } else if (p < -3) {
+    return -3
+  } else if (p > 3) {
+    return 3
+  } else {
+    return Math.trunc(p)
+  }
 }
 
 export class Scheduler {
-  static LOW    = 0
-  static NORMAL    = 1
-  static HIGH    = 2
+  static LOWEST           = -3
+  static LOWER           = -2
+  static LOW           = -1
+  static NORMAL           = 0
+  static HIGH           = 1
+  static HIGHER           = 2
+  static HIGHEST           = 3
 
   #concurrency
   #stateView
@@ -22,9 +81,15 @@ export class Scheduler {
   #releasing = false
   #deferred = 0
 
-  #lowQueue = new FastQueue()
-  #normalQueue = new FastQueue()
-  #highQueue = new FastQueue()
+  #queues = [
+    new FastQueue(), // 0 lowest
+    new FastQueue(), // 1 lower
+    new FastQueue(), // 2 low
+    new FastQueue(), // 3 normal
+    new FastQueue(), // 4 high
+    new FastQueue(), // 5 higher
+    new FastQueue(), // 6 highest
+  ]
 
   get concurrency() {
     return this.#concurrency
@@ -35,12 +100,7 @@ export class Scheduler {
       deferred: this.#deferred,
       running: this.#running,
       pending: this.#pending,
-      lowCount: this.#lowQueue.cnt,
-      normalCount: this.#normalQueue.cnt,
-      highCount: this.#highQueue.cnt,
-      lowLimit: this.#lowQueue.lim,
-      normalLimit: this.#normalQueue.lim,
-      highLimit: this.#highQueue.lim,
+      queues: this.#queues.map((q) => ({ count: q.cnt, age: q.age })),
     }
   }
 
@@ -61,58 +121,54 @@ export class Scheduler {
     } else {
       this.#concurrency = opts?.concurrency || Infinity
     }
-
-    this.#lowQueue.lim = this.#concurrency / 4
-    this.#normalQueue.lim = this.#concurrency - this.#lowQueue.lim
-    this.#highQueue.lim = this.#concurrency
   }
 
-  acquire(
-    fn                       ,
-    priority                                        = Scheduler.NORMAL,
-    opaque      ,
-  ) {
-    if (typeof priority === 'number' && Number.isInteger(priority) && priority >= 0) {
-      // Do nothing
-    } else if (priority == null) {
-      priority = Scheduler.NORMAL
-    } else if (typeof priority === 'string') {
-      if (priority === 'low') {
-        priority = Scheduler.LOW
-      } else if (priority === 'normal') {
-        priority = Scheduler.NORMAL
-      } else if (priority === 'high') {
-        priority = Scheduler.HIGH
-      } else {
-        throw new Error('Invalid priority')
-      }
-    } else {
-      throw new Error('Invalid priority')
-    }
+  run      (
+    fn                                ,
+    priority = Scheduler.NORMAL,
+    opaque    ,
+  )             {
+    return new Promise   ((resolve, reject) => {
+      this.acquire(
+        async (o) => {
+          try {
+            resolve(await fn(o))
+          } catch (err) {
+            reject(err)
+          } finally {
+            this.release()
+          }
+        },
+        priority,
+        opaque,
+      )
+    })
+  }
 
-    let queue
-    if (priority > Scheduler.NORMAL) {
-      queue = this.#highQueue
-    } else if (priority < Scheduler.NORMAL) {
-      queue = this.#lowQueue
-    } else {
-      queue = this.#normalQueue
-    }
+  acquire   (fn                         , priority           = Scheduler.NORMAL, opaque    )       {
+    const p = parsePriority(priority)          
+    const queue = this.#queues[p + 3]
 
     if (this.#stateView) {
-      if (this.#running < 1 || this.#stateView[RUNNING_INDEX] < queue.lim) {
+      if (this.#running < 1 || this.#stateView[RUNNING_INDEX] < this.#concurrency) {
         Atomics.add(this.#stateView, RUNNING_INDEX, 1)
         this.#running += 1
-        return fn(opaque)
+        fn(opaque)
+        return
       }
-    } else if (this.#running < 1 || this.#running < queue.lim) {
+    } else if (this.#running < 1 || this.#running < this.#concurrency) {
       this.#running += 1
-      return fn(opaque)
+      fn(opaque)
+      return
     }
 
     queue.arr.push(fn, opaque)
     queue.cnt += 1
 
+    if (queue.cnt === 1) {
+      queue.age = fastNow
+    }
+
     this.#deferred += 1
     this.#pending += 1
   }
@@ -130,30 +186,47 @@ export class Scheduler {
     try {
       this.#releasing = true
       while (this.#pending > 0) {
-        let queue
-        if (this.#highQueue.cnt > 0) {
-          queue = this.#highQueue
-        } else if (this.#normalQueue.cnt > 0) {
-          queue = this.#normalQueue
-        } else if (this.#lowQueue.cnt > 0) {
-          queue = this.#lowQueue
-        } else {
+        let queue                   = null
+
+        // Avoid starvation by randomizing the starting queue.
+
+        let idx = 6 // highest: 50%
+        if (this.#counter & 0b0000010) {
+          idx = 5 // higher: 25%
+        } else if (this.#counter & 0b0000100) {
+          idx = 4 // high: 12.5%
+        } else if (this.#counter & 0b0001000) {
+          idx = 3 // normal: 6.25%
+        } else if (this.#counter & 0b0010000) {
+          idx = 2 // low: 3.125%
+        } else if (this.#counter & 0b0100000) {
+          idx = 1 // lower: 1.5625%
+        } else if (this.#counter & 0b1000000) {
+          idx = 0 // lowest: 0.78%
+        }
+
+        for (let n = idx; n >= 0 && (queue == null || queue.cnt === 0); n--) {
+          queue = this.#queues[n]
+        }
+
+        for (let n = 6; n > idx && (queue == null || queue.cnt === 0); n--) {
+          queue = this.#queues[n]
+        }
+
+        if (queue == null || queue.cnt === 0) {
           throw new Error('Invariant violation: pending > 0 but no tasks in queues')
         }
 
-        if (this.#running > 0 && running >= queue.lim) {
+        if (this.#running > 0 && running >= this.#concurrency) {
           break
         }
 
-        if ((this.#counter & 63) === 0 && this.#lowQueue.cnt > 0) {
-          queue = this.#lowQueue
-        } else if ((this.#counter & 15) === 0 && this.#normalQueue.cnt > 0) {
-          queue = this.#normalQueue
-        }
+        this.#counter = (this.#counter + 1) & maxInt
 
         const fn = queue.arr[queue.idx++]
         const opaque = queue.arr[queue.idx++]
         queue.cnt -= 1
+        queue.age = fastNow
 
         if (queue.cnt === 0) {
           queue.idx = 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/scheduler",
-  "version": "2.0.3",
+  "version": "3.0.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -20,5 +20,5 @@
     "rimraf": "^6.1.2",
     "typescript": "^5.9.3"
   },
-  "gitHead": "c9cfc87959862c94ed18d15b6090eff035ed271a"
+  "gitHead": "dc18f1fb0cf53929205b2de3cb53c08b631a4a9d"
 }