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
impl Inbox
Sourcepub fn work_capacity(&self, lane: usize) -> Result<Option<usize>>
pub fn work_capacity(&self, lane: usize) -> Result<Option<usize>>
The receiver’s declared bound. None adds no execution ceiling.
Sourcepub fn set_work_execution(&self, lane: usize, execution: usize) -> Result<()>
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.
Sourcepub fn work_execution(&self, lane: usize) -> Result<Option<usize>>
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.
Sourcepub fn work_load(&self, lane: usize) -> Result<usize>
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.
Sourcepub fn check_work(&self, ticket: WorkTicket) -> Result<()>
pub fn check_work(&self, ticket: WorkTicket) -> Result<()>
Whether this reservation is still held and not yet accepted.
Sourcepub fn withdraw_work(&self, ticket: WorkTicket) -> bool
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.
Sourcepub fn watch_capacity(&self, lane: usize, origin: usize) -> Result<()>
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.
Sourcepub fn advertise_inline_exchanges(&self, lane: usize, epoch: u64) -> Result<()>
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.
Sourcepub fn inline_exchange_epoch(&self, lane: usize) -> Option<u64>
pub fn inline_exchange_epoch(&self, lane: usize) -> Option<u64>
The epoch of a lane advertising inline exchanges.
Sourcepub fn signals_inbox_space(&self, lane: usize, epoch: u64) -> bool
pub fn signals_inbox_space(&self, lane: usize, epoch: u64) -> bool
Whether this exact lane lifetime signals freed inbox space.
Sourcepub fn watch_inbox_space(
&self,
lane: usize,
epoch: u64,
origin: usize,
) -> Result<bool>
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.
pub fn capacity_generation(&self, origin: usize) -> Result<u64>
Source§impl Inbox
impl Inbox
Sourcepub unsafe fn initialize(
base: *mut u8,
fleet_capacity: usize,
geometry: InboxGeometry,
) -> Result<Self>
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.
Sourcepub unsafe fn attach(
base: *mut u8,
fleet_capacity: usize,
geometry: InboxGeometry,
) -> Result<Self>
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
pub fn geometry(&self) -> InboxGeometry
pub fn lanes(&self) -> usize
Sourcepub fn lane_epoch(&self, lane: usize) -> Result<u64>
pub fn lane_epoch(&self, lane: usize) -> Result<u64>
The lane lifetime to fence writes and capacity waits against.
Sourcepub fn advertise_paired_bodies(&self, lane: usize) -> Result<()>
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.
Sourcepub fn paired_bodies_epoch(&self, lane: usize) -> Option<u64>
pub fn paired_bodies_epoch(&self, lane: usize) -> Option<u64>
The current epoch in which the receiver advertised paired bodies.
Sourcepub fn claim_lane(
&self,
lane_index: usize,
service: &str,
role: &str,
incarnation: u64,
) -> Result<()>
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.
Sourcepub fn claim_lane_with_capacity(
&self,
lane_index: usize,
service: &str,
role: &str,
incarnation: u64,
capacity: Option<usize>,
) -> Result<()>
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.
Sourcepub fn join<H>(
&self,
service: &str,
role: &str,
incarnation: u64,
hold: impl FnMut(usize) -> Result<Option<H>>,
) -> Result<(usize, H)>
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.
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)>
Sourcepub fn reclaim(&self, lane_index: usize) -> Result<Option<Reclaimed>>
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.
Sourcepub fn park(&self, lane_index: usize, expected: u32) -> Result<()>
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.
Sourcepub fn nudge(&self, lane_index: usize) -> Result<()>
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.
Sourcepub fn service(&self, lane_index: usize) -> Result<Option<String>>
pub fn service(&self, lane_index: usize) -> Result<Option<String>>
The service this lane serves, if it is claimed.
Sourcepub fn owner(&self, lane_index: usize) -> Result<Option<u32>>
pub fn owner(&self, lane_index: usize) -> Result<Option<u32>>
The process that claimed this lane, if it said.
Sourcepub fn last_owner(&self, lane_index: usize) -> Result<Option<(u32, u64)>>
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.
Sourcepub fn role_accepted(
&self,
lane_index: usize,
accept: impl FnOnce(&str) -> bool,
) -> bool
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.
Sourcepub fn watcher_role_accepted(
&self,
slot: usize,
accept: impl FnOnce(&str) -> bool,
) -> bool
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.
pub fn role(&self, lane_index: usize) -> Result<Option<String>>
Sourcepub fn targets(&self, service: &str) -> Vec<(usize, u64)>
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.
Sourcepub fn directory(&self) -> u64
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.
Sourcepub fn set_growth_policy(&self, policy: Option<GrowthPolicy>)
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.
Sourcepub fn growth_policy(&self) -> Option<GrowthPolicy>
pub fn growth_policy(&self) -> Option<GrowthPolicy>
The growth policy the owner declared, if any.
Sourcepub fn report_pressure(&self) -> bool
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.
pub fn pressure_pending(&self) -> bool
Sourcepub fn take_pressure(&self) -> bool
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.
Sourcepub fn serving(&self, service: &str) -> Vec<usize>
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.
Sourcepub fn ready(&self, lanes: &[usize]) -> Vec<(usize, u64)>
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.
Sourcepub fn idlest(&self, lanes: &[usize]) -> Option<(usize, u64)>
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.
Sourcepub fn release_lane(&self, lane_index: usize) -> Result<()>
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.
Sourcepub fn admits(&self, lane_index: usize) -> Result<Admission>
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.
Sourcepub fn depth(&self, lane_index: usize) -> Result<u64>
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.
pub fn consumers(&self, lane_index: usize) -> Result<u32>
pub fn incarnation(&self, lane_index: usize) -> Result<u64>
Sourcepub fn write(&self, lane_index: usize, payload: &[u8]) -> Result<u64>
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.
Sourcepub fn write_vectored(&self, lane_index: usize, parts: &[&[u8]]) -> Result<u64>
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.
Sourcepub fn write_vectored_at_epoch(
&self,
lane: usize,
epoch: u64,
parts: &[&[u8]],
) -> Result<u64>
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.
Sourcepub fn write_reply_at_epoch(
&self,
lane: usize,
epoch: u64,
parts: &[&[u8]],
) -> Result<u64>
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.
Sourcepub fn reserved_through(&self, lane: usize) -> Result<u64>
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.
Sourcepub fn read_position(&self, lane: usize) -> Result<u64>
pub fn read_position(&self, lane: usize) -> Result<u64>
The next turn the single reader will consume.
Sourcepub fn read(&self, lane_index: usize, out: &mut Vec<u8>) -> Result<bool>
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.
Sourcepub fn read_frame(
&self,
lane_index: usize,
out: &mut Vec<u8>,
) -> Result<Option<Option<WorkTicket>>>
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.
Sourcepub fn wait_word(&self, lane_index: usize) -> Result<(&AtomicU32, u32)>
pub fn wait_word(&self, lane_index: usize) -> Result<(&AtomicU32, u32)>
The word a parked reader waits on, and its current value.