Skip to content

[Feature] Ring-buffer backing store for Mailbox to remove O(n) shift() #408

Description

@pathosDev

Rationale

Mailbox user/system queues are plain arrays and dequeue via Array.shift() (src/internal/Mailbox.ts:51, 55) — O(n) at queue depth. At the default BoundedMailbox capacity of 10k a deep mailbox pays a substantial reindexing tax per message. prependUser uses spread-unshift (O(n+m), stack risk for very large batches), and the ThroughputDispatcher work queue also shift()s (src/Dispatcher.ts:82).

Scope

  • Circular head/tail ring buffer in the base Mailbox so BoundedMailbox inherits it (the default mailbox is the one that must get faster).
  • Amortized O(1) enqueue/dequeue; bulk prependUser without spread.
  • Same treatment for the ThroughputDispatcher queue.
  • New deep-queue benchmark case alongside the existing single-node benches.

Documentation

  • CHANGELOG entry (internal performance; no user-facing API change expected).

Acceptance

Relates

Improvement program M2. #27 (benchmarks), #407.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestpriority: highTop priority — high impact, plan nextproduction-goalBlocks or defines the path to production readiness

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions