Struct Runnable

Source

pub struct Runnable<D = ()> { /* private fields */ }

Expand description

A handle to a runnable task.

Every spawned task has a single Runnable handle, which only exists when the task is scheduled for running.

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.

Dropping a Runnable cancels the task, which means its future won’t be polled again, and awaiting the Task after that will result in a panic.

§Examples

use async_task_ffi::Runnable;
use once_cell::sync::Lazy;
use std::{panic, thread};

// A simple executor.
static QUEUE: Lazy<flume::Sender<Runnable>> = Lazy::new(|| {
    let (sender, receiver) = flume::unbounded::<Runnable>();
    thread::spawn(|| {
        for runnable in receiver {
            let _ignore_panic = panic::catch_unwind(|| runnable.run());
        }
    });
    sender
});

// Create a task with a simple future.
let schedule = |runnable| QUEUE.send(runnable).unwrap();
let (runnable, task) = async_task_ffi::spawn(async { 1 + 2 }, schedule);

// Schedule the task and await its output.
runnable.schedule();
assert_eq!(smol::future::block_on(task), 3);

Implementations§

Source §

impl<D> Runnable<D>

Source

pub fn schedule(self)

Schedules the task.

This is a convenience method that passes the Runnable to the schedule function.

§Examples

// 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 a simple future and the schedule function.
let (runnable, task) = async_task_ffi::spawn(async {}, schedule);

// Schedule the task.
assert_eq!(r.len(), 0);
runnable.schedule();
assert_eq!(r.len(), 1);

Source

pub fn run(self) -> bool

Runs the task by polling its future.

Returns true if the task was woken while running, in which case the Runnable gets rescheduled at the end of this method invocation. Otherwise, returns false and the Runnable vanishes until the task is woken. The return value is just a hint: true usually indicates that the task has yielded, i.e. it woke itself and then gave the control back to the executor.

If the Task handle was dropped or if cancel() was called, then this method simply destroys the task.

If the polled future panics, this method propagates the panic, and awaiting the Task after that will also result in a panic.

§Examples

// 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 a simple future and the schedule function.
let (runnable, task) = async_task_ffi::spawn(async { 1 + 2 }, schedule);

// Run the task and check its output.
runnable.run();
assert_eq!(smol::future::block_on(task), 3);

Source

pub fn waker(&self) -> Waker

Returns a waker associated with this task.

§Examples

use smol::future;

// 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 a simple future and the schedule function.
let (runnable, task) = async_task_ffi::spawn(future::pending::<()>(), schedule);

// Take a waker and run the task.
let waker = runnable.waker();
runnable.run();

// Reschedule the task by waking it.
assert_eq!(r.len(), 0);
waker.wake();
assert_eq!(r.len(), 1);

Source

pub fn data(&self) -> &D

Returns a reference to the user data associated with this task.

For mutable access see [data_mut].

§Examples

use async_task_ffi::Runnable;

// A function that schedules the task and prints a message.
let (s, r) = flume::unbounded();
let schedule = move |runnable: Runnable<&'static str>| {
    println!("{}", runnable.data());
    s.send(runnable).unwrap();
};

// Create a task with a simple future, the schedule function and a message.
let (runnable, task) = async_task_ffi::spawn_with(
    async {},
    schedule,
    "Hello from the schedule function!",
);

// Schedule the task.
runnable.schedule();

Source

pub fn data_mut(&mut self) -> &mut D

Returns a mutable reference to the user data associated with this task.

For immutable access see [data].

§Examples

use async_task_ffi::Runnable;

// A function that schedules the task and
// counts the amount of times it has been.
let (s, r) = flume::unbounded();
let schedule = move |mut runnable: Runnable<usize>| {
    let counter = runnable.data_mut();
    println!("{}", counter);
    *counter += 1;
    s.send(runnable).unwrap();
};

// Create a task with a simple future,
// the schedule function and the initial counter value.
let (mut runnable, task) = async_task_ffi::spawn_with(async {}, schedule, 0);

// Schedule the task.
*runnable.data_mut() += 1;
runnable.schedule();