No Pin/PinMut distinction.

Author: boats

text/0000-pin.md

@@ -36,12 +36,12 @@ Let's take that goal apart, piece by piece, from the perspective of the futures
 
 At the same time, we want to support futures (and iterators, etc.) that *can* move. While it's possible to do so by providing two distinct `Future` (or `Iterator`, etc) traits, such designs incur unacceptable ergonomic costs.
 
-The key insight of this RFC is that we can create a new library type, `PinMut<'a, T>`, which encompasses *both* moveable and immobile referents. The type is paired with a new auto trait, `Unpin`, which determines the meaning of `PinMut<'a, T>`:
+The key insight of this RFC is that we can create a new library type, `Pin<'a, T>`, which encompasses *both* moveable and immobile referents. The type is paired with a new auto trait, `Unpin`, which determines the meaning of `Pin<'a, T>`:
 
-- If `T: Unpin` (which is the default), then `PinMut<'a, T>` is entirely equivalent to `&'a mut T`.
-- If `T: !Unpin`, then `PinMut<'a, T>` provides a unique reference to a `T` with lifetime `'a`, but only provides `&'a T` access safely. It also guarantees that the referent will *never* be moved. However, getting `&'a mut T` access is unsafe, because operations like `mem::replace` mean that `&mut` access is enough to move data out of the referent; you must promise not to do so.
+- If `T: Unpin` (which is the default), then `Pin<'a, T>` is entirely equivalent to `&'a mut T`.
+- If `T: !Unpin`, then `Pin<'a, T>` provides a unique reference to a `T` with lifetime `'a`, but only provides `&'a T` access safely. It also guarantees that the referent will *never* be moved. However, getting `&'a mut T` access is unsafe, because operations like `mem::replace` mean that `&mut` access is enough to move data out of the referent; you must promise not to do so.
 
-To be clear: the *sole* function of `Unpin` is to control the meaning of `PinMut`. Making `Unpin` an auto trait means that the vast majority of types are automatically "movable", so `PinMut` degenerates to `&mut`. In the case that you need immobility, you *opt out* of `Unpin`, and then `PinMut` becomes meaningful for your type.
+To be clear: the *sole* function of `Unpin` is to control the meaning of `Pin`. Making `Unpin` an auto trait means that the vast majority of types are automatically "movable", so `Pin` degenerates to `&mut`. In the case that you need immobility, you *opt out* of `Unpin`, and then `Pin` becomes meaningful for your type.
 
 Putting this all together, we arrive at the following definition of `Future`:
 
@@ -50,13 +50,13 @@ trait Future {
     type Item;
     type Error;
 
-    fn poll(self: PinMut<Self>, cx: task::Context) -> Poll<Self::Item, Self::Error>;
+    fn poll(self: Pin<Self>, cx: &mut task::Context) -> Poll<Self::Item, Self::Error>;
 }
 ```
 
-By default when implementing `Future` for a struct, this definition is equivalent to today's, which takes `&mut self`. But if you want to allow self-referencing in your future, you just opt out of `Unpin`, and `PinMut` takes care of the rest.
+By default when implementing `Future` for a struct, this definition is equivalent to today's, which takes `&mut self`. But if you want to allow self-referencing in your future, you just opt out of `Unpin`, and `Pin` takes care of the rest.
 
-This RFC also provides pinned analogies to `Box` and `&T` - `PinBox<T>` and `Pin<T>`. They work along the same lines as the `PinMut` type discussed here - if the type implements `Unpin`, they function the same as their unpinned varieties; if the type has opted out of `Unpin`, they guarantee that they type behind the reference will not be moved again.
+This RFC also provides a pinned analogiy to `Box` called `PinBox<T>`. It work alongs the same lines as the `Pin` type discussed here - if the type implements `Unpin`, it functions the same as the unpinned `Box`; if the type has opted out of `Unpin`, it guarantees that they type behind the reference will not be moved again.
 
 # Reference-level explanation
 
@@ -80,109 +80,87 @@ generators. Unlike previous `?Move` proposals, and unlike some traits like
 types that do or don't implement it. Instead, the semantics are entirely
 enforced through library APIs which use `Unpin` as a marker.
 
-## `Pin` and `PinMut`
+## `Pin`
 
-`Pin` and `PinMut` are two types added to `core::mem` and `std::mem`. They are
-analogous to `&T` and `&mut T` respectively.
+The `Pin` struct is added to both `core::mem` and `std::mem`. It is a new kind
+of reference, with stronger requirements than `&mut T`
 
 ```rust
 #[fundamental]
 pub struct Pin<'a, T: ?Sized + 'a> {
-    data: &'a T,
-}
-
-#[fundamental]
-pub struct PinMut<'a, T: ?Sized + 'a> {
     data: &'a mut T,
 }
 ```
 
 ### Safe APIs
 
-They both implement `Deref`, but `PinMut` only implements `DerefMut` if the
-type it references implements `Unpin`:
+`Pin` implements `Deref`, but only implements `DerefMut` if the type it
+references implements `Unpin`. This way, it is not safe to call `mem::swap` or
+`mem::replace` when the type referenced does not implement `Unpin`.
 
 ```rust
 impl<'a, T: ?Sized> Deref for Pin<'a, T> { ... }
 
-impl<'a, T: ?Sized> Deref for PinMut<'a, T> { ... }
-
-impl<'a, T: Unpin + ?Sized> DerefMut for PinMut<'a, T> { ... }
+impl<'a, T: Unpin + ?Sized> DerefMut for Pin<'a, T> { ... }
 ```
 
-They can only be safely constructed from references to types that implement
+It can only be safely constructed from references to types that implement
 `Unpin`:
 
 ```rust
 impl<'a, T: Unpin + ?Sized> Pin<'a, T> {
-    pub fn new(reference: &'a T) -> Pin<'a, T> { ... }
-}
-
-impl<'a, T: Unpin + ?Sized> PinMut<'a, T> {
-    pub fn new(reference: &'a mut T) -> PinMut<'a, T> { ... }
+    pub fn new(reference: &'a mut T) -> Pin<'a, T> { ... }
 }
 ```
 
-They also have a `borrow` function, which allows them to be transformed to pins
-with shorter lifetimes as may be necessary:
+It also has a function called `borrow`, which allows it to be transformed to a
+pin of a shorter lifetime:
 
 ```rust
 impl<'a, T: ?Sized> Pin<'a, T> {
-    pub fn borrow<'b>(this: &'b Pin<'a, T>) -> Pin<'b, T> { ... }
-}
-
-impl<'a, T: ?Sized> PinMut<'a, T> {
-    pub fn borrow<'b>(this: &'b PinMut<'a, T>) -> PinMut<'b, T> { ... }
+    pub fn borrow<'b>(this: &'b mut Pin<'a, T>) -> Pin<'b, T> { ... }
 }
 ```
 
-They may also implement additional APIs as is useful for type conversions, such
-as `AsRef`, `From`, and so on. They implement `CoerceUnsized` as necessary to
+It may also implement additional APIs as is useful for type conversions, such
+as `AsRef`, `From`, and so on. `Pin` implements `CoerceUnsized` as necessary to
 make coercing them into trait objects possible.
 
 ### Unsafe APIs
 
-Both types can be unsafely constructed from references to types which may not
-implement `Unpin`. Users who use these constructors must know that the type
-they are passing a reference to will never be moved again after the Pin is
-constructed.
+`Pin` can be unsafely constructed from mutable references to types that may not
+implement `Unpin`. Users who use this constructor must know that the type
+they are passing a reference to will never be moved again after the `Pin` is
+constructed, even after the lifetime of the reference has ended. (For example,
+it is always unsafe to construct a `Pin` from a reference you did not create,
+because you don't know what will happen once the lifetime of that reference
+ends.)
 
 ```rust
 impl<'a, T: ?Sized> Pin<'a, T> {
-    pub unsafe fn new_unchecked(reference: &'a T) -> Pin<'a, T> { ... }
-}
-
-impl<'a, T: ?Sized> PinMut<'a, T> {
-    pub unsafe fn new_unchecked(reference: &'a mut T) -> PinMut<'a, T> { ... }
+    pub unsafe fn new_unchecked(reference: &'a mut T) -> Pin<'a, T> { ... }
 }
 ```
 
-`PinMut` also has an API which allows it to be converted into a mutable
-reference for a type that doesn't implement `Unpin`. Users who use this API
-must guarantee that they never move out of the mutable reference they receive.
+`Pin` also has an API which allows it to be converted into a mutable reference
+for a type that doesn't implement `Unpin`. Users who use this API must
+guarantee that they never move out of the mutable reference they receive.
 
 ```rust
-impl<'a, T: ?Sized> PinMut<'a, T> {
-    pub unsafe fn get_mut<'b>(this: &'b mut PinMut<'a, T>) -> &'b mut T { ... }
+impl<'a, T: ?Sized> Pin<'a, T> {
+    pub unsafe fn get_mut<'b>(this: &'b mut Pin<'a, T>) -> &'b mut T { ... }
 }
 ```
 
-Finally, as a convenience, they both implement an unsafe `map` function, which
+Finally, as a convenience, `Pin` implements an unsafe `map` function, which
 makes it easier to project through a field. Users calling this function must
 guarantee that the value returned will not move as long as the referent of this
 pin doesn't move (e.g. it is a private field of the value). They also must not
-move out of the mutable reference they receive as the closure argument, in the
-case of `PinMut`:
+move out of the mutable reference they receive as the closure argument:
 
 ```rust
 impl<'a, T: ?Sized> Pin<'a, T> {
-    pub unsafe fn map<'b, U, F>(this: &'b Pin<'a, T>, f: F) -> Pin<'b, U>
-	where F: FnOnce(&T) -> &U
-    { ... }
-}
-
-impl<'a, T: ?Sized> PinMut<'a, T> {
-    pub unsafe fn map<'b, U, F>(this: &'b mut PinMut<'a, T>, f: F) -> PinMut<'b, U>
+    pub unsafe fn map<'b, U, F>(this: &'b mut Pin<'a, T>, f: F) -> Pin<'b, U>
 	where F: FnOnce(&mut T) -> &mut U
     { ... }
 }
@@ -193,15 +171,20 @@ struct Foo {
 }
 
 let foo_pin: Pin<Foo>;
-// ...
-let bar_pin: Pin<Bar> = unsafe { Pin::map(&foo_pin, |foo| &foo.bar) };
+
+let bar_pin: Pin<Bar> = unsafe { Pin::map(&mut foo_pin, |foo| &mut foo.bar) };
+// Equivalent to:
+let bar_pin: Pin<Bar> = unsafe {
+    let foo: &mut Foo = Pin::get_mut(&mut foo_pin);
+    Pin::new_unchecked(&mut foo.bar)
+};
 ```
 
 ## `PinBox`
 
 The `PinBox` type is added to alloc::boxed and std::boxed. It is analogous to
-the `Box` type in the same way that `Pin` and `PinMut` are analogous to the
-reference types, and it has a similar API.
+the `Box` type in the same way that `Pin` is analogous to the reference types,
+and it has a similar API.
 
 ```rust
 #[fundamental]
@@ -212,8 +195,8 @@ pub struct PinBox<T: ?Sized> {
 
 ### Safe API
 
-Unlike the other pin types, it is safe to construct a `PinBox` from a `T` and
-from a `Box<T>`:
+Unlike `Pin`, it is safe to construct a `PinBox` from a `T` and from a
+`Box<T>`, even if the type does not implement `Unpin`:
 
 ```rust
 impl<T> PinBox<T> {
@@ -225,7 +208,7 @@ impl<T: ?Sized> From<Box<T>> for PinBox<T> {
 }
 ```
 
-It also provides the same Deref impls as `PinMut` does:
+It also provides the same Deref impls as `Pin` does:
 
 ```rust
 impl<T: ?Sized> Deref for PinBox<T> { ... }
@@ -239,24 +222,23 @@ If the data implements `Unpin`, its also safe to convert a `PinBox` into a
 impl<T: Unpin + ?Sized> From<PinBox<T>> for Box<T> { ... }
 ```
 
-Finally, it is safe to get a `Pin` and a `PinMut` from borrows of `PinBox`:
+Finally, it is safe to get a `Pin` from borrows of `PinBox`:
 
 ```rust
 impl<T: ?Sized> PinBox<T> {
-    fn as_pin<'a>(&'a self) -> Pin<'a, T> { ... }
-    fn as_pin_mut<'a>(&'a mut self) -> PinMut<'a, T> { ... }
+    fn as_pin<'a>(&'a mut self) -> Pin<'a, T> { ... }
 }
 ```
 
 These APIs make `PinBox` a reasonable way of handling data which does not
 implement `!Unpin`. Once you heap allocate that data inside of a `PinBox`, you
-know that it will never change address again, and you can hand out `Pin` and
-`PinMut` references to that data.
+know that it will never change address again, and you can hand out `Pin`
+references to that data.
 
 ### Unsafe API
 
 `PinBox` can be unsafely converted into `&mut T` and `Box<T>` even if the type
-it references does not implement `Unpin`, similar to `PinMut`:
+it references does not implement `Unpin`, similar to `Pin`:
 
 ```rust
 impl<T: ?Sized> PinBox<T> {
@@ -276,7 +258,7 @@ references are invalidated if the type is moved, these kinds of generators
 Once the arbitrary_self_types feature becomes object safe, we will make three
 changes to the generator API:
 
-1. We will change the `resume` method to take self by `self: PinMut<Self>`
+1. We will change the `resume` method to take self by `self: Pin<Self>`
    instead of `&mut self`.
 2. We will implement `!Unpin` for the anonymous type of an immovable generator.
 3. We will make it safe to define an immovable generator.
@@ -377,12 +359,8 @@ struct PinTemporary<'a, T: 'a> {
 }
 
 impl<'a, T> PinTemporary<'a, T> {
-    pub fn into_pin(&'a self) -> Pin<'a, T> {
-        unsafe { Pin::new_unchecked(&self.data) }
-    }
-    
-    pub fn into_pin_mut(&'a mut self) -> PinMut<'a, T> {
-        unsafe { PinMut::new_unchecked(&mut self.data) }
+    pub fn into_pin(&'a mut self) -> Pin<'a, T> {
+        unsafe { Pin::new_unchecked(&mut self.data) }
     }
 }
 ```
@@ -398,6 +376,19 @@ big language change.
 For now, we're happy to stick with the `Pin` struct in std, and if this type is
 ever added, turn the `Pin` type into an alias for the reference type.
 
+## Having both `Pin` and `PinMut`
+
+Instead of just having `Pin`, the type called `Pin` could instead be `PinMut`,
+and we could have a type called `Pin`, which is like `PinMut`, but only
+contains a shared, immutable reference.
+
+Because we've determined that it should be safe to immutably dereference
+`Pin`/`PinMut`, this `Pin` type would not provide significant guarantees that a
+normal immutable reference does not. If a user needs to pass around references
+to data stored pinned, an `&Pin` (under the definition of `Pin` provided in
+this RFC) would suffice. For this reason, the `Pin`/`PinMut` distinction
+introduced extra types and complexity without any impactful benefit.
+
 # Unresolved questions
 [unresolved]: #unresolved-questions