Skip to main content

InputMailbox

Struct InputMailbox 

Source
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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for InputMailbox

Source§

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.

Source§

impl Default for InputMailbox

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.