momo/lib.rs
1//! # Momo
2//!
3//! A high-performance, atomic-free asynchronous runtime for Rust.
4//!
5//! **Momo** is an event-driven platform designed for writing non-blocking
6//! asynchronous applications with strict **Thread-Local Affinity**. Unlike
7//! traditional runtimes that rely on multi-threaded task migration, Momo
8//! pins tasks to their creation threads, eliminating synchronization overhead
9//! and core-to-core cache bouncing.
10//!
11//! ## Key Pillars
12//!
13//! - **[Execution Engine](crate::Executor)**: A localized task scheduler with zero-cost
14//! cross-thread wakeups.
15//! - **[Driver](crate::driver)**: A non-blocking I/O reactor supporting epoll,
16//! kqueue, and IOCP.
17//! - **[Time](crate::time)**: High-resolution timing via an O(1) hierarchical
18//! timer wheel.
19//! - **[Sync](crate::sync)**: Communication primitives optimized for
20//! thread-local and cross-thread signaling.
21//! - **[Net](crate::net)**: Unified async TCP and UDP networking.
22//!
23//! ## Getting Started
24//!
25//! Add **momo-rs** to your `Cargo.toml`:
26//!
27//! ```toml
28//! [dependencies]
29//! momo-rs = "0.1"
30//! ```
31//!
32//! ### A Simple Loop
33//!
34//! ```rust
35//! use core::time::Duration;
36//!
37//! #[momo::main]
38//! async fn main() {
39//! momo::spawn(async {
40//! println!("Hello from Momo!");
41//! momo::time::sleep(Duration::from_millis(50)).await;
42//! println!("Timer triggered on the local thread.");
43//! });
44//! }
45//! ```
46//!
47//! ## The Fixed-Affinity model
48//!
49//! In Momo, every task is owned by the thread that spawned it.
50//!
51//! 1. **No `Send` Constraints**: You can safely spawn and run futures that
52//! are `!Send`, as they are guaranteed never to migrate to another thread.
53//! 2. **Deterministic Scheduling**: Local tasks are executed in a stable
54//! FIFO order with a dedicated poll budget.
55//! 3. **Local Memory Safety**: Share state between tasks on the same thread
56//! with `Rc<RefCell<T>>` instead of heavier atomic primitives.
57//!
58//! ## Feature Flags
59//!
60//! Momo is modular. Configure your imports with these features:
61//!
62//! - `full`: All features enabled (default).
63//! - `net`: Async TCP/UDP primitives.
64//! - `sync`: Unbounded MPSC and Oneshot channels.
65//! - `time`: Hierarchical timer support and sleeps.
66//! - `macros`: The `#[momo::main]` entry point macro.
67
68#[doc(inline)]
69pub use momo_rs_core::{spawn, Executor, has_pending_tasks, stop, is_stopped, yield_now, set_wakeup_handler};
70
71#[cfg(feature = "driver")]
72#[doc(inline)]
73pub use momo_rs_driver as driver;
74
75#[cfg(feature = "time")]
76#[doc(inline)]
77pub use momo_rs_time as time;
78
79#[cfg(feature = "net")]
80#[doc(inline)]
81pub use momo_rs_net as net;
82
83#[cfg(feature = "sync")]
84#[doc(inline)]
85pub use momo_rs_sync as sync;
86
87/// The common prelude for Momo.
88pub mod prelude {
89 pub use crate::spawn;
90 #[cfg(feature = "time")]
91 pub use crate::time::sleep;
92 #[cfg(feature = "net")]
93 pub use crate::net::{TcpListener, TcpStream};
94}
95
96#[cfg(feature = "macros")]
97#[doc(inline)]
98pub use momo_rs_macros::main;