Attribute Macro 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.