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;