pub struct InputMailbox { /* private fields */ }Expand description
Thread-safe FIFO input storage with target-selective atomic claims.
§Conservation
A batch a Run claims from a Session’s mailbox ends in exactly one of three
states: committed to that Session’s transcript, refused by an
InputAdmitDecision::Reject, or —
when its admission ends any other way, including cancellation, a hook
contract error, a pre-commit transcript failure, or a panic — restored to
this mailbox in its original enqueue position, unrewritten, for a later
eligible boundary or a successor Run to claim. While an admission is in
flight the batch is in none of those places, so a concurrent
len, drain or claim may
briefly not see it; read the mailbox after the Run’s terminal is resolved to
observe the settled state. This public claim hands the batch
over outright and restores nothing.
§Panics
Every method here propagates a poisoned queue lock rather than recovering it,
per the crate-level lock-poisoning contract. Nothing a
caller passes can cause that: the queue holds owned InputBatch values and
no foreign code runs under the lock.
Implementations§
Source§impl InputMailbox
impl InputMailbox
Sourcepub fn new() -> Self
pub fn new() -> Self
Creates an empty mailbox attached to no Session.
This is for a composition layer assembling its own queue — a test double,
or a staging buffer drained into a real inbox later. It is not how you
reach a running Run: Session::input_mailbox returns a handle onto the
Session’s own queue, and a mailbox built here shares nothing with it, so
pushing to one succeeds and is never claimed by anybody.
Sourcepub fn push(&self, batch: InputBatch)
pub fn push(&self, batch: InputBatch)
Moves one already-frozen owned batch into global FIFO order.
§Panics
If the queue lock is poisoned, as the mailbox’s panic conditions describe.
Sourcepub fn claim(&self, target: InputTarget) -> Option<InputBatch>
pub fn claim(&self, target: InputTarget) -> Option<InputBatch>
Atomically removes the oldest batch for target without reordering peers.
The batch is handed over outright: a caller that claims it owns it, and the mailbox does not take it back. The conservation guarantee in the type-level documentation is about the claims a Run makes, not this one.
§Panics
If the queue lock is poisoned, as the mailbox’s panic conditions describe.
Sourcepub fn drain(&self) -> Vec<InputBatch>
pub fn drain(&self) -> Vec<InputBatch>
Atomically removes every currently queued batch in FIFO order.
§Panics
If the queue lock is poisoned, as the mailbox’s panic conditions describe.
Sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the number of queued batches at one lock linearization point.
§Panics
If the queue lock is poisoned, as the mailbox’s panic conditions describe.
Sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Reports whether the mailbox is empty at one lock linearization point.
§Panics
If the queue lock is poisoned, as the mailbox’s panic conditions describe.
Trait Implementations§
Source§impl Clone for InputMailbox
impl Clone for InputMailbox
Source§impl Debug for InputMailbox
impl Debug for InputMailbox
Source§fn fmt(&self, formatter: &mut Formatter<'_>) -> Result
fn fmt(&self, formatter: &mut Formatter<'_>) -> Result
Reports the queue depth at one non-blocking observation.
The mailbox is the session’s only concurrent write entry point, so a formatter that waited for the queue lock could stall the very producer it is describing. On contention it says so rather than guessing.