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/tokio/tutorial) |
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
99To see a list of the available features flags that can be enabled, check our
100[docs][feature-flag-docs].
101
102## Getting Help
103
104First, see if the answer to your question can be found in the [Guides] or the
105[API documentation]. If the answer is not there, there is an active community in
106the [Tokio Discord server][chat]. We would be happy to try to answer your
107question. You can also ask your question on [the discussions page][discussions].
108
109[Guides]: https://tokio.rs/tokio/tutorial
110[API documentation]: https://docs.rs/tokio/latest/tokio
111[chat]: https://discord.gg/tokio
112[discussions]: https://github.com/tokio-rs/tokio/discussions
113[feature-flag-docs]: https://docs.rs/tokio/#feature-flags
114
115## Contributing
116
117:balloon: Thanks for your help improving the project! We are so happy to have
118you! We have a [contributing guide][guide] to help you get involved in the Tokio
119project.
120
121[guide]: https://github.com/tokio-rs/tokio/blob/master/CONTRIBUTING.md
122
123## Related Projects
124
125In addition to the crates in this repository, the Tokio project also maintains
126several other libraries, including:
127
128* [`hyper`]: A fast and correct HTTP/1.1 and HTTP/2 implementation for Rust.
129
130* [`tonic`]: A gRPC over HTTP/2 implementation focused on high performance, interoperability, and flexibility.
131
132* [`warp`]: A super-easy, composable, web server framework for warp speeds.
133
134* [`tower`]: A library of modular and reusable components for building robust networking clients and servers.
135
136* [`tracing`] (formerly `tokio-trace`): A framework for application-level
137 tracing and async-aware diagnostics.
138
139* [`rdbc`]: A Rust database connectivity library for MySQL, Postgres and SQLite.
140
141* [`mio`]: A low-level, cross-platform abstraction over OS I/O APIs that powers
142 `tokio`.
143
144* [`bytes`]: Utilities for working with bytes, including efficient byte buffers.
145
146* [`loom`]: A testing tool for concurrent Rust code
147
148[`warp`]: https://github.com/seanmonstar/warp
149[`hyper`]: https://github.com/hyperium/hyper
150[`tonic`]: https://github.com/hyperium/tonic
151[`tower`]: https://github.com/tower-rs/tower
152[`loom`]: https://github.com/tokio-rs/loom
153[`rdbc`]: https://github.com/tokio-rs/rdbc
154[`tracing`]: https://github.com/tokio-rs/tracing
155[`mio`]: https://github.com/tokio-rs/mio
156[`bytes`]: https://github.com/tokio-rs/bytes
157
158## Supported Rust Versions
159
160Tokio is built against the latest stable release. The minimum supported version is 1.39.
161The current Tokio version is not guaranteed to build on Rust versions earlier than the
162minimum supported version.
163
164## License
165
166This project is licensed under the [MIT license].
167
168[MIT license]: https://github.com/tokio-rs/tokio/blob/master/LICENSE
169
170### Contribution
171
172Unless you explicitly state otherwise, any contribution intentionally submitted
173for inclusion in Tokio by you, shall be licensed as MIT, without any additional
174terms or conditions.
175
