orb/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![cfg_attr(docsrs, allow(unused_attributes))]
3#![doc = include_str!("../README.md")]
4
5//! ## Modules
6//!
7//! - [`runtime`] - Traits for task spawn, join and block_on.
8//! - [`io`] - Traits for asynchronous I/O operations, and buffered I/O wrapper.
9//! - [`net`] - Wrapper types for networking, and a "unify" type for tcp + unix stream.
10//! - [`time`] - Traits for time-related operations like sleeping and intervals
11//! - [`utils`] - Utility types and functions
12//!
13//! At top level [AsyncRuntime] trait will combine all the capabilities, including
14//! [`AsyncExec`], [`AsyncIO`], and [`AsyncTime`].
15//!
16//! You can write your own trait by inheriting AsyncRuntime or any other trait, to provide extra
17//! functions along with the runtime object.
18//! There's an blanket trait to auto impl AsyncRuntime on anything that is `Deref<Target>` to an AsyncRuntime.
19//!
20//! ``` no_compile
21//! pub trait AsyncRuntime: AsyncExec + AsyncIO + AsyncTime {}
22//!
23//! impl<F: std::ops::Deref<Target = T> + Send + Sync + 'static, T: AsyncRuntime> AsyncRuntime for F {}
24//! ```
25//! Simimlar blanket trait can be found on other sub traits.
26//!
27//! ## Important Notes
28//!
29//! When working with spawned tasks, be aware that some runtimes (like smol) will
30//! cancel the future if you drop the task handle without explicitly detaching it.
31//! If you want a task to continue running in the background, you must call
32//! [`AsyncJoinHandle::detach`] rather than just dropping the handle.
33
34pub mod io;
35pub mod net;
36pub mod runtime;
37pub mod time;
38pub mod utils;
39
40/// Re-export all the traits you need
41///
42/// This module contains all the essential traits needed to work with Orb.
43/// Importing this prelude is the recommended way to use Orb in your code.
44pub mod prelude {
45    pub use crate::AsyncRuntime;
46    pub use crate::io::{AsyncBufRead, AsyncBufWrite, AsyncFd, AsyncIO, AsyncRead, AsyncWrite};
47    pub use crate::net::AsyncListener;
48    pub use crate::runtime::{AsyncExec, AsyncJoinHandle};
49    pub use crate::time::{AsyncTime, TimeInterval};
50    // Re-export the Stream trait so users can import it
51    pub use futures_lite::stream::Stream;
52    pub use futures_lite::stream::StreamExt;
53}
54
55use prelude::*;
56
57/// A marker trait that combines all the core async runtime capabilities,
58/// including [`AsyncExec`], [`AsyncIO`], and [`AsyncTime`]. It serves as a convenient
59/// way to specify that a type provides all the core async runtime functionality.
60///
61/// You can write your own trait by inheriting AsyncRuntime or any other trait, to provide extra
62/// functions along with the runtime object.
63/// There's an blanket trait to auto impl AsyncRuntime on anything that is `Deref<Target>` to an AsyncRuntime.
64pub trait AsyncRuntime: AsyncExec + AsyncIO + AsyncTime {}
65
66impl<F: std::ops::Deref<Target = T> + Send + Sync + 'static, T: AsyncRuntime> AsyncRuntime for F {}
orb/lib.rs

orb/
lib.rs
