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

Trait Implementations§

source§

impl Debug for LocalExecutor<'_>

source§

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

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

impl<'a> Default for LocalExecutor<'a>

source§

fn default() -> LocalExecutor<'a>

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

impl RefUnwindSafe for LocalExecutor<'_>

source§

impl UnwindSafe for LocalExecutor<'_>

Auto Trait Implementations§

§

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

§

impl<'a> !Send for LocalExecutor<'a>

§

impl<'a> !Sync for LocalExecutor<'a>

§

impl<'a> Unpin for LocalExecutor<'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.