Text of rust.docs.kernel.org › src › core › ops › drop.rs.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

drop.rs - source

Skip to main content core/ops/ drop.rs 1 use 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

The rest of this page is on the live site.