moduvex_runtime/net/
mod.rs

1//! Async networking: TCP listener, TCP stream, UDP socket.
2//!
3//! # Traits
4//! - [`AsyncRead`] — poll-based non-blocking read
5//! - [`AsyncWrite`] — poll-based non-blocking write + flush + shutdown
6//!
7//! # Types
8//! - [`TcpListener`] — accepts incoming TCP connections
9//! - [`TcpStream`]   — bidirectional async byte stream
10//! - [`UdpSocket`]   — connectionless async datagram socket
11
12use std::io;
13use std::pin::Pin;
14use std::task::{Context, Poll};
15
16pub mod tcp_listener;
17pub mod tcp_stream;
18pub mod udp_socket;
19
20pub use tcp_listener::TcpListener;
21pub use tcp_stream::TcpStream;
22pub use udp_socket::UdpSocket;
23
24// ── AsyncRead ─────────────────────────────────────────────────────────────────
25
26/// Async version of `std::io::Read`.
27///
28/// The poll method must be called with a pinned `Self` and a `Context`.
29/// It returns `Poll::Ready(Ok(n))` when `n` bytes have been written into
30/// `buf`, or `Poll::Pending` when no bytes are available yet (the waker
31/// will be called when data arrives).
32pub trait AsyncRead {
33    /// Attempt to read bytes into `buf`.
34    ///
35    /// On success returns `Poll::Ready(Ok(n))` where `n` is the number of
36    /// bytes read. `n == 0` signals EOF. Returns `Poll::Pending` and
37    /// arranges for the waker to be called on the next read-readiness event.
38    fn poll_read(
39        self: Pin<&mut Self>,
40        cx: &mut Context<'_>,
41        buf: &mut [u8],
42    ) -> Poll<io::Result<usize>>;
43}
44
45// ── AsyncWrite ────────────────────────────────────────────────────────────────
46
47/// Async version of `std::io::Write`.
48///
49/// All three poll methods follow the same contract: `Poll::Ready(Ok(...))`
50/// on success, `Poll::Pending` when the underlying resource is not ready
51/// (with the waker arranged to fire when it becomes ready).
52pub trait AsyncWrite {
53    /// Attempt to write bytes from `buf` into the sink.
54    ///
55    /// Returns the number of bytes written. May be less than `buf.len()`.
56    fn poll_write(
57        self: Pin<&mut Self>,
58        cx: &mut Context<'_>,
59        buf: &[u8],
60    ) -> Poll<io::Result<usize>>;
61
62    /// Flush any internal buffers to the OS.
63    ///
64    /// For kernel-backed sockets this is a no-op that returns `Ready(Ok(()))`.
65    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>>;
66
67    /// Initiate a half-close: shut down the write side of the connection.
68    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>>;
69}
moduvex_runtime/net/mod.rs

moduvex_runtime/net/
mod.rs
