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.42.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* [`axum`]: A web application framework that focuses on ergonomics and modularity.
136
137* [`hyper`]: A fast and correct HTTP/1.1 and HTTP/2 implementation for Rust.
138
139* [`tonic`]: A gRPC over HTTP/2 implementation focused on high performance, interoperability, and flexibility.
140
141* [`warp`]: A super-easy, composable, web server framework for warp speeds.
142
143* [`tower`]: A library of modular and reusable components for building robust networking clients and servers.
144
145* [`tracing`] (formerly `tokio-trace`): A framework for application-level tracing and async-aware diagnostics.
146
147* [`mio`]: A low-level, cross-platform abstraction over OS I/O APIs that powers `tokio`.
148
149* [`bytes`]: Utilities for working with bytes, including efficient byte buffers.
150
151* [`loom`]: A testing tool for concurrent Rust code.
152
153[`axum`]: https://github.com/tokio-rs/axum
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[`tracing`]: https://github.com/tokio-rs/tracing
160[`mio`]: https://github.com/tokio-rs/mio
161[`bytes`]: https://github.com/tokio-rs/bytes
162
163## Changelog
164
165The Tokio repository contains multiple crates. Each crate has its own changelog.
166
167 * `tokio` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio/CHANGELOG.md)
168 * `tokio-util` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-util/CHANGELOG.md)
169 * `tokio-stream` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-stream/CHANGELOG.md)
170 * `tokio-macros` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-macros/CHANGELOG.md)
171 * `tokio-test` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-test/CHANGELOG.md)
172
173## Supported Rust Versions
174
175<!--
176When updating this, also update:
177- .github/workflows/ci.yml
178- CONTRIBUTING.md
179- README.md
180- tokio/README.md
181- tokio/Cargo.toml
182- tokio-util/Cargo.toml
183- tokio-test/Cargo.toml
184- tokio-stream/Cargo.toml
185-->
186
187Tokio will keep a rolling MSRV (minimum supported rust version) policy of **at
188least** 6 months. When increasing the MSRV, the new Rust version must have been
189released at least six months ago. The current MSRV is 1.70.
190
191Note that the MSRV is not increased automatically, and only as part of a minor
192release. The MSRV history for past minor releases can be found below:
193
194 * 1.39 to now  - Rust 1.70
195 * 1.30 to 1.38 - Rust 1.63
196 * 1.27 to 1.29 - Rust 1.56
197 * 1.17 to 1.26 - Rust 1.49
198 * 1.15 to 1.16 - Rust 1.46
199 * 1.0 to 1.14 - Rust 1.45
200
201Note that although we try to avoid the situation where a dependency transitively
202increases the MSRV of Tokio, we do not guarantee that this does not happen.
203However, every minor release will have some set of versions of dependencies that
204works with the MSRV of that minor release.
205
206## Release schedule
207
208Tokio doesn't follow a fixed release schedule, but we typically make one to two
209new minor releases each month. We make patch releases for bugfixes as necessary.
210
211## Bug patching policy
212
213For the purposes of making patch releases with bugfixes, we have designated
214certain minor releases as LTS (long term support) releases. Whenever a bug
215warrants a patch release with a fix for the bug, it will be backported and
216released as a new patch release for each LTS minor version. Our current LTS
217releases are:
218
219 * `1.36.x` - LTS release until March 2025. (MSRV 1.63)
220 * `1.38.x` - LTS release until July 2025. (MSRV 1.63)
221
222Each LTS release will continue to receive backported fixes for at least a year.
223If you wish to use a fixed minor release in your project, we recommend that you
224use an LTS release.
225
226To use a fixed minor version, you can specify the version with a tilde. For
227example, to specify that you wish to use the newest `1.32.x` patch release, you
228can use the following dependency specification:
229```text
230tokio = { version = "~1.32", features = [...] }
231```
232
233### Previous LTS releases
234
235 * `1.8.x` - LTS release until February 2022.
236 * `1.14.x` - LTS release until June 2022.
237 * `1.18.x` - LTS release until June 2023.
238 * `1.20.x` - LTS release until September 2023.
239 * `1.25.x` - LTS release until March 2024.
240 * `1.32.x` - LTS release until September 2024.
241
242## License
243
244This project is licensed under the [MIT license].
245
246[MIT license]: https://github.com/tokio-rs/tokio/blob/master/LICENSE
247
248### Contribution
249
250Unless you explicitly state otherwise, any contribution intentionally submitted
251for inclusion in Tokio by you, shall be licensed as MIT, without any additional
252terms or conditions.
253