Module futures::executor

Built-in executors and related tools.

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.

This module is only available when the executor feature of this library is activated.

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). Tasks spawned onto the pool with the spawn_ok function will run ambiently on the created threads.

Spawning additional tasks

Tasks can be spawned onto a spawner by calling its spawn_obj method directly. In the case of !Send futures, spawn_local_obj can be used instead.

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

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.
• LocalPool
  A single-threaded task pool for polling futures to completion.
• LocalSpawner
  A handle to a LocalPool that implements Spawn.
• ThreadPool
  A general-purpose thread pool for scheduling tasks that poll futures to completion.
• 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.