Module executor

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;

// assuming `my_app: Future`
ThreadPool::new().expect("Failed to create threadpool").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” executor 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, while routing any spawned tasks to a global thread pool.

Structs

• BlockingStream
  An iterator which blocks on values from a stream until they become available.
• Enter
  Represents an executor context.
• EnterError
  An error returned by enter if an execution scope has already been entered.
• JoinHandle
  The type of future returned from the ThreadPool::spawn function, which proxies the futures running on the thread pool.
• LocalExecutor
  A handle to a LocalPool that implements Executor.
• 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 JoinHandle to the spawned task.
• 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.
• block_on_stream
  Turn a stream into a blocking iterator.
• 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 JoinHandle to the spawned task.