Skip to main content

Inbox

Struct Inbox 

Source
pub struct Inbox { /* private fields */ }
Expand description

A mapped inbox table.

Holds a raw pointer into shared memory rather than a slice, because the bytes are written by other processes: a &[u8] would promise Rust that nothing else mutates them, and something else always does.

Implementations§

Source§

impl Inbox

Source

pub fn work_capacity(&self, lane: usize) -> Result<Option<usize>>

The receiver’s declared bound. None adds no execution ceiling.

Source

pub fn set_work_execution(&self, lane: usize, execution: usize) -> Result<()>

Declare how many of this receiver’s window slots run at once; the others are a queue the receiver drains itself. Senders read it to prefer a receiver that will start their exchange now. The caller owns the receiver lane.

Source

pub fn work_execution(&self, lane: usize) -> Result<Option<usize>>

How many exchanges this receiver runs at once: its declared execution, else its window. None for an unbounded receiver.

Source

pub fn work_load(&self, lane: usize) -> Result<usize>

Window slots held now: reserved, queued and running exchanges. Never above the truth; a crash can leave it low.

Source

pub fn check_work(&self, ticket: WorkTicket) -> Result<()>

Whether this reservation is still held and not yet accepted.

Source

pub fn withdraw_work(&self, ticket: WorkTicket) -> bool

Take back a published reservation the receiver has not accepted yet. True: it never started and its slot is free. False: the receiver accepted it first (or it is gone); its reply is still owed.

Source

pub fn watch_capacity(&self, lane: usize, origin: usize) -> Result<()>

Register interest before rechecking reservation availability. Multiple waits in one member share a bit; cancellation must not clear another wait’s interest. A subsequent change consumes the bit once.

Source

pub fn advertise_inline_exchanges(&self, lane: usize, epoch: u64) -> Result<()>

Advertise the protocol’s inline exchange support after opening its control table. Old readers leave this previously reserved word zero.

Source

pub fn inline_exchange_epoch(&self, lane: usize) -> Option<u64>

The epoch of a lane advertising inline exchanges.

Source

pub fn signals_inbox_space(&self, lane: usize, epoch: u64) -> bool

Whether this exact lane lifetime signals freed inbox space.

Source

pub fn watch_inbox_space( &self, lane: usize, epoch: u64, origin: usize, ) -> Result<bool>

Register for space in an exact destination inbox. Drive the origin’s receiver for Received::Capacity and retry the write after a wake. False means space is already visible. NoConsumer ends the wait.

Capture the destination epoch before the first write. Take a capacity generation snapshot before arming, then wait for a change from that snapshot. Like work admission notifications, wakes may coalesce or require another check. Both peers must support this notification.

Source

pub fn capacity_generation(&self, origin: usize) -> Result<u64>

Source§

impl Inbox

Source

pub unsafe fn initialize( base: *mut u8, fleet_capacity: usize, geometry: InboxGeometry, ) -> Result<Self>

Take ownership of a mapped region as a fresh table.

Only the table header is written. All-zero is already a table of free lanes, and a lane is set up by whoever takes it (claim_lane, join), so nothing here touches a lane’s pages: the kernel commits a page when it is first written, and a lane nobody claims costs no memory. Zeroing the whole segment here once made every byte of it resident — 69 MiB for 32 lanes of 128 frames of 17 KiB, whether or not a lane was used.

§Safety

base must point at geometry.segment_bytes(fleet_capacity) writable bytes, all zero, that stay mapped for as long as this Inbox lives. A newly created shared-memory object is: ftruncate extends it with zeros. Raw constructors do not install a producer death hold. Use LinkSegment for interprocess publishing; a raw mapping alone is not a registered SHM producer. Direct use is for process-local storage.

Source

pub unsafe fn attach( base: *mut u8, fleet_capacity: usize, geometry: InboxGeometry, ) -> Result<Self>

Attach to a table another process created, refusing anything whose header does not match this build.

§Safety

As Inbox::initialize.

Source

pub fn geometry(&self) -> InboxGeometry

Source

pub fn lanes(&self) -> usize

Source

pub fn lane_epoch(&self, lane: usize) -> Result<u64>

The lane lifetime to fence writes and capacity waits against.

Source

pub fn advertise_paired_bodies(&self, lane: usize) -> Result<()>

Advertise paired body support after the receiver’s tables are ready. The caller must own the lane. Older receivers never write this field, and the lane’s epoch changes even when one of them takes over.

Source

pub fn paired_bodies_epoch(&self, lane: usize) -> Option<u64>

The current epoch in which the receiver advertised paired bodies.

Source

pub fn claim_lane( &self, lane_index: usize, service: &str, role: &str, incarnation: u64, ) -> Result<()>

Claim a lane after fencing out its previous reader. Discard completed old work without resetting full queue positions. In-flight live writers retain ownership; their eventual frames are skipped by destination epoch. Named SHM users should use LinkSegment::join, which takes the hold.

Source

pub fn claim_lane_with_capacity( &self, lane_index: usize, service: &str, role: &str, incarnation: u64, capacity: Option<usize>, ) -> Result<()>

Publish the work bound before making this lane discoverable.

Source

pub fn join<H>( &self, service: &str, role: &str, incarnation: u64, hold: impl FnMut(usize) -> Result<Option<H>>, ) -> Result<(usize, H)>

Take a free lane and say which service this process serves.

There is no pool and no allocator. A service process starts on its own — its own binary, its own virtual environment, its own moment — and introduces itself here. Several processes serving the same name know nothing about each other and do not need to: the lane is won with a compare-and-swap on the consumer count, so exactly one of them takes it.

The name is published after the lane is won and cleared. In between, the lane is claimed but anonymous — and Inbox::targets matches on the name, so nothing is addressed to a lane that is still being made ready.

The index that comes back is this process’s address in the fleet, for the inbox and for its body streams alike.

hold takes a free lane’s hold before the lane is claimed: whatever it returns lives as long as the claim, and a lane it cannot hold is some live process’s. Over shared memory that is the lane’s lock (LinkSegment::join); a table in private memory has nobody else to hold it.

A name already served by another role is refused, naming the lane and process that hold it: two roles under one name would share this inbox and split its requests between them. The check runs before the lane is taken and again once this lane is published, because two processes of different roles joining at the same moment each pass the first; the second sees the other, and both refuse — a name given to two services is a configuration error either way, and it is caught at the door rather than half served.

Source

pub fn join_with_capacity<H>( &self, service: &str, role: &str, incarnation: u64, capacity: Option<usize>, hold: impl FnMut(usize) -> Result<Option<H>>, ) -> Result<(usize, H)>

Source

pub fn reclaim(&self, lane_index: usize) -> Result<Option<Reclaimed>>

Take back a claimed lane whose owner is known to be gone, and say who it was: the incarnation is what its body streams are stamped with.

The caller vouches for the death — over shared memory, by holding the lane’s lock. None when the lane was not claimed.

Source

pub fn park(&self, lane_index: usize, expected: u32) -> Result<()>

Park until something changes in this lane.

expected is the value Inbox::wait_word gave before the caller last drained, and the kernel compares it again under its own lock: a writer that committed in between means the wait returns instead of starting. There is no interval and no deadline here — the wait ends because someone wrote, or because Inbox::nudge woke it on purpose.

Source

pub fn nudge(&self, lane_index: usize) -> Result<()>

Wake this lane’s reader without writing anything.

For the one case that is not a frame: the owner is shutting down and the thread parked on the lane has to notice. A flag the reader checks plus this, rather than a timeout it would otherwise have to wait out.

Source

pub fn service(&self, lane_index: usize) -> Result<Option<String>>

The service this lane serves, if it is claimed.

Source

pub fn owner(&self, lane_index: usize) -> Result<Option<u32>>

The process that claimed this lane, if it said.

Source

pub fn last_owner(&self, lane_index: usize) -> Result<Option<(u32, u64)>>

The last process incarnation on a lane, including one withdrawn while its accepted exchanges drain. Not a routing or liveness observation.

Source

pub fn role_accepted( &self, lane_index: usize, accept: impl FnOnce(&str) -> bool, ) -> bool

What serves this lane’s name, if its owner said. Whether this lane’s role is one accept takes. The role is copied into a fixed buffer, as Inbox::role copies it, but never into a String: callers ask this of every lane for every event they route.

Source

pub fn watcher_role_accepted( &self, slot: usize, accept: impl FnOnce(&str) -> bool, ) -> bool

Whether this watcher slot is held and its role is one accept takes. Allocation-free, as Inbox::role_accepted.

Source

pub fn role(&self, lane_index: usize) -> Result<Option<String>>

Source

pub fn targets(&self, service: &str) -> Vec<(usize, u64)>

Lanes serving service that are ready to take a frame, idlest first.

This is the whole target-selection story: not a registry, not a health report, not a load metric anyone publishes — the queue an edge is about to write into, read directly. A worker that joined a moment ago is already here; one that left is already gone.

Source

pub fn directory(&self) -> u64

The generation of the lane directory: which lanes serve which name.

A caller that resolved a name while this number held may use that answer until it moves. It changes when a process claims a lane or gives one up, and at no other time — a frame written, read or refused leaves it alone.

Source

pub fn set_growth_policy(&self, policy: Option<GrowthPolicy>)

The fleet’s owner declares its growth policy: Some asks senders to report unmet demand and publishes the bounds, None (static) asks for nothing, and report_pressure then writes nothing.

Source

pub fn growth_policy(&self) -> Option<GrowthPolicy>

The growth policy the owner declared, if any.

Source

pub fn report_pressure(&self) -> bool

A sender that found every receiver full reports unmet demand. Only the first report of an episode writes and rings the directory watchers; every later one costs a load and returns false, so any number of senders produce one wake. Nothing is written unless the owner asked for reports.

Source

pub fn pressure_pending(&self) -> bool

Source

pub fn take_pressure(&self) -> bool

The owner ends the episode once it has acted; the next report starts another. Returns whether one was pending.

Source

pub fn serving(&self, service: &str) -> Vec<usize>

Which lanes advertise this name, live or not.

The walk over every lane lives here, so a caller that keeps the result pays it once per directory generation rather than once per exchange. Presence and capacity are deliberately not checked: those change with traffic, and a list that changed with traffic could not be kept.

Source

pub fn ready(&self, lanes: &[usize]) -> Vec<(usize, u64)>

Of these lanes, the ones that will take a frame now, idlest first.

This is the per-exchange half: admission and depth are read every time because both answer “now”, and depth is what the choice is made on.

Source

pub fn idlest(&self, lanes: &[usize]) -> Option<(usize, u64)>

The idlest of these lanes that will take a frame now: the first Inbox::ready would list, read without building the list.

Source

pub fn release_lane(&self, lane_index: usize) -> Result<()>

Give up a lane: its owner is leaving and writers should stop choosing it. In-flight frames are left where they are; the next incarnation clears them.

Source

pub fn admits(&self, lane_index: usize) -> Result<Admission>

Whether a writer may choose this lane, and why not when it may not.

Capacity and presence, never a duration: a writer refused here has been refused now, not after waiting.

Source

pub fn depth(&self, lane_index: usize) -> Result<u64>

Frames written to this lane that its owner has not taken yet.

This is what lets an edge choose a target by reading rather than guessing: with a socket you would need the other side to report its load; here the queue is the shared memory you are about to write into.

Source

pub fn consumers(&self, lane_index: usize) -> Result<u32>

Source

pub fn incarnation(&self, lane_index: usize) -> Result<u64>

Source

pub fn write(&self, lane_index: usize, payload: &[u8]) -> Result<u64>

Put one frame in a node’s lane.

Bounded admission: claim races help the winner and try a later turn, with at most capacity attempts. Full capacity or an exhausted contention budget returns InboxFull. A producer whose every record names a frame not read yet, on any lane, gets ProducerBusy: it can wait for a reader with LinkSegment::record_released. Helpers never commit another producer’s bytes.

Source

pub fn write_vectored(&self, lane_index: usize, parts: &[&[u8]]) -> Result<u64>

Inbox::write for a frame held in pieces — a head encoded here and a body that already has an owner — copied into the slot one after the other, so they need not be joined into one buffer first.

Source

pub fn write_vectored_at_epoch( &self, lane: usize, epoch: u64, parts: &[&[u8]], ) -> Result<u64>

Send only to the specified receiver epoch, including after reserving the producer frame. A replacement never receives this publication.

Source

pub fn write_reply_at_epoch( &self, lane: usize, epoch: u64, parts: &[&[u8]], ) -> Result<u64>

A reply write that distinguishes a full inbox from claim contention.

Source

pub fn reserved_through(&self, lane: usize) -> Result<u64>

Capture the exclusive upper position of currently reserved turns. After recovering a dead producer, its committed frames precede this position even when a still-live producer owns an earlier turn.

Source

pub fn read_position(&self, lane: usize) -> Result<u64>

The next turn the single reader will consume.

Source

pub fn read(&self, lane_index: usize, out: &mut Vec<u8>) -> Result<bool>

Take the next frame from this node’s own lane, if one is there.

Only the lane’s owner may call this. It copies out rather than lending a slice, because the slot is released the moment it returns and another process may fill it immediately.

Source

pub fn read_frame( &self, lane_index: usize, out: &mut Vec<u8>, ) -> Result<Option<Option<WorkTicket>>>

Copy a frame and its optional admission identity. Only the owning receiver may read, then accept work before dispatching its payload.

Source

pub fn wait_word(&self, lane_index: usize) -> Result<(&AtomicU32, u32)>

The word a parked reader waits on, and its current value.

Source

pub fn watcher(&self, slot: usize) -> Result<Option<u32>>

The process holding this watcher slot, if one said.

Source

pub fn watcher_role(&self, slot: usize) -> Result<Option<String>>

What the process holding this watcher slot said it is, if it holds it.

Trait Implementations§

Auto Trait Implementations§

§

impl !Freeze for Inbox

§

impl Forget for Inbox

§

impl Move for Inbox

§

impl RefUnwindSafe for Inbox

§

impl Unpin for Inbox

§

impl UnsafeUnpin for Inbox

§

impl UnwindSafe for Inbox

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> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
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, 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.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more