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