| 1 | //! Built-in executors and related tools. |
| 2 | //! |
|---|
| 3 | //! All asynchronous computation occurs within an executor, which is |
|---|
| 4 | //! capable of spawning futures as tasks. This module provides several |
|---|
| 5 | //! built-in executors, as well as tools for building your own. |
|---|
| 6 | //! |
|---|
| 7 | //! All items are only available when the `std` feature of this |
|---|
| 8 | //! library is activated, and it is activated by default. |
|---|
| 9 | //! |
|---|
| 10 | //! # Using a thread pool (M:N task scheduling) |
|---|
| 11 | //! |
|---|
| 12 | //! Most of the time tasks should be executed on a [thread pool](ThreadPool). |
|---|
| 13 | //! A small set of worker threads can handle a very large set of spawned tasks |
|---|
| 14 | //! (which are much lighter weight than threads). Tasks spawned onto the pool |
|---|
| 15 | //! with the [`spawn_ok`](ThreadPool::spawn_ok) function will run ambiently on |
|---|
| 16 | //! the created threads. |
|---|
| 17 | //! |
|---|
| 18 | //! # Spawning additional tasks |
|---|
| 19 | //! |
|---|
| 20 | //! Tasks can be spawned onto a spawner by calling its [`spawn_obj`] method |
|---|
| 21 | //! directly. In the case of `!Send` futures, [`spawn_local_obj`] can be used |
|---|
| 22 | //! instead. |
|---|
| 23 | //! |
|---|
| 24 | //! # Single-threaded execution |
|---|
| 25 | //! |
|---|
| 26 | //! In addition to thread pools, it's possible to run a task (and the tasks |
|---|
| 27 | //! it spawns) entirely within a single thread via the [`LocalPool`] executor. |
|---|
| 28 | //! Aside from cutting down on synchronization costs, this executor also makes |
|---|
| 29 | //! it possible to spawn non-`Send` tasks, via [`spawn_local_obj`]. The |
|---|
| 30 | //! [`LocalPool`] is best suited for running I/O-bound tasks that do relatively |
|---|
| 31 | //! little work between I/O operations. |
|---|
| 32 | //! |
|---|
| 33 | //! There is also a convenience function [`block_on`] for simply running a |
|---|
| 34 | //! future to completion on the current thread. |
|---|
| 35 | //! |
|---|
| 36 | //! [`spawn_obj`]: https://docs.rs/futures/0.3/futures/task/trait.Spawn.html#tymethod.spawn_obj |
|---|
| 37 | //! [`spawn_local_obj`]: https://docs.rs/futures/0.3/futures/task/trait.LocalSpawn.html#tymethod.spawn_local_obj |
|---|
| 38 | |
|---|
| 39 | #![cfg_attr (not(feature = "std" ), no_std)] |
|---|
| 40 | #![warn ( |
|---|
| 41 | missing_debug_implementations, |
|---|
| 42 | missing_docs, |
|---|
| 43 | rust_2018_idioms, |
|---|
| 44 | single_use_lifetimes, |
|---|
| 45 | unreachable_pub |
|---|
| 46 | )] |
|---|
| 47 | #![doc (test( |
|---|
| 48 | no_crate_inject, |
|---|
| 49 | attr( |
|---|
| 50 | deny(warnings, rust_2018_idioms, single_use_lifetimes), |
|---|
| 51 | allow(dead_code, unused_assignments, unused_variables) |
|---|
| 52 | ) |
|---|
| 53 | ))] |
|---|
| 54 | #![cfg_attr (docsrs, feature(doc_cfg))] |
|---|
| 55 | |
|---|
| 56 | #[cfg (feature = "std" )] |
|---|
| 57 | mod local_pool; |
|---|
| 58 | #[cfg (feature = "std" )] |
|---|
| 59 | pub use crate::local_pool::{block_on, block_on_stream, BlockingStream, LocalPool, LocalSpawner}; |
|---|
| 60 | |
|---|
| 61 | #[cfg (feature = "thread-pool" )] |
|---|
| 62 | #[cfg_attr (docsrs, doc(cfg(feature = "thread-pool" )))] |
|---|
| 63 | #[cfg (feature = "std" )] |
|---|
| 64 | mod thread_pool; |
|---|
| 65 | #[cfg (feature = "thread-pool" )] |
|---|
| 66 | #[cfg (feature = "std" )] |
|---|
| 67 | mod unpark_mutex; |
|---|
| 68 | #[cfg (feature = "thread-pool" )] |
|---|
| 69 | #[cfg_attr (docsrs, doc(cfg(feature = "thread-pool" )))] |
|---|
| 70 | #[cfg (feature = "std" )] |
|---|
| 71 | pub use crate::thread_pool::{ThreadPool, ThreadPoolBuilder}; |
|---|
| 72 | |
|---|
| 73 | #[cfg (feature = "std" )] |
|---|
| 74 | mod enter; |
|---|
| 75 | #[cfg (feature = "std" )] |
|---|
| 76 | pub use crate::enter::{enter, Enter, EnterError}; |
|---|
| 77 | |
|---|
