# Attribute Macro pin_project::pinned_drop [−] [src]

    #[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`.