Skip to main content

product_os_io_uring/
lib.rs

1//! # Product OS : IO Uring
2//!
3//! Multi-backend accept/runtime facade:
4//!
5//! - **Linux**: `io_uring` via `tokio-uring`, with optional SQPOLL, IOPOLL, and
6//!   kernel-registered buffers
7//! - **macOS / Windows**: portable tokio (`kqueue` / IOCP) workers under the same API
8//!
9//! This crate is **not** an async executor (see `product-os-async-executor`) and does
10//! **not** depend on Flow/hyper. Higher-level HTTP servers (e.g. Product OS Router
11//! `flow_perf_native`) integrate by implementing [`ConnectionHandler`].
12//!
13//! ## Quick start
14//!
15//! ```rust,no_run
16//! use product_os_io_uring::{
17//!     AcceptServer, BackendPreference, FnHandler, RuntimeConfig,
18//! };
19//! use std::net::SocketAddr;
20//!
21//! fn main() -> Result<(), product_os_io_uring::Error> {
22//!     let config = RuntimeConfig::builder()
23//!         .workers(2)
24//!         .backend(BackendPreference::Auto)
25//!         .build();
26//!     let server = AcceptServer::new(config)?;
27//!     let addr: SocketAddr = "127.0.0.1:8080".parse().unwrap();
28//!     server.run(addr, FnHandler::new(|_stream, peer| async move {
29//!         let _ = peer;
30//!     }))
31//! }
32//! ```
33//!
34//! ## Feature flags
35//!
36//! - `rt` / `net` / `portable` / `affinity` / `advanced` — enabled by default
37//! - `bridge_tokio` — convert [`AcceptedStream`] to `tokio::net::TcpStream`
38//! - `tracing` — diagnostic logs
39//!
40//! ## Platform notes
41//!
42//! io_uring syscalls exist only on Linux. On other OSes, [`BackendPreference::Auto`]
43//! selects the portable tokio backend. SQPOLL/IOPOLL/registered buffers are Linux-only;
44//! with [`RuntimeConfigBuilder::strict_uring_features`](config::RuntimeConfigBuilder::strict_uring_features)
45//! they error when unsupported.
46
47#![warn(missing_docs)]
48#![allow(clippy::module_name_repetitions)]
49
50mod affinity;
51mod buffer;
52mod config;
53mod error;
54mod features;
55mod listener;
56mod registered;
57
58#[cfg(feature = "rt")]
59mod runtime;
60
61#[cfg(feature = "net")]
62pub mod net;
63
64pub use affinity::{get_core_ids, pin_current_thread, try_pin_current_thread, CoreId};
65pub use buffer::{get as get_buffer, return_buf, PooledBuffer};
66pub use config::{
67    BackendKind, BackendPreference, BufferPoolConfig, RuntimeConfig, RuntimeConfigBuilder,
68};
69pub use error::{Error, Result};
70pub use features::{
71    io_uring_backend_available, iopoll_available, registered_buffers_available, sqpoll_available,
72};
73pub use listener::{create_reuseport_listener, create_reuseport_listener_nonblocking};
74pub use registered::{allocate_buffer_vecs, RegisteredBuffers};
75
76#[cfg(feature = "net")]
77pub use net::{AcceptServer, AcceptedStream, ConnectionHandler, FnHandler};
78
79#[cfg(all(feature = "net", feature = "bridge_tokio"))]
80pub use net::into_tokio_tcp_stream;
81
82#[cfg(all(target_os = "linux", feature = "rt"))]
83pub use runtime::apply_uring_builder;