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//! ## Runtime Varieties Note
17//!
18//! ### Task Detach
19//!
20//! The drop behavior of task handle is unified to "detach", task will not be cancel unless
21//! [abort](AsyncHandle::abort) is called.
22//!
23//! ### Panic
24//!
25//! - tokio will issolate panic between tasks, a task handle may return Err() on join.
26//! - smol will not issolate panic. Although a panic hook will work, the program might panic if one
27//! of the task panic. You may use feature `unwind` to enable panic capturing.
28//!
29//! ### Cloning
30//!
31//! Both `TokioRT` and `SmolRT` have impl Clone, but [AsyncRuntime] and [AsyncExec] does not
32//! include Clone because not sure about other runtime. you may explicitly mark Clone with our
33//! trait marker.
34//!
35//! ## Inherence
36//!
37//! You can write your own trait by inheriting AsyncRuntime or any other trait, to provide extra
38//! functions along with the runtime object.
39//! There's an blanket trait to auto impl AsyncRuntime on anything that is `Deref<Target>` to an AsyncRuntime.
40//!
41//! ``` no_compile
42//! pub trait AsyncRuntime: AsyncExec + AsyncIO + AsyncTime {}
43//!
44//! impl<F: std::ops::Deref<Target = T> + Send + Sync + 'static, T: AsyncRuntime> AsyncRuntime for F {}
45//! ```
46//! Simimlar blanket trait can be found on other sub traits.
47
48pub mod io;
49pub mod net;
50pub mod runtime;
51pub mod time;
52pub mod utils;
53
54/// Re-export all the traits you need
55///
56/// This module contains all the essential traits needed to work with Orb.
57/// Importing this prelude is the recommended way to use Orb in your code.
58pub mod prelude {
59    pub use crate::AsyncRuntime;
60    pub use crate::io::{AsyncBufRead, AsyncBufWrite, AsyncFd, AsyncIO, AsyncRead, AsyncWrite};
61    pub use crate::net::AsyncListener;
62    pub use crate::runtime::{AsyncExec, AsyncHandle, ThreadHandle};
63    pub use crate::time::{AsyncTime, TimeInterval};
64    // Re-export the Stream trait so users can import it
65    pub use futures_lite::stream::Stream;
66    pub use futures_lite::stream::StreamExt;
67}
68
69use prelude::*;
70
71/// A marker trait that combines all the core async runtime capabilities,
72/// including [`AsyncExec`], [`AsyncIO`], and [`AsyncTime`]. It serves as a convenient
73/// way to specify that a type provides all the core async runtime functionality.
74///
75/// You can write your own trait by inheriting AsyncRuntime or any other trait, to provide extra
76/// functions along with the runtime object.
77/// There's an blanket trait to auto impl AsyncRuntime on anything that is `Deref<Target>` to an AsyncRuntime.
78pub trait AsyncRuntime: AsyncExec + AsyncIO + AsyncTime {}
79
80impl<F: std::ops::Deref<Target = T> + Send + Sync + 'static, T: AsyncRuntime> AsyncRuntime for F {}
orb/lib.rs

orb/
lib.rs
