mirror of
https://github.com/rust-lang/rust.git
synced 2025-05-14 02:49:40 +00:00
93 lines
3.6 KiB
Rust
93 lines
3.6 KiB
Rust
#![unstable(feature = "wake_trait", issue = "69912")]
|
|
//! Types and Traits for working with asynchronous tasks.
|
|
use core::mem::ManuallyDrop;
|
|
use core::task::{RawWaker, RawWakerVTable, Waker};
|
|
|
|
use crate::sync::Arc;
|
|
|
|
/// The implementation of waking a task on an executor.
|
|
///
|
|
/// This trait can be used to create a [`Waker`]. An executor can define an
|
|
/// implementation of this trait, and use that to construct a Waker to pass
|
|
/// to the tasks that are executed on that executor.
|
|
///
|
|
/// This trait is a memory-safe and ergonomic alternative to constructing a
|
|
/// [`RawWaker`]. It supports the common executor design in which the data used
|
|
/// to wake up a task is stored in an [`Arc`][arc]. Some executors (especially
|
|
/// those for embedded systems) cannot use this API, which is why [`RawWaker`]
|
|
/// exists as an alternative for those systems.
|
|
///
|
|
/// [arc]: ../../std/sync/struct.Arc.html
|
|
#[unstable(feature = "wake_trait", issue = "69912")]
|
|
pub trait Wake {
|
|
/// Wake this task.
|
|
#[unstable(feature = "wake_trait", issue = "69912")]
|
|
fn wake(self: Arc<Self>);
|
|
|
|
/// Wake this task without consuming the waker.
|
|
///
|
|
/// If an executor supports a cheaper way to wake without consuming the
|
|
/// waker, it should override this method. By default, it clones the
|
|
/// [`Arc`] and calls `wake` on the clone.
|
|
#[unstable(feature = "wake_trait", issue = "69912")]
|
|
fn wake_by_ref(self: &Arc<Self>) {
|
|
self.clone().wake();
|
|
}
|
|
}
|
|
|
|
#[unstable(feature = "wake_trait", issue = "69912")]
|
|
impl<W: Wake + Send + Sync + 'static> From<Arc<W>> for Waker {
|
|
fn from(waker: Arc<W>) -> Waker {
|
|
// SAFETY: This is safe because raw_waker safely constructs
|
|
// a RawWaker from Arc<W>.
|
|
unsafe { Waker::from_raw(raw_waker(waker)) }
|
|
}
|
|
}
|
|
|
|
#[unstable(feature = "wake_trait", issue = "69912")]
|
|
impl<W: Wake + Send + Sync + 'static> From<Arc<W>> for RawWaker {
|
|
fn from(waker: Arc<W>) -> RawWaker {
|
|
raw_waker(waker)
|
|
}
|
|
}
|
|
|
|
// NB: This private function for constructing a RawWaker is used, rather than
|
|
// inlining this into the `From<Arc<W>> for RawWaker` impl, to ensure that
|
|
// the safety of `From<Arc<W>> for Waker` does not depend on the correct
|
|
// trait dispatch - instead both impls call this function directly and
|
|
// explicitly.
|
|
#[inline(always)]
|
|
fn raw_waker<W: Wake + Send + Sync + 'static>(waker: Arc<W>) -> RawWaker {
|
|
// Increment the reference count of the arc to clone it.
|
|
unsafe fn clone_waker<W: Wake + Send + Sync + 'static>(waker: *const ()) -> RawWaker {
|
|
unsafe { Arc::incr_strong_count(waker as *const W) };
|
|
RawWaker::new(
|
|
waker as *const (),
|
|
&RawWakerVTable::new(clone_waker::<W>, wake::<W>, wake_by_ref::<W>, drop_waker::<W>),
|
|
)
|
|
}
|
|
|
|
// Wake by value, moving the Arc into the Wake::wake function
|
|
unsafe fn wake<W: Wake + Send + Sync + 'static>(waker: *const ()) {
|
|
let waker: Arc<W> = unsafe { Arc::from_raw(waker as *const W) };
|
|
<W as Wake>::wake(waker);
|
|
}
|
|
|
|
// Wake by reference, wrap the waker in ManuallyDrop to avoid dropping it
|
|
unsafe fn wake_by_ref<W: Wake + Send + Sync + 'static>(waker: *const ()) {
|
|
let waker: ManuallyDrop<Arc<W>> =
|
|
unsafe { ManuallyDrop::new(Arc::from_raw(waker as *const W)) };
|
|
<W as Wake>::wake_by_ref(&waker);
|
|
}
|
|
|
|
// Decrement the reference count of the Arc on drop
|
|
unsafe fn drop_waker<W: Wake + Send + Sync + 'static>(waker: *const ()) {
|
|
unsafe { Arc::decr_strong_count(waker as *const W) };
|
|
}
|
|
|
|
RawWaker::new(
|
|
Arc::into_raw(waker) as *const (),
|
|
&RawWakerVTable::new(clone_waker::<W>, wake::<W>, wake_by_ref::<W>, drop_waker::<W>),
|
|
)
|
|
}
|