Change #[pinned_drop] to trait implementation

[taiki-e]

proc-macro just rewrites the trait path and adds unsafe.
It needs to write the documentation more.

Examples

Before:

use pin_project::{pin_project, pinned_drop, UnsafeUnpin};
use std::pin::Pin;

#[pin_project(UnsafeUnpin, PinnedDrop)]
pub struct Foo<T, U> {
    #[pin] pinned_field: T,
    unpin_field: U
}

#[pinned_drop]
fn do_drop<T, U>(this: Pin<&mut Foo<T, U>>) {
    // ..
}

unsafe impl<T: Unpin, U> UnsafeUnpin for Foo<T, U> {}

After:

use pin_project::{pin_project, pinned_drop};
use std::pin::Pin;

#[pin_project(UnsafeUnpin, PinnedDrop)]
pub struct Foo<T, U> {
    #[pin] pinned_field: T,
    unpin_field: U
}

#[pinned_drop]
impl<T, U> PinnedDrop for Foo<T, U> {
    fn drop(self: Pin<&mut Self>) {
        // ..
    }
}

unsafe impl<T: Unpin, U> UnsafeUnpin for Foo<T, U> {}

Closes #26

[taiki-e]

We also need to decide the method name: drop vs pinned_drop

#[pinned_drop]
impl<T, U> PinnedDrop for Foo<T, U> {
    fn pinned_drop(self: Pin<&mut Self>) {}
}
// vs
#[pinned_drop]
impl<T, U> PinnedDrop for Foo<T, U> {
    fn drop(self: Pin<&mut Self>) {}
}

[taiki-e]

bors r+

[bors]

Build succeeded

• taiki-e.pin-project

[RalfJung]

proc-macro just rewrites the trait path and adds unsafe.

Why does it have to add unsafe? And why is it safe to do so?
I am somewhat surprised that the pinned_drop macro is needed at all.

[taiki-e]

@RalfJung

Why does it have to add unsafe? And why is it safe to do so?
I am somewhat surprised that the pinned_drop macro is needed at all.

It is safe to implement PinnedDrop::drop, but it is not safe to call it. This is because destructors can be called multiple times (double dropping is unsound: rust-lang/rust#62360).

Ideally, it would be desirable to be able to prohibit manual calls in the same way as Drop::drop, but the library cannot. So, by using macros and replacing them with private unsafe traits, we prevent users from calling PinnedDrop::drop.

[RalfJung]

Thanks, that explanation should be in the code somewhere.

One thing though: if it is safe to implement, why is the trait unsafe? It should not be. Only its method should be unsafe, reflecting that it is unsafe to call.

[taiki-e]

that explanation should be in the code somewhere.

Although it is in a place that was not changed by this PR, I think this should be explained in the document, so I filed #88.

One thing though: if it is safe to implement, why is the trait unsafe? It should not be. Only its method should be unsafe, reflecting that it is unsafe to call.

Indeed. I forgot to update it.