/rust/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.43.0/src/lib.rs
Line | Count | Source (jump to first uncovered line) |
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 | 0 | pub(crate) fn trace_leaf(_: &mut std::task::Context<'_>) -> std::task::Poll<()> { |
572 | 0 | std::task::Poll::Ready(()) |
573 | 0 | } |
574 | | } |
575 | | |
576 | | #[cfg_attr(not(feature = "sync"), allow(dead_code))] |
577 | 0 | 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 | 0 | fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> { |
585 | 0 | trace_leaf(cx) |
586 | 0 | } |
587 | | } |
588 | | |
589 | 0 | Trace |
590 | 0 | } |
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; |