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}