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