Struct async_executor::LocalExecutor

source ·

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

Expand description

A thread-local executor.

The executor can only be run on the thread that created it.

§Examples

use async_executor::LocalExecutor;
use futures_lite::future;

let local_ex = LocalExecutor::new();

future::block_on(local_ex.run(async {
    println!("Hello world!");
}));

Implementations§

source §

impl LocalExecutor<'static>

source

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

Available on crate feature static only.

Consumes the LocalExecutor and intentionally leaks it.

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

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

§Example

use async_executor::LocalExecutor;
use futures_lite::future;

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

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

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

source §

impl<'a> LocalExecutor<'a>

source

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

Creates a single-threaded executor.

§Examples

use async_executor::LocalExecutor;

let local_ex = LocalExecutor::new();

source

pub fn is_empty(&self) -> bool

Returns true if there are no unfinished tasks.

§Examples

use async_executor::LocalExecutor;

let local_ex = LocalExecutor::new();
assert!(local_ex.is_empty());

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

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

source

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

Spawns a task onto the executor.

§Examples

use async_executor::LocalExecutor;

let local_ex = LocalExecutor::new();

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

source

pub fn spawn_many<T: 'a, F: Future<Output = T> + '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.

It is assumed that the iterator provided does not block; blocking iterators can lock up the internal mutex and therefore the entire executor. Unlike Executor::spawn, the mutex is not released, as there are no other threads that can poll this executor.

§Example

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

let mut ex = LocalExecutor::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::LocalExecutor;

let ex = LocalExecutor::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::LocalExecutor;
use futures_lite::future;

let ex = LocalExecutor::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::LocalExecutor;
use futures_lite::future;

let local_ex = LocalExecutor::new();

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

assert_eq!(res, 6);