README.md
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.16.1", 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.46. 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 * `1.14.x` - LTS release until June 2022.
185
186Each LTS release will continue to receive backported fixes for at least half a
187year. If you wish to use a fixed minor release in your project, we recommend
188that you use an LTS release.
189
190To use a fixed minor version, you can specify the version with a tilde. For
191example, to specify that you wish to use the newest `1.8.x` patch release, you
192can use the following dependency specification:
193```text
194tokio = { version = "~1.8", features = [...] }
195```
196
197## License
198
199This project is licensed under the [MIT license].
200
201[MIT license]: https://github.com/tokio-rs/tokio/blob/master/LICENSE
202
203### Contribution
204
205Unless you explicitly state otherwise, any contribution intentionally submitted
206for inclusion in Tokio by you, shall be licensed as MIT, without any additional
207terms or conditions.
208
