futures_executor/
lib.rs

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")]
51extern crate std;
52
53#[cfg(feature = "std")]
54mod local_pool;
55#[cfg(feature = "std")]
56pub 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")]
61mod thread_pool;
62#[cfg(feature = "thread-pool")]
63#[cfg(feature = "std")]
64mod unpark_mutex;
65#[cfg(feature = "thread-pool")]
66#[cfg_attr(docsrs, doc(cfg(feature = "thread-pool")))]
67#[cfg(feature = "std")]
68pub use crate::thread_pool::{ThreadPool, ThreadPoolBuilder};
69
70#[cfg(feature = "std")]
71mod enter;
72#[cfg(feature = "std")]
73pub use crate::enter::{enter, Enter, EnterError};