Coverage Report

Created: 2025-11-28 06:44

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