#[pinned_drop]
Expand description
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 takesPin
<&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
.