nexus_async_rt/net/
mod.rs

1//! Async network primitives.
2//!
3//! Wraps mio's TCP and UDP types with async read/write backed by the
4//! runtime's IO driver. Sockets register with mio lazily on first poll
5//! (edge-triggered — register once, no reregistration).
6//!
7//! # IO Traits
8//!
9//! [`AsyncRead`] and [`AsyncWrite`] are the core abstractions. They
10//! mirror `std::io::Read`/`Write` but return `Poll` and take a `Context`
11//! for waker registration. nexus-net codecs program against these traits.
12
13use std::io;
14use std::pin::Pin;
15use std::task::{Context, Poll};
16
17pub mod tcp;
18pub mod udp;
19
20pub use tcp::{
21    Accept, OwnedReadHalf, OwnedWriteHalf, ReadHalf, ReuniteError, TcpListener, TcpSocket,
22    TcpStream, WriteHalf,
23};
24pub use udp::UdpSocket;
25
26// =============================================================================
27// AsyncRead / AsyncWrite
28// =============================================================================
29
30/// Async read half of a byte stream.
31///
32/// Mirrors `std::io::Read` but returns `Poll` for non-blocking use
33/// with the executor.
34///
35/// # Contract
36///
37/// - `Poll::Ready(Ok(0))` means EOF — the peer closed its write half.
38/// - `Poll::Ready(Ok(n))` means `n` bytes were read into `buf[..n]`.
39/// - `Poll::Pending` means no data is available yet — the waker will
40///   be notified when the stream becomes readable.
41/// - `Poll::Ready(Err(e))` is a fatal IO error.
42pub trait AsyncRead {
43    /// Attempt to read from the stream into `buf`.
44    fn poll_read(
45        self: Pin<&mut Self>,
46        cx: &mut Context<'_>,
47        buf: &mut [u8],
48    ) -> Poll<io::Result<usize>>;
49}
50
51/// Async write half of a byte stream.
52///
53/// Mirrors `std::io::Write` but returns `Poll` for non-blocking use.
54///
55/// # Contract
56///
57/// - `Poll::Ready(Ok(n))` means `n` bytes from `buf[..n]` were written.
58/// - `Poll::Pending` means the write buffer is full — the waker will
59///   be notified when the stream becomes writable.
60/// - `poll_flush` ensures all buffered data reaches the OS send buffer.
61/// - `poll_shutdown` signals that no more data will be written (TCP FIN).
62pub trait AsyncWrite {
63    /// Attempt to write `buf` to the stream.
64    fn poll_write(
65        self: Pin<&mut Self>,
66        cx: &mut Context<'_>,
67        buf: &[u8],
68    ) -> Poll<io::Result<usize>>;
69
70    /// Flush any buffered data to the underlying transport.
71    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>>;
72
73    /// Initiate graceful shutdown of the write half.
74    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>>;
75}
76
77// =============================================================================
78// Helper: extract task pointer from waker
79// =============================================================================
80
81/// Extract the task pointer from a `Context`'s waker.
82///
83/// Our wakers store the task pointer as the `RawWaker` data field.
84/// Uses the stable `Waker::data()` API (Rust 1.83+).
85pub(crate) fn waker_to_ptr(cx: &Context<'_>) -> *mut u8 {
86    cx.waker().data() as *mut u8
87}
nexus_async_rt/net/mod.rs

nexus_async_rt/net/
mod.rs
