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