1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

//! Runtime is what we imagine async APIs could look like if they were part of stdlib. We want async
//! Rust to be an experience that mirrors the quality of the standard lib. We believe that in order for
//! Rust to succeed it's not only important to make async Rust _possible_, it's crucial to make async
//! Rust feel _seamless_.
//!
//! And the embodiment of these values is Runtime: a library crafted to empower everyone to build
//! asynchronous software.
//!
//! - __runtime agnostic:__ Runtime comes with minimal OS bindings out of the box, but switching to a
//!     different runtime is a matter of changing a single line.
//! - __await anywhere:__ Runtime allows you to write async main functions, async tests, and async
//!     benchmarks. Experience what first-class async support in Rust feels like.
//! - __built for performance:__ Runtime is the thinnest layer possible on top of the backing
//!     implementations. All of the speed, none of the boilerplate.
//!
//! ## Examples
//! __UDP Echo Server__
//! ```no_run
//! #![feature(async_await)]
//!
//! use runtime::net::UdpSocket;
//!
//! #[runtime::main]
//! async fn main() -> std::io::Result<()> {
//!     let mut socket = UdpSocket::bind("127.0.0.1:8080")?;
//!     let mut buf = vec![0u8; 1024];
//!
//!     println!("Listening on {}", socket.local_addr()?);
//!
//!     loop {
//!         let (recv, peer) = socket.recv_from(&mut buf).await?;
//!         let sent = socket.send_to(&buf[..recv], &peer).await?;
//!         println!("Sent {} out of {} bytes to {}", sent, recv, peer);
//!     }
//! }
//! ```
//!
//! To send messages do:
//! ```sh
//! $ nc -u localhost 8080
//! ```
//!
//! __More Examples__
//! - [Hello World](https://github.com/rustasync/runtime/tree/master/examples/hello.rs)
//! - [Guessing Game](https://github.com/rustasync/runtime/blob/master/examples/guessing.rs)
//! - [TCP Echo Server](https://github.com/rustasync/runtime/blob/master/examples/tcp-echo.rs)
//! - [TCP Client](https://github.com/rustasync/runtime/tree/master/examples/tcp-client.rs)
//! - [TCP Proxy Server](https://github.com/rustasync/runtime/tree/master/examples/tcp-proxy.rs)
//! - [UDP Echo Server](https://github.com/rustasync/runtime/tree/master/examples/udp-echo.rs)
//! - [UDP Client](https://github.com/rustasync/runtime/tree/master/examples/udp-client.rs)
//!
//! ## Attributes
//! Runtime introduces 3 attributes to enable the use of await anywhere, and swap between different
//! runtimes. Each Runtime is bound locally to the initializing thread. This enables the testing of
//! different runtimes during testing or benchmarking.
//!
//! ```ignore
//! #[runtime::main]
//! async fn main() {}
//!
//! #[runtime::test]
//! async fn my_test() {}
//!
//! #[runtime::bench]
//! async fn my_bench() {}
//! ```
//!
//! ## Runtimes
//! Switching runtimes is a one-line change:
//!
//! ```ignore
//! /// Use the default Native Runtime
//! #[runtime::main]
//! async fn main() {}
//!
//! /// Use the Tokio Runtime
//! #[runtime::main(runtime_tokio::Tokio)]
//! async fn main() {}
//! ```
//!
//! The following backing runtimes are available:
//!
//! - [Runtime Native (default)](https://docs.rs/runtime-native) provides
//!   a thread pool, bindings to the OS, and a concurrent scheduler.
//! - [Runtime Tokio](https://docs.rs/runtime-tokio) provides a thread pool, bindings to the OS, and
//!   a work-stealing scheduler.

#![feature(async_await)]
#![deny(unsafe_code)]
#![warn(
    missing_debug_implementations,
    missing_docs,
    nonstandard_style,
    rust_2018_idioms
)]

pub mod net;
pub mod task;
pub mod time;

/// The Runtime Prelude.
///
/// Rust comes with a variety of things in its standard library. However, Runtime and Futures
/// provide new functionality outside of it. We want to make Runtime feel as close to standard Rust
/// as possible. We care deeply about usability.
///
/// The _prelude_ is the list of things we recommend importing into Runtime programs. It's kept as
/// small as possible, and is focused on things, particularly traits.
///
/// To use the `prelude` do:
/// ```
/// use runtime::prelude::*;
/// ```
pub mod prelude {
    #[doc(inline)]
    pub use super::time::AsyncReadExt as _;
    #[doc(inline)]
    pub use super::time::FutureExt as _;
    #[doc(inline)]
    pub use super::time::StreamExt as _;
}

#[doc(inline)]
pub use task::spawn;

#[doc(inline)]
pub use runtime_attributes::{bench, test};

#[doc(inline)]
#[cfg(not(test))] // NOTE: exporting main breaks tests, we should file an issue.
pub use runtime_attributes::main;

#[doc(hidden)]
pub use runtime_raw as raw;

#[doc(hidden)]
#[cfg(feature = "native")]
pub use runtime_native as native;