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);

Trait Implementations§

source§

impl Debug for Executor<'_>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl<'a> Default for Executor<'a>

source§

fn default() -> Executor<'a>

Returns the “default value” for a type. Read more
source§

impl Drop for Executor<'_>

source§

fn drop(&mut self)

Executes the destructor for this type. Read more
source§

impl RefUnwindSafe for Executor<'_>

source§

impl Send for Executor<'_>

source§

impl Sync for Executor<'_>

source§

impl UnwindSafe for Executor<'_>

Auto Trait Implementations§

§

impl<'a> !Freeze for Executor<'a>

§

impl<'a> Unpin for Executor<'a>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.