Module futures::executor
[−]
[src]
Task execution.
All asynchronous computation occurs within an executor, which is capable of spawning futures as tasks. This module provides several built-in executors, as well as tools for building your own.
Using a thread pool (M:N task scheduling)
Most of the time tasks should be executed on a thread pool. A small set of worker threads can handle a very large set of spawned tasks (which are much lighter weight than threads).
The simplest way to use a thread pool is to
run
an initial task on it, which can
then spawn further tasks back onto the pool to complete its work:
use futures::executor::ThreadPool; // assumping `my_app: Future` ThreadPool::new().run(my_app);
The call to run
will block the current
thread until the future defined by my_app
completes, and will return
the result of that future.
Spawning additional tasks
There are two ways to spawn a task:
-
Spawn onto a "default" execuctor by calling the top-level
spawn
function or pulling the executor from the task context. -
Spawn onto a specific executor by calling its
spawn
method directly.
Every task always has an associated default executor, which is usually the executor on which the task is running.
Single-threaded execution
In addition to thread pools, it's possible to run a task (and the tasks
it spawns) entirely within a single thread via the
LocalPool
executor. Aside from cutting down
on synchronization costs, this executor also makes it possible to
execute non-Send
tasks, via
spawn_local
. The LocalPool
is best suited for running I/O-bound tasks that do relatively little
work between I/O operations.
There is also a convenience function,
block_on
, for simply running a future to
completion on the current thread. However, any tasks spawned by the
future will also be run on the current thread (via LocalPool
), and
will be dropped when the primary future completes.
Structs
Enter |
Represents an executor context. |
EnterError |
An error returned by |
JoinHandle |
The type of future returned from the |
LocalExecutor | |
LocalPool |
A single-threaded task pool. |
Spawn |
A future representing the completion of task spawning. |
SpawnError |
Provides the reason that an executor was unable to spawn. |
SpawnWithHandle |
A future representing the completion of task spawning, yielding a
|
ThreadPool |
A general-purpose thread pool for scheduling asynchronous tasks. |
ThreadPoolBuilder |
Thread pool configuration object. |
Traits
Executor |
A task executor. |
Functions
block_on |
Run a future to completion on the current thread. |
enter |
Marks the current thread as being within the dynamic extent of an executor. |
spawn |
Spawn a task onto the default executor. |
spawn_with_handle |
Spawn a task onto the default executor, yielding a
|