RingBuffer

Defined in: src/util/RingBuffer.ts:39

A first-in-first-out queue whose removal from the front is O(1).

Array.prototype.shift() is O(n): it reindexes every remaining element. That is invisible on a queue of ten and quadratic on a queue of a hundred thousand — and since #1148 removed the default mailbox bound, an actor that falls behind its producers has no ceiling short of the heap. A deep mailbox was paying one memmove of the whole backlog per message delivered (#408).

This is the standard circular buffer: elements live in a fixed array between a moving head and head + count, both wrapping at the end, so removing the front advances an index instead of moving the payload. Growth doubles the array and re-lays the elements from index 0, which is the one O(n) step and happens log2(n) times — amortized O(1) per push.

Deliberately not a general-purpose deque. It carries exactly the five operations its callers need — push, shift, pop, unshiftAll and drain — because every extra one is another index-wrapping edge case, and this type sits on the message path of every actor in the system.

Type Parameters

T

T

Constructors

Constructor

new RingBuffer<T>(): RingBuffer<T>

Returns

RingBuffer<T>

Accessors

length

Get Signature

get length(): number

Defined in: src/util/RingBuffer.ts:57

Number of queued elements.

Returns

number

Methods

drain()

drain(): T[]

Defined in: src/util/RingBuffer.ts:128

Remove every element and return them in queue order.

Returns a fresh array rather than handing out the backing store: the ring is not a dense T[] and the caller must not see its holes or its wrap-around. The backing store is released too, so draining a queue that grew to a million entries gives the memory back instead of holding a million empty slots for an actor that is usually shutting down.

Returns

T[]

---

pop()

pop(): T | undefined

Defined in: src/util/RingBuffer.ts:89

Remove and return the back element, or undefined when empty. O(1).

The mirror of shift, and it exists for one caller: a bound that has to make room for something inserted at the front sheds at the back, because that is the end furthest from the arrival (#772). Without it a mailbox could only evict what it was about to deliver.

Returns

T | undefined

---

push()

push(item): void

Defined in: src/util/RingBuffer.ts:62

Append to the back. Amortized O(1).

Parameters

item

T

Returns

void

---

shift()

shift(): T | undefined

Defined in: src/util/RingBuffer.ts:69

Remove and return the front element, or undefined when empty. O(1).

Returns

T | undefined

---

unshiftAll()

unshiftAll(items): void

Defined in: src/util/RingBuffer.ts:109

Insert items at the FRONT, preserving their order relative to each other and placing all of them ahead of what is already queued.

One bulk move rather than n individual unshifts, and — unlike Array.prototype.unshift(...items) — no spread, so a stash replay of a thousand messages neither reindexes the backlog n times nor pushes a thousand arguments onto the call stack.

Parameters

items

readonly T[]

Returns

void