Module tokio::executor::current_thread

Execute many tasks concurrently on the current thread.

CurrentThread is an executor that keeps tasks on the same thread that they were spawned from. This allows it to execute futures that are not Send.

A single CurrentThread instance is able to efficiently manage a large number of tasks and will attempt to schedule all tasks fairly.

All tasks that are being managed by a CurrentThread executor are able to spawn additional tasks by calling spawn. This function only works from within the context of a running CurrentThread instance.

The easiest way to start a new CurrentThread executor is to call block_on_all with an initial task to seed the executor.

For example:

use futures::future::lazy;

// Calling execute here results in a panic
// current_thread::spawn(my_future);

current_thread::block_on_all(lazy(|| {
    // The execution context is setup, futures may be executed.
    current_thread::spawn(lazy(|| {
        println!("called from the current thread executor");
        Ok(())
    }));

    Ok::<_, ()>(())
}));

The block_on_all function will block the current thread until all tasks that have been spawned onto the CurrentThread instance have completed.

More fine-grain control can be achieved by using CurrentThread directly.

use futures::future::{lazy, empty};
use std::time::Duration;

// Calling execute here results in a panic
// current_thread::spawn(my_future);

let mut current_thread = CurrentThread::new();

// Spawn a task, the task is not executed yet.
current_thread.spawn(lazy(|| {
    println!("Spawning a task");
    Ok(())
}));

// Spawn a task that never completes
current_thread.spawn(empty());

// Run the executor, but only until the provided future completes. This
// provides the opportunity to start executing previously spawned tasks.
let res = current_thread.block_on(lazy(|| {
    Ok::<_, ()>("Hello")
})).unwrap();

// Now, run the executor for *at most* 1 second. Since a task was spawned
// that never completes, this function will return with an error.
current_thread.run_timeout(Duration::from_secs(1)).unwrap_err();

Execution model

Internally, CurrentThread maintains a queue. When one of its tasks is notified, the task gets added to the queue. The executor will pop tasks from the queue and call Future::poll. If the task gets notified while it is being executed, it won't get re-executed until all other tasks currently in the queue get polled.

Before the task is polled, a thread-local variable referencing the current CurrentThread instance is set. This enables spawn to spawn new tasks onto the same executor without having to thread through a handle value.

If the CurrentThread instance still has uncompleted tasks, but none of these tasks are ready to be polled, the current thread is put to sleep. When a task is notified, the thread is woken up and processing resumes.

All tasks managed by CurrentThread remain on the current thread. When a task completes, it is dropped.

Structs

BlockError	Error returned by the block_on function.
CurrentThread	Executes tasks on the current thread
Entered	A CurrentThread instance bound to a supplied execution conext.
RunError	Error returned by the run function.
RunTimeoutError	Error returned by the run_timeout function.
TaskExecutor	Executes futures on the current thread.
Turn	Returned by the turn function
TurnError	Error returned by the turn function.

Functions

block_on_all	Run the executor bootstrapping the execution with the provided future.
spawn	Executes a future on the current thread.