lib: optimize FixedQueue by reusing one segment

[gurgunday]

Benchmarks:

main:

node % ./node benchmark/run.js --filter fixed-queue util
util/fixed-queue-oscillate.js
util/fixed-queue-oscillate.js cycles=5000: 240,760,722.06068513
util/fixed-queue.js
util/fixed-queue.js n=100000: 30,605,608.47775355

branch:

node % ./node benchmark/run.js --filter fixed-queue util
util/fixed-queue-oscillate.js
util/fixed-queue-oscillate.js cycles=5000: 283,339,287.4243814
util/fixed-queue.js
util/fixed-queue.js n=100000: 32,606,927.0808029

When the head segment fills, we reuse a “spare” FixedCircularBuffer if available; when a segment becomes empty, we reset it and stash it as the spare instead of wasting it. This cuts allocations/GC especially when the queue oscillates between N and N+1 segments, which is more than likely to be the case in real life scenarios where Events/Promises/Tasks are emitted/created and consumed in bursts.

We only call reset() when reusing a spare (not for a freshly allocated buffer).

And finally, there is no behavior change: we have the same data structure (linked fixed-size circular buffers), same invariants (one-slot-wasted), same FIFO semantics and API. Capacity per segment stays kSize - 1, so overall capacity is unchanged.

[nodejs-github-bot]

Review requested:

• @nodejs/performance

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.46%. Comparing base (eda67ac) to head (c99a6c4).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #60031   +/-   ##
=======================================
  Coverage   88.45%   88.46%           
=======================================
  Files         703      703           
  Lines      207805   207821   +16     
  Branches    40022    40029    +7     
=======================================
+ Hits       183822   183848   +26     
+ Misses      15980    15961   -19     
- Partials     8003     8012    +9     

Files with missing lines	Coverage Δ
lib/internal/fixed_queue.js	100.00% <100.00%> (ø)

... and 45 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mcollina]

Great work! There are diagrams explaining this data structure at the top of the file that would need updating.

[gurgunday]

Great work! There are diagrams explaining this data structure at the top of the file that would need updating.

The new spare segment isn’t part of the list. It’s just a detached buffer we park for reuse once it's created, so it doesn’t really affect the diagrams. But nonetheless, I added a small paragraph to explain how it works.

Let me know if you'd like to see more explanation in the code!

[github-actions]

Failed to start CI

   ⚠  No approving reviews found
   ✘  Refusing to run CI on potentially unsafe PR

https://github.com/nodejs/node/actions/runs/18073218517

[gurgunday]

@mcollina PTAL

[RafaelGSS]

I wouldn't include this inside benchmark/util. I believe benchmark/internal would be more appropriate. To be fair, creating a benchmark for a public API that makes use of FixedQueue behind the scenes would be better.

[gurgunday]

Hey @RafaelGSS, I looked at the other benchmarks and unfortunately I would need to create something super targeted for this. And even then, it might be hard to see the difference indirectly

This is a specific improvement that only gets triggered if we reach segment N + 1, and cycle between N and N + 1

For the benchmark, I was inspired by the priority queue benchmark. If you prefer, I can remove benchmark/util/fixed-queue-oscillate.js

[lemire]

It is a tradeoff: using more memory but also getting more performance.

[gurgunday]

It is a tradeoff: using more memory but also getting more performance.

Yes, that's correct. It hinges on the idea that if we reach N+1 segments, there is a higher chance we will reach there again. But the good thing here is that we keep at max 1 extra spare segment. If 2 segments are empty (we're at N-1), segment N+1 will still be GC'd with its spare

[lemire]

@gurgunday Yes, to be clearer, my comment was tied with my approval of the PR.

[gurgunday]

I can't see an improvement in the next-tick or event.on benchmarks unfortunately