core/ops/drop.rs
1use crate::pin::Pin;
2
3/// Custom code within the destructor.
4///
5/// When a value is no longer needed, Rust will run a "destructor" on that value.
6/// The most common way that a value is no longer needed is when it goes out of
7/// scope. Destructors may still run in other circumstances, but we're going to
8/// focus on scope for the examples here. To learn about some of those other cases,
9/// please see [the reference] section on destructors.
10///
11/// [the reference]: https://doc.rust-lang.org/reference/destructors.html
12///
13/// This destructor consists of two components:
14/// - A call to `Drop::drop` for that value, if this special `Drop` trait is implemented for its type.
15/// - The automatically generated "drop glue" which recursively calls the destructors
16/// of all the fields of this value.
17///
18/// As Rust automatically calls the destructors of all contained fields,
19/// you don't have to implement `Drop` in most cases. But there are some cases where
20/// it is useful, for example for types which directly manage a resource.
21/// That resource may be memory, it may be a file descriptor, it may be a network socket.
22/// Once a value of that type is no longer going to be used, it should "clean up" its
23/// resource by freeing the memory or closing the file or socket. This is
24/// the job of a destructor, and therefore the job of `Drop::drop`.
25///
26/// ## Examples
27///
28/// To see destructors in action, let's take a look at the following program:
29///
30/// ```rust
31/// struct HasDrop;
32///
33/// impl Drop for HasDrop {
34/// fn drop(&mut self) {
35/// println!("Dropping HasDrop!");
36/// }
37/// }
38///
39/// struct HasTwoDrops {
40/// one: HasDrop,
41/// two: HasDrop,
42/// }
43///
44/// impl Drop for HasTwoDrops {
45/// fn drop(&mut self) {
46/// println!("Dropping HasTwoDrops!");
47/// }
48/// }
49///
50/// fn main() {
51/// let _x = HasTwoDrops { one: HasDrop, two: HasDrop };
52/// println!("Running!");
53/// }
54/// ```
55///
56/// Rust will first call `Drop::drop` for `_x` and then for both `_x.one` and `_x.two`,
57/// meaning that running this will print
58///
59/// ```text
60/// Running!
61/// Dropping HasTwoDrops!
62/// Dropping HasDrop!
63/// Dropping HasDrop!
64/// ```
65///
66/// Even if we remove the implementation of `Drop` for `HasTwoDrop`, the destructors of its fields are still called.
67/// This would result in
68///
69/// ```test
70/// Running!
71/// Dropping HasDrop!
72/// Dropping HasDrop!
73/// ```
74///
75/// ## You cannot call `Drop::drop` yourself
76///
77/// Because `Drop::drop` is used to clean up a value, it may be dangerous to use this value after
78/// the method has been called. As `Drop::drop` does not take ownership of its input,
79/// Rust prevents misuse by not allowing you to call `Drop::drop` directly.
80///
81/// In other words, if you tried to explicitly call `Drop::drop` in the above example, you'd get a compiler error.
82///
83/// If you'd like to explicitly call the destructor of a value, [`mem::drop`] can be used instead.
84///
85/// [`mem::drop`]: drop
86///
87/// ## Drop order
88///
89/// Which of our two `HasDrop` drops first, though? For structs, it's the same
90/// order that they're declared: first `one`, then `two`. If you'd like to try
91/// this yourself, you can modify `HasDrop` above to contain some data, like an
92/// integer, and then use it in the `println!` inside of `Drop`. This behavior is
93/// guaranteed by the language.
94///
95/// Unlike for structs, local variables are dropped in reverse order:
96///
97/// ```rust
98/// struct Foo;
99///
100/// impl Drop for Foo {
101/// fn drop(&mut self) {
102/// println!("Dropping Foo!")
103/// }
104/// }
105///
106/// struct Bar;
107///
108/// impl Drop for Bar {
109/// fn drop(&mut self) {
110/// println!("Dropping Bar!")
111/// }
112/// }
113///
114/// fn main() {
115/// let _foo = Foo;
116/// let _bar = Bar;
117/// }
118/// ```
119///
120/// This will print
121///
122/// ```text
123/// Dropping Bar!
124/// Dropping Foo!
125/// ```
126///
127/// Please see [the reference] for the full rules.
128///
129/// [the reference]: https://doc.rust-lang.org/reference/destructors.html
130///
131/// ## `Copy` and `Drop` are exclusive
132///
133/// You cannot implement both [`Copy`] and `Drop` on the same type. Types that
134/// are `Copy` get implicitly duplicated by the compiler, making it very
135/// hard to predict when, and how often destructors will be executed. As such,
136/// these types cannot have destructors.
137///
138/// ## Drop check
139///
140/// Dropping interacts with the borrow checker in subtle ways: when a type `T` is being implicitly
141/// dropped as some variable of this type goes out of scope, the borrow checker needs to ensure that
142/// calling `T`'s destructor at this moment is safe. In particular, it also needs to be safe to
143/// recursively drop all the fields of `T`. For example, it is crucial that code like the following
144/// is being rejected:
145///
146/// ```compile_fail,E0597
147/// use std::cell::Cell;
148///
149/// struct S<'a>(Cell<Option<&'a S<'a>>>, Box<i32>);
150/// impl Drop for S<'_> {
151/// fn drop(&mut self) {
152/// if let Some(r) = self.0.get() {
153/// // Print the contents of the `Box` in `r`.
154/// println!("{}", r.1);
155/// }
156/// }
157/// }
158///
159/// fn main() {
160/// // Set up two `S` that point to each other.
161/// let s1 = S(Cell::new(None), Box::new(42));
162/// let s2 = S(Cell::new(Some(&s1)), Box::new(42));
163/// s1.0.set(Some(&s2));
164/// // Now they both get dropped. But whichever is the 2nd one
165/// // to be dropped will access the `Box` in the first one,
166/// // which is a use-after-free!
167/// }
168/// ```
169///
170/// The Nomicon discusses the need for [drop check in more detail][drop check].
171///
172/// To reject such code, the "drop check" analysis determines which types and lifetimes need to
173/// still be live when `T` gets dropped. The exact details of this analysis are not yet
174/// stably guaranteed and **subject to change**. Currently, the analysis works as follows:
175/// - If `T` has no drop glue, then trivially nothing is required to be live. This is the case if
176/// neither `T` nor any of its (recursive) fields have a destructor (`impl Drop`). [`PhantomData`],
177/// arrays of length 0 and [`ManuallyDrop`] are considered to never have a destructor, no matter
178/// their field type.
179/// - If `T` has drop glue, then, for all types `U` that are *owned* by any field of `T`,
180/// recursively add the types and lifetimes that need to be live when `U` gets dropped. The set of
181/// owned types is determined by recursively traversing `T`:
182/// - Recursively descend through `PhantomData`, `Box`, tuples, and arrays (excluding arrays of
183/// length 0).
184/// - Stop at reference and raw pointer types as well as function pointers and function items;
185/// they do not own anything.
186/// - Stop at non-composite types (type parameters that remain generic in the current context and
187/// base types such as integers and `bool`); these types are owned.
188/// - When hitting an ADT with `impl Drop`, stop there; this type is owned.
189/// - When hitting an ADT without `impl Drop`, recursively descend to its fields. (For an `enum`,
190/// consider all fields of all variants.)
191/// - Furthermore, if `T` implements `Drop`, then all generic (lifetime and type) parameters of `T`
192/// must be live.
193///
194/// In the above example, the last clause implies that `'a` must be live when `S<'a>` is dropped,
195/// and hence the example is rejected. If we remove the `impl Drop`, the liveness requirement
196/// disappears and the example is accepted.
197///
198/// There exists an unstable way for a type to opt-out of the last clause; this is called "drop
199/// check eyepatch" or `may_dangle`. For more details on this nightly-only feature, see the
200/// [discussion in the Nomicon][nomicon].
201///
202/// [`ManuallyDrop`]: crate::mem::ManuallyDrop
203/// [`PhantomData`]: crate::marker::PhantomData
204/// [drop check]: ../../nomicon/dropck.html
205/// [nomicon]: ../../nomicon/phantom-data.html#an-exception-the-special-case-of-the-standard-library-and-its-unstable-may_dangle
206#[lang = "drop"]
207#[stable(feature = "rust1", since = "1.0.0")]
208#[rustc_const_unstable(feature = "const_destruct", issue = "133214")]
209pub const trait Drop {
210 /// Executes the destructor for this type.
211 ///
212 /// This method is called implicitly when the value goes out of scope,
213 /// and cannot be called explicitly (this is compiler error [E0040]).
214 /// However, the [`mem::drop`] function in the prelude can be
215 /// used to call the argument's `Drop` implementation.
216 ///
217 /// When this method has been called, `self` has not yet been deallocated.
218 /// That only happens after the method is over.
219 /// If this wasn't the case, `self` would be a dangling reference.
220 ///
221 /// # Panics
222 ///
223 /// Implementations should generally avoid [`panic!`]ing, because `drop()` may itself be called
224 /// during unwinding due to a panic, and if the `drop()` panics in that situation (a “double
225 /// panic”), this will likely abort the program. It is possible to check [`panicking()`] first,
226 /// which may be desirable for a `Drop` implementation that is reporting a bug of the kind
227 /// “you didn't finish using this before it was dropped”; but most types should simply clean up
228 /// their owned allocations or other resources and return normally from `drop()`, regardless of
229 /// what state they are in.
230 ///
231 /// Note that even if this panics, the value is considered to be dropped;
232 /// you must not cause `drop` to be called again. This is normally automatically
233 /// handled by the compiler, but when using unsafe code, can sometimes occur
234 /// unintentionally, particularly when using [`ptr::drop_in_place`].
235 ///
236 /// [E0040]: ../../error_codes/E0040.html
237 /// [`panic!`]: crate::panic!
238 /// [`panicking()`]: ../../std/thread/fn.panicking.html
239 /// [`mem::drop`]: drop
240 /// [`ptr::drop_in_place`]: crate::ptr::drop_in_place
241 #[stable(feature = "rust1", since = "1.0.0")]
242 #[rustc_default_body_unstable(feature = "pin_ergonomics", issue = "130494")]
243 fn drop(&mut self) {
244 // SAFETY: `self` is pinned till after dropped.
245 unsafe { Drop::pin_drop(Pin::new_unchecked(self)) }
246 }
247
248 /// Execute the destructor for this type, but different to [`Drop::drop`], it requires `self`
249 /// to be pinned.
250 ///
251 /// By implementing this method instead of [`Drop::drop`], the receiver type [`Pin<&mut Self>`]
252 /// makes sure that the value is pinned until it is deallocated (See [`std::pin` module docs] for
253 /// more details), which enables us to support field projections of `Self` type safely.
254 ///
255 /// For types that support pin-projection (i.e., marked with `#[pin_v2]`), this method must be used.
256 ///
257 /// For any type, at least and at most one of [`Drop::drop`] and [`Drop::pin_drop`] should be
258 /// implemented.
259 ///
260 /// See also [`Drop::drop`] for more details.
261 ///
262 /// [`Drop::drop`]: crate::ops::Drop::drop
263 /// [`Drop::pin_drop`]: crate::ops::Drop::pin_drop
264 /// [`Pin<&mut Self>`]: crate::pin::Pin
265 /// [`std::pin` module docs]: crate::pin
266 #[unstable(feature = "pin_ergonomics", issue = "130494")]
267 fn pin_drop(self: Pin<&mut Self>) {}
268}