Attribute Macro pin_project_internal::pinned_drop

#[pinned_drop]

An attribute used for custom implementations of Drop.

This attribute is used in conjunction with the PinnedDrop argument to the #[pin_project] attribute.

The impl block annotated with this attribute acts just like a normal Drop impl, except for the following two:

• drop method takes Pin<&mut Self>
• Name of the trait is PinnedDrop.

pub trait PinnedDrop {
    fn drop(self: Pin<&mut Self>);
}

#[pin_project] implements the actual Drop trait via PinnedDrop you implemented. To drop a type that implements PinnedDrop, use the drop function just like dropping a type that directly implements Drop.

In particular, it will never be called more than once, just like Drop::drop.

Examples

use std::pin::Pin;

use pin_project::{pin_project, pinned_drop};

#[pin_project(PinnedDrop)]
struct PrintOnDrop {
    #[pin]
    field: u8,
}

#[pinned_drop]
impl PinnedDrop for PrintOnDrop {
    fn drop(self: Pin<&mut Self>) {
        println!("Dropping: {}", self.field);
    }
}

fn main() {
    let _x = PrintOnDrop { field: 50 };
}

See also “pinned-drop” section of #[pin_project] attribute.

Why #[pinned_drop] attribute is needed?

Implementing PinnedDrop::drop is safe, but calling it is not safe. This is because destructors can be called multiple times in safe code and double dropping is unsound.

Ideally, it would be desirable to be able to forbid manual calls in the same way as Drop::drop, but the library cannot do it. So, by using macros and replacing them with private traits like the following, this crate prevent users from calling PinnedDrop::drop in safe code.

pub trait PinnedDrop {
    unsafe fn drop(self: Pin<&mut Self>);
}

This allows implementing Drop safely using #[pinned_drop]. Also by using the drop function just like dropping a type that directly implements Drop, can drop safely a type that implements PinnedDrop.