third_party/rust/tokio/README.md

   1 # Tokio
   2
   3 A runtime for writing reliable, asynchronous, and slim applications with
   4 the 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
  36 Tokio is an event-driven, non-blocking I/O platform for writing
  37 asynchronous applications with the Rust programming language. At a high
  38 level, 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
  45 These components provide the runtime components necessary for building
  46 an 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
  53 A basic TCP echo server with Tokio.
  54
  55 Make sure you activated the full features of the tokio crate on Cargo.toml:
  56
  57 ```toml
  58 [dependencies]
  59 tokio = { version = "1.29.1", features = ["full"] }
  60 ```
  61 Then, on your main.rs:
  62
  63 ```rust,no_run
  64 use tokio::net::TcpListener;
  65 use tokio::io::{AsyncReadExt, AsyncWriteExt};
  66
  67 #[tokio::main]
  68 async 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
 100 More 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
 106 To see a list of the available features flags that can be enabled, check our
 107 [docs][feature-flag-docs].
 108
 109 ## Getting Help
 110
 111 First, 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
 113 the [Tokio Discord server][chat]. We would be happy to try to answer your
 114 question. 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
 125 you! We have a [contributing guide][guide] to help you get involved in the Tokio
 126 project.
 127
 128 [guide]: https://github.com/tokio-rs/tokio/blob/master/CONTRIBUTING.md
 129
 130 ## Related Projects
 131
 132 In addition to the crates in this repository, the Tokio project also maintains
 133 several 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
 166 The 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 <!--
 177 When 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
 188 Tokio will keep a rolling MSRV (minimum supported rust version) policy of **at
 189 least** 6 months. When increasing the MSRV, the new Rust version must have been
 190 released at least six months ago. The current MSRV is 1.56.0.
 191
 192 Note that the MSRV is not increased automatically, and only as part of a minor
 193 release. The MSRV history for past minor releases can be found below:
 194
 195  * 1.27 to now - Rust 1.56
 196  * 1.17 to 1.26 - Rust 1.49
 197  * 1.15 to 1.16 - Rust 1.46
 198  * 1.0 to 1.14 - Rust 1.45
 199
 200 Note that although we try to avoid the situation where a dependency transitively
 201 increases the MSRV of Tokio, we do not guarantee that this does not happen.
 202 However, every minor release will have some set of versions of dependencies that
 203 works with the MSRV of that minor release.
 204
 205 ## Release schedule
 206
 207 Tokio doesn't follow a fixed release schedule, but we typically make one to two
 208 new minor releases each month. We make patch releases for bugfixes as necessary.
 209
 210 ## Bug patching policy
 211
 212 For the purposes of making patch releases with bugfixes, we have designated
 213 certain minor releases as LTS (long term support) releases. Whenever a bug
 214 warrants a patch release with a fix for the bug, it will be backported and
 215 released as a new patch release for each LTS minor version. Our current LTS
 216 releases are:
 217
 218  * `1.18.x` - LTS release until June 2023. (MSRV 1.49)
 219  * `1.20.x` - LTS release until September 2023. (MSRV 1.49)
 220  * `1.25.x` - LTS release until March 2024. (MSRV 1.49)
 221
 222 Each LTS release will continue to receive backported fixes for at least a year.
 223 If you wish to use a fixed minor release in your project, we recommend that you
 224 use an LTS release.
 225
 226 To use a fixed minor version, you can specify the version with a tilde. For
 227 example, to specify that you wish to use the newest `1.18.x` patch release, you
 228 can use the following dependency specification:
 229 ```text
 230 tokio = { version = "~1.18", features = [...] }
 231 ```
 232
 233 ## License
 234
 235 This project is licensed under the [MIT license].
 236
 237 [MIT license]: https://github.com/tokio-rs/tokio/blob/master/LICENSE
 238
 239 ### Contribution
 240
 241 Unless you explicitly state otherwise, any contribution intentionally submitted
 242 for inclusion in Tokio by you, shall be licensed as MIT, without any additional
 243 terms or conditions.