Module mailbox 

Bounded message queue with caller-managed overflow.

Architecture

The mailbox is split into two queues: a bounded ready queue that producers push to and the receiver pops from, and an unbounded overflow queue that holds messages displaced when ready is full. A Policy or UnreliablePolicy decides how overflow is updated when overflow is contended.

                         senders
                            |
        +-------------------+--------------------+
        | overflow inactive                      | overflow active
        | and ready has room                     | or ready full
        v                                        v
    +----------+    refill front-to-back     +----------+
    |  ready   |<----------------------------| overflow |
    +----------+    after each ready pop     +----------+
        |
        | pop first
        v
     receiver

The receiver always pops from the ready queue first. After each ready pop, it eagerly refills ready from published overflow so senders can return to the ready fast path without waiting for ready to drain completely. Overflow is refilled from front to back, but policies decide which overflow messages are retained and in what order.

Overflow should be rare. When overflow is populated, the receiver refills ready immediately instead of waiting to batch refill work. This can take the overflow lock once per popped message, but it keeps ready capacity available for later sends as soon as possible.

Ordering

Enqueue calls from the same sender will be delivered in order. Concurrent enqueue calls, however, are not globally ordered and may be observed in any interleaving.

Structs

Receiver

Receiver half of a mailbox.

Sender

Sender half of a mailbox.

UnreliableReceiver

Receiver half of an unreliable mailbox.

UnreliableSender

Sender half of an unreliable mailbox.

Traits

Overflow

Retained overflow messages for a mailbox policy.

Policy

Overflow behavior for actor messages when an inbox is full.

UnreliablePolicy

Overflow behavior for actor messages that can be rejected when an inbox is full.

Functions

new

Create a new bounded mailbox.

new_unreliable

Create a new bounded unreliable mailbox.