Struct Builder

Source

pub struct Builder<M> { /* private fields */ }

Expand description

A builder that creates a new task.

Implementations§

Source §

impl Builder<()>

Source

pub fn new() -> Builder<()>

Creates a new task builder.

By default, this task builder has no metadata. Use the [metadata] method to set the metadata.

§Examples

use async_task::Builder;

let (runnable, task) = Builder::new().spawn(|()| async {}, |_| {});

Source

pub fn metadata<M>(self, metadata: M) -> Builder<M>

Adds metadata to the task.

In certain cases, it may be useful to associate some metadata with a task. For instance, you may want to associate a name with a task, or a priority for a priority queue. This method allows the user to attach arbitrary metadata to a task that is available through the Runnable or the Task.

§Examples

This example creates an executor that associates a “priority” number with each task, and then runs the tasks in order of priority.

use async_task::{Builder, Runnable};
use once_cell::sync::Lazy;
use std::cmp;
use std::collections::BinaryHeap;
use std::sync::Mutex;

/// A wrapper around a `Runnable<usize>` that implements `Ord` so that it can be used in a
/// priority queue.
struct TaskWrapper(Runnable<usize>);

impl PartialEq for TaskWrapper {
    fn eq(&self, other: &Self) -> bool {
        self.0.metadata() == other.0.metadata()
    }
}

impl Eq for TaskWrapper {}

impl PartialOrd for TaskWrapper {
   fn partial_cmp(&self, other: &Self) -> Option<cmp::Ordering> {
      Some(self.cmp(other))
   }
}

impl Ord for TaskWrapper {
   fn cmp(&self, other: &Self) -> cmp::Ordering {
       self.0.metadata().cmp(other.0.metadata())
   }
}

static EXECUTOR: Lazy<Mutex<BinaryHeap<TaskWrapper>>> = Lazy::new(|| {
    Mutex::new(BinaryHeap::new())
});

let schedule = |runnable| {
    EXECUTOR.lock().unwrap().push(TaskWrapper(runnable));
};

// Spawn a few tasks with different priorities.
let spawn_task = move |priority| {
    let (runnable, task) = Builder::new().metadata(priority).spawn(
        move |_| async move { priority },
        schedule,
    );
    runnable.schedule();
    task
};

let t1 = spawn_task(1);
let t2 = spawn_task(2);
let t3 = spawn_task(3);

// Run the tasks in order of priority.
let mut metadata_seen = vec![];
while let Some(TaskWrapper(runnable)) = EXECUTOR.lock().unwrap().pop() {
    metadata_seen.push(*runnable.metadata());
    runnable.run();
}

assert_eq!(metadata_seen, vec![3, 2, 1]);
assert_eq!(t1.await, 1);
assert_eq!(t2.await, 2);
assert_eq!(t3.await, 3);

Source §

impl<M> Builder<M>

Source

pub fn propagate_panic(self, propagate_panic: bool) -> Builder<M>

Propagates panics that occur in the task.

When this is true, panics that occur in the task will be propagated to the caller of the Task. When this is false, no special action is taken when a panic occurs in the task, meaning that the caller of Runnable::run will observe a panic.

This is only available when the std feature is enabled. By default, this is false.

§Examples

use async_task::Builder;
use futures_lite::future::poll_fn;
use std::future::Future;
use std::panic;
use std::pin::Pin;
use std::task::{Context, Poll};

fn did_panic<F: FnOnce()>(f: F) -> bool {
    panic::catch_unwind(panic::AssertUnwindSafe(f)).is_err()
}

let (runnable1, mut task1) = Builder::new()
   .propagate_panic(true)
   .spawn(|()| async move { panic!() }, |_| {});

let (runnable2, mut task2) = Builder::new()
   .propagate_panic(false)
   .spawn(|()| async move { panic!() }, |_| {});

assert!(!did_panic(|| { runnable1.run(); }));
assert!(did_panic(|| { runnable2.run(); }));

let waker = poll_fn(|cx| Poll::Ready(cx.waker().clone())).await;
let mut cx = Context::from_waker(&waker);
assert!(did_panic(|| { let _ = Pin::new(&mut task1).poll(&mut cx); }));
assert!(did_panic(|| { let _ = Pin::new(&mut task2).poll(&mut cx); }));

Source

pub fn spawn<F, Fut, S>( self, future: F, schedule: S, ) -> (Runnable<M>, Task<Fut::Output, M>)
where F: FnOnce(&M) -> Fut, Fut: Future + Send + 'static, Fut::Output: Send + 'static, S: Schedule<M> + Send + Sync + 'static,

Creates a new task.

The returned Runnable is used to poll the future, and the Task is used to await its output.

Method run() polls the task’s future once. Then, the Runnable vanishes and only reappears when its Waker wakes the task, thus scheduling it to be run again.

When the task is woken, its Runnable is passed to the schedule function. The schedule function should not attempt to run the Runnable nor to drop it. Instead, it should push it into a task queue so that it can be processed later.

If you need to spawn a future that does not implement Send or isn’t 'static, consider using spawn_local() or spawn_unchecked() instead.

§Examples

use async_task::Builder;

// The future inside the task.
let future = async {
    println!("Hello, world!");
};

// A function that schedules the task when it gets woken up.
let (s, r) = flume::unbounded();
let schedule = move |runnable| s.send(runnable).unwrap();

// Create a task with the future and the schedule function.
let (runnable, task) = Builder::new().spawn(|()| future, schedule);

Source

pub fn spawn_local<F, Fut, S>( self, future: F, schedule: S, ) -> (Runnable<M>, Task<Fut::Output, M>)
where F: FnOnce(&M) -> Fut, Fut: Future + 'static, Fut::Output: 'static, S: Schedule<M> + Send + Sync + 'static,

Creates a new thread-local task.

This function is same as spawn(), except it does not require Send on future. If the Runnable is used or dropped on another thread, a panic will occur.

This function is only available when the std feature for this crate is enabled.

§Examples

use async_task::{Builder, Runnable};
use flume::{Receiver, Sender};
use std::rc::Rc;

thread_local! {
    // A queue that holds scheduled tasks.
    static QUEUE: (Sender<Runnable>, Receiver<Runnable>) = flume::unbounded();
}

// Make a non-Send future.
let msg: Rc<str> = "Hello, world!".into();
let future = async move {
    println!("{}", msg);
};

// A function that schedules the task when it gets woken up.
let s = QUEUE.with(|(s, _)| s.clone());
let schedule = move |runnable| s.send(runnable).unwrap();

// Create a task with the future and the schedule function.
let (runnable, task) = Builder::new().spawn_local(move |()| future, schedule);

Source

pub unsafe fn spawn_unchecked<'a, F, Fut, S>( self, future: F, schedule: S, ) -> (Runnable<M>, Task<Fut::Output, M>)
where F: FnOnce(&'a M) -> Fut, Fut: Future + 'a, S: Schedule<M>, M: 'a,

Creates a new task without Send, Sync, and 'static bounds.

This function is same as spawn(), except it does not require Send, Sync, and 'static on future and schedule.

§Safety

If Fut is not Send, its Runnable must be used and dropped on the original thread.
If Fut is not 'static, borrowed non-metadata variables must outlive its Runnable.
If schedule is not Send and Sync, all instances of the Runnable’s Waker must be used and dropped on the original thread.
If schedule is not 'static, borrowed variables must outlive all instances of the Runnable’s Waker.

§Examples

use async_task::Builder;

// The future inside the task.
let future = async {
    println!("Hello, world!");
};

// If the task gets woken up, it will be sent into this channel.
let (s, r) = flume::unbounded();
let schedule = move |runnable| s.send(runnable).unwrap();

// Create a task with the future and the schedule function.
let (runnable, task) = unsafe { Builder::new().spawn_unchecked(move |()| future, schedule) };