1# Tokio 2 3A runtime for writing reliable, asynchronous, and slim applications with 4the Rust programming language. It is: 5 6* **Fast**: Tokio's zero-cost abstractions give you bare-metal 7 performance. 8 9* **Reliable**: Tokio leverages Rust's ownership, type system, and 10 concurrency model to reduce bugs and ensure thread safety. 11 12* **Scalable**: Tokio has a minimal footprint, and handles backpressure 13 and cancellation naturally. 14 15[![Crates.io][crates-badge]][crates-url] 16[![MIT licensed][mit-badge]][mit-url] 17[![Build Status][actions-badge]][actions-url] 18[![Discord chat][discord-badge]][discord-url] 19 20[crates-badge]: https://img.shields.io/crates/v/tokio.svg 21[crates-url]: https://crates.io/crates/tokio 22[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg 23[mit-url]: https://github.com/tokio-rs/tokio/blob/master/LICENSE 24[actions-badge]: https://github.com/tokio-rs/tokio/workflows/CI/badge.svg 25[actions-url]: https://github.com/tokio-rs/tokio/actions?query=workflow%3ACI+branch%3Amaster 26[discord-badge]: https://img.shields.io/discord/500028886025895936.svg?logo=discord&style=flat-square 27[discord-url]: https://discord.gg/tokio 28 29[Website](https://tokio.rs) | 30[Guides](https://tokio.rs/tokio/tutorial) | 31[API Docs](https://docs.rs/tokio/latest/tokio) | 32[Chat](https://discord.gg/tokio) 33 34## Overview 35 36Tokio is an event-driven, non-blocking I/O platform for writing 37asynchronous applications with the Rust programming language. At a high 38level, it provides a few major components: 39 40* A multithreaded, work-stealing based task [scheduler]. 41* A reactor backed by the operating system's event queue (epoll, kqueue, 42 IOCP, etc...). 43* Asynchronous [TCP and UDP][net] sockets. 44 45These components provide the runtime components necessary for building 46an asynchronous application. 47 48[net]: https://docs.rs/tokio/latest/tokio/net/index.html 49[scheduler]: https://docs.rs/tokio/latest/tokio/runtime/index.html 50 51## Example 52 53A basic TCP echo server with Tokio. 54 55Make sure you activated the full features of the tokio crate on Cargo.toml: 56 57```toml 58[dependencies] 59tokio = { version = "1.14.0", features = ["full"] } 60``` 61Then, on your main.rs: 62 63```rust,no_run 64use tokio::net::TcpListener; 65use tokio::io::{AsyncReadExt, AsyncWriteExt}; 66 67#[tokio::main] 68async fn main() -> Result<(), Box<dyn std::error::Error>> { 69 let listener = TcpListener::bind("127.0.0.1:8080").await?; 70 71 loop { 72 let (mut socket, _) = listener.accept().await?; 73 74 tokio::spawn(async move { 75 let mut buf = [0; 1024]; 76 77 // In a loop, read data from the socket and write the data back. 78 loop { 79 let n = match socket.read(&mut buf).await { 80 // socket closed 81 Ok(n) if n == 0 => return, 82 Ok(n) => n, 83 Err(e) => { 84 eprintln!("failed to read from socket; err = {:?}", e); 85 return; 86 } 87 }; 88 89 // Write the data back 90 if let Err(e) = socket.write_all(&buf[0..n]).await { 91 eprintln!("failed to write to socket; err = {:?}", e); 92 return; 93 } 94 } 95 }); 96 } 97} 98``` 99 100More examples can be found [here][examples]. For a larger "real world" example, see the 101[mini-redis] repository. 102 103[examples]: https://github.com/tokio-rs/tokio/tree/master/examples 104[mini-redis]: https://github.com/tokio-rs/mini-redis/ 105 106To see a list of the available features flags that can be enabled, check our 107[docs][feature-flag-docs]. 108 109## Getting Help 110 111First, see if the answer to your question can be found in the [Guides] or the 112[API documentation]. If the answer is not there, there is an active community in 113the [Tokio Discord server][chat]. We would be happy to try to answer your 114question. You can also ask your question on [the discussions page][discussions]. 115 116[Guides]: https://tokio.rs/tokio/tutorial 117[API documentation]: https://docs.rs/tokio/latest/tokio 118[chat]: https://discord.gg/tokio 119[discussions]: https://github.com/tokio-rs/tokio/discussions 120[feature-flag-docs]: https://docs.rs/tokio/#feature-flags 121 122## Contributing 123 124:balloon: Thanks for your help improving the project! We are so happy to have 125you! We have a [contributing guide][guide] to help you get involved in the Tokio 126project. 127 128[guide]: https://github.com/tokio-rs/tokio/blob/master/CONTRIBUTING.md 129 130## Related Projects 131 132In addition to the crates in this repository, the Tokio project also maintains 133several other libraries, including: 134 135* [`hyper`]: A fast and correct HTTP/1.1 and HTTP/2 implementation for Rust. 136 137* [`tonic`]: A gRPC over HTTP/2 implementation focused on high performance, interoperability, and flexibility. 138 139* [`warp`]: A super-easy, composable, web server framework for warp speeds. 140 141* [`tower`]: A library of modular and reusable components for building robust networking clients and servers. 142 143* [`tracing`] (formerly `tokio-trace`): A framework for application-level tracing and async-aware diagnostics. 144 145* [`rdbc`]: A Rust database connectivity library for MySQL, Postgres and SQLite. 146 147* [`mio`]: A low-level, cross-platform abstraction over OS I/O APIs that powers 148 `tokio`. 149 150* [`bytes`]: Utilities for working with bytes, including efficient byte buffers. 151 152* [`loom`]: A testing tool for concurrent Rust code 153 154[`warp`]: https://github.com/seanmonstar/warp 155[`hyper`]: https://github.com/hyperium/hyper 156[`tonic`]: https://github.com/hyperium/tonic 157[`tower`]: https://github.com/tower-rs/tower 158[`loom`]: https://github.com/tokio-rs/loom 159[`rdbc`]: https://github.com/tokio-rs/rdbc 160[`tracing`]: https://github.com/tokio-rs/tracing 161[`mio`]: https://github.com/tokio-rs/mio 162[`bytes`]: https://github.com/tokio-rs/bytes 163 164## Supported Rust Versions 165 166Tokio is built against the latest stable release. The minimum supported version 167is 1.45. The current Tokio version is not guaranteed to build on Rust versions 168earlier than the minimum supported version. 169 170## Release schedule 171 172Tokio doesn't follow a fixed release schedule, but we typically make one to two 173new minor releases each month. We make patch releases for bugfixes as necessary. 174 175## Bug patching policy 176 177For the purposes of making patch releases with bugfixes, we have designated 178certain minor releases as LTS (long term support) releases. Whenever a bug 179warrants a patch release with a fix for the bug, it will be backported and 180released as a new patch release for each LTS minor version. Our current LTS 181releases are: 182 183 * `1.8.x` - LTS release until February 2022. 184 185Each LTS release will continue to receive backported fixes for at least half a 186year. If you wish to use a fixed minor release in your project, we recommend 187that you use an LTS release. 188 189To use a fixed minor version, you can specify the version with a tilde. For 190example, to specify that you wish to use the newest `1.8.x` patch release, you 191can use the following dependency specification: 192```text 193tokio = { version = "~1.8", features = [...] } 194``` 195 196## License 197 198This project is licensed under the [MIT license]. 199 200[MIT license]: https://github.com/tokio-rs/tokio/blob/master/LICENSE 201 202### Contribution 203 204Unless you explicitly state otherwise, any contribution intentionally submitted 205for inclusion in Tokio by you, shall be licensed as MIT, without any additional 206terms or conditions. 207
