Auto merge of #51263 - cramertj:futures-in-core, r=aturon

Add Future and task system to the standard library

This adds preliminary versions of the `std::future` and `std::task` modules in order to unblock development of async/await (#50547). These shouldn't be considered as final forms of these libraries-- design questions about the libraries should be left on rust-lang/rfcs#2418. Once that RFC (or a successor) is merged, these APIs will be adjusted as necessary.

r? @aturon

Author: bors

src/liballoc/boxed.rs

@@ -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))
+    }
+}

src/liballoc/lib.rs

@@ -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(specialization)]
 #![feature(staged_api)]
@@ -155,6 +157,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
 

src/liballoc/task.rs

@@ -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)
+        }
+    }
+}