Struct async_global_executor::Task

#[must_use =
  "tasks get canceled when dropped, use `.detach()` to run them in the background"]pub struct Task<T>(_);

A spawned future.

Tasks are also futures themselves and yield the output of the spawned future.

When a task is dropped, its gets canceled and won't be polled again. To cancel a task a bit more gracefully and wait until it stops running, use the cancel() method.

Tasks that panic get immediately canceled. Awaiting a canceled task also causes a panic.

If a task panics, the panic will be thrown into the Executor::run() or LocalExecutor::run() invocation that polled it.

Examples

use async_executor::Executor;
use futures_lite::future;
use std::thread;

let ex = Executor::new();

// Spawn a future onto the executor.
let task = ex.spawn(async {
    println!("Hello from a task!");
    1 + 2
});

// Run an executor thread.
thread::spawn(move || future::block_on(ex.run(future::pending::<()>())));

// Wait for the result.
assert_eq!(future::block_on(task), 3);

Implementations

impl<T> Task<T>

pub fn detach(self)

Detaches the task to let it keep running in the background.

Examples

use async_executor::Executor;
use async_io::Timer;
use std::time::Duration;

let ex = Executor::new();

// Spawn a deamon future.
ex.spawn(async {
    loop {
        println!("I'm a daemon task looping forever.");
        Timer::after(Duration::from_secs(1)).await;
    }
})
.detach();

pub async fn cancel(self) -> Option<T>

Cancels the task and waits for it to stop running.

Returns the task's output if it was completed just before it got canceled, or None if it didn't complete.

While it's possible to simply drop the Task to cancel it, this is a cleaner way of canceling because it also waits for the task to stop running.

Examples

use async_executor::Executor;
use async_io::Timer;
use futures_lite::future;
use std::thread;
use std::time::Duration;

let ex = Executor::new();

// Spawn a deamon future.
let task = ex.spawn(async {
    loop {
        println!("Even though I'm in an infinite loop, you can still cancel me!");
        Timer::after(Duration::from_secs(1)).await;
    }
});

// Run an executor thread.
thread::spawn(move || future::block_on(ex.run(future::pending::<()>())));

future::block_on(async {
    Timer::after(Duration::from_secs(3)).await;
    task.cancel().await;
});

Trait Implementations

impl<T> Debug for Task<T> where
    T: Debug, 

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

Formats the value using the given formatter.

impl<T> Drop for Task<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Future for Task<T>

type Output = T

The type of value produced on completion.

fn poll(
    self: Pin<&mut Task<T>>,
    cx: &mut Context<'_>
) -> Poll<<Task<T> as Future>::Output>

Attempt to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.