README.android
1The Android.bp file contains the "winapi" feature even though it is not used on Android. This gets added automatically by cargo2android.py and removing it would be non-trivial. It should have no effect on the crate, as the code is included only on Windows, so we keep it rather than maintaining a patch to remove it.
2
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.25.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## Changelog
165
166The Tokio repository contains multiple crates. Each crate has its own changelog.
167
168 * `tokio` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio/CHANGELOG.md)
169 * `tokio-util` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-util/CHANGELOG.md)
170 * `tokio-stream` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-stream/CHANGELOG.md)
171 * `tokio-macros` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-macros/CHANGELOG.md)
172 * `tokio-test` - [view changelog](https://github.com/tokio-rs/tokio/blob/master/tokio-test/CHANGELOG.md)
173
174## Supported Rust Versions
175
176<!--
177When updating this, also update:
178- .github/workflows/ci.yml
179- CONTRIBUTING.md
180- README.md
181- tokio/README.md
182- tokio/Cargo.toml
183- tokio-util/Cargo.toml
184- tokio-test/Cargo.toml
185- tokio-stream/Cargo.toml
186-->
187
188Tokio will keep a rolling MSRV (minimum supported rust version) policy of **at
189least** 6 months. When increasing the MSRV, the new Rust version must have been
190released at least six months ago. The current MSRV is 1.49.0.
191
192## Release schedule
193
194Tokio doesn't follow a fixed release schedule, but we typically make one to two
195new minor releases each month. We make patch releases for bugfixes as necessary.
196
197## Bug patching policy
198
199For the purposes of making patch releases with bugfixes, we have designated
200certain minor releases as LTS (long term support) releases. Whenever a bug
201warrants a patch release with a fix for the bug, it will be backported and
202released as a new patch release for each LTS minor version. Our current LTS
203releases are:
204
205 * `1.18.x` - LTS release until June 2023
206 * `1.20.x` - LTS release until September 2023.
207
208Each LTS release will continue to receive backported fixes for at least a year.
209If you wish to use a fixed minor release in your project, we recommend that you
210use an LTS release.
211
212To use a fixed minor version, you can specify the version with a tilde. For
213example, to specify that you wish to use the newest `1.18.x` patch release, you
214can use the following dependency specification:
215```text
216tokio = { version = "~1.18", features = [...] }
217```
218
219## License
220
221This project is licensed under the [MIT license].
222
223[MIT license]: https://github.com/tokio-rs/tokio/blob/master/LICENSE
224
225### Contribution
226
227Unless you explicitly state otherwise, any contribution intentionally submitted
228for inclusion in Tokio by you, shall be licensed as MIT, without any additional
229terms or conditions.
230
