Coverage Report

Created: 2025-02-25 06:39

/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;