Module tokio::executor::current_thread [] [src]

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

Handle

Handle to spawn a future on the corresponding CurrentThread instance

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.