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 #![no_std]
40 #![doc(test(
41     no_crate_inject,
42     attr(
43         deny(warnings, rust_2018_idioms, single_use_lifetimes),
44         allow(dead_code, unused_assignments, unused_variables)
45     )
46 ))]
47 #![warn(missing_docs, unsafe_op_in_unsafe_fn)]
48 #![cfg_attr(docsrs, feature(doc_cfg))]
49 
50 #[cfg(feature = "std")]
51 extern crate std;
52 
53 #[cfg(feature = "std")]
54 mod local_pool;
55 #[cfg(feature = "std")]
56 pub use crate::local_pool::{block_on, block_on_stream, BlockingStream, LocalPool, LocalSpawner};
57 
58 #[cfg(feature = "thread-pool")]
59 #[cfg_attr(docsrs, doc(cfg(feature = "thread-pool")))]
60 #[cfg(feature = "std")]
61 mod thread_pool;
62 #[cfg(feature = "thread-pool")]
63 #[cfg(feature = "std")]
64 mod unpark_mutex;
65 #[cfg(feature = "thread-pool")]
66 #[cfg_attr(docsrs, doc(cfg(feature = "thread-pool")))]
67 #[cfg(feature = "std")]
68 pub use crate::thread_pool::{ThreadPool, ThreadPoolBuilder};
69 
70 #[cfg(feature = "std")]
71 mod enter;
72 #[cfg(feature = "std")]
73 pub use crate::enter::{enter, Enter, EnterError};
74