Struct Outbox 

pub struct Outbox<S: OutboxSink> { /* private fields */ }

The handle callers stage through; owns the queue and its writer task.

Implementations

impl<S: OutboxSink> Outbox<S>

pub fn new(sink: S, concurrency: usize, limits: OutboxLimits) -> Arc<Self>

Creates the outbox around sink and starts its writer.

concurrency is the most writes run at once across every tenant and lane, which bounds the connections the sink may hold; limits are the most items and bytes admitted at once, which bound the memory queued, waiting, retrying, and in-flight work may hold.

Panics

Panics when called outside a Tokio runtime, because the writer task is spawned immediately.

pub fn sink(&self) -> &S

Borrows the sink this outbox writes through.

pub fn stage(&self, tenant: DataTenantId, item: impl Into<S::Item>)

Queues one item for tenant without waiting and never fails.

The item is admitted and counted pending before it is sent, so the writer can never release it first. Admission happens under the queue’s read lock, so nothing is admitted once shutdown has taken the queue. When either unreserved limit would be passed the item is shed: counted lost with LossReason::Shed and recorded by Self::shed. Once shutdown has begun, or if the writer is gone, the item is counted lost with LossReason::Shutdown and logged.

pub fn reserve( self: &Arc<Self>, slots: usize, ) -> Result<Reservation<S>, OutboxFull>

Reserves slots items of capacity for a producer that must refuse its caller instead of losing what it stages.

The reservation is admitted at once and holds its slots until each is staged through it or it is dropped, which releases the unused rest. An item staged through it keeps its slot until it is written or lost. Unreserved items never count against reservations.

Errors

Returns OutboxFull, admitting nothing, when the reservation would take reservations past RESERVED_SHARE of the capacity.

pub async fn reserve_until( self: &Arc<Self>, slots: usize, deadline: Instant, ) -> Result<Reservation<S>, OutboxFull>

Reserves slots like Self::reserve, waiting until deadline for capacity instead of refusing at once.

Waiters are admitted in arrival order. Under one short lock a caller either reserves, when no one is waiting and the reservation fits, or joins the back of the queue; only a queued caller suspends, so callers that find capacity never wait on one another. Only the head of the queue reserves, retrying whenever admitted items or unspent slots are released, so it never sleeps past freed capacity and no later caller takes capacity freed for it. A caller that leaves the queue, admitted, timed out, or cancelled, wakes the next head.

Errors

Returns the latest OutboxFull the queue’s head was refused with, admitting nothing, when deadline passes before the reservation fits.

pub fn pending(&self) -> usize

Returns the number of items not yet written.

pub async fn settle(&self, deadline: Instant) -> usize

Waits until deadline for everything staged so far to be written, without closing the outbox, and returns how many items remain.

The outbox keeps accepting items throughout; callers that read the sink’s destination right after staging use this to observe their items.

pub async fn shutdown(&self, deadline: Instant) -> usize

Stops taking items, keeps writing and retrying until deadline, and returns how many items were lost at the deadline.

The staging sender is dropped before the first await, which is a one-way fence: everything staged before it drains, and every later Outbox::stage is refused and counted lost without entering the queue. Shed counts not yet recorded are recorded at the fence. Items still unwritten at the deadline are abandoned with the writer, which cancels any in-flight write; once the writer is gone they are counted in outbox_events_lost_total with LossReason::Shutdown, logged, and released from pending() and outbox_pending, which both end at zero, and released from their admission shares. When shutdown is called concurrently, exactly one caller reports the loss and settles both shares, and the others report zero. Unspent Reservation slots stay held until their reservation drops.

Trait Implementations

impl<S> AuditStage for Outbox<S>

where S: OutboxSink, S::Item: From<AuditEvent>,

fn stage(&self, tenant: DataTenantId, event: AuditEvent)

Stages event on this outbox through its ordinary non-blocking Outbox::stage.

impl<S: OutboxSink> Debug for Outbox<S>

Names the outbox and its pending count, so values carrying a handle — a staged write that hands off to a second outbox — stay debuggable.

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Write the sink’s name and a relaxed snapshot of the pending count; queued items and the sink itself are never formatted.

Errors

Returns the formatter’s error when it rejects a write.