| 1 | #![allow ( |
| 2 | clippy::cognitive_complexity, |
|---|
| 3 | clippy::large_enum_variant, |
|---|
| 4 | clippy::module_inception, |
|---|
| 5 | clippy::needless_doctest_main, |
|---|
| 6 | clippy::declare_interior_mutable_const |
|---|
| 7 | )] |
|---|
| 8 | #![warn ( |
|---|
| 9 | missing_debug_implementations, |
|---|
| 10 | missing_docs, |
|---|
| 11 | rust_2018_idioms, |
|---|
| 12 | unreachable_pub |
|---|
| 13 | )] |
|---|
| 14 | #![deny (unused_must_use)] |
|---|
| 15 | #![doc (test( |
|---|
| 16 | no_crate_inject, |
|---|
| 17 | attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables)) |
|---|
| 18 | ))] |
|---|
| 19 | #![cfg_attr (docsrs, feature(doc_cfg))] |
|---|
| 20 | #![cfg_attr (docsrs, allow(unused_attributes))] |
|---|
| 21 | #![cfg_attr (loom, allow(dead_code, unreachable_pub))] |
|---|
| 22 | |
|---|
| 23 | //! A runtime for writing reliable network applications without compromising speed. |
|---|
| 24 | //! |
|---|
| 25 | //! Tokio is an event-driven, non-blocking I/O platform for writing asynchronous |
|---|
| 26 | //! applications with the Rust programming language. At a high level, it |
|---|
| 27 | //! provides a few major components: |
|---|
| 28 | //! |
|---|
| 29 | //! * Tools for [working with asynchronous tasks][tasks], including |
|---|
| 30 | //! [synchronization primitives and channels][sync] and [timeouts, sleeps, and |
|---|
| 31 | //! intervals][time]. |
|---|
| 32 | //! * APIs for [performing asynchronous I/O][io], including [TCP and UDP][net] sockets, |
|---|
| 33 | //! [filesystem][fs] operations, and [process] and [signal] management. |
|---|
| 34 | //! * A [runtime] for executing asynchronous code, including a task scheduler, |
|---|
| 35 | //! an I/O driver backed by the operating system's event queue (epoll, kqueue, |
|---|
| 36 | //! IOCP, etc...), and a high performance timer. |
|---|
| 37 | //! |
|---|
| 38 | //! Guide level documentation is found on the [website]. |
|---|
| 39 | //! |
|---|
| 40 | //! [tasks]: #working-with-tasks |
|---|
| 41 | //! [sync]: crate::sync |
|---|
| 42 | //! [time]: crate::time |
|---|
| 43 | //! [io]: #asynchronous-io |
|---|
| 44 | //! [net]: crate::net |
|---|
| 45 | //! [fs]: crate::fs |
|---|
| 46 | //! [process]: crate::process |
|---|
| 47 | //! [signal]: crate::signal |
|---|
| 48 | //! [fs]: crate::fs |
|---|
| 49 | //! [runtime]: crate::runtime |
|---|
| 50 | //! [website]: https://tokio.rs/tokio/tutorial |
|---|
| 51 | //! |
|---|
| 52 | //! # A Tour of Tokio |
|---|
| 53 | //! |
|---|
| 54 | //! Tokio consists of a number of modules that provide a range of functionality |
|---|
| 55 | //! essential for implementing asynchronous applications in Rust. In this |
|---|
| 56 | //! section, we will take a brief tour of Tokio, summarizing the major APIs and |
|---|
| 57 | //! their uses. |
|---|
| 58 | //! |
|---|
| 59 | //! The easiest way to get started is to enable all features. Do this by |
|---|
| 60 | //! enabling the `full` feature flag: |
|---|
| 61 | //! |
|---|
| 62 | //! ```toml |
|---|
| 63 | //! tokio = { version = "1", features = ["full"] } |
|---|
| 64 | //! ``` |
|---|
| 65 | //! |
|---|
| 66 | //! ### Authoring applications |
|---|
| 67 | //! |
|---|
| 68 | //! Tokio is great for writing applications and most users in this case shouldn't |
|---|
| 69 | //! worry too much about what features they should pick. If you're unsure, we suggest |
|---|
| 70 | //! going with `full` to ensure that you don't run into any road blocks while you're |
|---|
| 71 | //! building your application. |
|---|
| 72 | //! |
|---|
| 73 | //! #### Example |
|---|
| 74 | //! |
|---|
| 75 | //! This example shows the quickest way to get started with Tokio. |
|---|
| 76 | //! |
|---|
| 77 | //! ```toml |
|---|
| 78 | //! tokio = { version = "1", features = ["full"] } |
|---|
| 79 | //! ``` |
|---|
| 80 | //! |
|---|
| 81 | //! ### Authoring libraries |
|---|
| 82 | //! |
|---|
| 83 | //! As a library author your goal should be to provide the lightest weight crate |
|---|
| 84 | //! that is based on Tokio. To achieve this you should ensure that you only enable |
|---|
| 85 | //! the features you need. This allows users to pick up your crate without having |
|---|
| 86 | //! to enable unnecessary features. |
|---|
| 87 | //! |
|---|
| 88 | //! #### Example |
|---|
| 89 | //! |
|---|
| 90 | //! This example shows how you may want to import features for a library that just |
|---|
| 91 | //! needs to `tokio::spawn` and use a `TcpStream`. |
|---|
| 92 | //! |
|---|
| 93 | //! ```toml |
|---|
| 94 | //! tokio = { version = "1", features = ["rt", "net"] } |
|---|
| 95 | //! ``` |
|---|
| 96 | //! |
|---|
| 97 | //! ## Working With Tasks |
|---|
| 98 | //! |
|---|
| 99 | //! Asynchronous programs in Rust are based around lightweight, non-blocking |
|---|
| 100 | //! units of execution called [_tasks_][tasks]. The [`tokio::task`] module provides |
|---|
| 101 | //! important tools for working with tasks: |
|---|
| 102 | //! |
|---|
| 103 | //! * The [`spawn`] function and [`JoinHandle`] type, for scheduling a new task |
|---|
| 104 | //! on the Tokio runtime and awaiting the output of a spawned task, respectively, |
|---|
| 105 | //! * Functions for [running blocking operations][blocking] in an asynchronous |
|---|
| 106 | //! task context. |
|---|
| 107 | //! |
|---|
| 108 | //! The [`tokio::task`] module is present only when the "rt" feature flag |
|---|
| 109 | //! is enabled. |
|---|
| 110 | //! |
|---|
| 111 | //! [tasks]: task/index.html#what-are-tasks |
|---|
| 112 | //! [`tokio::task`]: crate::task |
|---|
| 113 | //! [`spawn`]: crate::task::spawn() |
|---|
| 114 | //! [`JoinHandle`]: crate::task::JoinHandle |
|---|
| 115 | //! [blocking]: task/index.html#blocking-and-yielding |
|---|
| 116 | //! |
|---|
| 117 | //! The [`tokio::sync`] module contains synchronization primitives to use when |
|---|
| 118 | //! needing to communicate or share data. These include: |
|---|
| 119 | //! |
|---|
| 120 | //! * channels ([`oneshot`], [`mpsc`], [`watch`], and [`broadcast`]), for sending values |
|---|
| 121 | //! between tasks, |
|---|
| 122 | //! * a non-blocking [`Mutex`], for controlling access to a shared, mutable |
|---|
| 123 | //! value, |
|---|
| 124 | //! * an asynchronous [`Barrier`] type, for multiple tasks to synchronize before |
|---|
| 125 | //! beginning a computation. |
|---|
| 126 | //! |
|---|
| 127 | //! The `tokio::sync` module is present only when the "sync" feature flag is |
|---|
| 128 | //! enabled. |
|---|
| 129 | //! |
|---|
| 130 | //! [`tokio::sync`]: crate::sync |
|---|
| 131 | //! [`Mutex`]: crate::sync::Mutex |
|---|
| 132 | //! [`Barrier`]: crate::sync::Barrier |
|---|
| 133 | //! [`oneshot`]: crate::sync::oneshot |
|---|
| 134 | //! [`mpsc`]: crate::sync::mpsc |
|---|
| 135 | //! [`watch`]: crate::sync::watch |
|---|
| 136 | //! [`broadcast`]: crate::sync::broadcast |
|---|
| 137 | //! |
|---|
| 138 | //! The [`tokio::time`] module provides utilities for tracking time and |
|---|
| 139 | //! scheduling work. This includes functions for setting [timeouts][timeout] for |
|---|
| 140 | //! tasks, [sleeping][sleep] work to run in the future, or [repeating an operation at an |
|---|
| 141 | //! interval][interval]. |
|---|
| 142 | //! |
|---|
| 143 | //! In order to use `tokio::time`, the "time" feature flag must be enabled. |
|---|
| 144 | //! |
|---|
| 145 | //! [`tokio::time`]: crate::time |
|---|
| 146 | //! [sleep]: crate::time::sleep() |
|---|
| 147 | //! [interval]: crate::time::interval() |
|---|
| 148 | //! [timeout]: crate::time::timeout() |
|---|
| 149 | //! |
|---|
| 150 | //! Finally, Tokio provides a _runtime_ for executing asynchronous tasks. Most |
|---|
| 151 | //! applications can use the [`#[tokio::main]`][main] macro to run their code on the |
|---|
| 152 | //! Tokio runtime. However, this macro provides only basic configuration options. As |
|---|
| 153 | //! an alternative, the [`tokio::runtime`] module provides more powerful APIs for configuring |
|---|
| 154 | //! and managing runtimes. You should use that module if the `#[tokio::main]` macro doesn't |
|---|
| 155 | //! provide the functionality you need. |
|---|
| 156 | //! |
|---|
| 157 | //! Using the runtime requires the "rt" or "rt-multi-thread" feature flags, to |
|---|
| 158 | //! enable the current-thread [single-threaded scheduler][rt] and the [multi-thread |
|---|
| 159 | //! scheduler][rt-multi-thread], respectively. See the [`runtime` module |
|---|
| 160 | //! documentation][rt-features] for details. In addition, the "macros" feature |
|---|
| 161 | //! flag enables the `#[tokio::main]` and `#[tokio::test]` attributes. |
|---|
| 162 | //! |
|---|
| 163 | //! [main]: attr.main.html |
|---|
| 164 | //! [`tokio::runtime`]: crate::runtime |
|---|
| 165 | //! [`Builder`]: crate::runtime::Builder |
|---|
| 166 | //! [`Runtime`]: crate::runtime::Runtime |
|---|
| 167 | //! [rt]: runtime/index.html#current-thread-scheduler |
|---|
| 168 | //! [rt-multi-thread]: runtime/index.html#multi-thread-scheduler |
|---|
| 169 | //! [rt-features]: runtime/index.html#runtime-scheduler |
|---|
| 170 | //! |
|---|
| 171 | //! ## CPU-bound tasks and blocking code |
|---|
| 172 | //! |
|---|
| 173 | //! Tokio is able to concurrently run many tasks on a few threads by repeatedly |
|---|
| 174 | //! swapping the currently running task on each thread. However, this kind of |
|---|
| 175 | //! swapping can only happen at `.await` points, so code that spends a long time |
|---|
| 176 | //! without reaching an `.await` will prevent other tasks from running. To |
|---|
| 177 | //! combat this, Tokio provides two kinds of threads: Core threads and blocking threads. |
|---|
| 178 | //! |
|---|
| 179 | //! The core threads are where all asynchronous code runs, and Tokio will by default |
|---|
| 180 | //! spawn one for each CPU core. You can use the environment variable `TOKIO_WORKER_THREADS` |
|---|
| 181 | //! to override the default value. |
|---|
| 182 | //! |
|---|
| 183 | //! The blocking threads are spawned on demand, can be used to run blocking code |
|---|
| 184 | //! that would otherwise block other tasks from running and are kept alive when |
|---|
| 185 | //! not used for a certain amount of time which can be configured with [`thread_keep_alive`]. |
|---|
| 186 | //! Since it is not possible for Tokio to swap out blocking tasks, like it |
|---|
| 187 | //! can do with asynchronous code, the upper limit on the number of blocking |
|---|
| 188 | //! threads is very large. These limits can be configured on the [`Builder`]. |
|---|
| 189 | //! |
|---|
| 190 | //! To spawn a blocking task, you should use the [`spawn_blocking`] function. |
|---|
| 191 | //! |
|---|
| 192 | //! [`Builder`]: crate::runtime::Builder |
|---|
| 193 | //! [`spawn_blocking`]: crate::task::spawn_blocking() |
|---|
| 194 | //! [`thread_keep_alive`]: crate::runtime::Builder::thread_keep_alive() |
|---|
| 195 | //! |
|---|
| 196 | //! ``` |
|---|
| 197 | //! #[tokio::main] |
|---|
| 198 | //! async fn main() { |
|---|
| 199 | //! // This is running on a core thread. |
|---|
| 200 | //! |
|---|
| 201 | //! let blocking_task = tokio::task::spawn_blocking(|| { |
|---|
| 202 | //! // This is running on a blocking thread. |
|---|
| 203 | //! // Blocking here is ok. |
|---|
| 204 | //! }); |
|---|
| 205 | //! |
|---|
| 206 | //! // We can wait for the blocking task like this: |
|---|
| 207 | //! // If the blocking task panics, the unwrap below will propagate the |
|---|
| 208 | //! // panic. |
|---|
| 209 | //! blocking_task.await.unwrap(); |
|---|
| 210 | //! } |
|---|
| 211 | //! ``` |
|---|
| 212 | //! |
|---|
| 213 | //! If your code is CPU-bound and you wish to limit the number of threads used |
|---|
| 214 | //! to run it, you should use a separate thread pool dedicated to CPU bound tasks. |
|---|
| 215 | //! For example, you could consider using the [rayon] library for CPU-bound |
|---|
| 216 | //! tasks. It is also possible to create an extra Tokio runtime dedicated to |
|---|
| 217 | //! CPU-bound tasks, but if you do this, you should be careful that the extra |
|---|
| 218 | //! runtime runs _only_ CPU-bound tasks, as IO-bound tasks on that runtime |
|---|
| 219 | //! will behave poorly. |
|---|
| 220 | //! |
|---|
| 221 | //! Hint: If using rayon, you can use a [`oneshot`] channel to send the result back |
|---|
| 222 | //! to Tokio when the rayon task finishes. |
|---|
| 223 | //! |
|---|
| 224 | //! [rayon]: https://docs.rs/rayon |
|---|
| 225 | //! [`oneshot`]: crate::sync::oneshot |
|---|
| 226 | //! |
|---|
| 227 | //! ## Asynchronous IO |
|---|
| 228 | //! |
|---|
| 229 | //! As well as scheduling and running tasks, Tokio provides everything you need |
|---|
| 230 | //! to perform input and output asynchronously. |
|---|
| 231 | //! |
|---|
| 232 | //! The [`tokio::io`] module provides Tokio's asynchronous core I/O primitives, |
|---|
| 233 | //! the [`AsyncRead`], [`AsyncWrite`], and [`AsyncBufRead`] traits. In addition, |
|---|
| 234 | //! when the "io-util" feature flag is enabled, it also provides combinators and |
|---|
| 235 | //! functions for working with these traits, forming as an asynchronous |
|---|
| 236 | //! counterpart to [`std::io`]. |
|---|
| 237 | //! |
|---|
| 238 | //! Tokio also includes APIs for performing various kinds of I/O and interacting |
|---|
| 239 | //! with the operating system asynchronously. These include: |
|---|
| 240 | //! |
|---|
| 241 | //! * [`tokio::net`], which contains non-blocking versions of [TCP], [UDP], and |
|---|
| 242 | //! [Unix Domain Sockets][UDS] (enabled by the "net" feature flag), |
|---|
| 243 | //! * [`tokio::fs`], similar to [`std::fs`] but for performing filesystem I/O |
|---|
| 244 | //! asynchronously (enabled by the "fs" feature flag), |
|---|
| 245 | //! * [`tokio::signal`], for asynchronously handling Unix and Windows OS signals |
|---|
| 246 | //! (enabled by the "signal" feature flag), |
|---|
| 247 | //! * [`tokio::process`], for spawning and managing child processes (enabled by |
|---|
| 248 | //! the "process" feature flag). |
|---|
| 249 | //! |
|---|
| 250 | //! [`tokio::io`]: crate::io |
|---|
| 251 | //! [`AsyncRead`]: crate::io::AsyncRead |
|---|
| 252 | //! [`AsyncWrite`]: crate::io::AsyncWrite |
|---|
| 253 | //! [`AsyncBufRead`]: crate::io::AsyncBufRead |
|---|
| 254 | //! [`std::io`]: std::io |
|---|
| 255 | //! [`tokio::net`]: crate::net |
|---|
| 256 | //! [TCP]: crate::net::tcp |
|---|
| 257 | //! [UDP]: crate::net::UdpSocket |
|---|
| 258 | //! [UDS]: crate::net::unix |
|---|
| 259 | //! [`tokio::fs`]: crate::fs |
|---|
| 260 | //! [`std::fs`]: std::fs |
|---|
| 261 | //! [`tokio::signal`]: crate::signal |
|---|
| 262 | //! [`tokio::process`]: crate::process |
|---|
| 263 | //! |
|---|
| 264 | //! # Examples |
|---|
| 265 | //! |
|---|
| 266 | //! A simple TCP echo server: |
|---|
| 267 | //! |
|---|
| 268 | //! ```no_run |
|---|
| 269 | //! use tokio::net::TcpListener; |
|---|
| 270 | //! use tokio::io::{AsyncReadExt, AsyncWriteExt}; |
|---|
| 271 | //! |
|---|
| 272 | //! #[tokio::main] |
|---|
| 273 | //! async fn main() -> Result<(), Box<dyn std::error::Error>> { |
|---|
| 274 | //! let listener = TcpListener::bind("127.0.0.1:8080" ).await?; |
|---|
| 275 | //! |
|---|
| 276 | //! loop { |
|---|
| 277 | //! let (mut socket, _) = listener.accept().await?; |
|---|
| 278 | //! |
|---|
| 279 | //! tokio::spawn(async move { |
|---|
| 280 | //! let mut buf = [0; 1024]; |
|---|
| 281 | //! |
|---|
| 282 | //! // In a loop, read data from the socket and write the data back. |
|---|
| 283 | //! loop { |
|---|
| 284 | //! let n = match socket.read(&mut buf).await { |
|---|
| 285 | //! // socket closed |
|---|
| 286 | //! Ok(n) if n == 0 => return, |
|---|
| 287 | //! Ok(n) => n, |
|---|
| 288 | //! Err(e) => { |
|---|
| 289 | //! eprintln!("failed to read from socket; err = {:?}" , e); |
|---|
| 290 | //! return; |
|---|
| 291 | //! } |
|---|
| 292 | //! }; |
|---|
| 293 | //! |
|---|
| 294 | //! // Write the data back |
|---|
| 295 | //! if let Err(e) = socket.write_all(&buf[0..n]).await { |
|---|
| 296 | //! eprintln!("failed to write to socket; err = {:?}" , e); |
|---|
| 297 | //! return; |
|---|
| 298 | //! } |
|---|
| 299 | //! } |
|---|
| 300 | //! }); |
|---|
| 301 | //! } |
|---|
| 302 | //! } |
|---|
| 303 | //! ``` |
|---|
| 304 | //! |
|---|
| 305 | //! ## Feature flags |
|---|
| 306 | //! |
|---|
| 307 | //! Tokio uses a set of [feature flags] to reduce the amount of compiled code. It |
|---|
| 308 | //! is possible to just enable certain features over others. By default, Tokio |
|---|
| 309 | //! does not enable any features but allows one to enable a subset for their use |
|---|
| 310 | //! case. Below is a list of the available feature flags. You may also notice |
|---|
| 311 | //! above each function, struct and trait there is listed one or more feature flags |
|---|
| 312 | //! that are required for that item to be used. If you are new to Tokio it is |
|---|
| 313 | //! recommended that you use the `full` feature flag which will enable all public APIs. |
|---|
| 314 | //! Beware though that this will pull in many extra dependencies that you may not |
|---|
| 315 | //! need. |
|---|
| 316 | //! |
|---|
| 317 | //! - `full`: Enables all features listed below except `test-util` and `tracing`. |
|---|
| 318 | //! - `rt`: Enables `tokio::spawn`, the current-thread scheduler, |
|---|
| 319 | //! and non-scheduler utilities. |
|---|
| 320 | //! - `rt-multi-thread`: Enables the heavier, multi-threaded, work-stealing scheduler. |
|---|
| 321 | //! - `io-util`: Enables the IO based `Ext` traits. |
|---|
| 322 | //! - `io-std`: Enable `Stdout`, `Stdin` and `Stderr` types. |
|---|
| 323 | //! - `net`: Enables `tokio::net` types such as `TcpStream`, `UnixStream` and |
|---|
| 324 | //! `UdpSocket`, as well as (on Unix-like systems) `AsyncFd` and (on |
|---|
| 325 | //! FreeBSD) `PollAio`. |
|---|
| 326 | //! - `time`: Enables `tokio::time` types and allows the schedulers to enable |
|---|
| 327 | //! the built in timer. |
|---|
| 328 | //! - `process`: Enables `tokio::process` types. |
|---|
| 329 | //! - `macros`: Enables `#[tokio::main]` and `#[tokio::test]` macros. |
|---|
| 330 | //! - `sync`: Enables all `tokio::sync` types. |
|---|
| 331 | //! - `signal`: Enables all `tokio::signal` types. |
|---|
| 332 | //! - `fs`: Enables `tokio::fs` types. |
|---|
| 333 | //! - `test-util`: Enables testing based infrastructure for the Tokio runtime. |
|---|
| 334 | //! - `parking_lot`: As a potential optimization, use the _parking_lot_ crate's |
|---|
| 335 | //! synchronization primitives internally. Also, this |
|---|
| 336 | //! dependency is necessary to construct some of our primitives |
|---|
| 337 | //! in a const context. MSRV may increase according to the |
|---|
| 338 | //! _parking_lot_ release in use. |
|---|
| 339 | //! |
|---|
| 340 | //! _Note: `AsyncRead` and `AsyncWrite` traits do not require any features and are |
|---|
| 341 | //! always available._ |
|---|
| 342 | //! |
|---|
| 343 | //! ### Unstable features |
|---|
| 344 | //! |
|---|
| 345 | //! Some feature flags are only available when specifying the `tokio_unstable` flag: |
|---|
| 346 | //! |
|---|
| 347 | //! - `tracing`: Enables tracing events. |
|---|
| 348 | //! |
|---|
| 349 | //! Likewise, some parts of the API are only available with the same flag: |
|---|
| 350 | //! |
|---|
| 351 | //! - [`task::Builder`] |
|---|
| 352 | //! - Some methods on [`task::JoinSet`] |
|---|
| 353 | //! - [`runtime::RuntimeMetrics`] |
|---|
| 354 | //! - [`runtime::Builder::unhandled_panic`] |
|---|
| 355 | //! - [`task::Id`] |
|---|
| 356 | //! |
|---|
| 357 | //! This flag enables **unstable** features. The public API of these features |
|---|
| 358 | //! may break in 1.x releases. To enable these features, the `--cfg |
|---|
| 359 | //! tokio_unstable` argument must be passed to `rustc` when compiling. This |
|---|
| 360 | //! serves to explicitly opt-in to features which may break semver conventions, |
|---|
| 361 | //! since Cargo [does not yet directly support such opt-ins][unstable features]. |
|---|
| 362 | //! |
|---|
| 363 | //! You can specify it in your project's `.cargo/config.toml` file: |
|---|
| 364 | //! |
|---|
| 365 | //! ```toml |
|---|
| 366 | //! [build] |
|---|
| 367 | //! rustflags = ["--cfg", "tokio_unstable"] |
|---|
| 368 | //! ``` |
|---|
| 369 | //! |
|---|
| 370 | //! Alternatively, you can specify it with an environment variable: |
|---|
| 371 | //! |
|---|
| 372 | //! ```sh |
|---|
| 373 | //! ## Many *nix shells: |
|---|
| 374 | //! export RUSTFLAGS="--cfg tokio_unstable" |
|---|
| 375 | //! cargo build |
|---|
| 376 | //! ``` |
|---|
| 377 | //! |
|---|
| 378 | //! ```powershell |
|---|
| 379 | //! ## Windows PowerShell: |
|---|
| 380 | //! $Env:RUSTFLAGS="--cfg tokio_unstable" |
|---|
| 381 | //! cargo build |
|---|
| 382 | //! ``` |
|---|
| 383 | //! |
|---|
| 384 | //! [unstable features]: https://internals.rust-lang.org/t/feature-request-unstable-opt-in-non-transitive-crate-features/16193#why-not-a-crate-feature-2 |
|---|
| 385 | //! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section |
|---|
| 386 | //! |
|---|
| 387 | //! ## Supported platforms |
|---|
| 388 | //! |
|---|
| 389 | //! Tokio currently guarantees support for the following platforms: |
|---|
| 390 | //! |
|---|
| 391 | //! * Linux |
|---|
| 392 | //! * Windows |
|---|
| 393 | //! * Android (API level 21) |
|---|
| 394 | //! * macOS |
|---|
| 395 | //! * iOS |
|---|
| 396 | //! * FreeBSD |
|---|
| 397 | //! |
|---|
| 398 | //! Tokio will continue to support these platforms in the future. However, |
|---|
| 399 | //! future releases may change requirements such as the minimum required libc |
|---|
| 400 | //! version on Linux, the API level on Android, or the supported FreeBSD |
|---|
| 401 | //! release. |
|---|
| 402 | //! |
|---|
| 403 | //! Beyond the above platforms, Tokio is intended to work on all platforms |
|---|
| 404 | //! supported by the mio crate. You can find a longer list [in mio's |
|---|
| 405 | //! documentation][mio-supported]. However, these additional platforms may |
|---|
| 406 | //! become unsupported in the future. |
|---|
| 407 | //! |
|---|
| 408 | //! Note that Wine is considered to be a different platform from Windows. See |
|---|
| 409 | //! mio's documentation for more information on Wine support. |
|---|
| 410 | //! |
|---|
| 411 | //! [mio-supported]: https://crates.io/crates/mio#platforms |
|---|
| 412 | //! |
|---|
| 413 | //! ### WASM support |
|---|
| 414 | //! |
|---|
| 415 | //! Tokio has some limited support for the WASM platform. Without the |
|---|
| 416 | //! `tokio_unstable` flag, the following features are supported: |
|---|
| 417 | //! |
|---|
| 418 | //! * `sync` |
|---|
| 419 | //! * `macros` |
|---|
| 420 | //! * `io-util` |
|---|
| 421 | //! * `rt` |
|---|
| 422 | //! * `time` |
|---|
| 423 | //! |
|---|
| 424 | //! Enabling any other feature (including `full`) will cause a compilation |
|---|
| 425 | //! failure. |
|---|
| 426 | //! |
|---|
| 427 | //! The `time` module will only work on WASM platforms that have support for |
|---|
| 428 | //! timers (e.g. wasm32-wasi). The timing functions will panic if used on a WASM |
|---|
| 429 | //! platform that does not support timers. |
|---|
| 430 | //! |
|---|
| 431 | //! Note also that if the runtime becomes indefinitely idle, it will panic |
|---|
| 432 | //! immediately instead of blocking forever. On platforms that don't support |
|---|
| 433 | //! time, this means that the runtime can never be idle in any way. |
|---|
| 434 | //! |
|---|
| 435 | //! ### Unstable WASM support |
|---|
| 436 | //! |
|---|
| 437 | //! Tokio also has unstable support for some additional WASM features. This |
|---|
| 438 | //! requires the use of the `tokio_unstable` flag. |
|---|
| 439 | //! |
|---|
| 440 | //! Using this flag enables the use of `tokio::net` on the wasm32-wasi target. |
|---|
| 441 | //! However, not all methods are available on the networking types as WASI |
|---|
| 442 | //! currently does not support the creation of new sockets from within WASM. |
|---|
| 443 | //! Because of this, sockets must currently be created via the `FromRawFd` |
|---|
| 444 | //! trait. |
|---|
| 445 | |
|---|
| 446 | // Test that pointer width is compatible. This asserts that e.g. usize is at |
|---|
| 447 | // least 32 bits, which a lot of components in Tokio currently assumes. |
|---|
| 448 | // |
|---|
| 449 | // TODO: improve once we have MSRV access to const eval to make more flexible. |
|---|
| 450 | #[cfg (not(any( |
|---|
| 451 | target_pointer_width = "32" , |
|---|
| 452 | target_pointer_width = "64" , |
|---|
| 453 | target_pointer_width = "128" |
|---|
| 454 | )))] |
|---|
| 455 | compile_error! { |
|---|
| 456 | "Tokio requires the platform pointer width to be 32, 64, or 128 bits" |
|---|
| 457 | } |
|---|
| 458 | |
|---|
| 459 | #[cfg (all( |
|---|
| 460 | not(tokio_unstable), |
|---|
| 461 | target_family = "wasm" , |
|---|
| 462 | any( |
|---|
| 463 | feature = "fs" , |
|---|
| 464 | feature = "io-std" , |
|---|
| 465 | feature = "net" , |
|---|
| 466 | feature = "process" , |
|---|
| 467 | feature = "rt-multi-thread" , |
|---|
| 468 | feature = "signal" |
|---|
| 469 | ) |
|---|
| 470 | ))] |
|---|
| 471 | compile_error!("Only features sync,macros,io-util,rt,time are supported on wasm." ); |
|---|
| 472 | |
|---|
| 473 | #[cfg (all(not(tokio_unstable), tokio_taskdump))] |
|---|
| 474 | compile_error!("The `tokio_taskdump` feature requires `--cfg tokio_unstable`." ); |
|---|
| 475 | |
|---|
| 476 | #[cfg (all( |
|---|
| 477 | tokio_taskdump, |
|---|
| 478 | not(all( |
|---|
| 479 | target_os = "linux" , |
|---|
| 480 | any(target_arch = "aarch64" , target_arch = "x86" , target_arch = "x86_64" ) |
|---|
| 481 | )) |
|---|
| 482 | ))] |
|---|
| 483 | compile_error!( |
|---|
| 484 | "The `tokio_taskdump` feature is only currently supported on \ |
|---|
| 485 | linux, on `aarch64`, `x86` and `x86_64`." |
|---|
| 486 | ); |
|---|
| 487 | |
|---|
| 488 | // Includes re-exports used by macros. |
|---|
| 489 | // |
|---|
| 490 | // This module is not intended to be part of the public API. In general, any |
|---|
| 491 | // `doc(hidden)` code is not part of Tokio's public and stable API. |
|---|
| 492 | #[macro_use ] |
|---|
| 493 | #[doc (hidden)] |
|---|
| 494 | pub mod macros; |
|---|
| 495 | |
|---|
| 496 | cfg_fs! { |
|---|
| 497 | pub mod fs; |
|---|
| 498 | } |
|---|
| 499 | |
|---|
| 500 | mod future; |
|---|
| 501 | |
|---|
| 502 | pub mod io; |
|---|
| 503 | pub mod net; |
|---|
| 504 | |
|---|
| 505 | mod loom; |
|---|
| 506 | |
|---|
| 507 | cfg_process! { |
|---|
| 508 | pub mod process; |
|---|
| 509 | } |
|---|
| 510 | |
|---|
| 511 | #[cfg (any( |
|---|
| 512 | feature = "fs" , |
|---|
| 513 | feature = "io-std" , |
|---|
| 514 | feature = "net" , |
|---|
| 515 | all(windows, feature = "process" ), |
|---|
| 516 | ))] |
|---|
| 517 | mod blocking; |
|---|
| 518 | |
|---|
| 519 | cfg_rt! { |
|---|
| 520 | pub mod runtime; |
|---|
| 521 | } |
|---|
| 522 | cfg_not_rt! { |
|---|
| 523 | pub(crate) mod runtime; |
|---|
| 524 | } |
|---|
| 525 | |
|---|
| 526 | cfg_signal! { |
|---|
| 527 | pub mod signal; |
|---|
| 528 | } |
|---|
| 529 | |
|---|
| 530 | cfg_signal_internal! { |
|---|
| 531 | #[cfg (not(feature = "signal" ))] |
|---|
| 532 | #[allow (dead_code)] |
|---|
| 533 | #[allow (unreachable_pub)] |
|---|
| 534 | pub(crate) mod signal; |
|---|
| 535 | } |
|---|
| 536 | |
|---|
| 537 | cfg_sync! { |
|---|
| 538 | pub mod sync; |
|---|
| 539 | } |
|---|
| 540 | cfg_not_sync! { |
|---|
| 541 | mod sync; |
|---|
| 542 | } |
|---|
| 543 | |
|---|
| 544 | pub mod task; |
|---|
| 545 | cfg_rt! { |
|---|
| 546 | pub use task::spawn; |
|---|
| 547 | } |
|---|
| 548 | |
|---|
| 549 | cfg_time! { |
|---|
| 550 | pub mod time; |
|---|
| 551 | } |
|---|
| 552 | |
|---|
| 553 | mod trace { |
|---|
| 554 | use std::future::Future; |
|---|
| 555 | use std::pin::Pin; |
|---|
| 556 | use std::task::{Context, Poll}; |
|---|
| 557 | |
|---|
| 558 | cfg_taskdump! { |
|---|
| 559 | pub(crate) use crate::runtime::task::trace::trace_leaf; |
|---|
| 560 | } |
|---|
| 561 | |
|---|
| 562 | cfg_not_taskdump! { |
|---|
| 563 | #[inline (always)] |
|---|
| 564 | #[allow (dead_code)] |
|---|
| 565 | pub(crate) fn trace_leaf(_: &mut std::task::Context<'_>) -> std::task::Poll<()> { |
|---|
| 566 | std::task::Poll::Ready(()) |
|---|
| 567 | } |
|---|
| 568 | } |
|---|
| 569 | |
|---|
| 570 | #[cfg_attr (not(feature = "sync" ), allow(dead_code))] |
|---|
| 571 | pub(crate) fn async_trace_leaf() -> impl Future<Output = ()> { |
|---|
| 572 | struct Trace; |
|---|
| 573 | |
|---|
| 574 | impl Future for Trace { |
|---|
| 575 | type Output = (); |
|---|
| 576 | |
|---|
| 577 | #[inline (always)] |
|---|
| 578 | fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> { |
|---|
| 579 | trace_leaf(cx) |
|---|
| 580 | } |
|---|
| 581 | } |
|---|
| 582 | |
|---|
| 583 | Trace |
|---|
| 584 | } |
|---|
| 585 | } |
|---|
| 586 | |
|---|
| 587 | mod util; |
|---|
| 588 | |
|---|
| 589 | /// Due to the `Stream` trait's inclusion in `std` landing later than Tokio's 1.0 |
|---|
| 590 | /// release, most of the Tokio stream utilities have been moved into the [`tokio-stream`] |
|---|
| 591 | /// crate. |
|---|
| 592 | /// |
|---|
| 593 | /// # Why was `Stream` not included in Tokio 1.0? |
|---|
| 594 | /// |
|---|
| 595 | /// Originally, we had planned to ship Tokio 1.0 with a stable `Stream` type |
|---|
| 596 | /// but unfortunately the [RFC] had not been merged in time for `Stream` to |
|---|
| 597 | /// reach `std` on a stable compiler in time for the 1.0 release of Tokio. For |
|---|
| 598 | /// this reason, the team has decided to move all `Stream` based utilities to |
|---|
| 599 | /// the [`tokio-stream`] crate. While this is not ideal, once `Stream` has made |
|---|
| 600 | /// it into the standard library and the MSRV period has passed, we will implement |
|---|
| 601 | /// stream for our different types. |
|---|
| 602 | /// |
|---|
| 603 | /// While this may seem unfortunate, not all is lost as you can get much of the |
|---|
| 604 | /// `Stream` support with `async/await` and `while let` loops. It is also possible |
|---|
| 605 | /// to create a `impl Stream` from `async fn` using the [`async-stream`] crate. |
|---|
| 606 | /// |
|---|
| 607 | /// [`tokio-stream`]: https://docs.rs/tokio-stream |
|---|
| 608 | /// [`async-stream`]: https://docs.rs/async-stream |
|---|
| 609 | /// [RFC]: https://github.com/rust-lang/rfcs/pull/2996 |
|---|
| 610 | /// |
|---|
| 611 | /// # Example |
|---|
| 612 | /// |
|---|
| 613 | /// Convert a [`sync::mpsc::Receiver`] to an `impl Stream`. |
|---|
| 614 | /// |
|---|
| 615 | /// ```rust,no_run |
|---|
| 616 | /// use tokio::sync::mpsc; |
|---|
| 617 | /// |
|---|
| 618 | /// let (tx, mut rx) = mpsc::channel::<usize>(16); |
|---|
| 619 | /// |
|---|
| 620 | /// let stream = async_stream::stream! { |
|---|
| 621 | /// while let Some(item) = rx.recv().await { |
|---|
| 622 | /// yield item; |
|---|
| 623 | /// } |
|---|
| 624 | /// }; |
|---|
| 625 | /// ``` |
|---|
| 626 | pub mod stream {} |
|---|
| 627 | |
|---|
| 628 | // local re-exports of platform specific things, allowing for decent |
|---|
| 629 | // documentation to be shimmed in on docs.rs |
|---|
| 630 | |
|---|
| 631 | #[cfg (docsrs)] |
|---|
| 632 | pub mod doc; |
|---|
| 633 | |
|---|
| 634 | #[cfg (docsrs)] |
|---|
| 635 | #[allow (unused)] |
|---|
| 636 | pub(crate) use self::doc::os; |
|---|
| 637 | |
|---|
| 638 | #[cfg (not(docsrs))] |
|---|
| 639 | #[allow (unused)] |
|---|
| 640 | pub(crate) use std::os; |
|---|
| 641 | |
|---|
| 642 | cfg_macros! { |
|---|
| 643 | /// Implementation detail of the `select!` macro. This macro is **not** |
|---|
| 644 | /// intended to be used as part of the public API and is permitted to |
|---|
| 645 | /// change. |
|---|
| 646 | #[doc (hidden)] |
|---|
| 647 | pub use tokio_macros::select_priv_declare_output_enum; |
|---|
| 648 | |
|---|
| 649 | /// Implementation detail of the `select!` macro. This macro is **not** |
|---|
| 650 | /// intended to be used as part of the public API and is permitted to |
|---|
| 651 | /// change. |
|---|
| 652 | #[doc (hidden)] |
|---|
| 653 | pub use tokio_macros::select_priv_clean_pattern; |
|---|
| 654 | |
|---|
| 655 | cfg_rt! { |
|---|
| 656 | #[cfg (feature = "rt-multi-thread" )] |
|---|
| 657 | #[cfg (not(test))] // Work around for rust-lang/rust#62127 |
|---|
| 658 | #[cfg_attr (docsrs, doc(cfg(feature = "macros" )))] |
|---|
| 659 | #[doc (inline)] |
|---|
| 660 | pub use tokio_macros::main; |
|---|
| 661 | |
|---|
| 662 | #[cfg (feature = "rt-multi-thread" )] |
|---|
| 663 | #[cfg_attr (docsrs, doc(cfg(feature = "macros" )))] |
|---|
| 664 | #[doc (inline)] |
|---|
| 665 | pub use tokio_macros::test; |
|---|
| 666 | |
|---|
| 667 | cfg_not_rt_multi_thread! { |
|---|
| 668 | #[cfg (not(test))] // Work around for rust-lang/rust#62127 |
|---|
| 669 | #[doc (inline)] |
|---|
| 670 | pub use tokio_macros::main_rt as main; |
|---|
| 671 | |
|---|
| 672 | #[doc (inline)] |
|---|
| 673 | pub use tokio_macros::test_rt as test; |
|---|
| 674 | } |
|---|
| 675 | } |
|---|
| 676 | |
|---|
| 677 | // Always fail if rt is not enabled. |
|---|
| 678 | cfg_not_rt! { |
|---|
| 679 | #[cfg (not(test))] |
|---|
| 680 | #[doc (inline)] |
|---|
| 681 | pub use tokio_macros::main_fail as main; |
|---|
| 682 | |
|---|
| 683 | #[doc (inline)] |
|---|
| 684 | pub use tokio_macros::test_fail as test; |
|---|
| 685 | } |
|---|
| 686 | } |
|---|
| 687 | |
|---|
| 688 | // TODO: rm |
|---|
| 689 | #[cfg (feature = "io-util" )] |
|---|
| 690 | #[cfg (test)] |
|---|
| 691 | fn is_unpin<T: Unpin>() {} |
|---|
| 692 | |
|---|
| 693 | /// fuzz test (fuzz_linked_list) |
|---|
| 694 | #[cfg (fuzzing)] |
|---|
| 695 | pub mod fuzz; |
|---|
| 696 | |
|---|
