@nxtedition/scheduler 1.0.8 → 2.0.2

package/lib/index.d.ts

@@ -4,9 +4,21 @@ export declare class Scheduler {
     static NORMAL: 1;
     static HIGH: 2;
     get concurrency(): number;
-    static makeSharedState(concurrency?: number): SharedArrayBuffer;
-    constructor(opts?: SharedArrayBuffer | {
+    get stats(): {
+        deferred: number;
+        running: number;
+        pending: number;
+        lowCount: number;
+        normalCount: number;
+        highCount: number;
+        lowLimit: number;
+        normalLimit: number;
+        highLimit: number;
+    };
+    static makeSharedState(concurrency: number): SharedArrayBuffer;
+    constructor(opts: SharedArrayBuffer | {
         concurrency?: number;
     });
-    schedule(fn: (next: Function) => any, priority?: 0 | 1 | 2 | 'low' | 'normal' | 'high'): any;
+    acquire(fn: (opaque?: any) => any, priority?: 0 | 1 | 2 | 'low' | 'normal' | 'high', opaque?: any): any;
+    release(): void;
 }

package/lib/index.js

@@ -1,4 +1,12 @@
-import { FixedQueue } from './fixed-queue.js'
+const RUNNING_INDEX = 0
+const CONCURRENCY_INDEX = 1
+
+class FastQueue {
+  idx = 0
+  cnt = 0
+  arr                        = []
+  lim = 0
+}
 
 export class Scheduler {
   static LOW    = 0
@@ -8,51 +16,65 @@ export class Scheduler {
   #concurrency
   #stateView
 
-  static #RUNNING_INDEX = 0
-  static #COUNTER_INDEX = 1
-  static #CONCURRENCY_INDEX = 2
-
   #running = 0
   #pending = 0
   #counter = 0
-  #actived = false
+  #releasing = false
+  #deferred = 0
 
-  #lowQueue = new FixedQueue()
-  #normalQueue = new FixedQueue()
-  #highQueue = new FixedQueue()
+  #lowQueue = new FastQueue()
+  #normalQueue = new FastQueue()
+  #highQueue = new FastQueue()
 
   get concurrency() {
     return this.#concurrency
   }
 
-  static makeSharedState(concurrency         = 0) {
-    if (concurrency < 0 || !Number.isInteger(concurrency)) {
+  get stats() {
+    return {
+      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,
+    }
+  }
+
+  static makeSharedState(concurrency        ) {
+    if (concurrency != null && (concurrency < 0 || !Number.isInteger(concurrency))) {
       throw new Error('Invalid concurrency')
     }
     const stateBuffer = new SharedArrayBuffer(64)
     const stateView = new Uint32Array(stateBuffer)
-    Atomics.store(stateView, Scheduler.#CONCURRENCY_INDEX, concurrency ?? 0)
+    Atomics.store(stateView, CONCURRENCY_INDEX, concurrency ?? 0)
     return stateBuffer
   }
 
-  constructor(opts                                               = {}) {
+  constructor(opts                                              ) {
     if (opts instanceof SharedArrayBuffer) {
       this.#stateView = new Uint32Array(opts)
-      this.#concurrency = Atomics.load(this.#stateView, Scheduler.#CONCURRENCY_INDEX)
+      this.#concurrency = Atomics.load(this.#stateView, CONCURRENCY_INDEX) || Infinity
     } else {
-      this.#concurrency = opts?.concurrency ?? 0
+      this.#concurrency = opts?.concurrency || Infinity
     }
+
+    this.#lowQueue.lim = this.#concurrency / 4
+    this.#normalQueue.lim = this.#concurrency - this.#lowQueue.lim
+    this.#highQueue.lim = this.#concurrency
   }
 
-  schedule(
-    fn                         ,
+  acquire(
+    fn                       ,
     priority                                        = Scheduler.NORMAL,
+    opaque      ,
   ) {
-    if (typeof fn !== 'function') {
-      throw new TypeError('First argument must be a function')
-    }
-
-    if (priority == null) {
+    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') {
@@ -64,63 +86,93 @@ export class Scheduler {
       } else {
         throw new Error('Invalid priority')
       }
-    } else if (!Number.isInteger(priority)) {
+    } else {
       throw new Error('Invalid priority')
     }
 
-    const running = this.#stateView
-      ? Atomics.load(this.#stateView, Scheduler.#RUNNING_INDEX)
-      : this.#running
+    let queue
+    if (priority > Scheduler.NORMAL) {
+      queue = this.#highQueue
+    } else if (priority < Scheduler.NORMAL) {
+      queue = this.#lowQueue
+    } else {
+      queue = this.#normalQueue
+    }
 
-    if (this.#running < 1 || running < this.#concurrency) {
-      if (this.#stateView) {
-        Atomics.add(this.#stateView, Scheduler.#RUNNING_INDEX, 1)
+    if (this.#stateView) {
+      if (this.#running < 1 || this.#stateView[RUNNING_INDEX] < queue.lim) {
+        Atomics.add(this.#stateView, RUNNING_INDEX, 1)
+        this.#running += 1
+        return fn(opaque)
       }
+    } else if (this.#running < 1 || this.#running < queue.lim) {
       this.#running += 1
-      return fn(this.#next)
+      return fn(opaque)
     }
 
-    if (priority > Scheduler.NORMAL) {
-      this.#highQueue.push(fn)
-    } else if (priority < Scheduler.NORMAL) {
-      this.#lowQueue.push(fn)
-    } else {
-      this.#normalQueue.push(fn)
-    }
+    queue.arr.push(fn, opaque)
+    queue.cnt += 1
+
+    this.#deferred += 1
     this.#pending += 1
   }
 
-  #next = () => {
-    try {
-      let running = this.#stateView
-        ? Atomics.sub(this.#stateView, Scheduler.#RUNNING_INDEX, 1) - 1
-        : this.#running - 1
-      this.#running -= 1
+  release() {
+    let running = this.#stateView
+      ? Atomics.sub(this.#stateView, RUNNING_INDEX, 1) - 1
+      : this.#running - 1
+    this.#running -= 1
 
-      if (this.#actived) {
-        return
-      }
+    if (this.#pending === 0 || this.#releasing) {
+      return
+    }
 
-      this.#actived = true
-      while (this.#pending > 0 && (this.#running < 1 || running < this.#concurrency)) {
-        const counter = this.#stateView
-          ? Atomics.add(this.#stateView, Scheduler.#COUNTER_INDEX, 1)
-          : this.#counter++
-        const fn =
-          ((counter & 63) === 0 && this.#lowQueue.shift()) ||
-          ((counter & 15) === 0 && this.#normalQueue.shift()) ||
-          this.#highQueue.shift() ||
-          this.#normalQueue.shift() ||
-          this.#lowQueue.shift()
+    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 {
+          throw new Error('Invariant violation: pending > 0 but no tasks in queues')
+        }
+
+        if (this.#running > 0 && running >= queue.lim) {
+          break
+        }
+
+        if ((this.#counter & 63) === 0) {
+          queue = this.#lowQueue
+        } else if ((this.#counter & 15) === 0) {
+          queue = this.#normalQueue
+        }
+
+        const fn = queue.arr[queue.idx++]
+        const opaque = queue.arr[queue.idx++]
+        queue.cnt -= 1
+
+        if (queue.cnt === 0) {
+          queue.idx = 0
+          queue.arr.length = 0
+        } else if (queue.idx > 1024) {
+          queue.arr.splice(0, queue.idx)
+          queue.idx = 0
+        }
 
         running = this.#stateView
-          ? Atomics.add(this.#stateView, Scheduler.#RUNNING_INDEX, 1) + 1
+          ? Atomics.add(this.#stateView, RUNNING_INDEX, 1) + 1
           : this.#running + 1
-        this.#running += 1
+
+        this.#counter += 1
         this.#pending -= 1
-        fn(this.#next)
+        this.#running += 1
+        fn(opaque)
       }
-      this.#actived = false
+      this.#releasing = false
     } catch (err) {
       // Throwing here is undefined behavior...
       queueMicrotask(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/scheduler",
-  "version": "1.0.8",
+  "version": "2.0.2",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -9,7 +9,7 @@
   ],
   "license": "UNLICENSED",
   "scripts": {
-    "build": "rimraf lib && tsc && amaroc ./src/index.ts && mv src/index.js lib/ && cp src/fixed-queue.js lib/",
+    "build": "rimraf lib && tsc && amaroc ./src/index.ts && mv src/index.js lib/",
     "prepublishOnly": "yarn build",
     "typecheck": "tsc --noEmit",
     "test": "node --test",
@@ -20,5 +20,5 @@
     "rimraf": "^6.1.2",
     "typescript": "^5.9.3"
   },
-  "gitHead": "ba7f0417c8dbf2a8d6e38f5848f5e8ec162f4eb7"
+  "gitHead": "ee95b62bb1f5bc494fa4fcff603f5a44b44723ac"
 }

package/lib/fixed-queue.d.ts

@@ -1,8 +0,0 @@
-export class FixedQueue {
-    head: any;
-    tail: any;
-    size: number;
-    isEmpty(): any;
-    push(data: any): void;
-    shift(): any;
-}

package/lib/fixed-queue.js

@@ -1,123 +0,0 @@
-// Extracted from node/lib/internal/fixed_queue.js
-
-// Currently optimal queue size, tested on V8 6.0 - 6.6. Must be power of two.
-const kSize = 2048
-const kMask = kSize - 1
-
-// The FixedQueue is implemented as a singly-linked list of fixed-size
-// circular buffers. It looks something like this:
-//
-//  head                                                       tail
-//    |                                                          |
-//    v                                                          v
-// +-----------+ <-----\       +-----------+ <------\         +-----------+
-// |  [null]   |        \----- |   next    |         \------- |   next    |
-// +-----------+               +-----------+                  +-----------+
-// |   item    | <-- bottom    |   item    | <-- bottom       |  [empty]  |
-// |   item    |               |   item    |                  |  [empty]  |
-// |   item    |               |   item    |                  |  [empty]  |
-// |   item    |               |   item    |                  |  [empty]  |
-// |   item    |               |   item    |       bottom --> |   item    |
-// |   item    |               |   item    |                  |   item    |
-// |    ...    |               |    ...    |                  |    ...    |
-// |   item    |               |   item    |                  |   item    |
-// |   item    |               |   item    |                  |   item    |
-// |  [empty]  | <-- top       |   item    |                  |   item    |
-// |  [empty]  |               |   item    |                  |   item    |
-// |  [empty]  |               |  [empty]  | <-- top  top --> |  [empty]  |
-// +-----------+               +-----------+                  +-----------+
-//
-// Or, if there is only one circular buffer, it looks something
-// like either of these:
-//
-//  head   tail                                 head   tail
-//    |     |                                     |     |
-//    v     v                                     v     v
-// +-----------+                               +-----------+
-// |  [null]   |                               |  [null]   |
-// +-----------+                               +-----------+
-// |  [empty]  |                               |   item    |
-// |  [empty]  |                               |   item    |
-// |   item    | <-- bottom            top --> |  [empty]  |
-// |   item    |                               |  [empty]  |
-// |  [empty]  | <-- top            bottom --> |   item    |
-// |  [empty]  |                               |   item    |
-// +-----------+                               +-----------+
-//
-// Adding a value means moving `top` forward by one, removing means
-// moving `bottom` forward by one. After reaching the end, the queue
-// wraps around.
-//
-// When `top === bottom` the current queue is empty and when
-// `top + 1 === bottom` it's full. This wastes a single space of storage
-// but allows much quicker checks.
-
-class FixedCircularBuffer {
-  constructor() {
-    this.bottom = 0
-    this.top = 0
-    this.list = new Array(kSize).fill(undefined)
-    this.next = null
-  }
-
-  isEmpty() {
-    return this.top === this.bottom
-  }
-
-  isFull() {
-    return ((this.top + 1) & kMask) === this.bottom
-  }
-
-  push(data) {
-    this.list[this.top] = data
-    this.top = (this.top + 1) & kMask
-  }
-
-  shift() {
-    const nextItem = this.list[this.bottom]
-    if (nextItem === undefined) {
-      return null
-    }
-    this.list[this.bottom] = undefined
-    this.bottom = (this.bottom + 1) & kMask
-    return nextItem
-  }
-}
-
-const POOL = []
-
-export class FixedQueue {
-  constructor() {
-    this.head = this.tail = POOL.pop() ?? new FixedCircularBuffer()
-    this.size = 0
-  }
-
-  isEmpty() {
-    return this.head.isEmpty()
-  }
-
-  push(data) {
-    if (this.head.isFull()) {
-      // Head is full: Creates a new queue, sets the old queue's `.next` to it,
-      // and sets it as the new main queue.
-      this.head = this.head.next = POOL.pop() ?? new FixedCircularBuffer()
-    }
-    this.head.push(data)
-  }
-
-  shift() {
-    const tail = this.tail
-    const next = tail.shift()
-    if (tail.isEmpty() && tail.next !== null) {
-      // If there is another queue, it forms the new tail.
-      this.tail = tail.next
-      tail.next = null
-      tail.bottom = 0
-      tail.top = 0
-      if (POOL.length < 64) {
-        POOL.push(tail)
-      }
-    }
-    return next
-  }
-}