smol-rs
/
async-task
mirror of https://github.com/smol-rs/async-task
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Docs and comments

This commit is contained in:
Stjepan Glavina 2020-09-19 21:34:44 +02:00
parent 77a70b5f5d
commit 2404b1b32e
17 changed files with 287 additions and 196 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
Cargo.toml
View File

@ -18,8 +18,7 @@ std = []
[dev-dependencies] [dev-dependencies]
atomic-waker = "1.0.0" atomic-waker = "1.0.0"
concurrent-queue = "1.2.2"
easy-parallel = "3.1.0" easy-parallel = "3.1.0"
flume = { version = "0.9.0", default-features = false } flume = { version = "0.9.0", default-features = false }
futures-lite = "1.7.0"
once_cell = "1.4.1" once_cell = "1.4.1"
smol = "1.0.1"

2
benches/spawn.rs
View File

@ -2,7 +2,7 @@
extern crate test; extern crate test;
use futures_lite::future; use smol::future;
use test::Bencher; use test::Bencher;
#[bench] #[bench]

6
examples/spawn-local.rs
View File

@ -7,7 +7,7 @@ use std::rc::Rc;
use async_task::{Runnable, Task}; use async_task::{Runnable, Task};
thread_local! { thread_local! {
// A channel that holds scheduled tasks. // A queue that holds scheduled tasks.
static QUEUE: (flume::Sender<Runnable>, flume::Receiver<Runnable>) = flume::unbounded(); static QUEUE: (flume::Sender<Runnable>, flume::Receiver<Runnable>) = flume::unbounded();
} }
@ -17,11 +17,11 @@ where
F: Future<Output = T> + 'static, F: Future<Output = T> + 'static,
T: 'static, T: 'static,
{ {
// Create a task that is scheduled by sending itself into the channel. // Create a task that is scheduled by pushing itself into the queue.
let schedule = |t| QUEUE.with(|(s, _)| s.send(t).unwrap()); let schedule = |t| QUEUE.with(|(s, _)| s.send(t).unwrap());
let (runnable, task) = async_task::spawn_local(future, schedule); let (runnable, task) = async_task::spawn_local(future, schedule);
// Schedule the task by sending it into the queue. // Schedule the task by pushing it into the queue.
runnable.schedule(); runnable.schedule();
task task

4
examples/spawn-on-thread.rs
View File

@ -5,7 +5,7 @@ use std::sync::Arc;
use std::thread; use std::thread;
use async_task::Task; use async_task::Task;
use futures_lite::future; use smol::future;
/// Spawns a future on a new dedicated thread. /// Spawns a future on a new dedicated thread.
/// ///
@ -27,7 +27,7 @@ where
future.await future.await
}; };
// Create a task that is scheduled by sending itself into the channel. // Create a task that is scheduled by sending it into the channel.
let schedule = move |t| s.upgrade().unwrap().send(t).unwrap(); let schedule = move |t| s.upgrade().unwrap().send(t).unwrap();
let (runnable, task) = async_task::spawn(future, schedule); let (runnable, task) = async_task::spawn(future, schedule);

8
examples/spawn.rs
View File

@ -5,8 +5,8 @@ use std::panic::catch_unwind;
use std::thread; use std::thread;
use async_task::{Runnable, Task}; use async_task::{Runnable, Task};
use futures_lite::future;
use once_cell::sync::Lazy; use once_cell::sync::Lazy;
use smol::future;
/// Spawns a future on the executor. /// Spawns a future on the executor.
fn spawn<F, T>(future: F) -> Task<T> fn spawn<F, T>(future: F) -> Task<T>
@ -14,7 +14,7 @@ where
F: Future<Output = T> + Send + 'static, F: Future<Output = T> + Send + 'static,
T: Send + 'static, T: Send + 'static,
{ {
// A channel that holds scheduled tasks. // A queue that holds scheduled tasks.
static QUEUE: Lazy<flume::Sender<Runnable>> = Lazy::new(|| { static QUEUE: Lazy<flume::Sender<Runnable>> = Lazy::new(|| {
let (sender, receiver) = flume::unbounded::<Runnable>(); let (sender, receiver) = flume::unbounded::<Runnable>();
@ -29,11 +29,11 @@ where
sender sender
}); });
// Create a task that is scheduled by sending itself into the channel. // Create a task that is scheduled by pushing it into the queue.
let schedule = |t| QUEUE.send(t).unwrap(); let schedule = |t| QUEUE.send(t).unwrap();
let (runnable, task) = async_task::spawn(future, schedule); let (runnable, task) = async_task::spawn(future, schedule);
// Schedule the task by sending it into the channel. // Schedule the task by pushing it into the queue.
runnable.schedule(); runnable.schedule();
task task

41
src/header.rs
View File

@ -9,14 +9,14 @@ use crate::utils::abort_on_panic;
/// The header of a task. /// The header of a task.
/// ///
/// This header is stored right at the beginning of every heap-allocated task. /// This header is stored in memory at the beginning of the heap-allocated task.
pub(crate) struct Header { pub(crate) struct Header {
/// Current state of the task. /// Current state of the task.
/// ///
/// Contains flags representing the current state and the reference count. /// Contains flags representing the current state and the reference count.
pub(crate) state: AtomicUsize, pub(crate) state: AtomicUsize,
/// The task that is blocked on the `Task`. /// The task that is blocked on the `Task` handle.
/// ///
/// This waker needs to be woken up once the task completes or is closed. /// This waker needs to be woken up once the task completes or is closed.
pub(crate) awaiter: UnsafeCell<Option<Waker>>, pub(crate) awaiter: UnsafeCell<Option<Waker>>,
@ -29,49 +29,24 @@ pub(crate) struct Header {
} }
impl Header { impl Header {
/// Cancels the task.
///
/// This method will mark the task as closed, but it won't reschedule the task or drop its
/// future.
pub(crate) fn cancel(&self) {
let mut state = self.state.load(Ordering::Acquire);
loop {
// If the task has been completed or closed, it can't be canceled.
if state & (COMPLETED | CLOSED) != 0 {
break;
}
// Mark the task as closed.
match self.state.compare_exchange_weak(
state,
state | CLOSED,
Ordering::AcqRel,
Ordering::Acquire,
) {
Ok(_) => break,
Err(s) => state = s,
}
}
}
/// Notifies the awaiter blocked on this task. /// Notifies the awaiter blocked on this task.
/// ///
/// If the awaiter is the same as the current waker, it will not be notified. /// If the awaiter is the same as the current waker, it will not be notified.
#[inline] #[inline]
pub(crate) fn notify(&self, current: Option<&Waker>) { pub(crate) fn notify(&self, current: Option<&Waker>) {
// Mark the awaiter as being notified. // Set the bit indicating that the task is notifying its awaiter.
let state = self.state.fetch_or(NOTIFYING, Ordering::AcqRel); let state = self.state.fetch_or(NOTIFYING, Ordering::AcqRel);
// If the awaiter was not being notified nor registered... // If the task was not notifying or registering an awaiter...
if state & (NOTIFYING | REGISTERING) == 0 { if state & (NOTIFYING | REGISTERING) == 0 {
// Take the waker out. // Take the waker out.
let waker = unsafe { (*self.awaiter.get()).take() }; let waker = unsafe { (*self.awaiter.get()).take() };
// Mark the state as not being notified anymore nor containing an awaiter. // Unset the bit indicating that the task is notifying its awaiter.
self.state self.state
.fetch_and(!NOTIFYING & !AWAITER, Ordering::Release); .fetch_and(!NOTIFYING & !AWAITER, Ordering::Release);
// Finally, notify the waker if it's different from the current waker.
if let Some(w) = waker { if let Some(w) = waker {
// We need a safeguard against panics because waking can panic. // We need a safeguard against panics because waking can panic.
abort_on_panic(|| match current { abort_on_panic(|| match current {
@ -85,7 +60,7 @@ impl Header {
/// Registers a new awaiter blocked on this task. /// Registers a new awaiter blocked on this task.
/// ///
/// This method is called when `Task` is polled and the task has not completed. /// This method is called when `Task` is polled and it has not yet completed.
#[inline] #[inline]
pub(crate) fn register(&self, waker: &Waker) { pub(crate) fn register(&self, waker: &Waker) {
// Load the state and synchronize with it. // Load the state and synchronize with it.
@ -169,7 +144,7 @@ impl fmt::Debug for Header {
.field("completed", &(state & COMPLETED != 0)) .field("completed", &(state & COMPLETED != 0))
.field("closed", &(state & CLOSED != 0)) .field("closed", &(state & CLOSED != 0))
.field("awaiter", &(state & AWAITER != 0)) .field("awaiter", &(state & AWAITER != 0))
.field("handle", &(state & HANDLE != 0)) .field("task", &(state & TASK != 0))
.field("ref_count", &(state / REFERENCE)) .field("ref_count", &(state / REFERENCE))
.finish() .finish()
} }

53
src/lib.rs
View File

@ -1,12 +1,10 @@
//! Task abstraction for building executors. //! Task abstraction for building executors.
//! //!
//! # Spawning
//!
//! To spawn a future onto an executor, we first need to allocate it on the heap and keep some //! To spawn a future onto an executor, we first need to allocate it on the heap and keep some
//! state alongside it. The state indicates whether the future is ready for polling, waiting to be //! state attached to it. The state indicates whether the future is ready for polling, waiting to
//! woken up, or completed. Such a future is called a *task*. //! be woken up, or completed. Such a stateful future is called a *task*.
//! //!
//! All executors have some kind of queue that holds runnable tasks: //! All executors have a queue that holds scheduled tasks:
//! //!
//! ``` //! ```
//! let (sender, receiver) = flume::unbounded(); //! let (sender, receiver) = flume::unbounded();
@ -17,11 +15,12 @@
//! # // A function that schedules the task when it gets woken up. //! # // A function that schedules the task when it gets woken up.
//! # let schedule = move |runnable| sender.send(runnable).unwrap(); //! # let schedule = move |runnable| sender.send(runnable).unwrap();
//! # //! #
//! # // Construct a task. //! # // Create a task.
//! # let (runnable, task) = async_task::spawn(future, schedule); //! # let (runnable, task) = async_task::spawn(future, schedule);
//! ``` //! ```
//! //!
//! A task is constructed using either [`spawn`] or [`spawn_local`]: //! A task is created using either [`spawn()`], [`spawn_local()`], or [`spawn_unchecked()`] which
//! return a [`Runnable`] and a [`Task`]:
//! //!
//! ``` //! ```
//! # let (sender, receiver) = flume::unbounded(); //! # let (sender, receiver) = flume::unbounded();
@ -39,12 +38,10 @@
//! runnable.schedule(); //! runnable.schedule();
//! ``` //! ```
//! //!
//! The function returns a runnable [`Runnable`] and a [`Task`] that can await the result. //! The [`Runnable`] is used to poll the task's future, and the [`Task`] is used to await its
//! output.
//! //!
//! # Execution //! Finally, we need a loop that takes scheduled tasks from the queue and runs them:
//!
//! Task executors have some kind of main loop that drives tasks to completion. That means taking
//! runnable tasks out of the queue and running each one in order:
//! //!
//! ```no_run //! ```no_run
//! # let (sender, receiver) = flume::unbounded(); //! # let (sender, receiver) = flume::unbounded();
@ -55,7 +52,7 @@
//! # // A function that schedules the task when it gets woken up. //! # // A function that schedules the task when it gets woken up.
//! # let schedule = move |runnable| sender.send(runnable).unwrap(); //! # let schedule = move |runnable| sender.send(runnable).unwrap();
//! # //! #
//! # // Construct a task. //! # // Create a task.
//! # let (runnable, task) = async_task::spawn(future, schedule); //! # let (runnable, task) = async_task::spawn(future, schedule);
//! # //! #
//! # // Push the task into the queue by invoking its schedule function. //! # // Push the task into the queue by invoking its schedule function.
@ -66,31 +63,9 @@
//! } //! }
//! ``` //! ```
//! //!
//! When a task is run, its future gets polled. If polling does not complete the task, that means //! Method [`run()`][`Runnable::run()`] polls the task's future once. Then, the [`Runnable`]
//! it's waiting for another future and needs to go to sleep. When woken up, its schedule function //! vanishes and only reappears when its [`Waker`][`core::task::Waker`] wakes the task, thus
//! will be invoked, pushing it back into the queue so that it can be run again. //! scheduling it to be run again.
//!
//! # Cancelation
//!
//! Both [`Runnable`] and [`Task`] have methods that cancel the task. When canceled, the
//! task's future will not be polled again and will get dropped instead.
//!
//! If canceled by the [`Runnable`] instance, the task is destroyed immediately. If canceled by the
//! [`Task`] instance, it will be scheduled one more time and the next attempt to run it will
//! simply destroy it.
//!
//! The `Task` future will then evaluate to `None`, but only after the task's future is
//! dropped.
//!
//! # Performance
//!
//! Task construction incurs a single allocation that holds its state, the schedule function, and
//! the future or the result of the future if completed.
//!
//! The layout of a task is equivalent to 4 `usize`s followed by the schedule function, and then by
//! a union of the future and its output.
//!
//! [`block_on`]: https://github.com/stjepang/async-task/blob/master/examples/block.rs
#![cfg_attr(not(feature = "std"), no_std)] #![cfg_attr(not(feature = "std"), no_std)]
#![warn(missing_docs, missing_debug_implementations, rust_2018_idioms)] #![warn(missing_docs, missing_debug_implementations, rust_2018_idioms)]
@ -106,7 +81,7 @@ mod state;
mod task; mod task;
mod utils; mod utils;
pub use crate::runnable::{spawn, Runnable}; pub use crate::runnable::{spawn, spawn_unchecked, Runnable};
pub use crate::task::Task; pub use crate::task::Task;
#[cfg(feature = "std")] #[cfg(feature = "std")]

64
src/raw.rs
View File

@ -23,8 +23,8 @@ pub(crate) struct TaskVTable {
/// Returns a pointer to the output stored after completion. /// Returns a pointer to the output stored after completion.
pub(crate) get_output: unsafe fn(*const ()) -> *const (), pub(crate) get_output: unsafe fn(*const ()) -> *const (),
/// Drops the task. /// Drops the task reference (`Runnable` or `Waker`).
pub(crate) drop_task: unsafe fn(ptr: *const ()), pub(crate) drop_ref: unsafe fn(ptr: *const ()),
/// Destroys the task. /// Destroys the task.
pub(crate) destroy: unsafe fn(*const ()), pub(crate) destroy: unsafe fn(*const ()),
@ -82,8 +82,8 @@ impl<F, T, S> Clone for RawTask<F, T, S> {
impl<F, T, S> RawTask<F, T, S> impl<F, T, S> RawTask<F, T, S>
where where
F: Future<Output = T> + 'static, F: Future<Output = T>,
S: Fn(Runnable) + Send + Sync + 'static, S: Fn(Runnable),
{ {
const RAW_WAKER_VTABLE: RawWakerVTable = RawWakerVTable::new( const RAW_WAKER_VTABLE: RawWakerVTable = RawWakerVTable::new(
Self::clone_waker, Self::clone_waker,
@ -94,29 +94,29 @@ where
/// Allocates a task with the given `future` and `schedule` function. /// Allocates a task with the given `future` and `schedule` function.
/// ///
/// It is assumed that initially only the `Runnable` reference and the `Task` exist. /// It is assumed that initially only the `Runnable` and the `Task` exist.
pub(crate) fn allocate(future: F, schedule: S) -> NonNull<()> { pub(crate) fn allocate(future: F, schedule: S) -> NonNull<()> {
// Compute the layout of the task for allocation. Abort if the computation fails. // Compute the layout of the task for allocation. Abort if the computation fails.
let task_layout = abort_on_panic(|| Self::task_layout()); let task_layout = abort_on_panic(|| Self::task_layout());
unsafe { unsafe {
// Allocate enough space for the entire task. // Allocate enough space for the entire task.
let raw_task = match NonNull::new(alloc::alloc::alloc(task_layout.layout) as *mut ()) { let ptr = match NonNull::new(alloc::alloc::alloc(task_layout.layout) as *mut ()) {
None => abort(), None => abort(),
Some(p) => p, Some(p) => p,
}; };
let raw = Self::from_ptr(raw_task.as_ptr()); let raw = Self::from_ptr(ptr.as_ptr());
// Write the header as the first field of the task. // Write the header as the first field of the task.
(raw.header as *mut Header).write(Header { (raw.header as *mut Header).write(Header {
state: AtomicUsize::new(SCHEDULED | HANDLE | REFERENCE), state: AtomicUsize::new(SCHEDULED | TASK | REFERENCE),
awaiter: UnsafeCell::new(None), awaiter: UnsafeCell::new(None),
vtable: &TaskVTable { vtable: &TaskVTable {
schedule: Self::schedule, schedule: Self::schedule,
drop_future: Self::drop_future, drop_future: Self::drop_future,
get_output: Self::get_output, get_output: Self::get_output,
drop_task: Self::drop_task, drop_ref: Self::drop_ref,
destroy: Self::destroy, destroy: Self::destroy,
run: Self::run, run: Self::run,
clone_waker: Self::clone_waker, clone_waker: Self::clone_waker,
@ -129,7 +129,7 @@ where
// Write the future as the fourth field of the task. // Write the future as the fourth field of the task.
raw.future.write(future); raw.future.write(future);
raw_task ptr
} }
} }
@ -296,7 +296,7 @@ where
// because the schedule function cannot be destroyed while the waker is // because the schedule function cannot be destroyed while the waker is
// still alive. // still alive.
let task = Runnable { let task = Runnable {
raw_task: NonNull::new_unchecked(ptr as *mut ()), ptr: NonNull::new_unchecked(ptr as *mut ()),
}; };
(*raw.schedule)(task); (*raw.schedule)(task);
} }
@ -328,7 +328,7 @@ where
/// Drops a waker. /// Drops a waker.
/// ///
/// This function will decrement the reference count. If it drops down to zero, the associated /// This function will decrement the reference count. If it drops down to zero, the associated
/// join handle has been dropped too, and the task has not been completed, then it will get /// `Task` has been dropped too, and the task has not been completed, then it will get
/// scheduled one more time so that its future gets dropped by the executor. /// scheduled one more time so that its future gets dropped by the executor.
#[inline] #[inline]
unsafe fn drop_waker(ptr: *const ()) { unsafe fn drop_waker(ptr: *const ()) {
@ -339,7 +339,7 @@ where
// If this was the last reference to the task and the `Task` has been dropped too, // If this was the last reference to the task and the `Task` has been dropped too,
// then we need to decide how to destroy the task. // then we need to decide how to destroy the task.
if new & !(REFERENCE - 1) == 0 && new & HANDLE == 0 { if new & !(REFERENCE - 1) == 0 && new & TASK == 0 {
if new & (COMPLETED | CLOSED) == 0 { if new & (COMPLETED | CLOSED) == 0 {
// If the task was not completed nor closed, close it and schedule one more time so // If the task was not completed nor closed, close it and schedule one more time so
// that its future gets dropped by the executor. // that its future gets dropped by the executor.
@ -354,12 +354,12 @@ where
} }
} }
/// Drops a task. /// Drops a task reference (`Runnable` or `Waker`).
/// ///
/// This function will decrement the reference count. If it drops down to zero and the /// This function will decrement the reference count. If it drops down to zero and the
/// associated join handle has been dropped too, then the task gets destroyed. /// associated `Task` handle has been dropped too, then the task gets destroyed.
#[inline] #[inline]
unsafe fn drop_task(ptr: *const ()) { unsafe fn drop_ref(ptr: *const ()) {
let raw = Self::from_ptr(ptr); let raw = Self::from_ptr(ptr);
// Decrement the reference count. // Decrement the reference count.
@ -367,7 +367,7 @@ where
// If this was the last reference to the task and the `Task` has been dropped too, // If this was the last reference to the task and the `Task` has been dropped too,
// then destroy the task. // then destroy the task.
if new & !(REFERENCE - 1) == 0 && new & HANDLE == 0 { if new & !(REFERENCE - 1) == 0 && new & TASK == 0 {
Self::destroy(ptr); Self::destroy(ptr);
} }
} }
@ -387,7 +387,7 @@ where
} }
let task = Runnable { let task = Runnable {
raw_task: NonNull::new_unchecked(ptr as *mut ()), ptr: NonNull::new_unchecked(ptr as *mut ()),
}; };
(*raw.schedule)(task); (*raw.schedule)(task);
} }
@ -457,7 +457,7 @@ where
} }
// Drop the task reference. // Drop the task reference.
Self::drop_task(ptr); Self::drop_ref(ptr);
return false; return false;
} }
@ -494,8 +494,8 @@ where
// The task is now completed. // The task is now completed.
loop { loop {
// If the handle is dropped, we'll need to close it and drop the output. // If the `Task` is dropped, we'll need to close it and drop the output.
let new = if state & HANDLE == 0 { let new = if state & TASK == 0 {
(state & !RUNNING & !SCHEDULED) | COMPLETED | CLOSED (state & !RUNNING & !SCHEDULED) | COMPLETED | CLOSED
} else { } else {
(state & !RUNNING & !SCHEDULED) | COMPLETED (state & !RUNNING & !SCHEDULED) | COMPLETED
@ -509,9 +509,9 @@ where
Ordering::Acquire, Ordering::Acquire,
) { ) {
Ok(_) => { Ok(_) => {
// If the handle is dropped or if the task was closed while running, // If the `Task` is dropped or if the task was closed while running,
// now it's time to drop the output. // now it's time to drop the output.
if state & HANDLE == 0 || state & CLOSED != 0 { if state & TASK == 0 || state & CLOSED != 0 {
// Read the output. // Read the output.
output = Some(raw.output.read()); output = Some(raw.output.read());
} }
@ -522,7 +522,7 @@ where
} }
// Drop the task reference. // Drop the task reference.
Self::drop_task(ptr); Self::drop_ref(ptr);
break; break;
} }
Err(s) => state = s, Err(s) => state = s,
@ -569,7 +569,7 @@ where
(*raw.header).notify(None); (*raw.header).notify(None);
} }
// Drop the task reference. // Drop the task reference.
Self::drop_task(ptr); Self::drop_ref(ptr);
} else if state & SCHEDULED != 0 { } else if state & SCHEDULED != 0 {
// The thread that woke the task up didn't reschedule it because // The thread that woke the task up didn't reschedule it because
// it was running so now it's our responsibility to do so. // it was running so now it's our responsibility to do so.
@ -577,7 +577,7 @@ where
return true; return true;
} else { } else {
// Drop the task reference. // Drop the task reference.
Self::drop_task(ptr); Self::drop_ref(ptr);
} }
break; break;
} }
@ -592,13 +592,13 @@ where
/// A guard that closes the task if polling its future panics. /// A guard that closes the task if polling its future panics.
struct Guard<F, T, S>(RawTask<F, T, S>) struct Guard<F, T, S>(RawTask<F, T, S>)
where where
F: Future<Output = T> + 'static, F: Future<Output = T>,
S: Fn(Runnable) + Send + Sync + 'static; S: Fn(Runnable);
impl<F, T, S> Drop for Guard<F, T, S> impl<F, T, S> Drop for Guard<F, T, S>
where where
F: Future<Output = T> + 'static, F: Future<Output = T>,
S: Fn(Runnable) + Send + Sync + 'static, S: Fn(Runnable),
{ {
fn drop(&mut self) { fn drop(&mut self) {
let raw = self.0; let raw = self.0;
@ -626,7 +626,7 @@ where
} }
// Drop the task reference. // Drop the task reference.
RawTask::<F, T, S>::drop_task(ptr); RawTask::<F, T, S>::drop_ref(ptr);
break; break;
} }
@ -647,7 +647,7 @@ where
} }
// Drop the task reference. // Drop the task reference.
RawTask::<F, T, S>::drop_task(ptr); RawTask::<F, T, S>::drop_ref(ptr);
break; break;
} }
Err(s) => state = s, Err(s) => state = s,

154
src/runnable.rs
View File

@ -13,17 +13,18 @@ use crate::Task;
/// Creates a new task. /// Creates a new task.
/// ///
/// This constructor returns a [`Runnable`] reference that runs the future and a [`Task`] /// The returned [`Runnable`] is used to poll the `future`, and the [`Task`] is used to await its
/// that awaits its result. /// output.
/// ///
/// When run, the task polls `future`. When woken up, it gets scheduled for running by the /// Method [`Runnable::run()`] polls the `future` once. Then, the [`Runnable`] vanishes and
/// `schedule` function. /// only reappears when its [`Waker`] wakes the task, thus scheduling it to be run again.
/// ///
/// The schedule function should not attempt to run the task nor to drop it. Instead, it should /// When the task is woken, its [`Runnable`] is passed to the `schedule` function.
/// push the task into some kind of queue so that it can be processed later. /// 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`], consider using the /// If you need to spawn a future that does not implement [`Send`] or isn't `'static`, consider
/// [`spawn_local`] function instead. /// using [`spawn_local()`] or [`spawn_unchecked()`] instead.
/// ///
/// # Examples /// # Examples
/// ///
@ -40,40 +41,28 @@ use crate::Task;
/// // Create a task with the future and the schedule function. /// // Create a task with the future and the schedule function.
/// let (runnable, task) = async_task::spawn(future, schedule); /// let (runnable, task) = async_task::spawn(future, schedule);
/// ``` /// ```
pub fn spawn<F, T, S>(future: F, schedule: S) -> (Runnable, Task<T>) pub fn spawn<F, S>(future: F, schedule: S) -> (Runnable, Task<F::Output>)
where where
F: Future<Output = T> + Send + 'static, F: Future + Send + 'static,
T: Send + 'static, F::Output: Send + 'static,
S: Fn(Runnable) + Send + Sync + 'static, S: Fn(Runnable) + Send + Sync + 'static,
{ {
// Allocate large futures on the heap. unsafe { spawn_unchecked(future, schedule) }
let raw_task = if mem::size_of::<F>() >= 2048 {
let future = alloc::boxed::Box::pin(future);
RawTask::<_, T, S>::allocate(future, schedule)
} else {
RawTask::<F, T, S>::allocate(future, schedule)
};
let runnable = Runnable { raw_task };
let task = Task {
raw_task,
_marker: PhantomData,
};
(runnable, task)
} }
/// Creates a new local task. /// Creates a new local task.
/// ///
/// This constructor returns a [`Runnable`] reference that runs the future and a [`Task`] /// The returned [`Runnable`] is used to poll the `future`, and the [`Task`] is used to await its
/// that awaits its result. /// output.
/// ///
/// When run, the task polls `future`. When woken up, it gets scheduled for running by the /// Method [`Runnable::run()`] polls the `future` once. Then, the [`Runnable`] vanishes and
/// `schedule` function. /// only reappears when its [`Waker`] wakes the task, thus scheduling it to be run again.
/// ///
/// The schedule function should not attempt to run the task nor to drop it. Instead, it should /// When the task is woken, its [`Runnable`] is passed to the `schedule` function.
/// push the task into some kind of queue so that it can be processed later. /// 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.
/// ///
/// Unlike [`spawn`], this function does not require the future to implement [`Send`]. If the /// Unlike [`spawn()`], this function does not require the `future` to implement [`Send`]. If the
/// [`Runnable`] reference is run or dropped on a thread it was not created on, a panic will occur. /// [`Runnable`] reference is run or dropped on a thread it was not created on, a panic will occur.
/// ///
/// **NOTE:** This function is only available when the `std` feature for this crate is enabled (it /// **NOTE:** This function is only available when the `std` feature for this crate is enabled (it
@ -95,10 +84,10 @@ where
/// let (runnable, task) = async_task::spawn_local(future, schedule); /// let (runnable, task) = async_task::spawn_local(future, schedule);
/// ``` /// ```
#[cfg(feature = "std")] #[cfg(feature = "std")]
pub fn spawn_local<F, T, S>(future: F, schedule: S) -> (Runnable, Task<T>) pub fn spawn_local<F, S>(future: F, schedule: S) -> (Runnable, Task<F::Output>)
where where
F: Future<Output = T> + 'static, F: Future + 'static,
T: 'static, F::Output: 'static,
S: Fn(Runnable) + Send + Sync + 'static, S: Fn(Runnable) + Send + Sync + 'static,
{ {
use std::mem::ManuallyDrop; use std::mem::ManuallyDrop;
@ -144,23 +133,60 @@ where
} }
} }
// Wrap the future into one that which thread it's on. // Wrap the future into one that checks which thread it's on.
let future = Checked { let future = Checked {
id: thread_id(), id: thread_id(),
inner: ManuallyDrop::new(future), inner: ManuallyDrop::new(future),
}; };
unsafe { spawn_unchecked(future, schedule) }
}
/// Creates a new task.
///
/// The returned [`Runnable`] is used to poll the `future`, and the [`Task`] is used to await its
/// output.
///
/// Method [`Runnable::run()`] polls the `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.
///
/// Safe but more restrictive variants of this function are [`spawn()`] or [`spawn_local()`].
///
/// # Examples
///
/// ```
/// // 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 { async_task::spawn_unchecked(future, schedule) };
/// ```
pub unsafe fn spawn_unchecked<F, S>(future: F, schedule: S) -> (Runnable, Task<F::Output>)
where
F: Future,
S: Fn(Runnable),
{
// Allocate large futures on the heap. // Allocate large futures on the heap.
let raw_task = if mem::size_of::<F>() >= 2048 { let ptr = if mem::size_of::<F>() >= 2048 {
let future = alloc::boxed::Box::pin(future); let future = alloc::boxed::Box::pin(future);
RawTask::<_, T, S>::allocate(future, schedule) RawTask::<_, F::Output, S>::allocate(future, schedule)
} else { } else {
RawTask::<_, T, S>::allocate(future, schedule) RawTask::<F, F::Output, S>::allocate(future, schedule)
}; };
let runnable = Runnable { raw_task }; let runnable = Runnable { ptr };
let task = Task { let task = Task {
raw_task, ptr,
_marker: PhantomData, _marker: PhantomData,
}; };
(runnable, task) (runnable, task)
@ -182,9 +208,17 @@ where
/// canceled. When canceled, the task won't be scheduled again even if a [`Waker`] wakes it. It is /// canceled. When canceled, the task won't be scheduled again even if a [`Waker`] wakes it. It is
/// possible for the [`Task`] to cancel while the [`Runnable`] reference exists, in which /// possible for the [`Task`] to cancel while the [`Runnable`] reference exists, in which
/// case an attempt to run the task won't do anything. /// case an attempt to run the task won't do anything.
///
/// ----------------
///
/// A runnable future, ready for execution.
///
/// Once a `Runnable` is run, it "vanishes" and only reappears when its future is woken. When it's
/// woken up, its schedule function is called, which means the `Runnable` gets pushed into a task
/// queue in an executor.
pub struct Runnable { pub struct Runnable {
/// A pointer to the heap-allocated task. /// A pointer to the heap-allocated task.
pub(crate) raw_task: NonNull<()>, pub(crate) ptr: NonNull<()>,
} }
unsafe impl Send for Runnable {} unsafe impl Send for Runnable {}
@ -203,7 +237,7 @@ impl Runnable {
/// ///
/// If the task is canceled, this method won't do anything. /// If the task is canceled, this method won't do anything.
pub fn schedule(self) { pub fn schedule(self) {
let ptr = self.raw_task.as_ptr(); let ptr = self.ptr.as_ptr();
let header = ptr as *const Header; let header = ptr as *const Header;
mem::forget(self); mem::forget(self);
@ -226,9 +260,10 @@ impl Runnable {
/// ///
/// It is possible that polling the future panics, in which case the panic will be propagated /// It is possible that polling the future panics, in which case the panic will be propagated
/// into the caller. It is advised that invocations of this method are wrapped inside /// into the caller. It is advised that invocations of this method are wrapped inside
/// [`catch_unwind`]. If a panic occurs, the task is automatically canceled. /// [`catch_unwind`][`std::panic::catch_unwind`]. If a panic occurs, the task is automatically
/// canceled.
pub fn run(self) -> bool { pub fn run(self) -> bool {
let ptr = self.raw_task.as_ptr(); let ptr = self.ptr.as_ptr();
let header = ptr as *const Header; let header = ptr as *const Header;
mem::forget(self); mem::forget(self);
@ -237,7 +272,7 @@ impl Runnable {
/// Returns a waker associated with this task. /// Returns a waker associated with this task.
pub fn waker(&self) -> Waker { pub fn waker(&self) -> Waker {
let ptr = self.raw_task.as_ptr(); let ptr = self.ptr.as_ptr();
let header = ptr as *const Header; let header = ptr as *const Header;
unsafe { unsafe {
@ -249,12 +284,29 @@ impl Runnable {
impl Drop for Runnable { impl Drop for Runnable {
fn drop(&mut self) { fn drop(&mut self) {
let ptr = self.raw_task.as_ptr(); let ptr = self.ptr.as_ptr();
let header = ptr as *const Header; let header = ptr as *const Header;
unsafe { unsafe {
// Cancel the task. let mut state = (*header).state.load(Ordering::Acquire);
(*header).cancel();
loop {
// If the task has been completed or closed, it can't be canceled.
if state & (COMPLETED | CLOSED) != 0 {
break;
}
// Mark the task as closed.
match (*header).state.compare_exchange_weak(
state,
state | CLOSED,
Ordering::AcqRel,
Ordering::Acquire,
) {
Ok(_) => break,
Err(s) => state = s,
}
}
// Drop the future. // Drop the future.
((*header).vtable.drop_future)(ptr); ((*header).vtable.drop_future)(ptr);
@ -268,14 +320,14 @@ impl Drop for Runnable {
} }
// Drop the task reference. // Drop the task reference.
((*header).vtable.drop_task)(ptr); ((*header).vtable.drop_ref)(ptr);
} }
} }
} }
impl fmt::Debug for Runnable { impl fmt::Debug for Runnable {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let ptr = self.raw_task.as_ptr(); let ptr = self.ptr.as_ptr();
let header = ptr as *const Header; let header = ptr as *const Header;
f.debug_struct("Runnable") f.debug_struct("Runnable")

9
src/state.rs
View File

@ -1,7 +1,6 @@
/// Set if the task is scheduled for running. /// Set if the task is scheduled for running.
/// ///
/// A task is considered to be scheduled whenever its `Runnable` reference exists. It therefore /// A task is considered to be scheduled whenever its `Runnable` exists.
/// also begins in scheduled state at the moment of creation.
/// ///
/// This flag can't be set when the task is completed. However, it can be set while the task is /// This flag can't be set when the task is completed. However, it can be set while the task is
/// running, in which case it will be rescheduled as soon as polling finishes. /// running, in which case it will be rescheduled as soon as polling finishes.
@ -27,7 +26,7 @@ pub(crate) const COMPLETED: usize = 1 << 2;
/// Set if the task is closed. /// Set if the task is closed.
/// ///
/// If a task is closed, that means it's either canceled or its output has been consumed by the /// If a task is closed, that means it's either canceled or its output has been consumed by the
/// `Task`. A task becomes closed when: /// `Task`. A task becomes closed in the following cases:
/// ///
/// 1. It gets canceled by `Runnable::drop()`, `Task::drop()`, or `Task::cancel()`. /// 1. It gets canceled by `Runnable::drop()`, `Task::drop()`, or `Task::cancel()`.
/// 2. Its output gets awaited by the `Task`. /// 2. Its output gets awaited by the `Task`.
@ -39,7 +38,7 @@ pub(crate) const CLOSED: usize = 1 << 3;
/// ///
/// The `Task` is a special case in that it is only tracked by this flag, while all other /// The `Task` is a special case in that it is only tracked by this flag, while all other
/// task references (`Runnable` and `Waker`s) are tracked by the reference count. /// task references (`Runnable` and `Waker`s) are tracked by the reference count.
pub(crate) const HANDLE: usize = 1 << 4; pub(crate) const TASK: usize = 1 << 4;
/// Set if the `Task` is awaiting the output. /// Set if the `Task` is awaiting the output.
/// ///
@ -66,5 +65,5 @@ pub(crate) const NOTIFYING: usize = 1 << 7;
/// total reference count. /// total reference count.
/// ///
/// Note that the reference counter only tracks the `Runnable` and `Waker`s. The `Task` is /// Note that the reference counter only tracks the `Runnable` and `Waker`s. The `Task` is
/// tracked separately by the `HANDLE` flag. /// tracked separately by the `TASK` flag.
pub(crate) const REFERENCE: usize = 1 << 8; pub(crate) const REFERENCE: usize = 1 << 8;

127
src/task.rs
View File

@ -10,16 +10,43 @@ use core::task::{Context, Poll};
use crate::header::Header; use crate::header::Header;
use crate::state::*; use crate::state::*;
/// A handle that awaits the result of a task. /// A spawned task.
/// ///
/// This type is a future that resolves to an `Option<T>` where: /// A [`Task`] can be awaited to retrieve the output of its future.
/// ///
/// * `None` indicates the task has panicked or was canceled. /// Dropping a [`Task`] cancels it, which means its future won't be polled again.
/// * `Some(result)` indicates the task has completed with `result` of type `T`. /// To drop the [`Task`] handle without canceling it, use [`detach()`][`Task::detach()`] instead.
/// To cancel a task gracefully and wait until it is fully destroyed, use the
/// [`cancel()`][Task::cancel()] method.
///
/// Note that canceling a task actually wakes it and reschedules one last time. Then, the executor
/// can destroy the task by simply dropping its [`Runnable`][`crate::Runnable`] or by invoking
/// [`run()`][`crate::Runnable::run()`].
///
/// # Examples
///
/// ```
/// use smol::{future, Executor};
/// 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 task's output.
/// assert_eq!(future::block_on(task), 3);
/// ```
#[must_use = "tasks get canceled when dropped, use `.detach()` to run them in the background"] #[must_use = "tasks get canceled when dropped, use `.detach()` to run them in the background"]
pub struct Task<T> { pub struct Task<T> {
/// A raw task pointer. /// A raw task pointer.
pub(crate) raw_task: NonNull<()>, pub(crate) ptr: NonNull<()>,
/// A marker capturing generic type `T`. /// A marker capturing generic type `T`.
pub(crate) _marker: PhantomData<T>, pub(crate) _marker: PhantomData<T>,
@ -36,12 +63,64 @@ impl<T> std::panic::UnwindSafe for Task<T> {}
impl<T> std::panic::RefUnwindSafe for Task<T> {} impl<T> std::panic::RefUnwindSafe for Task<T> {}
impl<T> Task<T> { impl<T> Task<T> {
/// Detaches the task to let it keep running in the background.
///
/// # Examples
///
/// ```
/// use smol::{Executor, 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 fn detach(self) { pub fn detach(self) {
let mut this = self; let mut this = self;
let _out = this.set_detached(); let _out = this.set_detached();
mem::forget(this); mem::forget(this);
} }
/// 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 smol::{future, Executor, Timer};
/// 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;
/// });
/// ```
pub async fn cancel(self) -> Option<T> { pub async fn cancel(self) -> Option<T> {
let mut this = self; let mut this = self;
this.set_canceled(); this.set_canceled();
@ -52,15 +131,16 @@ impl<T> Task<T> {
type Output = Option<T>; type Output = Option<T>;
fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> { fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
self.0.poll_result(cx) self.0.poll_task(cx)
} }
} }
Fut(this).await Fut(this).await
} }
/// Puts the task in canceled state.
fn set_canceled(&mut self) { fn set_canceled(&mut self) {
let ptr = self.raw_task.as_ptr(); let ptr = self.ptr.as_ptr();
let header = ptr as *const Header; let header = ptr as *const Header;
unsafe { unsafe {
@ -106,19 +186,20 @@ impl<T> Task<T> {
} }
} }
/// Puts the task in detached state.
fn set_detached(&mut self) -> Option<T> { fn set_detached(&mut self) -> Option<T> {
let ptr = self.raw_task.as_ptr(); let ptr = self.ptr.as_ptr();
let header = ptr as *const Header; let header = ptr as *const Header;
unsafe { unsafe {
// A place where the output will be stored in case it needs to be dropped. // A place where the output will be stored in case it needs to be dropped.
let mut output = None; let mut output = None;
// Optimistically assume the `Task` is being detached just after creating the // Optimistically assume the `Task` is being detached just after creating the task.
// task. This is a common case so if the handle is not used, the overhead of it is only // This is a common case so if the `Task` is datached, the overhead of it is only one
// one compare-exchange operation. // compare-exchange operation.
if let Err(mut state) = (*header).state.compare_exchange_weak( if let Err(mut state) = (*header).state.compare_exchange_weak(
SCHEDULED | HANDLE | REFERENCE, SCHEDULED | TASK | REFERENCE,
SCHEDULED | REFERENCE, SCHEDULED | REFERENCE,
Ordering::AcqRel, Ordering::AcqRel,
Ordering::Acquire, Ordering::Acquire,
@ -151,10 +232,10 @@ impl<T> Task<T> {
let new = if state & (!(REFERENCE - 1) | CLOSED) == 0 { let new = if state & (!(REFERENCE - 1) | CLOSED) == 0 {
SCHEDULED | CLOSED | REFERENCE SCHEDULED | CLOSED | REFERENCE
} else { } else {
state & !HANDLE state & !TASK
}; };
// Unset the handle flag. // Unset the `TASK` flag.
match (*header).state.compare_exchange_weak( match (*header).state.compare_exchange_weak(
state, state,
new, new,
@ -184,8 +265,18 @@ impl<T> Task<T> {
} }
} }
fn poll_result(&mut self, cx: &mut Context<'_>) -> Poll<Option<T>> { /// Polls the task to retrieve its output.
let ptr = self.raw_task.as_ptr(); ///
/// Returns `Some` if the task has completed or `None` if it was closed.
///
/// A task becomes closed in the following cases:
///
/// 1. It gets canceled by `Runnable::drop()`, `Task::drop()`, or `Task::cancel()`.
/// 2. Its output gets awaited by the `Task`.
/// 3. It panics while polling the future.
/// 4. It is completed and the `Task` gets dropped.
fn poll_task(&mut self, cx: &mut Context<'_>) -> Poll<Option<T>> {
let ptr = self.ptr.as_ptr();
let header = ptr as *const Header; let header = ptr as *const Header;
unsafe { unsafe {
@ -273,7 +364,7 @@ impl<T> Future for Task<T> {
type Output = T; type Output = T;
fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> { fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
match self.poll_result(cx) { match self.poll_task(cx) {
Poll::Ready(t) => Poll::Ready(t.expect("task has failed")), Poll::Ready(t) => Poll::Ready(t.expect("task has failed")),
Poll::Pending => Poll::Pending, Poll::Pending => Poll::Pending,
} }
@ -282,7 +373,7 @@ impl<T> Future for Task<T> {
impl<T> fmt::Debug for Task<T> { impl<T> fmt::Debug for Task<T> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let ptr = self.raw_task.as_ptr(); let ptr = self.ptr.as_ptr();
let header = ptr as *const Header; let header = ptr as *const Header;
f.debug_struct("Task") f.debug_struct("Task")

2
tests/basic.rs
View File

@ -4,7 +4,7 @@ use std::sync::atomic::{AtomicUsize, Ordering};
use std::task::{Context, Poll}; use std::task::{Context, Poll};
use async_task::Runnable; use async_task::Runnable;
use futures_lite::future; use smol::future;
// Creates a future with event counters. // Creates a future with event counters.
// //

2
tests/cancel.rs
View File

@ -7,7 +7,7 @@ use std::time::Duration;
use async_task::Runnable; use async_task::Runnable;
use easy_parallel::Parallel; use easy_parallel::Parallel;
use futures_lite::future; use smol::future;
// Creates a future with event counters. // Creates a future with event counters.
// //

2
tests/join.rs
View File

@ -9,7 +9,7 @@ use std::time::Duration;
use async_task::Runnable; use async_task::Runnable;
use easy_parallel::Parallel; use easy_parallel::Parallel;
use futures_lite::future; use smol::future;
// Creates a future with event counters. // Creates a future with event counters.
// //

2
tests/panic.rs
View File

@ -8,7 +8,7 @@ use std::time::Duration;
use async_task::Runnable; use async_task::Runnable;
use easy_parallel::Parallel; use easy_parallel::Parallel;
use futures_lite::future; use smol::future;
// Creates a future with event counters. // Creates a future with event counters.
// //

2
tests/ready.rs
View File

@ -7,7 +7,7 @@ use std::time::Duration;
use async_task::Runnable; use async_task::Runnable;
use easy_parallel::Parallel; use easy_parallel::Parallel;
use futures_lite::future; use smol::future;
// Creates a future with event counters. // Creates a future with event counters.
// //

2
tests/waker_panic.rs
View File

@ -10,7 +10,7 @@ use std::time::Duration;
use async_task::Runnable; use async_task::Runnable;
use atomic_waker::AtomicWaker; use atomic_waker::AtomicWaker;
use easy_parallel::Parallel; use easy_parallel::Parallel;
use futures_lite::future; use smol::future;
// Creates a future with event counters. // Creates a future with event counters.
// //