Rollup merge of #56939 - cramertj:pin-stabilization, r=alexcrichton

Pin stabilization

This implements the changes suggested in https://github.com/rust-lang/rust/issues/55766#issue-378417538 and stabilizes the `pin` feature. @alexcrichton also listed several "blockers" in that issue, but then in [this comment](https://github.com/rust-lang/rust/issues/55766#issuecomment-445074980) mentioned that they're more "TODO items":
>  In that vein I think it's fine for a stabilization PR to be posted at any time now with FCP lapsed for a week or so now. The final points about self/pin/pinned can be briefly discussed there (if even necessary, they could be left as the proposal above).

Let's settle these last bits here and get this thing stabilized! :)

r? @alexcrichton
cc @withoutboats

src/liballoc/boxed.rs

@@ -111,9 +111,11 @@ impl<T> Box<T> {
         box x
     }
 
-    #[unstable(feature = "pin", issue = "49150")]
+    /// Constructs a new `Pin<Box<T>>`. If `T` does not implement `Unpin`, then
+    /// `x` will be pinned in memory and unable to be moved.
+    #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
-    pub fn pinned(x: T) -> Pin<Box<T>> {
+    pub fn pin(x: T) -> Pin<Box<T>> {
         (box x).into()
     }
 }
@@ -446,7 +448,7 @@ impl<T> From<T> for Box<T> {
     }
 }
 
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl<T> From<Box<T>> for Pin<Box<T>> {
     fn from(boxed: Box<T>) -> Self {
         // It's not possible to move or replace the insides of a `Pin<Box<T>>`
@@ -813,7 +815,7 @@ impl<T: ?Sized> AsMut<T> for Box<T> {
  *  implementation of `Unpin` (where `T: Unpin`) would be valid/safe, and
  *  could have a method to project a Pin<T> from it.
  */
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl<T: ?Sized> Unpin for Box<T> { }
 
 #[unstable(feature = "generator_trait", issue = "43122")]

src/liballoc/lib.rs

@@ -102,7 +102,6 @@
 #![feature(nll)]
 #![feature(optin_builtin_traits)]
 #![feature(pattern)]
-#![feature(pin)]
 #![feature(ptr_internals)]
 #![feature(ptr_offset_from)]
 #![feature(rustc_attrs)]

src/liballoc/rc.rs

@@ -325,8 +325,10 @@ impl<T> Rc<T> {
         }
     }
 
-    #[unstable(feature = "pin", issue = "49150")]
+    /// Constructs a new `Pin<Rc<T>>`. If `T` does not implement `Unpin`, then
-    pub fn pinned(value: T) -> Pin<Rc<T>> {
+    /// `value` will be pinned in memory and unable to be moved.
+    #[stable(feature = "pin", since = "1.33.0")]
+    pub fn pin(value: T) -> Pin<Rc<T>> {
         unsafe { Pin::new_unchecked(Rc::new(value)) }
     }
 
@@ -1934,5 +1936,5 @@ impl<T: ?Sized> AsRef<T> for Rc<T> {
     }
 }
 
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl<T: ?Sized> Unpin for Rc<T> { }

src/liballoc/sync.rs

@@ -303,8 +303,10 @@ impl<T> Arc<T> {
         Arc { ptr: Box::into_raw_non_null(x), phantom: PhantomData }
     }
 
-    #[unstable(feature = "pin", issue = "49150")]
+    /// Constructs a new `Pin<Arc<T>>`. If `T` does not implement `Unpin`, then
-    pub fn pinned(data: T) -> Pin<Arc<T>> {
+    /// `data` will be pinned in memory and unable to be moved.
+    #[stable(feature = "pin", since = "1.33.0")]
+    pub fn pin(data: T) -> Pin<Arc<T>> {
         unsafe { Pin::new_unchecked(Arc::new(data)) }
     }
 
@@ -2050,5 +2052,5 @@ impl<T: ?Sized> AsRef<T> for Arc<T> {
     }
 }
 
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl<T: ?Sized> Unpin for Arc<T> { }

src/libcore/future/future.rs

@@ -120,7 +120,7 @@ impl<'a, F: ?Sized + Future + Unpin> Future for &'a mut F {
 
 impl<P> Future for Pin<P>
 where
-    P: ops::DerefMut,
+    P: Unpin + ops::DerefMut,
     P::Target: Future,
 {
     type Output = <<P as ops::Deref>::Target as Future>::Output;

src/libcore/marker.rs

@@ -621,7 +621,6 @@ unsafe impl<T: ?Sized> Freeze for &mut T {}
 /// So this, for example, can only be done on types implementing `Unpin`:
 ///
 /// ```rust
-/// #![feature(pin)]
 /// use std::mem::replace;
 /// use std::pin::Pin;
 ///
@@ -637,23 +636,23 @@ unsafe impl<T: ?Sized> Freeze for &mut T {}
 /// [`replace`]: ../../std/mem/fn.replace.html
 /// [`Pin`]: ../pin/struct.Pin.html
 /// [`pin module`]: ../../std/pin/index.html
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 pub auto trait Unpin {}
 
 /// A marker type which does not implement `Unpin`.
 ///
 /// If a type contains a `PhantomPinned`, it will not implement `Unpin` by default.
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
 pub struct PhantomPinned;
 
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl !Unpin for PhantomPinned {}
 
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl<'a, T: ?Sized + 'a> Unpin for &'a T {}
 
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl<'a, T: ?Sized + 'a> Unpin for &'a mut T {}
 
 /// Implementations of `Copy` for primitive types.

src/libcore/option.rs

@@ -273,7 +273,7 @@ impl<T> Option<T> {
 
     /// Converts from `Pin<&Option<T>>` to `Option<Pin<&T>>`
     #[inline]
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
     pub fn as_pin_ref<'a>(self: Pin<&'a Option<T>>) -> Option<Pin<&'a T>> {
         unsafe {
             Pin::get_ref(self).as_ref().map(|x| Pin::new_unchecked(x))
@@ -282,10 +282,10 @@ impl<T> Option<T> {
 
     /// Converts from `Pin<&mut Option<T>>` to `Option<Pin<&mut T>>`
     #[inline]
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
     pub fn as_pin_mut<'a>(self: Pin<&'a mut Option<T>>) -> Option<Pin<&'a mut T>> {
         unsafe {
-            Pin::get_mut_unchecked(self).as_mut().map(|x| Pin::new_unchecked(x))
+            Pin::get_unchecked_mut(self).as_mut().map(|x| Pin::new_unchecked(x))
         }
     }
 

src/libcore/pin.rs

@@ -36,15 +36,13 @@
 //! are always freely movable, even if the data they point to isn't.
 //!
 //! [`Pin`]: struct.Pin.html
-//! [`Unpin`]: trait.Unpin.html
+//! [`Unpin`]: ../../std/marker/trait.Unpin.html
 //! [`swap`]: ../../std/mem/fn.swap.html
 //! [`Box`]: ../../std/boxed/struct.Box.html
 //!
 //! # Examples
 //!
 //! ```rust
-//! #![feature(pin)]
-//!
 //! use std::pin::Pin;
 //! use std::marker::PhantomPinned;
 //! use std::ptr::NonNull;
@@ -72,13 +70,13 @@
 //!             slice: NonNull::dangling(),
 //!             _pin: PhantomPinned,
 //!         };
-//!         let mut boxed = Box::pinned(res);
+//!         let mut boxed = Box::pin(res);
 //!
 //!         let slice = NonNull::from(&boxed.data);
 //!         // we know this is safe because modifying a field doesn't move the whole struct
 //!         unsafe {
 //!             let mut_ref: Pin<&mut Self> = Pin::as_mut(&mut boxed);
-//!             Pin::get_mut_unchecked(mut_ref).slice = slice;
+//!             Pin::get_unchecked_mut(mut_ref).slice = slice;
 //!         }
 //!         boxed
 //!     }
@@ -97,15 +95,12 @@
 //! // std::mem::swap(&mut *still_unmoved, &mut *new_unmoved);
 //! ```
 
-#![unstable(feature = "pin", issue = "49150")]
+#![stable(feature = "pin", since = "1.33.0")]
 
 use fmt;
-use marker::Sized;
+use marker::{Sized, Unpin};
 use ops::{Deref, DerefMut, Receiver, CoerceUnsized, DispatchFromDyn};
 
-#[doc(inline)]
-pub use marker::Unpin;
-
 /// A pinned pointer.
 ///
 /// This is a wrapper around a kind of pointer which makes that pointer "pin" its
@@ -119,8 +114,9 @@ pub use marker::Unpin;
 //
 // Note: the derives below are allowed because they all only use `&P`, so they
 // cannot move the value behind `pointer`.
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 #[fundamental]
+#[repr(transparent)]
 #[derive(Copy, Clone, Hash, Eq, PartialEq, Ord, PartialOrd)]
 pub struct Pin<P> {
     pointer: P,
@@ -132,7 +128,7 @@ where
 {
     /// Construct a new `Pin` around a pointer to some data of a type that
     /// implements `Unpin`.
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
     pub fn new(pointer: P) -> Pin<P> {
         // Safety: the value pointed to is `Unpin`, and so has no requirements
@@ -154,14 +150,14 @@ impl<P: Deref> Pin<P> {
     ///
     /// If `pointer` dereferences to an `Unpin` type, `Pin::new` should be used
     /// instead.
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
     pub unsafe fn new_unchecked(pointer: P) -> Pin<P> {
         Pin { pointer }
     }
 
     /// Get a pinned shared reference from this pinned pointer.
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
     pub fn as_ref(self: &Pin<P>) -> Pin<&P::Target> {
         unsafe { Pin::new_unchecked(&*self.pointer) }
@@ -170,14 +166,14 @@ impl<P: Deref> Pin<P> {
 
 impl<P: DerefMut> Pin<P> {
     /// Get a pinned mutable reference from this pinned pointer.
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
     pub fn as_mut(self: &mut Pin<P>) -> Pin<&mut P::Target> {
         unsafe { Pin::new_unchecked(&mut *self.pointer) }
     }
 
     /// Assign a new value to the memory behind the pinned reference.
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
     pub fn set(mut self: Pin<P>, value: P::Target)
     where
@@ -199,11 +195,11 @@ impl<'a, T: ?Sized> Pin<&'a T> {
     /// will not move so long as the argument value does not move (for example,
     /// because it is one of the fields of that value), and also that you do
     /// not move out of the argument you receive to the interior function.
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
-    pub unsafe fn map_unchecked<U, F>(this: Pin<&'a T>, func: F) -> Pin<&'a U> where
+    pub unsafe fn map_unchecked<U, F>(self: Pin<&'a T>, func: F) -> Pin<&'a U> where
         F: FnOnce(&T) -> &U,
     {
-        let pointer = &*this.pointer;
+        let pointer = &*self.pointer;
         let new_pointer = func(pointer);
         Pin::new_unchecked(new_pointer)
     }
@@ -215,19 +211,19 @@ impl<'a, T: ?Sized> Pin<&'a T> {
     /// that lives for as long as the borrow of the `Pin`, not the lifetime of
     /// the `Pin` itself. This method allows turning the `Pin` into a reference
     /// with the same lifetime as the original `Pin`.
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
-    pub fn get_ref(this: Pin<&'a T>) -> &'a T {
+    pub fn get_ref(self: Pin<&'a T>) -> &'a T {
-        this.pointer
+        self.pointer
     }
 }
 
 impl<'a, T: ?Sized> Pin<&'a mut T> {
     /// Convert this `Pin<&mut T>` into a `Pin<&T>` with the same lifetime.
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
-    pub fn into_ref(this: Pin<&'a mut T>) -> Pin<&'a T> {
+    pub fn into_ref(self: Pin<&'a mut T>) -> Pin<&'a T> {
-        Pin { pointer: this.pointer }
+        Pin { pointer: self.pointer }
     }
 
     /// Get a mutable reference to the data inside of this `Pin`.
@@ -239,12 +235,12 @@ impl<'a, T: ?Sized> Pin<&'a mut T> {
     /// that lives for as long as the borrow of the `Pin`, not the lifetime of
     /// the `Pin` itself. This method allows turning the `Pin` into a reference
     /// with the same lifetime as the original `Pin`.
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
-    pub fn get_mut(this: Pin<&'a mut T>) -> &'a mut T
+    pub fn get_mut(self: Pin<&'a mut T>) -> &'a mut T
         where T: Unpin,
     {
-        this.pointer
+        self.pointer
     }
 
     /// Get a mutable reference to the data inside of this `Pin`.
@@ -257,10 +253,10 @@ impl<'a, T: ?Sized> Pin<&'a mut T> {
     ///
     /// If the underlying data is `Unpin`, `Pin::get_mut` should be used
     /// instead.
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
-    pub unsafe fn get_mut_unchecked(this: Pin<&'a mut T>) -> &'a mut T {
+    pub unsafe fn get_unchecked_mut(self: Pin<&'a mut T>) -> &'a mut T {
-        this.pointer
+        self.pointer
     }
 
     /// Construct a new pin by mapping the interior value.
@@ -274,17 +270,17 @@ impl<'a, T: ?Sized> Pin<&'a mut T> {
     /// will not move so long as the argument value does not move (for example,
     /// because it is one of the fields of that value), and also that you do
     /// not move out of the argument you receive to the interior function.
-    #[unstable(feature = "pin", issue = "49150")]
+    #[stable(feature = "pin", since = "1.33.0")]
-    pub unsafe fn map_unchecked_mut<U, F>(this: Pin<&'a mut T>, func: F) -> Pin<&'a mut U> where
+    pub unsafe fn map_unchecked_mut<U, F>(self: Pin<&'a mut T>, func: F) -> Pin<&'a mut U> where
         F: FnOnce(&mut T) -> &mut U,
     {
-        let pointer = Pin::get_mut_unchecked(this);
+        let pointer = Pin::get_unchecked_mut(self);
         let new_pointer = func(pointer);
         Pin::new_unchecked(new_pointer)
     }
 }
 
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl<P: Deref> Deref for Pin<P> {
     type Target = P::Target;
     fn deref(&self) -> &P::Target {
@@ -292,7 +288,7 @@ impl<P: Deref> Deref for Pin<P> {
     }
 }
 
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl<P: DerefMut> DerefMut for Pin<P>
 where
     P::Target: Unpin
@@ -305,21 +301,21 @@ where
 #[unstable(feature = "receiver_trait", issue = "0")]
 impl<P: Receiver> Receiver for Pin<P> {}
 
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl<P: fmt::Debug> fmt::Debug for Pin<P> {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         fmt::Debug::fmt(&self.pointer, f)
     }
 }
 
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl<P: fmt::Display> fmt::Display for Pin<P> {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         fmt::Display::fmt(&self.pointer, f)
     }
 }
 
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl<P: fmt::Pointer> fmt::Pointer for Pin<P> {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         fmt::Pointer::fmt(&self.pointer, f)
@@ -331,17 +327,14 @@ impl<P: fmt::Pointer> fmt::Pointer for Pin<P> {
 // `Deref<Target=Unpin>` is unsound. Any such impl would probably be unsound
 // for other reasons, though, so we just need to take care not to allow such
 // impls to land in std.
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl<P, U> CoerceUnsized<Pin<U>> for Pin<P>
 where
     P: CoerceUnsized<U>,
 {}
 
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 impl<'a, P, U> DispatchFromDyn<Pin<U>> for Pin<P>
 where
     P: DispatchFromDyn<U>,
 {}
-
-#[unstable(feature = "pin", issue = "49150")]
-impl<P> Unpin for Pin<P> {}

src/libcore/prelude/v1.rs

@@ -19,7 +19,7 @@
 // Re-exported core operators
 #[stable(feature = "core_prelude", since = "1.4.0")]
 #[doc(no_inline)]
-pub use marker::{Copy, Send, Sized, Sync};
+pub use marker::{Copy, Send, Sized, Sync, Unpin};
 #[stable(feature = "core_prelude", since = "1.4.0")]
 #[doc(no_inline)]
 pub use ops::{Drop, Fn, FnMut, FnOnce};

src/libstd/future.rs

@@ -43,7 +43,7 @@ impl<T: Generator<Yield = ()>> !Unpin for GenFuture<T> {}
 impl<T: Generator<Yield = ()>> Future for GenFuture<T> {
     type Output = T::Return;
     fn poll(self: Pin<&mut Self>, lw: &LocalWaker) -> Poll<Self::Output> {
-        set_task_waker(lw, || match unsafe { Pin::get_mut_unchecked(self).0.resume() } {
+        set_task_waker(lw, || match unsafe { Pin::get_unchecked_mut(self).0.resume() } {
             GeneratorState::Yielded(()) => Poll::Pending,
             GeneratorState::Complete(x) => Poll::Ready(x),
         })

src/libstd/lib.rs

@@ -282,7 +282,6 @@
 #![feature(optin_builtin_traits)]
 #![feature(panic_internals)]
 #![feature(panic_unwind)]
-#![feature(pin)]
 #![feature(prelude_import)]
 #![feature(ptr_internals)]
 #![feature(raw)]
@@ -434,7 +433,7 @@ pub use alloc_crate::borrow;
 pub use alloc_crate::fmt;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use alloc_crate::format;
-#[unstable(feature = "pin", issue = "49150")]
+#[stable(feature = "pin", since = "1.33.0")]
 pub use core::pin;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use alloc_crate::slice;

src/test/compile-fail/must_use-in-stdlib-traits.rs

@@ -1,5 +1,5 @@
 #![deny(unused_must_use)]
-#![feature(futures_api, pin, arbitrary_self_types)]
+#![feature(arbitrary_self_types, futures_api)]
 
 use std::iter::Iterator;
 use std::future::Future;

src/test/run-pass/arbitrary_self_types_stdlib_pointers.rs

@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-#![feature(pin)]
+#![feature(arbitrary_self_types)]
 #![feature(rustc_attrs)]
 
 use std::{

src/test/run-pass/async-await.rs

@@ -10,7 +10,7 @@
 
 // edition:2018
 
-#![feature(arbitrary_self_types, async_await, await_macro, futures_api, pin)]
+#![feature(arbitrary_self_types, async_await, await_macro, futures_api)]
 
 use std::pin::Pin;
 use std::future::Future;
@@ -138,7 +138,7 @@ where
     F: FnOnce(u8) -> Fut,
     Fut: Future<Output = u8>,
 {
-    let mut fut = Box::pinned(f(9));
+    let mut fut = Box::pin(f(9));
     let counter = Arc::new(Counter { wakes: AtomicUsize::new(0) });
     let waker = local_waker_from_nonlocal(counter.clone());
     assert_eq!(0, counter.wakes.load(atomic::Ordering::SeqCst));

src/test/run-pass/futures-api.rs

@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-#![feature(arbitrary_self_types, futures_api, pin)]
+#![feature(arbitrary_self_types, futures_api)]
 #![allow(unused)]
 
 use std::future::Future;