Struct async_executor::Executor

source ·

pub struct Executor<'a> { /* private fields */ }

Expand description

An async executor.

§Examples

A multi-threaded executor:

use async_channel::unbounded;
use async_executor::Executor;
use easy_parallel::Parallel;
use futures_lite::future;

let ex = Executor::new();
let (signal, shutdown) = unbounded::<()>();

Parallel::new()
    // Run four executor threads.
    .each(0..4, |_| future::block_on(ex.run(shutdown.recv())))
    // Run the main future on the current thread.
    .finish(|| future::block_on(async {
        println!("Hello world!");
        drop(signal);
    }));

Implementations§

source §

impl Executor<'static>

source

pub fn leak(self) -> &'static StaticExecutor

Available on crate feature static only.

Consumes the Executor and intentionally leaks it.

Largely equivalent to calling Box::leak(Box::new(executor)), but the produced StaticExecutor’s functions are optimized to require fewer synchronizing operations when spawning, running, and finishing tasks.

StaticExecutor cannot be converted back into a Executor, so this operation is irreversible without the use of unsafe.

§Example

use async_executor::Executor;
use futures_lite::future;

let ex = Executor::new().leak();

let task = ex.spawn(async {
    println!("Hello world");
});

future::block_on(ex.run(task));

source §

impl<'a> Executor<'a>

source

pub const fn new() -> Executor<'a>

Creates a new executor.

§Examples

use async_executor::Executor;

let ex = Executor::new();

source

pub fn is_empty(&self) -> bool

Returns true if there are no unfinished tasks.

§Examples

use async_executor::Executor;

let ex = Executor::new();
assert!(ex.is_empty());

let task = ex.spawn(async {
    println!("Hello world");
});
assert!(!ex.is_empty());

assert!(ex.try_tick());
assert!(ex.is_empty());

source

pub fn spawn<T: Send + 'a>( &self, future: impl Future<Output = T> + Send + 'a, ) -> Task<T>

Spawns a task onto the executor.

§Examples

use async_executor::Executor;

let ex = Executor::new();

let task = ex.spawn(async {
    println!("Hello world");
});

source

pub fn spawn_many<T: Send + 'a, F: Future<Output = T> + Send + 'a>( &self, futures: impl IntoIterator<Item = F>, handles: &mut impl Extend<Task<F::Output>>, )

Spawns many tasks onto the executor.

As opposed to the spawn method, this locks the executor’s inner task lock once and spawns all of the tasks in one go. With large amounts of tasks this can improve contention.

For very large numbers of tasks the lock is occasionally dropped and re-acquired to prevent runner thread starvation. It is assumed that the iterator provided does not block; blocking iterators can lock up the internal mutex and therefore the entire executor.

§Example

use async_executor::Executor;
use futures_lite::{stream, prelude::*};
use std::future::ready;

let mut ex = Executor::new();

let futures = [
    ready(1),
    ready(2),
    ready(3)
];

// Spawn all of the futures onto the executor at once.
let mut tasks = vec![];
ex.spawn_many(futures, &mut tasks);

// Await all of them.
let results = ex.run(async move {
    stream::iter(tasks).then(|x| x).collect::<Vec<_>>().await
}).await;
assert_eq!(results, [1, 2, 3]);

source

pub fn try_tick(&self) -> bool

Attempts to run a task if at least one is scheduled.

Running a scheduled task means simply polling its future once.

§Examples

use async_executor::Executor;

let ex = Executor::new();
assert!(!ex.try_tick()); // no tasks to run

let task = ex.spawn(async {
    println!("Hello world");
});
assert!(ex.try_tick()); // a task was found

source

pub async fn tick(&self)

Runs a single task.

Running a task means simply polling its future once.

If no tasks are scheduled when this method is called, it will wait until one is scheduled.

§Examples

use async_executor::Executor;
use futures_lite::future;

let ex = Executor::new();

let task = ex.spawn(async {
    println!("Hello world");
});
future::block_on(ex.tick()); // runs the task

source

pub async fn run<T>(&self, future: impl Future<Output = T>) -> T

Runs the executor until the given future completes.

§Examples

use async_executor::Executor;
use futures_lite::future;

let ex = Executor::new();

let task = ex.spawn(async { 1 + 2 });
let res = future::block_on(ex.run(async { task.await * 2 }));

assert_eq!(res, 6);