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().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:

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_obj. 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.

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.

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.