timers: address PR review feedback

- Add hysteresis to prevent mode switching thrashing
  - Up threshold: n=10 (convert to heap)
  - Down threshold: n=6 (convert to linear)
  - Prevents oscillation around boundary

- Add comprehensive test suite (test/parallel/test-priority-queue-adaptive.js)
  - Basic operations (insert, shift, peek)
  - Mode switching behavior
  - Edge cases (empty queue, single element)
  - Custom comparators and setPosition callbacks
  - DOS attack pattern (10K oscillations)
  - Stress test (1000 random operations)

- Add statistical benchmark with variance reporting
  - Multiple trials for reproducibility
  - Reports stddev and coefficient of variation
  - Deterministic random pattern for consistency

- Fix linearShift() bug when removing last element
- Verify compatibility with timers.js call sites
- All tests pass

Author: kayossouza

benchmark/timers/priority-queue-statistical.js

@@ -0,0 +1,107 @@
+'use strict';
+
+// Statistical benchmark with variance/stddev reporting
+// Runs multiple trials to ensure reproducibility
+
+const common = require('../common.js');
+
+const bench = common.createBenchmark(main, {
+  queueSize: [5, 10, 20, 100, 1000, 10000],
+  impl: ['original', 'adaptive'],
+  trials: [10],
+});
+
+function createHeap(impl, comparator, setPosition) {
+  if (impl === 'original') {
+    const PriorityQueue = require('../../lib/internal/priority_queue');
+    return new PriorityQueue(comparator, setPosition);
+  } else if (impl === 'adaptive') {
+    const PriorityQueueAdaptive = require('../../lib/internal/priority_queue_adaptive');
+    return new PriorityQueueAdaptive(comparator, setPosition);
+  } else {
+    throw new Error(`Unknown implementation: ${impl}`);
+  }
+}
+
+function runTrial(queueSize, impl) {
+  const comparator = (a, b) => a.expiry - b.expiry;
+  const setPosition = (node, pos) => { node.pos = pos; };
+  const heap = createHeap(impl, comparator, setPosition);
+
+  // Initial queue state
+  const timers = [];
+  for (let i = 0; i < queueSize; i++) {
+    timers.push({
+      expiry: 1000 + i * 10000,
+      id: i,
+      pos: null,
+    });
+    heap.insert(timers[i]);
+  }
+
+  const iterations = 100000;
+  const startTime = process.hrtime.bigint();
+
+  for (let i = 0; i < iterations; i++) {
+    const op = (i % 100) / 100; // Deterministic pattern
+
+    if (op < 0.80) {
+      // 80% peek()
+      heap.peek();
+    } else if (op < 0.90) {
+      // 10% shift + insert
+      heap.shift();
+      const newTimer = {
+        expiry: 1000 + ((i * 12345) % 100000), // Deterministic random
+        id: i,
+        pos: null,
+      };
+      heap.insert(newTimer);
+    } else {
+      // 10% percolateDown
+      const min = heap.peek();
+      if (min) {
+        min.expiry += 100;
+        heap.percolateDown(1);
+      }
+    }
+  }
+
+  const endTime = process.hrtime.bigint();
+  const durationNs = Number(endTime - startTime);
+  const opsPerSec = (iterations / durationNs) * 1e9;
+
+  return opsPerSec;
+}
+
+function mean(values) {
+  return values.reduce((a, b) => a + b, 0) / values.length;
+}
+
+function stddev(values) {
+  const avg = mean(values);
+  const squareDiffs = values.map((value) => Math.pow(value - avg, 2));
+  const avgSquareDiff = mean(squareDiffs);
+  return Math.sqrt(avgSquareDiff);
+}
+
+function main({ queueSize, impl, trials }) {
+  const results = [];
+
+  // Run multiple trials
+  for (let i = 0; i < trials; i++) {
+    results.push(runTrial(queueSize, impl));
+  }
+
+  const avg = mean(results);
+  const std = stddev(results);
+  const cv = (std / avg) * 100; // Coefficient of variation
+
+  bench.start();
+  // Report mean as the primary metric
+  bench.end(avg);
+
+  // Log statistical info (will appear in benchmark output)
+  console.error(`n=${queueSize} impl=${impl}: ${avg.toFixed(0)} ops/sec ` +
+                `(stddev=${std.toFixed(0)}, cv=${cv.toFixed(2)}%)`);
+}

lib/internal/priority_queue_adaptive.js

@@ -18,7 +18,9 @@
 // holds TimersList objects (one per unique timeout duration), not individual
 // timers, resulting in small queue sizes even in large applications.
 
-const THRESHOLD = 10;
+// Hysteresis thresholds to prevent mode switching thrashing
+const HEAP_THRESHOLD = 10;      // Switch to heap when size reaches this
+const LINEAR_THRESHOLD = 6;     // Switch back to linear when size drops to this
 const D = 4; // D-ary branching factor
 
 module.exports = class PriorityQueueAdaptive {
@@ -50,7 +52,7 @@ module.exports = class PriorityQueueAdaptive {
     const size = this.#size;
 
     // Check if we need to convert to heap mode
-    if (!this.#isHeap && size >= THRESHOLD) {
+    if (!this.#isHeap && size >= HEAP_THRESHOLD) {
       this.#convertToHeap();
     }
 
@@ -66,8 +68,8 @@ module.exports = class PriorityQueueAdaptive {
 
     const result = this.#isHeap ? this.#heapShift() : this.#linearShift();
 
-    // Convert back to linear if size drops below threshold
-    if (this.#isHeap && this.#size < THRESHOLD) {
+    // Convert back to linear if size drops below lower threshold (hysteresis)
+    if (this.#isHeap && this.#size < LINEAR_THRESHOLD) {
       this.#convertToLinear();
     }
 
@@ -83,7 +85,7 @@ module.exports = class PriorityQueueAdaptive {
       this.#linearRemoveAt(pos);
     }
 
-    if (this.#isHeap && this.#size < THRESHOLD) {
+    if (this.#isHeap && this.#size < LINEAR_THRESHOLD) {
       this.#convertToLinear();
     }
   }
@@ -97,7 +99,7 @@ module.exports = class PriorityQueueAdaptive {
       heap[i] = array[i];
     }
 
-    if (len >= THRESHOLD) {
+    if (len >= HEAP_THRESHOLD) {
       this.#isHeap = true;
       this.#heapifyArray();
     } else {
@@ -159,13 +161,15 @@ module.exports = class PriorityQueueAdaptive {
     const minValue = heap[minPos];
     const lastPos = this.#size - 1;
 
-    if (minPos === lastPos) {
-      heap[lastPos] = undefined;
+    // If removing the last element, just clear it
+    if (lastPos === 0) {
+      heap[0] = undefined;
       this.#size = 0;
       this.#minPos = 0;
       return minValue;
     }
 
+    // Swap min with last element
     const lastValue = heap[lastPos];
     heap[minPos] = lastValue;
     heap[lastPos] = undefined;
@@ -174,6 +178,7 @@ module.exports = class PriorityQueueAdaptive {
     if (this.#setPosition !== undefined)
       this.#setPosition(lastValue, minPos);
 
+    // Find new minimum
     this.#updateMinPosition();
     return minValue;
   }