Make generated 'project' reference take an '&mut Pin<&mut Self>'

[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:

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:

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:

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.

[taiki-e]

I was using .as_mut() to do that, but this is more convenient. Thanks!

[taiki-e]

The way to refer the projected-type should be improved in #46, but should this be format_ident!("{}Projection", ident)?
Personally, I don't want to recommend relying on the internal implementation of proc-macro, but I don't plan to change this frequently.

[taiki-e]

cc @Nemo157

[Nemo157]

I only used the type name for the example in #43 because it was the only way to implement it then, I'm not using it in any real code and wouldn't expect it to stay the same across builds (I would even be for hashing the input AST and sticking part of that hash in the generated type names to block anyone actually relying on it with any reliability).

[taiki-e]

Okay, thanks for clarifying.

I would even be for hashing the input AST and sticking part of that hash in the generated type names to block anyone actually relying on it with any reliability

Unfortunately, I think this is difficult because #[project] depends on the current behavior (simple naming). So for now, I will keep the current one.

[taiki-e]

bors r+

[bors]

Build succeeded

• taiki-e.pin-project

[RalfJung]

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.

That is not true, you can just reborrow the Pin<&mut Self> via as_mut. A double pointer-indirection is unnecessary. Just call foo.as_mut().project() instead of foo.project().

Is there any other reason why double pointer-indirections are used? If not, I suggest to revert this.

[taiki-e]

I was aware of it, but I approved this PR because I felt it would be more convenient to call it without .as_mut().

However, in reality, I missed some of the drawbacks (#65, #21 (comment), etc.). So now I feel that this approach is not always convenient.

[taiki-e]

Filed #89