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][azure-badge]][azure-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[azure-badge]: https://dev.azure.com/tokio-rs/Tokio/_apis/build/status/tokio-rs.tokio?branchName=master
25[azure-url]: https://dev.azure.com/tokio-rs/Tokio/_build/latest?definitionId=1&branchName=master
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/docs/overview/) |
31[API Docs](https://docs.rs/tokio/latest/tokio) |
32[Roadmap](https://github.com/tokio-rs/tokio/blob/master/ROADMAP.md) |
33[Chat](https://discord.gg/tokio)
34
35## Overview
36
37Tokio is an event-driven, non-blocking I/O platform for writing
38asynchronous applications with the Rust programming language. At a high
39level, it provides a few major components:
40
41* A multithreaded, work-stealing based task [scheduler].
42* A reactor backed by the operating system's event queue (epoll, kqueue,
43 IOCP, etc...).
44* Asynchronous [TCP and UDP][net] sockets.
45
46These components provide the runtime components necessary for building
47an asynchronous application.
48
49[net]: https://docs.rs/tokio/latest/tokio/net/index.html
50[scheduler]: https://docs.rs/tokio/latest/tokio/runtime/index.html
51
52## Example
53
54A basic TCP echo server with Tokio:
55
56```rust,no_run
57use tokio::net::TcpListener;
58use tokio::prelude::*;
59
60#[tokio::main]
61async fn main() -> Result<(), Box<dyn std::error::Error>> {
62 let mut listener = TcpListener::bind("127.0.0.1:8080").await?;
63
64 loop {
65 let (mut socket, _) = listener.accept().await?;
66
67 tokio::spawn(async move {
68 let mut buf = [0; 1024];
69
70 // In a loop, read data from the socket and write the data back.
71 loop {
72 let n = match socket.read(&mut buf).await {
73 // socket closed
74 Ok(n) if n == 0 => return,
75 Ok(n) => n,
76 Err(e) => {
77 eprintln!("failed to read from socket; err = {:?}", e);
78 return;
79 }
80 };
81
82 // Write the data back
83 if let Err(e) = socket.write_all(&buf[0..n]).await {
84 eprintln!("failed to write to socket; err = {:?}", e);
85 return;
86 }
87 }
88 });
89 }
90}
91```
92
93More examples can be found [here][examples]. For a larger "real world" example, see the
94[mini-redis] repository.
95
96[examples]: https://github.com/tokio-rs/tokio/tree/master/examples
97[mini-redis]: https://github.com/tokio-rs/mini-redis/
98
99## Getting Help
100
101First, see if the answer to your question can be found in the [Guides] or the
102[API documentation]. If the answer is not there, there is an active community in
103the [Tokio Discord server][chat]. We would be happy to try to answer your
104question. You can also ask your question on [the discussions page][discussions].
105
106[Guides]: https://tokio.rs/docs/overview/
107[API documentation]: https://docs.rs/tokio/latest/tokio
108[chat]: https://discord.gg/tokio
109[discussions]: https://github.com/tokio-rs/tokio/discussions
110
111## Contributing
112
113:balloon: Thanks for your help improving the project! We are so happy to have
114you! We have a [contributing guide][guide] to help you get involved in the Tokio
115project.
116
117[guide]: https://github.com/tokio-rs/tokio/blob/master/CONTRIBUTING.md
118
119## Related Projects
120
121In addition to the crates in this repository, the Tokio project also maintains
122several other libraries, including:
123
124* [`hyper`]: A fast and correct HTTP/1.1 and HTTP/2 implementation for Rust.
125
126* [`tonic`]: A gRPC over HTTP/2 implementation focused on high performance, interoperability, and flexibility.
127
128* [`warp`]: A super-easy, composable, web server framework for warp speeds.
129
130* [`tower`]: A library of modular and reusable components for building robust networking clients and servers.
131
132* [`tracing`] (formerly `tokio-trace`): A framework for application-level
133 tracing and async-aware diagnostics.
134
135* [`rdbc`]: A Rust database connectivity library for MySQL, Postgres and SQLite.
136
137* [`mio`]: A low-level, cross-platform abstraction over OS I/O APIs that powers
138 `tokio`.
139
140* [`bytes`]: Utilities for working with bytes, including efficient byte buffers.
141
142* [`loom`]: A testing tool for concurrent Rust code
143
144[`warp`]: https://github.com/seanmonstar/warp
145[`hyper`]: https://github.com/hyperium/hyper
146[`tonic`]: https://github.com/hyperium/tonic
147[`tower`]: https://github.com/tower-rs/tower
148[`loom`]: https://github.com/tokio-rs/loom
149[`rdbc`]: https://github.com/tokio-rs/rdbc
150[`tracing`]: https://github.com/tokio-rs/tracing
151[`mio`]: https://github.com/tokio-rs/mio
152[`bytes`]: https://github.com/tokio-rs/bytes
153
154## Supported Rust Versions
155
156Tokio is built against the latest stable release. The minimum supported version is 1.39.
157The current Tokio version is not guaranteed to build on Rust versions earlier than the
158minimum supported version.
159
160## License
161
162This project is licensed under the [MIT license].
163
164[MIT license]: https://github.com/tokio-rs/tokio/blob/master/LICENSE
165
166### Contribution
167
168Unless you explicitly state otherwise, any contribution intentionally submitted
169for inclusion in Tokio by you, shall be licensed as MIT, without any additional
170terms or conditions.
171
