Allow using #[pin_project] type with private field types

[Aaron1011]

Previously, given code such as:

struct Private<T>;

#[pin_project]
pub struct Public<T> {
    #[pin] private: Private<T>
}

we would generate an Unpin impl like this:

impl Unpin for Public where Private: Unpin {}

Unfortunately, since Private is not a public type,
this would cause an E0446 ('private type Private in public interface)

When RFC 2145 is implemented (rust-lang/rust#48054),
this will become a lint, rather then a hard error.

In the time being, we need a solution that will work with the current
type privacy rules.

The solution is to generate code like this:

fn __private_scope() {
    pub struct __UnpinPublic<T> {
        __field0: Private<T>
    }
    impl<T> Unpin for Public<T> where __UnpinPublic<T>: Unpin {}
}

That is, we generate a new struct, containing all of the pinned
fields from our #[pin_project] type. This struct is delcared within
a function, which makes it impossible to be named by user code.
This guarnatees that it will use the default auto-trait impl for Unpin -
that is, it will implement Unpin iff all of its fields implement Unpin.
This type can be safely declared as 'public', satisfiying the privacy
checker without actually allowing user code to access it.

This allows users to apply the #[pin_project] attribute to types
regardless of the privacy of the types of their fields.

[taiki-e]

Looks good to me aside from one concern. Thanks!

[taiki-e]

My concern is that this generates the following documents (due to rust-lang/rust#63281):

impl<T> Unpin for PublicStruct<T>
where
    __UnpinStructPublicStruct<T>: Unpin, 

[taiki-e]

Even if UnsafeUnpin is used, a similar document is generated, but UnsafeUnpin impl is also documented at the same time, so we can know which type needs to be Unpin.

impl<T> Unpin for Foo<T>
where
    Wrapper<Self>: UnsafeUnpin,

[Aaron1011]

I think this would be fine if __UnpinStructPublicStruct had documentation generated - that would allow users to use --document-private-items to seewhen it implemented Unpin. However, the fact that __UnpinStructPublicStruct is defined within a function seems to be preventing rustdoc from documenting it.

I'll investigate further.

[Aaron1011]

@taiki-e: Unfortunately, there doesn't appear to be a simple way to allow documenting the Unpin impl on stable rust. There are two ways we can make the __UnpinStruct$Ident structs inaccessible to user code (which prevents them from manually implementing Unpin):

1. Declare the struct inside a new function: e.g. fn foo() { pub struct __UnpinStructFoo; } While this prevents user code from referencing __UnpinStructFoo, it also prevents rustdoc from generating documentation for __UnpinStructFoo.
2. Declare the struct within nested private modules: e.g. mod outer { mod inner { pub struct __UnpinStructFoo; } } User code will be able to reference outer, but will not be able to reference __UnpinStructFoo inside inner. However, this does not work when our original type is itself declared within a function (e.g. fn foo() { #[pin_project] struct Foo }. From within inner, it is impossible to reference any type declared within the containing function.

However, a solution is possible on nightly. When compiling on nightly, we can make use of the unstable Span::def_site() constructor. When such a span is used with an identifier, that identifier opts into def-site hygiene - that is, it becomes impossible for user code to even refer to that identifier (even if it's public!).

By using a build script, we can get the best of both worlds. At compile time, we detect the current rust channel. If we're on nightly, we use the nightly-only Span::def_site. If we're on stable, we use a normal span, but wrap our generated code in a function.

Since docs.rs uses nightly rust, libraries will automatically get the nicer documentation when built on docs.rs. Users building documentation locally can use cargo +nightly doc, but still target stable rust.

[taiki-e]

@Aaron1011: Okay, thanks for the investigation.

Since docs.rs uses nightly rust, libraries will automatically get the nicer documentation when built on docs.rs. Users building documentation locally can use cargo +nightly doc, but still target stable rust.

Should we provide a way to opt-out of this? (the documents generated this way is probably not very clean) cc @Nemo157

[taiki-e]

r=me with #53 (comment) addressed.

[taiki-e]

bors delegate+

[bors]

✌️ Aaron1011 can now approve this pull request

[Aaron1011]

Should we provide a way to opt-out of this? (the documents generated this way is probably not very clean)

I don't really see a use case for this. While the generated documentation certainly could be cleaner, I think it's always useful to know when a pin-projected type implements Unpin.

[Aaron1011]

@taiki-e: I've added a comment explaining why the generated struct must be public, and squashed my commits.

[Aaron1011]

@taiki-e: Note that once rust-lang/rust#48054 is implemented and stabilized, it will be possible to remove almost all of this code, and just generate normal bounds in the 'where' clause.

[taiki-e]

@Aaron1011: That's great, I'll look forward to that!

[taiki-e]

bors r+

[bors]

Build succeeded

• taiki-e.pin-project