Crate orbit_stream 

Bounded byte streams and paired exchanges between members of an Orbit fleet.

A stream is a place with two ends. Streams::create takes a slot in this process’s lane, hands back the endpoint for side A and a Ticket for side B; whoever in the fleet Streams::opens that ticket holds the other end. Each direction is its own bounded ring: bytes go in at one end and come out, in order and without loss, at the other; when the ring is full the writer waits, when it is empty the reader waits. A writer that is done shuts its direction down (FIN) and the reader drains to a clean end; a writer that gives up resets it and the reader sees an error.

Standalone the rings live in process memory; in a shared-memory fleet they live in the fleet’s segment and the two ends may be in different processes. The address that travels is a NetId64: its kind is the segment’s, its node the creator’s lane, its counter the slot and the slot’s generation; the Ticket around it adds the table’s epoch. An address kept past the stream’s end, or past a reset, answers Error::Stale instead of reaching whoever took the slot next.

The blocking calls park on the direction’s own change word through the platform’s shared address wait, like a cell. With the tokio feature the halves implement AsyncRead and AsyncWrite; a poll that finds nothing registers its waker and returns Pending, and one thread per process turns the fleet’s doorbell into those wakes. No thread and no descriptor per stream.

exchange builds a symmetric event program above that lossless control path. Payload bytes live in one shared arena whose per-node lanes make allocation ownership explicit: fixed-size slots are physical allocation units, while each published chunk is one descriptor spanning as many contiguous slots as that runtime decision needs. Both directions have independent START, FIN and RESET state, so either may begin first without imposing an application sequencing rule on the transport.

Modules

exchange

Paired, symmetric byte flows over one control channel and shared or directional payload arenas. Each endpoint owns an outbound sender and an inbound receiver.

Structs

Endpoint

Both ends of one side: what Streams::create and Streams::open return. Reads and writes go through it directly, or Endpoint::split gives the halves to two tasks.

Incarnation

Which life of a process holds a side. A node id is a role that a replacement process inherits; the incarnation tells the two apart, so a late death report for the old process never touches the new one’s streams. Orbit does not mint it: the embedder knows what identifies one live process (a start stamp, a supervisor generation) and supplies it.

ReadHalf

The reading end of one side. Dropping it tells the peer’s writer that nothing more will be read.

Readiness

The consumer’s end: put it in a poll set, drain it, re-read your state.

StreamId

The address of one stream: a NetId64 whose node is the creator’s lane and whose counter is the slot and its generation.

StreamSpec

Which segment a Streams table uses, and how big its lanes and rings are.

Streams

The fleet’s stream table. Cheap to clone; every clone in a process is the same table, the same driver and the same wakers.

Ticket

One end of a stream, in the form that crosses a setup channel: the address, the side, and the epoch of the table the address was minted in. Prints as <address>/b/<epoch>.

WriteHalf

The writing end of one side. Dropping it without WriteHalf::finish resets the direction, as a dropped socket would.

Enums

Error

Additions are expected: a cause discovered later lands here rather than in a new major version, so a caller matches what it handles and leaves the rest to a catch-all.

Side

Which end of a stream a handle holds. The creator holds A.

Constants

STREAM_BUFFER_BYTES

Bytes each direction of a stream can hold before its writer waits, in the default spec.

STREAM_KIND

Reserved Orbit SHM kind for the default stream segment. Another table names its own through a StreamSpec.

STREAM_LANE_CAPACITY

Streams one fleet node can hold open at once, in the default spec.

Functions

segment_size

Bytes the segment needs for fleet_capacity lanes; what a lifecycle tool validates an existing object against without mapping it read-write.

segment_size_for

Bytes spec’s segment needs for fleet_capacity lanes.

Type Aliases

Result