moq_uring/lib.rs
1//! A thread-per-core io_uring worker for the native MoQ stack.
2//!
3//! One [`Worker`] per pinned thread. It owns a `SINGLE_ISSUER | DEFER_TASKRUN |
4//! COOP_TASKRUN` ring, a userspace timer heap, a local task set, and the UDP
5//! sockets bound through it. The caller owns the thread loop: drive everything
6//! with [`Worker::block_on`], spawn extra `!Send` tasks through [`Handle`], and
7//! wake the worker from other threads through any [`std::task::Waker`] it hands
8//! out (a futex word, no ring or syscall needed while the worker is awake).
9//!
10//! UDP is the point: [`udp::Socket`] receives through one multishot `recvmsg`
11//! with a registered provided-buffer ring (one whole buffer per completion,
12//! `UDP_GRO` coalesced) and sends with an explicit `UDP_SEGMENT` control
13//! message per `sendmsg` from a growable pool of staging buffers.
14//!
15//! [`quic`] stacks a sans-IO QUIC stack on that path: a [`quic::Endpoint`]
16//! serves many connections on one socket (demuxed by connection id, dials
17//! included), each a [`quic::Connection`] implementing the transport traits,
18//! so `moq_net::Client::connect_lite` and `Server::accept_lite` run real
19//! moq-lite sessions on the worker. The socket is the identity: whatever is
20//! built on it runs on the worker that adopted it, and a socket adopted as a
21//! member of a steered reuseport group ([`udp::Bound`]) issues connection ids
22//! that steer back to it. [`Handle::run`] supplies time and schedules driver
23//! wakeups; callers run the returned drivers with [`Handle::spawn`]. The stack
24//! underneath is enabled by the `noq` feature; a build without it leaves the
25//! module out.
26//!
27//! [`metrics::Metrics`] is how the worker's own health leaves its thread:
28//! relaxed counters for the buffer pools, the batching mechanisms, the ring,
29//! and the scheduler, snapshotted from anywhere. Hand one to
30//! [`Config::metrics`] to keep a copy where the worker was spawned, or read the
31//! worker's own through [`Handle::metrics`].
32//!
33//! Requires Linux 6.12; [`Worker::new`] refuses older kernels with a legible
34//! error instead of degrading. The crate compiles to nothing off Linux.
35// Off Linux the crate compiles to nothing, so these doc links have no target.
36#![cfg_attr(not(target_os = "linux"), allow(rustdoc::broken_intra_doc_links))]
37#![cfg(target_os = "linux")]
38
39mod error;
40pub mod metrics;
41mod park;
42#[cfg(feature = "noq")]
43pub mod quic;
44mod shared;
45mod timer;
46pub mod udp;
47mod worker;
48
49pub use error::Error;
50pub use timer::Timer;
51pub use worker::{Config, Handle, Worker};
52
53/// The `url` crate, re-exported because
54/// [`quic::web::Request::url`](crate::quic::web::Request::url) hands one back.
55/// Naming that type otherwise means depending on a matching `url` version
56/// directly, so a major bump here is a breaking change for this crate.
57pub use url;