vibeio/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2
3//! # vibeio
4//!
5//! A high-performance, cross-platform asynchronous runtime for Rust.
6//!
7//! `vibeio` provides an efficient I/O event loop that leverages the best available driver for each operating system:
8//!
9//! - **Linux** - uses `io_uring` for true asynchronous I/O.
10//! - **Windows** - uses I/O Completion Ports (IOCP) for scalable I/O.
11//! - **macOS / BSD / Others** - uses `kqueue` or `epoll` via `mio` for event notification.
12//!
13//! ## Core features
14//!
15//! - **Networking** - asynchronous TCP, UDP, and Unix Domain Sockets.
16//! - **File system** - asynchronous file operations.
17//! - **Timers** - efficient timer and sleep functionality.
18//! - **Signals** - handling of OS signals.
19//! - **Process management** - spawning and managing child processes.
20//! - **Blocking tasks** - offload CPU-intensive or blocking operations to a thread pool.
21//!
22//! ## Concurrency model: thread-per-core
23//!
24//! `vibeio` is designed as a **single-threaded** runtime. To utilize multiple cores, you should employ a **thread-per-core** architecture, where a separate `Runtime` is pinned to each processor core. This approach minimizes synchronization overhead and maximizes cache locality.
25//!
26//! Shared state can be communicated between runtimes using message passing (e.g., channels) or shared atomic structures, but I/O resources are typically owned by the thread that created them.
27//!
28//! ## Getting started
29//!
30//! Add `vibeio` to your `Cargo.toml`:
31//!
32//! ```toml
33//! [dependencies]
34//! vibeio = "0.1"
35//! ```
36//!
37//! ### Example: TCP echo server
38//!
39//! ```rust,no_run
40//! use vibeio::RuntimeBuilder;
41//! use vibeio::net::TcpListener;
42//!
43//! fn main() -> std::io::Result<()> {
44//!     // 1. Build the runtime
45//!     let runtime = RuntimeBuilder::new()
46//!         .enable_timer(true)
47//!         .build()?;
48//!
49//!     // 2. Run the main future
50//!     runtime.block_on(async {
51//!         let listener = TcpListener::bind("127.0.0.1:8080")?;
52//!         println!("Listening on 127.0.0.1:8080");
53//!
54//!         loop {
55//!             let (mut stream, _) = listener.accept().await?;
56//!
57//!             vibeio::spawn(async move {
58//!                 let (mut reader, mut writer) = vibeio::io::split(stream);
59//!                 if let Err(e) = vibeio::io::copy(&mut reader, &mut writer).await {
60//!                     eprintln!("Echo failed: {}", e);
61//!                 }
62//!             });
63//!         }
64//!     })
65//! }
66//! ```
67//!
68//! ## Feature flags
69//!
70//! The following features are available (most are enabled by default):
71//!
72//! - `fs` - enables asynchronous file system operations.
73//! - `time` - enables time and timer functionality.
74//! - `signal` - enables signal handling.
75//! - `process` - enables child process management.
76//! - `pipe` - enables pipe support.
77//! - `stdio` - enables standard I/O support.
78//! - `splice` - enables splice support (Linux).
79//! - `blocking-default` - enables the default blocking thread pool.
80
81pub mod blocking;
82mod builder;
83mod driver;
84mod executor;
85mod fd_inner;
86#[cfg(feature = "fs")]
87pub mod fs;
88pub mod io;
89pub mod net;
90mod op;
91#[cfg(feature = "process")]
92pub mod process;
93#[cfg(feature = "signal")]
94pub mod signal;
95mod task;
96#[cfg(feature = "time")]
97pub mod time;
98#[cfg(feature = "time")]
99mod timer;
100pub mod util;
101
102pub use crate::builder::*;
103pub use crate::executor::*;
vibeio/lib.rs

vibeio/
lib.rs
