Merge #47

47: Make generated 'project' reference take an '&mut Pin<&mut Self>' r=taiki-e a=Aaron1011

Based on rust-lang/unsafe-code-guidelines#148 (comment)
by @CAD97

Currently, the generated 'project' method takes a 'Pin<&mut Self>',
consuming it. This makes it impossible to use the original Pin<&mut Self>
after calling project(), since the 'Pin<&mut Self>' has been moved into
the the 'Project' method.

This makes it impossible to implement useful pattern when working with
enums:

```rust

enum Foo {
    Variant1(#[pin] SomeFuture),
    Variant2(OtherType)
}

fn process(foo: Pin<&mut Foo>) {
    match foo.project() {
        __FooProjection(fut) => {
            fut.poll();
            let new_foo: Foo = ...;
            foo.set(new_foo);
        },
        _ => {}
    }
}
```

This pattern is common when implementing a Future combinator - an inner
future is polled, and then the containing enum is changed to a new
variant. However, as soon as 'project()' is called, it becoms imposible
to call 'set' on the original 'Pin<&mut Self>'.

To support this pattern, this commit changes the 'project' method to
take a '&mut Pin<&mut Self>'. The projection types work exactly as
before - however, creating it no longer requires consuming the original
'Pin<&mut Self>'

Unfortunately, current limitations of Rust prevent us from simply
modifying the signature of the 'project' method in the inherent impl
of the projection type. While using 'Pin<&mut Self>' as a receiver is
supported on stable rust, using '&mut Pin<&mut Self>' as a receiver
requires the unstable `#![feature(arbitrary_self_types)]`

For compatibility with stable Rust, we instead dynamically define a new
trait, '__{Type}ProjectionTrait', where {Type} is the name of the type
with the `#[pin_project]` attribute.

This trait looks like this:

```rust
trait __FooProjectionTrait {
    fn project(&'a mut self) -> __FooProjection<'a>;
}
```

It is then implemented for `Pin<&mut {Type}>`. This allows the `project`
method to be invoked on `&mut Pin<&mut {Type}>`, which is what we want.

If Generic Associated Types (rust-lang/rust#44265)
were implemented and stabilized, we could use a single trait for all pin
projections:

```rust
trait Projectable {
    type Projection<'a>;
    fn project(&'a mut self) -> Self::Projection<'a>;
}
```

However, Generic Associated Types are not even implemented on nightly
yet, so we need to generate a new trait per type for the foreseeable
future.

Co-authored-by: Aaron Hill <aa1ronham@gmail.com>

pin-project-internal/src/lib.rs

@@ -92,7 +92,7 @@ use syn::parse::Nothing;
 /// }
 ///
 /// impl<T, U> Foo<T, U> {
-///     fn baz(self: Pin<&mut Self>) {
+///     fn baz(mut self: Pin<&mut Self>) {
 ///         let this = self.project();
 ///         let _: Pin<&mut T> = this.future; // Pinned reference to the field
 ///         let _: &mut U = this.field; // Normal reference to the field
@@ -115,7 +115,7 @@ use syn::parse::Nothing;
 /// }
 ///
 /// impl<T, U> Foo<T, U> {
-///     fn baz(self: Pin<&mut Self>) {
+///     fn baz(mut self: Pin<&mut Self>) {
 ///         let this = self.project();
 ///         let _: Pin<&mut T> = this.future; // Pinned reference to the field
 ///         let _: &mut U = this.field; // Normal reference to the field
@@ -162,7 +162,7 @@ use syn::parse::Nothing;
 /// }
 ///
 /// #[pinned_drop]
-/// fn my_drop_fn<T: Debug, U: Debug>(foo: Pin<&mut Foo<T, U>>) {
+/// fn my_drop_fn<T: Debug, U: Debug>(mut foo: Pin<&mut Foo<T, U>>) {
 ///     let foo = foo.project();
 ///     println!("Dropping pinned field: {:?}", foo.pinned_field);
 ///     println!("Dropping unpin field: {:?}", foo.unpin_field);
@@ -193,7 +193,7 @@ use syn::parse::Nothing;
 /// }
 ///
 /// impl<T, U> Foo<T, U> {
-///     fn baz(self: Pin<&mut Self>) {
+///     fn baz(mut self: Pin<&mut Self>) {
 ///         let this = self.project();
 ///         let _: Pin<&mut T> = this.future;
 ///         let _: &mut U = this.field;
@@ -211,7 +211,7 @@ use syn::parse::Nothing;
 /// struct Foo<T, U>(#[pin] T, U);
 ///
 /// impl<T, U> Foo<T, U> {
-///     fn baz(self: Pin<&mut Self>) {
+///     fn baz(mut self: Pin<&mut Self>) {
 ///         let this = self.project();
 ///         let _: Pin<&mut T> = this.0;
 ///         let _: &mut U = this.1;
@@ -250,7 +250,7 @@ use syn::parse::Nothing;
 /// # #[cfg(feature = "project_attr")]
 /// impl<A, B, C> Foo<A, B, C> {
 ///     #[project] // Nightly does not need a dummy attribute to the function.
-///     fn baz(self: Pin<&mut Self>) {
+///     fn baz(mut self: Pin<&mut Self>) {
 ///         #[project]
 ///         match self.project() {
 ///             Foo::Tuple(x, y) => {
@@ -347,7 +347,7 @@ pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream {
 ///
 /// impl<T, U> Foo<T, U> {
 ///     #[project] // Nightly does not need a dummy attribute to the function.
-///     fn baz(self: Pin<&mut Self>) {
+///     fn baz(mut self: Pin<&mut Self>) {
 ///         #[project]
 ///         let Foo { future, field } = self.project();
 ///
@@ -372,7 +372,7 @@ pub fn pinned_drop(args: TokenStream, input: TokenStream) -> TokenStream {
 ///
 /// impl<A, B, C> Foo<A, B, C> {
 ///     #[project] // Nightly does not need a dummy attribute to the function.
-///     fn baz(self: Pin<&mut Self>) {
+///     fn baz(mut self: Pin<&mut Self>) {
 ///         #[project]
 ///         match self.project() {
 ///             Foo::Tuple(x, y) => {

pin-project-internal/src/pin_project/enums.rs

@@ -6,7 +6,7 @@ use crate::utils::VecExt;
 
 use super::{proj_generics, Context, PIN};
 
-pub(super) fn parse(mut cx: Context, mut item: ItemEnum) -> Result<TokenStream> {
+pub(super) fn parse(cx: &mut Context, mut item: ItemEnum) -> Result<TokenStream> {
     if item.variants.is_empty() {
         return Err(error!(item, "cannot be implemented for enums without variants"));
     }
@@ -23,22 +23,23 @@ pub(super) fn parse(mut cx: Context, mut item: ItemEnum) -> Result<TokenStream>
         return Err(error!(item.variants, "cannot be implemented for enums that have no field"));
     }
 
-    let (proj_variants, proj_arms) = variants(&mut cx, &mut item)?;
+    let (proj_variants, proj_arms) = variants(cx, &mut item)?;
 
-    let impl_drop = cx.impl_drop(&item.generics);
+    let mut impl_drop = cx.impl_drop(&item.generics);
     let Context { original, projected, lifetime, impl_unpin, .. } = cx;
     let proj_generics = proj_generics(&item.generics, &lifetime);
     let proj_ty_generics = proj_generics.split_for_impl().1;
+    let proj_trait = &cx.projected_trait;
     let (impl_generics, ty_generics, where_clause) = item.generics.split_for_impl();
 
     let mut proj_items = quote! {
         enum #projected #proj_generics #where_clause { #(#proj_variants,)* }
     };
     let proj_method = quote! {
-        impl #impl_generics #original #ty_generics #where_clause {
-            fn project<#lifetime>(self: ::core::pin::Pin<&#lifetime mut Self>) -> #projected #proj_ty_generics {
+        impl #impl_generics #proj_trait #ty_generics for ::core::pin::Pin<&mut #original #ty_generics> #where_clause {
+            fn project<#lifetime>(&#lifetime mut self) -> #projected #proj_ty_generics #where_clause {
                 unsafe {
-                    match ::core::pin::Pin::get_unchecked_mut(self) {
+                    match self.as_mut().get_unchecked_mut() {
                         #(#proj_arms,)*
                     }
                 }

pin-project-internal/src/pin_project/mod.rs

@@ -4,11 +4,10 @@ use syn::{
     parse::{Parse, ParseStream},
     punctuated::Punctuated,
     token::Comma,
-    Fields, FieldsNamed, FieldsUnnamed, GenericParam, Generics, Index, Item, ItemStruct, Lifetime,
-    LifetimeDef, Meta, NestedMeta, Result, Type,
+    *,
 };
 
-use crate::utils::{crate_path, proj_ident};
+use crate::utils::{crate_path, proj_ident, proj_trait_ident};
 
 mod enums;
 mod structs;
@@ -51,6 +50,10 @@ struct Context {
     original: Ident,
     /// Name of the projected type.
     projected: Ident,
+    /// Name of the trait generated
+    /// to provide a 'project' method
+    projected_trait: Ident,
+    generics: Generics,
 
     lifetime: Lifetime,
     impl_unpin: ImplUnpin,
@@ -63,7 +66,16 @@ impl Context {
         let projected = proj_ident(&original);
         let lifetime = proj_lifetime(&generics.params);
         let impl_unpin = ImplUnpin::new(generics, unsafe_unpin);
-        Ok(Self { original, projected, lifetime, impl_unpin, pinned_drop })
+        let projected_trait = proj_trait_ident(&original);
+        Ok(Self {
+            original,
+            projected,
+            projected_trait,
+            lifetime,
+            impl_unpin,
+            pinned_drop,
+            generics: generics.clone(),
+        })
     }
 
     fn impl_drop<'a>(&self, generics: &'a Generics) -> ImplDrop<'a> {
@@ -74,22 +86,42 @@ impl Context {
 fn parse(args: TokenStream, input: TokenStream) -> Result<TokenStream> {
     match syn::parse2(input)? {
         Item::Struct(item) => {
-            let cx = Context::new(args, item.ident.clone(), &item.generics)?;
-            let packed_check = ensure_not_packed(&item)?;
-            let mut res = structs::parse(cx, item)?;
-            res.extend(packed_check);
+            let mut cx = Context::new(args, item.ident.clone(), &item.generics)?;
+
+            let mut res = structs::parse(&mut cx, item.clone())?;
+            res.extend(ensure_not_packed(&item)?);
+            res.extend(make_proj_trait(&mut cx)?);
             Ok(res)
         }
         Item::Enum(item) => {
-            let cx = Context::new(args, item.ident.clone(), &item.generics)?;
+            let mut cx = Context::new(args, item.ident.clone(), &item.generics)?;
+
             // We don't need to check for '#[repr(packed)]',
             // since it does not apply to enums
-            enums::parse(cx, item)
+            let mut res = enums::parse(&mut cx, item.clone())?;
+            res.extend(make_proj_trait(&mut cx)?);
+            Ok(res)
         }
         item => Err(error!(item, "may only be used on structs or enums")),
     }
 }
 
+fn make_proj_trait(cx: &mut Context) -> Result<TokenStream> {
+    let proj_trait = &cx.projected_trait;
+    let lifetime = &cx.lifetime;
+    let proj_ident = &cx.projected;
+    let proj_generics = proj_generics(&cx.generics, &cx.lifetime);
+    let proj_ty_generics = proj_generics.split_for_impl().1;
+
+    let (orig_generics, _orig_ty_generics, orig_where_clause) = cx.generics.split_for_impl();
+
+    Ok(quote! {
+        trait #proj_trait #orig_generics {
+            fn project<#lifetime>(&#lifetime mut self) -> #proj_ident #proj_ty_generics #orig_where_clause;
+        }
+    })
+}
+
 fn ensure_not_packed(item: &ItemStruct) -> Result<TokenStream> {
     for meta in item.attrs.iter().filter_map(|attr| attr.parse_meta().ok()) {
         if let Meta::List(l) = meta {
@@ -220,7 +252,7 @@ impl<'a> ImplDrop<'a> {
         Self { generics, pinned_drop }
     }
 
-    fn build(self, ident: &Ident) -> TokenStream {
+    fn build(&mut self, ident: &Ident) -> TokenStream {
         let (impl_generics, ty_generics, where_clause) = self.generics.split_for_impl();
 
         if let Some(pinned_drop) = self.pinned_drop {
@@ -292,7 +324,7 @@ impl ImplUnpin {
     }
 
     /// Creates `Unpin` implementation.
-    fn build(self, ident: &Ident) -> TokenStream {
+    fn build(&mut self, ident: &Ident) -> TokenStream {
         let (impl_generics, ty_generics, where_clause) = self.generics.split_for_impl();
         quote! {
             impl #impl_generics ::core::marker::Unpin for #ident #ty_generics #where_clause {}

pin-project-internal/src/pin_project/structs.rs

@@ -6,7 +6,7 @@ use crate::utils::VecExt;
 
 use super::{proj_generics, Context, PIN};
 
-pub(super) fn parse(mut cx: Context, mut item: ItemStruct) -> Result<TokenStream> {
+pub(super) fn parse(cx: &mut Context, mut item: ItemStruct) -> Result<TokenStream> {
     let (proj_fields, proj_init) = match &mut item.fields {
         Fields::Named(FieldsNamed { named: fields, .. })
         | Fields::Unnamed(FieldsUnnamed { unnamed: fields, .. })
@@ -16,26 +16,27 @@ pub(super) fn parse(mut cx: Context, mut item: ItemStruct) -> Result<TokenStream
         }
         Fields::Unit => return Err(error!(item, "cannot be implemented for structs with units")),
 
-        Fields::Named(fields) => named(&mut cx, fields)?,
-        Fields::Unnamed(fields) => unnamed(&mut cx, fields)?,
+        Fields::Named(fields) => named(cx, fields)?,
+        Fields::Unnamed(fields) => unnamed(cx, fields)?,
     };
 
     let orig_ident = &cx.original;
     let proj_ident = &cx.projected;
     let lifetime = &cx.lifetime;
-    let impl_drop = cx.impl_drop(&item.generics);
+    let mut impl_drop = cx.impl_drop(&item.generics);
     let proj_generics = proj_generics(&item.generics, &cx.lifetime);
     let proj_ty_generics = proj_generics.split_for_impl().1;
+    let proj_trait = &cx.projected_trait;
     let (impl_generics, ty_generics, where_clause) = item.generics.split_for_impl();
 
     let mut proj_items = quote! {
         struct #proj_ident #proj_generics #where_clause #proj_fields
     };
     let proj_method = quote! {
-        impl #impl_generics #orig_ident #ty_generics #where_clause {
-            fn project<#lifetime>(self: ::core::pin::Pin<&#lifetime mut Self>) -> #proj_ident #proj_ty_generics {
+        impl #impl_generics #proj_trait #ty_generics for ::core::pin::Pin<&mut #orig_ident #ty_generics> #where_clause {
+            fn project<#lifetime>(&#lifetime mut self) -> #proj_ident #proj_ty_generics #where_clause {
                 unsafe {
-                    let this = ::core::pin::Pin::get_unchecked_mut(self);
+                    let this = self.as_mut().get_unchecked_mut();
                     #proj_ident #proj_init
                 }
             }

pin-project-internal/src/utils.rs

@@ -7,6 +7,10 @@ pub(crate) fn proj_ident(ident: &Ident) -> Ident {
     format_ident!("__{}Projection", ident)
 }
 
+pub(crate) fn proj_trait_ident(ident: &Ident) -> Ident {
+    format_ident!("__{}ProjectionTrait", ident)
+}
+
 pub(crate) trait VecExt {
     fn find_remove(&mut self, ident: &str) -> Option<Attribute>;
 }

src/lib.rs

@@ -22,7 +22,7 @@
 //! }
 //!
 //! impl<T, U> Foo<T, U> {
-//!     fn baz(self: Pin<&mut Self>) {
+//!     fn baz(mut self: Pin<&mut Self>) {
 //!         let this = self.project();
 //!         let _: Pin<&mut T> = this.future; // Pinned reference to the field
 //!         let _: &mut U = this.field; // Normal reference to the field

tests/pin_project.rs

@@ -19,17 +19,22 @@ fn test_pin_project() {
 
     let mut foo = Foo { field1: 1, field2: 2 };
 
-    let foo = Pin::new(&mut foo).project();
+    let mut foo_orig = Pin::new(&mut foo);
+    let foo = foo_orig.project();
 
     let x: Pin<&mut i32> = foo.field1;
     assert_eq!(*x, 1);
 
     let y: &mut i32 = foo.field2;
     assert_eq!(*y, 2);
 
+    assert_eq!(foo_orig.as_ref().field1, 1);
+    assert_eq!(foo_orig.as_ref().field2, 2);
+
     let mut foo = Foo { field1: 1, field2: 2 };
 
-    let foo = Pin::new(&mut foo).project();
+    let mut foo = Pin::new(&mut foo);
+    let foo = foo.project();
 
     let __FooProjection { field1, field2 } = foo;
     let _: Pin<&mut i32> = field1;
@@ -42,7 +47,8 @@ fn test_pin_project() {
 
     let mut bar = Bar(1, 2);
 
-    let bar = Pin::new(&mut bar).project();
+    let mut bar = Pin::new(&mut bar);
+    let bar = bar.project();
 
     let x: Pin<&mut i32> = bar.0;
     assert_eq!(*x, 1);
@@ -53,6 +59,7 @@ fn test_pin_project() {
     // enum
 
     #[pin_project]
+    #[derive(Eq, PartialEq, Debug)]
     enum Baz<A, B, C, D> {
         Variant1(#[pin] A, B),
         Variant2 {
@@ -65,7 +72,8 @@ fn test_pin_project() {
 
     let mut baz = Baz::Variant1(1, 2);
 
-    let baz = Pin::new(&mut baz).project();
+    let mut baz_orig = Pin::new(&mut baz);
+    let baz = baz_orig.project();
 
     match baz {
         __BazProjection::Variant1(x, y) => {
@@ -82,9 +90,12 @@ fn test_pin_project() {
         __BazProjection::None => {}
     }
 
+    assert_eq!(Pin::into_ref(baz_orig).get_ref(), &Baz::Variant1(1, 2));
+
     let mut baz = Baz::Variant2 { field1: 3, field2: 4 };
 
-    let mut baz = Pin::new(&mut baz).project();
+    let mut baz = Pin::new(&mut baz);
+    let mut baz = baz.project();
 
     match &mut baz {
         __BazProjection::Variant1(x, y) => {
@@ -110,6 +121,30 @@ fn test_pin_project() {
     }
 }
 
+#[test]
+fn enum_project_set() {
+    #[pin_project]
+    #[derive(Eq, PartialEq, Debug)]
+    enum Bar {
+        Variant1(#[pin] u8),
+        Variant2(bool),
+    }
+
+    let mut bar = Bar::Variant1(25);
+    let mut bar_orig = Pin::new(&mut bar);
+    let bar_proj = bar_orig.project();
+
+    match bar_proj {
+        __BarProjection::Variant1(val) => {
+            let new_bar = Bar::Variant2(val.as_ref().get_ref() == &25);
+            bar_orig.set(new_bar);
+        }
+        _ => unreachable!(),
+    }
+
+    assert_eq!(bar, Bar::Variant2(true));
+}
+
 #[test]
 fn where_clause_and_associated_type_fields() {
     // struct

tests/pinned_drop.rs

@@ -14,7 +14,7 @@ pub struct Foo<'a> {
 }
 
 #[pinned_drop]
-fn do_drop(foo: Pin<&mut Foo<'_>>) {
+fn do_drop(mut foo: Pin<&mut Foo<'_>>) {
     **foo.project().was_dropped = true;
 }