nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2025-01-25 22:22:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add Future and task system to the standard library

Browse Source
This commit is contained in:
Taylor Cramer 2018-05-30 18:23:10 -07:00
parent fddb46eda3
commit a6055c8859
8 changed files with 961 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
src/liballoc/boxed.rs
View File

@ -59,12 +59,14 @@ use core::any::Any;
use core::borrow;
use core::cmp::Ordering;
use core::fmt;
use core::future::Future;
use core::hash::{Hash, Hasher};
use core::iter::FusedIterator;
use core::marker::{Unpin, Unsize};
use core::mem::{self, PinMut};
use core::ops::{CoerceUnsized, Deref, DerefMut, Generator, GeneratorState};
use core::ptr::{self, NonNull, Unique};
use core::task::{Context, Poll, UnsafePoll, TaskObj};
use core::convert::From;
use raw_vec::RawVec;
@ -755,6 +757,7 @@ impl<T> Generator for Box<T>
/// A pinned, heap allocated reference.
#[unstable(feature = "pin", issue = "49150")]
#[fundamental]
#[repr(transparent)]
pub struct PinBox<T: ?Sized> {
inner: Box<T>,
}
@ -771,14 +774,72 @@ impl<T> PinBox<T> {
#[unstable(feature = "pin", issue = "49150")]
impl<T: ?Sized> PinBox<T> {
/// Get a pinned reference to the data in this PinBox.
#[inline]
pub fn as_pin_mut<'a>(&'a mut self) -> PinMut<'a, T> {
unsafe { PinMut::new_unchecked(&mut *self.inner) }
}
/// Constructs a `PinBox` from a raw pointer.
///
/// After calling this function, the raw pointer is owned by the
/// resulting `PinBox`. Specifically, the `PinBox` destructor will call
/// the destructor of `T` and free the allocated memory. Since the
/// way `PinBox` allocates and releases memory is unspecified, the
/// only valid pointer to pass to this function is the one taken
/// from another `PinBox` via the [`PinBox::into_raw`] function.
///
/// This function is unsafe because improper use may lead to
/// memory problems. For example, a double-free may occur if the
/// function is called twice on the same raw pointer.
///
/// [`PinBox::into_raw`]: struct.PinBox.html#method.into_raw
///
/// # Examples
///
/// ```
/// #![feature(pin)]
/// use std::boxed::PinBox;
/// let x = PinBox::new(5);
/// let ptr = PinBox::into_raw(x);
/// let x = unsafe { PinBox::from_raw(ptr) };
/// ```
#[inline]
pub unsafe fn from_raw(raw: *mut T) -> Self {
PinBox { inner: Box::from_raw(raw) }
}
/// Consumes the `PinBox`, returning the wrapped raw pointer.
///
/// After calling this function, the caller is responsible for the
/// memory previously managed by the `PinBox`. In particular, the
/// caller should properly destroy `T` and release the memory. The
/// proper way to do so is to convert the raw pointer back into a
/// `PinBox` with the [`PinBox::from_raw`] function.
///
/// Note: this is an associated function, which means that you have
/// to call it as `PinBox::into_raw(b)` instead of `b.into_raw()`. This
/// is so that there is no conflict with a method on the inner type.
///
/// [`PinBox::from_raw`]: struct.PinBox.html#method.from_raw
///
/// # Examples
///
/// ```
/// #![feature(pin)]
/// use std::boxed::PinBox;
/// let x = PinBox::new(5);
/// let ptr = PinBox::into_raw(x);
/// ```
#[inline]
pub fn into_raw(b: PinBox<T>) -> *mut T {
Box::into_raw(b.inner)
}
/// Get a mutable reference to the data inside this PinBox.
///
/// This function is unsafe. Users must guarantee that the data is never
/// moved out of this reference.
#[inline]
pub unsafe fn get_mut<'a>(this: &'a mut PinBox<T>) -> &'a mut T {
&mut *this.inner
}
@ -787,6 +848,7 @@ impl<T: ?Sized> PinBox<T> {
///
/// This function is unsafe. Users must guarantee that the data is never
/// moved out of the box.
#[inline]
pub unsafe fn unpin(this: PinBox<T>) -> Box<T> {
this.inner
}
@ -851,3 +913,34 @@ impl<T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<PinBox<U>> for PinBox<T> {}
#[unstable(feature = "pin", issue = "49150")]
impl<T: ?Sized> Unpin for PinBox<T> {}
#[unstable(feature = "futures_api", issue = "50547")]
unsafe impl<F: Future<Output = ()> + Send + 'static> UnsafePoll for PinBox<F> {
fn into_raw(self) -> *mut () {
PinBox::into_raw(self) as *mut ()
}
unsafe fn poll(task: *mut (), cx: &mut Context) -> Poll<()> {
let ptr = task as *mut F;
let pin: PinMut<F> = PinMut::new_unchecked(&mut *ptr);
pin.poll(cx)
}
unsafe fn drop(task: *mut ()) {
drop(PinBox::from_raw(task as *mut F))
}
}
#[unstable(feature = "futures_api", issue = "50547")]
impl<F: Future<Output = ()> + Send + 'static> From<PinBox<F>> for TaskObj {
fn from(boxed: PinBox<F>) -> Self {
TaskObj::from_poll_task(boxed)
}
}
#[unstable(feature = "futures_api", issue = "50547")]
impl<F: Future<Output = ()> + Send + 'static> From<Box<F>> for TaskObj {
fn from(boxed: Box<F>) -> Self {
TaskObj::from_poll_task(PinBox::from(boxed))
}
}

6
src/liballoc/lib.rs
View File

@ -95,6 +95,7 @@
#![feature(fmt_internals)]
#![feature(from_ref)]
#![feature(fundamental)]
#![feature(futures_api)]
#![feature(lang_items)]
#![feature(libc)]
#![feature(needs_allocator)]
@ -103,6 +104,7 @@
#![feature(pin)]
#![feature(ptr_internals)]
#![feature(ptr_offset_from)]
#![feature(repr_transparent)]
#![feature(rustc_attrs)]
#![feature(slice_get_slice)]
#![feature(specialization)]
@ -156,6 +158,10 @@ pub mod heap {
pub use alloc::*;
}
#[unstable(feature = "futures_api",
reason = "futures in libcore are unstable",
issue = "50547")]
pub mod task;
// Primitive types using the heaps above

140
src/liballoc/task.rs Normal file
View File

@ -0,0 +1,140 @@
// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
// file at the top-level directory of this distribution and at
// http://rust-lang.org/COPYRIGHT.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.
//! Types and Traits for working with asynchronous tasks.
pub use core::task::*;
#[cfg(target_has_atomic = "ptr")]
pub use self::if_arc::*;
#[cfg(target_has_atomic = "ptr")]
mod if_arc {
use super::*;
use arc::Arc;
use core::marker::PhantomData;
use core::mem;
use core::ptr::{self, NonNull};
/// A way of waking up a specific task.
///
/// Any task executor must provide a way of signaling that a task it owns
/// is ready to be `poll`ed again. Executors do so by implementing this trait.
pub trait Wake: Send + Sync {
/// Indicates that the associated task is ready to make progress and should
/// be `poll`ed.
///
/// Executors generally maintain a queue of "ready" tasks; `wake` should place
/// the associated task onto this queue.
fn wake(arc_self: &Arc<Self>);
/// Indicates that the associated task is ready to make progress and should
/// be `poll`ed. This function is like `wake`, but can only be called from the
/// thread on which this `Wake` was created.
///
/// Executors generally maintain a queue of "ready" tasks; `wake_local` should place
/// the associated task onto this queue.
#[inline]
unsafe fn wake_local(arc_self: &Arc<Self>) {
Self::wake(arc_self);
}
}
#[cfg(target_has_atomic = "ptr")]
struct ArcWrapped<T>(PhantomData<T>);
unsafe impl<T: Wake + 'static> UnsafeWake for ArcWrapped<T> {
#[inline]
unsafe fn clone_raw(&self) -> Waker {
let me: *const ArcWrapped<T> = self;
let arc = (*(&me as *const *const ArcWrapped<T> as *const Arc<T>)).clone();
Waker::from(arc)
}
#[inline]
unsafe fn drop_raw(&self) {
let mut me: *const ArcWrapped<T> = self;
let me = &mut me as *mut *const ArcWrapped<T> as *mut Arc<T>;
ptr::drop_in_place(me);
}
#[inline]
unsafe fn wake(&self) {
let me: *const ArcWrapped<T> = self;
T::wake(&*(&me as *const *const ArcWrapped<T> as *const Arc<T>))
}
#[inline]
unsafe fn wake_local(&self) {
let me: *const ArcWrapped<T> = self;
T::wake_local(&*(&me as *const *const ArcWrapped<T> as *const Arc<T>))
}
}
impl<T> From<Arc<T>> for Waker
where T: Wake + 'static,
{
fn from(rc: Arc<T>) -> Self {
unsafe {
let ptr = mem::transmute::<Arc<T>, NonNull<ArcWrapped<T>>>(rc);
Waker::new(ptr)
}
}
}
/// Creates a `LocalWaker` from a local `wake`.
///
/// This function requires that `wake` is "local" (created on the current thread).
/// The resulting `LocalWaker` will call `wake.wake_local()` when awoken, and
/// will call `wake.wake()` if awoken after being converted to a `Waker`.
#[inline]
pub unsafe fn local_waker<W: Wake + 'static>(wake: Arc<W>) -> LocalWaker {
let ptr = mem::transmute::<Arc<W>, NonNull<ArcWrapped<W>>>(wake);
LocalWaker::new(ptr)
}
struct NonLocalAsLocal<T>(ArcWrapped<T>);
unsafe impl<T: Wake + 'static> UnsafeWake for NonLocalAsLocal<T> {
#[inline]
unsafe fn clone_raw(&self) -> Waker {
self.0.clone_raw()
}
#[inline]
unsafe fn drop_raw(&self) {
self.0.drop_raw()
}
#[inline]
unsafe fn wake(&self) {
self.0.wake()
}
#[inline]
unsafe fn wake_local(&self) {
// Since we're nonlocal, we can't call wake_local
self.0.wake()
}
}
/// Creates a `LocalWaker` from a non-local `wake`.
///
/// This function is similar to `local_waker`, but does not require that `wake`
/// is local to the current thread. The resulting `LocalWaker` will call
/// `wake.wake()` when awoken.
#[inline]
pub fn local_waker_from_nonlocal<W: Wake + 'static>(wake: Arc<W>) -> LocalWaker {
unsafe {
let ptr = mem::transmute::<Arc<W>, NonNull<NonLocalAsLocal<W>>>(wake);
LocalWaker::new(ptr)
}
}
}

93
src/libcore/future.rs Normal file
View File

@ -0,0 +1,93 @@
// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
// file at the top-level directory of this distribution and at
// http://rust-lang.org/COPYRIGHT.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.
#![unstable(feature = "futures_api",
reason = "futures in libcore are unstable",
issue = "50547")]
//! Asynchronous values.
use mem::PinMut;
use task::{self, Poll};
/// A future represents an asychronous computation.
///
/// A future is a value that may not have finished computing yet. This kind of
/// "asynchronous value" makes it possible for a thread to continue doing useful
/// work while it waits for the value to become available.
///
/// # The `poll` method
///
/// The core method of future, `poll`, *attempts* to resolve the future into a
/// final value. This method does not block if the value is not ready. Instead,
/// the current task is scheduled to be woken up when it's possible to make
/// further progress by `poll`ing again. The wake up is performed using
/// `cx.waker()`, a handle for waking up the current task.
///
/// When using a future, you generally won't call `poll` directly, but instead
/// `await!` the value.
pub trait Future {
/// The result of the `Future`.
type Output;
/// Attempt to resolve the future to a final value, registering
/// the current task for wakeup if the value is not yet available.
///
/// # Return value
///
/// This function returns:
///
/// - `Poll::Pending` if the future is not ready yet
/// - `Poll::Ready(val)` with the result `val` of this future if it finished
/// successfully.
///
/// Once a future has finished, clients should not `poll` it again.
///
/// When a future is not ready yet, `poll` returns
/// [`Poll::Pending`](::task::Poll). The future will *also* register the
/// interest of the current task in the value being produced. For example,
/// if the future represents the availability of data on a socket, then the
/// task is recorded so that when data arrives, it is woken up (via
/// [`cx.waker()`](::task::Context::waker)). Once a task has been woken up,
/// it should attempt to `poll` the future again, which may or may not
/// produce a final value.
///
/// Note that if `Pending` is returned it only means that the *current* task
/// (represented by the argument `cx`) will receive a notification. Tasks
/// from previous calls to `poll` will *not* receive notifications.
///
/// # Runtime characteristics
///
/// Futures alone are *inert*; they must be *actively* `poll`ed to make
/// progress, meaning that each time the current task is woken up, it should
/// actively re-`poll` pending futures that it still has an interest in.
///
/// The `poll` function is not called repeatedly in a tight loop for
/// futures, but only whenever the future itself is ready, as signaled via
/// the `Waker` inside `task::Context`. If you're familiar with the
/// `poll(2)` or `select(2)` syscalls on Unix it's worth noting that futures
/// typically do *not* suffer the same problems of "all wakeups must poll
/// all events"; they are more like `epoll(4)`.
///
/// An implementation of `poll` should strive to return quickly, and must
/// *never* block. Returning quickly prevents unnecessarily clogging up
/// threads or event loops. If it is known ahead of time that a call to
/// `poll` may end up taking awhile, the work should be offloaded to a
/// thread pool (or something similar) to ensure that `poll` can return
/// quickly.
///
/// # Panics
///
/// Once a future has completed (returned `Ready` from `poll`),
/// then any future calls to `poll` may panic, block forever, or otherwise
/// cause bad behavior. The `Future` trait itself provides no guarantees
/// about the behavior of `poll` after a future has completed.
fn poll(self: PinMut<Self>, cx: &mut task::Context) -> Poll<Self::Output>;
}

5
src/libcore/lib.rs
View File

@ -100,6 +100,7 @@
#![feature(optin_builtin_traits)]
#![feature(prelude_import)]
#![feature(repr_simd, platform_intrinsics)]
#![feature(repr_transparent)]
#![feature(rustc_attrs)]
#![feature(rustc_const_unstable)]
#![feature(simd_ffi)]
@ -206,6 +207,10 @@ pub mod time;
pub mod unicode;
/* Async */
pub mod future;
pub mod task;
/* Heap memory allocator trait */
#[allow(missing_docs)]
pub mod alloc;

513
src/libcore/task.rs Normal file
View File

@ -0,0 +1,513 @@
// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
// file at the top-level directory of this distribution and at
// http://rust-lang.org/COPYRIGHT.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.
#![unstable(feature = "futures_api",
reason = "futures in libcore are unstable",
issue = "50547")]
//! Types and Traits for working with asynchronous tasks.
use fmt;
use ptr::NonNull;
/// Indicates whether a value is available or if the current task has been
/// scheduled to receive a wakeup instead.
#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
pub enum Poll<T> {
/// Represents that a value is immediately ready.
Ready(T),
/// Represents that a value is not ready yet.
///
/// When a function returns `Pending`, the function *must* also
/// ensure that the current task is scheduled to be awoken when
/// progress can be made.
Pending,
}
/// A `Waker` is a handle for waking up a task by notifying its executor that it
/// is ready to be run.
///
/// This handle contains a trait object pointing to an instance of the `UnsafeWake`
/// trait, allowing notifications to get routed through it.
#[repr(transparent)]
pub struct Waker {
inner: NonNull<UnsafeWake>,
}
unsafe impl Send for Waker {}
unsafe impl Sync for Waker {}
impl Waker {
/// Constructs a new `Waker` directly.
///
/// Note that most code will not need to call this. Implementers of the
/// `UnsafeWake` trait will typically provide a wrapper that calls this
/// but you otherwise shouldn't call it directly.
///
/// If you're working with the standard library then it's recommended to
/// use the `Waker::from` function instead which works with the safe
/// `Arc` type and the safe `Wake` trait.
#[inline]
pub unsafe fn new(inner: NonNull<UnsafeWake>) -> Self {
Waker { inner: inner }
}
/// Wake up the task associated with this `Waker`.
#[inline]
pub fn wake(&self) {
unsafe { self.inner.as_ref().wake() }
}
/// Returns whether or not this `Waker` and `other` awaken the same task.
///
/// This function works on a best-effort basis, and may return false even
/// when the `Waker`s would awaken the same task. However, if this function
/// returns true, it is guaranteed that the `Waker`s will awaken the same
/// task.
///
/// This function is primarily used for optimization purposes.
#[inline]
pub fn will_wake(&self, other: &Waker) -> bool {
self.inner == other.inner
}
}
impl Clone for Waker {
#[inline]
fn clone(&self) -> Self {
unsafe {
self.inner.as_ref().clone_raw()
}
}
}
impl fmt::Debug for Waker {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
f.debug_struct("Waker")
.finish()
}
}
impl Drop for Waker {
#[inline]
fn drop(&mut self) {
unsafe {
self.inner.as_ref().drop_raw()
}
}
}
/// A `LocalWaker` is a handle for waking up a task by notifying its executor that it
/// is ready to be run.
///
/// This is similar to the `Waker` type, but cannot be sent across threads.
/// Task executors can use this type to implement more optimized singlethreaded wakeup
/// behavior.
#[repr(transparent)]
pub struct LocalWaker {
inner: NonNull<UnsafeWake>,
}
impl !Send for LocalWaker {}
impl !Sync for LocalWaker {}
impl LocalWaker {
/// Constructs a new `LocalWaker` directly.
///
/// Note that most code will not need to call this. Implementers of the
/// `UnsafeWake` trait will typically provide a wrapper that calls this
/// but you otherwise shouldn't call it directly.
///
/// If you're working with the standard library then it's recommended to
/// use the `LocalWaker::from` function instead which works with the safe
/// `Rc` type and the safe `LocalWake` trait.
///
/// For this function to be used safely, it must be sound to call `inner.wake_local()`
/// on the current thread.
#[inline]
pub unsafe fn new(inner: NonNull<UnsafeWake>) -> Self {
LocalWaker { inner: inner }
}
/// Wake up the task associated with this `LocalWaker`.
#[inline]
pub fn wake(&self) {
unsafe { self.inner.as_ref().wake_local() }
}
/// Returns whether or not this `LocalWaker` and `other` `LocalWaker` awaken the same task.
///
/// This function works on a best-effort basis, and may return false even
/// when the `LocalWaker`s would awaken the same task. However, if this function
/// returns true, it is guaranteed that the `LocalWaker`s will awaken the same
/// task.
///
/// This function is primarily used for optimization purposes.
#[inline]
pub fn will_wake(&self, other: &LocalWaker) -> bool {
self.inner == other.inner
}
/// Returns whether or not this `LocalWaker` and `other` `Waker` awaken the same task.
///
/// This function works on a best-effort basis, and may return false even
/// when the `Waker`s would awaken the same task. However, if this function
/// returns true, it is guaranteed that the `LocalWaker`s will awaken the same
/// task.
///
/// This function is primarily used for optimization purposes.
#[inline]
pub fn will_wake_nonlocal(&self, other: &Waker) -> bool {
self.inner == other.inner
}
}
impl From<LocalWaker> for Waker {
#[inline]
fn from(local_waker: LocalWaker) -> Self {
Waker { inner: local_waker.inner }
}
}
impl Clone for LocalWaker {
#[inline]
fn clone(&self) -> Self {
unsafe {
LocalWaker { inner: self.inner.as_ref().clone_raw().inner }
}
}
}
impl fmt::Debug for LocalWaker {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
f.debug_struct("Waker")
.finish()
}
}
impl Drop for LocalWaker {
#[inline]
fn drop(&mut self) {
unsafe {
self.inner.as_ref().drop_raw()
}
}
}
/// An unsafe trait for implementing custom memory management for a `Waker` or `LocalWaker`.
///
/// A `Waker` conceptually is a cloneable trait object for `Wake`, and is
/// most often essentially just `Arc<dyn Wake>`. However, in some contexts
/// (particularly `no_std`), it's desirable to avoid `Arc` in favor of some
/// custom memory management strategy. This trait is designed to allow for such
/// customization.
///
/// When using `std`, a default implementation of the `UnsafeWake` trait is provided for
/// `Arc<T>` where `T: Wake` and `Rc<T>` where `T: LocalWake`.
///
/// Although the methods on `UnsafeWake` take pointers rather than references,
pub unsafe trait UnsafeWake: Send + Sync {
/// Creates a clone of this `UnsafeWake` and stores it behind a `Waker`.
///
/// This function will create a new uniquely owned handle that under the
/// hood references the same notification instance. In other words calls
/// to `wake` on the returned handle should be equivalent to calls to
/// `wake` on this handle.
///
/// # Unsafety
///
/// This function is unsafe to call because it's asserting the `UnsafeWake`
/// value is in a consistent state, i.e. hasn't been dropped.
unsafe fn clone_raw(&self) -> Waker;
/// Drops this instance of `UnsafeWake`, deallocating resources
/// associated with it.
///
/// FIXME(cramertj)
/// This method is intended to have a signature such as:
///
/// ```ignore (not-a-doctest)
/// fn drop_raw(self: *mut Self);
/// ```
///
/// Unfortunately in Rust today that signature is not object safe.
/// Nevertheless it's recommended to implement this function *as if* that
/// were its signature. As such it is not safe to call on an invalid
/// pointer, nor is the validity of the pointer guaranteed after this
/// function returns.
///
/// # Unsafety
///
/// This function is unsafe to call because it's asserting the `UnsafeWake`
/// value is in a consistent state, i.e. hasn't been dropped.
unsafe fn drop_raw(&self);
/// Indicates that the associated task is ready to make progress and should
/// be `poll`ed.
///
/// Executors generally maintain a queue of "ready" tasks; `wake` should place
/// the associated task onto this queue.
///
/// # Panics
///
/// Implementations should avoid panicking, but clients should also be prepared
/// for panics.
///
/// # Unsafety
///
/// This function is unsafe to call because it's asserting the `UnsafeWake`
/// value is in a consistent state, i.e. hasn't been dropped.
unsafe fn wake(&self);
/// Indicates that the associated task is ready to make progress and should
/// be `poll`ed. This function is the same as `wake`, but can only be called
/// from the thread that this `UnsafeWake` is "local" to. This allows for
/// implementors to provide specialized wakeup behavior specific to the current
/// thread. This function is called by `LocalWaker::wake`.
///
/// Executors generally maintain a queue of "ready" tasks; `wake_local` should place
/// the associated task onto this queue.
///
/// # Panics
///
/// Implementations should avoid panicking, but clients should also be prepared
/// for panics.
///
/// # Unsafety
///
/// This function is unsafe to call because it's asserting the `UnsafeWake`
/// value is in a consistent state, i.e. hasn't been dropped, and that the
/// `UnsafeWake` hasn't moved from the thread on which it was created.
unsafe fn wake_local(&self) {
self.wake()
}
}
/// Information about the currently-running task.
///
/// Contexts are always tied to the stack, since they are set up specifically
/// when performing a single `poll` step on a task.
pub struct Context<'a> {
local_waker: &'a LocalWaker,
executor: &'a mut Executor,
}
impl<'a> fmt::Debug for Context<'a> {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
f.debug_struct("Context")
.finish()
}
}
impl<'a> Context<'a> {
/// Create a new task `Context` with the provided `local_waker`, `waker`, and `executor`.
#[inline]
pub fn new(local_waker: &'a LocalWaker, executor: &'a mut Executor) -> Context<'a> {
Context {
local_waker,
executor,
}
}
/// Get the `LocalWaker` associated with the current task.
#[inline]
pub fn local_waker(&self) -> &'a LocalWaker {
self.local_waker
}
/// Get the `Waker` associated with the current task.
#[inline]
pub fn waker(&self) -> &'a Waker {
unsafe { &*(self.local_waker as *const LocalWaker as *const Waker) }
}
/// Get the default executor associated with this task.
///
/// This method is useful primarily if you want to explicitly handle
/// spawn failures.
#[inline]
pub fn executor(&mut self) -> &mut Executor {
self.executor
}
/// Produce a context like the current one, but using the given waker instead.
///
/// This advanced method is primarily used when building "internal
/// schedulers" within a task, where you want to provide some customized
/// wakeup logic.
#[inline]
pub fn with_waker<'b>(&'b mut self, local_waker: &'b LocalWaker) -> Context<'b> {
Context {
local_waker,
executor: self.executor,
}
}
/// Produce a context like the current one, but using the given executor
/// instead.
///
/// This advanced method is primarily used when building "internal
/// schedulers" within a task.
#[inline]
pub fn with_executor<'b, E>(&'b mut self, executor: &'b mut E) -> Context<'b>
where E: Executor
{
Context {
local_waker: self.local_waker,
executor: executor,
}
}
}
/// A task executor.
///
/// A *task* is a `()`-producing async value that runs at the top level, and will
/// be `poll`ed until completion. It's also the unit at which wake-up
/// notifications occur. Executors, such as thread pools, allow tasks to be
/// spawned and are responsible for putting tasks onto ready queues when
/// they are woken up, and polling them when they are ready.
pub trait Executor {
/// Spawn the given task, polling it until completion.
///
/// # Errors
///
/// The executor may be unable to spawn tasks, either because it has
/// been shut down or is resource-constrained.
fn spawn_obj(&mut self, task: TaskObj) -> Result<(), SpawnObjError>;
/// Determine whether the executor is able to spawn new tasks.
///
/// # Returns
///
/// An `Ok` return means the executor is *likely* (but not guaranteed)
/// to accept a subsequent spawn attempt. Likewise, an `Err` return
/// means that `spawn` is likely, but not guaranteed, to yield an error.
#[inline]
fn status(&self) -> Result<(), SpawnErrorKind> {
Ok(())
}
}
/// A custom trait object for polling tasks, roughly akin to
/// `Box<Future<Output = ()> + Send>`.
pub struct TaskObj {
ptr: *mut (),
poll: unsafe fn(*mut (), &mut Context) -> Poll<()>,
drop: unsafe fn(*mut ()),
}
impl fmt::Debug for TaskObj {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
f.debug_struct("TaskObj")
.finish()
}
}
unsafe impl Send for TaskObj {}
unsafe impl Sync for TaskObj {}
/// A custom implementation of a task trait object for `TaskObj`, providing
/// a hand-rolled vtable.
///
/// This custom representation is typically used only in `no_std` contexts,
/// where the default `Box`-based implementation is not available.
///
/// The implementor must guarantee that it is safe to call `poll` repeatedly (in
/// a non-concurrent fashion) with the result of `into_raw` until `drop` is
/// called.
pub unsafe trait UnsafePoll: Send + 'static {
/// Convert a owned instance into a (conceptually owned) void pointer.
fn into_raw(self) -> *mut ();
/// Poll the task represented by the given void pointer.
///
/// # Safety
///
/// The trait implementor must guarantee that it is safe to repeatedly call
/// `poll` with the result of `into_raw` until `drop` is called; such calls
/// are not, however, allowed to race with each other or with calls to `drop`.
unsafe fn poll(task: *mut (), cx: &mut Context) -> Poll<()>;
/// Drops the task represented by the given void pointer.
///
/// # Safety
///
/// The trait implementor must guarantee that it is safe to call this
/// function once per `into_raw` invocation; that call cannot race with
/// other calls to `drop` or `poll`.
unsafe fn drop(task: *mut ());
}
impl TaskObj {
/// Create a `TaskObj` from a custom trait object representation.
#[inline]
pub fn from_poll_task<T: UnsafePoll>(t: T) -> TaskObj {
TaskObj {
ptr: t.into_raw(),
poll: T::poll,
drop: T::drop,
}
}
/// Poll the task.
///
/// The semantics here are identical to that for futures, but unlike
/// futures only an `&mut self` reference is needed here.
#[inline]
pub fn poll_task(&mut self, cx: &mut Context) -> Poll<()> {
unsafe {
(self.poll)(self.ptr, cx)
}
}
}
impl Drop for TaskObj {
fn drop(&mut self) {
unsafe {
(self.drop)(self.ptr)
}
}
}
/// Provides the reason that an executor was unable to spawn.
pub struct SpawnErrorKind {
_hidden: (),
}
impl fmt::Debug for SpawnErrorKind {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
f.debug_tuple("SpawnErrorKind")
.field(&"shutdown")
.finish()
}
}
impl SpawnErrorKind {
/// Spawning is failing because the executor has been shut down.
pub fn shutdown() -> SpawnErrorKind {
SpawnErrorKind { _hidden: () }
}
/// Check whether this error is the `shutdown` error.
pub fn is_shutdown(&self) -> bool {
true
}
}
/// The result of a failed spawn
#[derive(Debug)]
pub struct SpawnObjError {
/// The kind of error
pub kind: SpawnErrorKind,
/// The task for which spawning was attempted
pub task: TaskObj,
}

16
src/libstd/lib.rs
View File

@ -261,6 +261,7 @@
#![feature(float_from_str_radix)]
#![feature(fn_traits)]
#![feature(fnbox)]
#![feature(futures_api)]
#![feature(hashmap_internals)]
#![feature(heap_api)]
#![feature(int_error_internals)]
@ -282,6 +283,7 @@
#![feature(panic_internals)]
#![feature(panic_unwind)]
#![feature(peek)]
#![feature(pin)]
#![feature(placement_new_protocol)]
#![feature(prelude_import)]
#![feature(ptr_internals)]
@ -457,6 +459,20 @@ pub use core::u128;
#[stable(feature = "core_hint", since = "1.27.0")]
pub use core::hint;
#[unstable(feature = "futures_api",
reason = "futures in libcore are unstable",
issue = "50547")]
pub mod task {
//! Types and Traits for working with asynchronous tasks.
pub use core::task::*;
pub use alloc_crate::task::*;
}
#[unstable(feature = "futures_api",
reason = "futures in libcore are unstable",
issue = "50547")]
pub use core::future;
pub mod f32;
pub mod f64;

95
src/test/run-pass/futures-api.rs Normal file
View File

@ -0,0 +1,95 @@
// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
// file at the top-level directory of this distribution and at
// http://rust-lang.org/COPYRIGHT.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.
#![feature(arbitrary_self_types, futures_api, pin)]
#![allow(unused)]
use std::boxed::PinBox;
use std::future::Future;
use std::mem::PinMut;
use std::rc::Rc;
use std::sync::{
Arc,
atomic::{self, AtomicUsize},
};
use std::task::{
Context, Poll,
Wake, Waker, LocalWaker,
Executor, TaskObj, SpawnObjError,
local_waker, local_waker_from_nonlocal,
};
struct Counter {
local_wakes: AtomicUsize,
nonlocal_wakes: AtomicUsize,
}
impl Wake for Counter {
fn wake(this: &Arc<Self>) {
this.nonlocal_wakes.fetch_add(1, atomic::Ordering::SeqCst);
}
unsafe fn wake_local(this: &Arc<Self>) {
this.local_wakes.fetch_add(1, atomic::Ordering::SeqCst);
}
}
struct NoopExecutor;
impl Executor for NoopExecutor {
fn spawn_obj(&mut self, _: TaskObj) -> Result<(), SpawnObjError> {
Ok(())
}
}
struct MyFuture;
impl Future for MyFuture {
type Output = ();
fn poll(self: PinMut<Self>, cx: &mut Context) -> Poll<Self::Output> {
// Ensure all the methods work appropriately
cx.waker().wake();
cx.waker().wake();
cx.local_waker().wake();
cx.executor().spawn_obj(PinBox::new(MyFuture).into()).unwrap();
Poll::Ready(())
}
}
fn test_local_waker() {
let counter = Arc::new(Counter {
local_wakes: AtomicUsize::new(0),
nonlocal_wakes: AtomicUsize::new(0),
});
let waker = unsafe { local_waker(counter.clone()) };
let executor = &mut NoopExecutor;
let cx = &mut Context::new(&waker, executor);
assert_eq!(Poll::Ready(()), PinMut::new(&mut MyFuture).poll(cx));
assert_eq!(1, counter.local_wakes.load(atomic::Ordering::SeqCst));
assert_eq!(2, counter.nonlocal_wakes.load(atomic::Ordering::SeqCst));
}
fn test_local_as_nonlocal_waker() {
let counter = Arc::new(Counter {
local_wakes: AtomicUsize::new(0),
nonlocal_wakes: AtomicUsize::new(0),
});
let waker: LocalWaker = local_waker_from_nonlocal(counter.clone());
let executor = &mut NoopExecutor;
let cx = &mut Context::new(&waker, executor);
assert_eq!(Poll::Ready(()), PinMut::new(&mut MyFuture).poll(cx));
assert_eq!(0, counter.local_wakes.load(atomic::Ordering::SeqCst));
assert_eq!(3, counter.nonlocal_wakes.load(atomic::Ordering::SeqCst));
}
fn main() {
test_local_waker();
test_local_as_nonlocal_waker();
}