Skip to main content

fv_streams_exchange/
lib.rs

1//! THE INTERNAL EXCHANGE (Phase 4): Arrow-IPC-carrying frames over kernel TCP on tokio, the transport
2//! a shuffle edge takes when its destination lives in another process. Decision D3 built to the
3//! letter (design/streams-v2-plan.md §1; investigation §7.1–7.3; review-followups §3):
4//!
5//! - **kernel TCP on tokio, `TCP_NODELAY`** — Flight, rkyv, io_uring and QUIC each rejected with
6//!   evidence; the transport sits behind a trait so a `SEND_ZC` experiment can swap in later (D6).
7//! - **N flows per ordered worker pair**, each with its own source port so the NIC's RSS hash spreads
8//!   them across queues and CPUs — the one thing that steps past the single-flow ceiling Flink,
9//!   Arroyo and timely all sit under (§3.3).
10//! - **one owner task per socket direction** — compute tasks never touch a socket; they push frames
11//!   into bounded per-channel queues, so the only real `sk_lock` contention (more than one writer per
12//!   socket) never arises.
13//! - **credit-based flow control** in bytes per channel, granted by the receiver from its own
14//!   consumption of that channel alone — never conditioned on another channel draining, which is what
15//!   keeps a join diamond (Nexmark q8) deadlock-free.
16//!
17//! The transport moves opaque [`Frame`]s tagged with a [`ChannelId`] and a [`FrameKind`]; it routes on
18//! the channel, acts on `Credit` itself, and delivers `Data`/`Signal`/`Eos` to the engine, which maps
19//! them to and from its runtime `Msg`. That boundary keeps this crate free of the engine's types.
20
21mod frame;
22mod link;
23mod transport;
24
25pub use frame::{ChannelId, Frame, FrameError, FrameKind, HEADER, WIRE_VERSION};
26pub use link::{Closed, Grant, Link, LinkReceiver, LinkSender};
27pub use transport::{read_loop, write_loop};
28
29use bytes::Bytes;
30use std::future::Future;
31
32/// The transport seam. Today the only implementor is the TCP [`Link`]; the point of the trait is that
33/// the engine holds `impl Exchange` and never learns which — so a `SEND_ZC` / io_uring transport on a
34/// new kernel (D6, deferred behind exactly this trait) or an in-memory loopback for a test can take
35/// its place without an engine change. Deliberately not `dyn`-safe: the engine is generic over its
36/// transport, not boxing a heterogeneous set, so the seam stays zero-cost.
37pub trait Exchange: Send {
38    /// Send a `Data`/`Signal`/`Eos` frame on a channel, blocking on that channel's credit (the
39    /// backpressure). Errors only when the far end is gone.
40    fn send(&self, channel: ChannelId, kind: FrameKind, body: Bytes)
41        -> impl Future<Output = Result<(), Closed>> + Send;
42    /// Receive the next delivered frame, granting its credit back to the sender for its channel.
43    fn recv(&mut self) -> impl Future<Output = Option<Frame>> + Send;
44}
45
46impl Exchange for Link {
47    fn send(
48        &self,
49        channel: ChannelId,
50        kind: FrameKind,
51        body: Bytes,
52    ) -> impl Future<Output = Result<(), Closed>> + Send {
53        Link::send(self, channel, kind, body)
54    }
55    fn recv(&mut self) -> impl Future<Output = Option<Frame>> + Send {
56        Link::recv(self)
57    }
58}