1 use crate::ops::{Deref, DerefMut};
4 /// A wrapper to inhibit compiler from automatically calling `T`’s destructor.
5 /// This wrapper is 0-cost.
7 /// `ManuallyDrop<T>` is subject to the same layout optimizations as `T`.
8 /// As a consequence, it has *no effect* on the assumptions that the compiler makes
9 /// about its contents. For example, initializing a `ManuallyDrop<&mut T>`
10 /// with [`mem::zeroed`] is undefined behavior.
11 /// If you need to handle uninitialized data, use [`MaybeUninit<T>`] instead.
13 /// Note that accessing the value inside a `ManuallyDrop<T>` is safe.
14 /// This means that a `ManuallyDrop<T>` whose content has been dropped must not
15 /// be exposed through a public safe API.
16 /// Correspondingly, `ManuallyDrop::drop` is unsafe.
20 /// This wrapper can be used to enforce a particular drop order on fields, regardless
21 /// of how they are defined in the struct:
24 /// use std::mem::ManuallyDrop;
29 /// // Immediately clear there’s something non-trivial going on with these fields.
30 /// peach: ManuallyDrop<Peach>,
31 /// melon: Melon, // Field that’s independent of the other two.
32 /// banana: ManuallyDrop<Banana>,
35 /// impl Drop for FruitBox {
36 /// fn drop(&mut self) {
38 /// // Explicit ordering in which field destructors are run specified in the intuitive
39 /// // location – the destructor of the structure containing the fields.
40 /// // Moreover, one can now reorder fields within the struct however much they want.
41 /// ManuallyDrop::drop(&mut self.peach);
42 /// ManuallyDrop::drop(&mut self.banana);
44 /// // After destructor for `FruitBox` runs (this function), the destructor for Melon gets
45 /// // invoked in the usual manner, as it is not wrapped in `ManuallyDrop`.
50 /// However, care should be taken when using this pattern as it can lead to *leak amplification*.
51 /// In this example, if the `Drop` implementation for `Peach` were to panic, the `banana` field
52 /// would also be leaked.
54 /// In contrast, the automatically-generated compiler drop implementation would have ensured
55 /// that all fields are dropped even in the presence of panics. This is especially important when
56 /// working with [pinned] data, where reusing the memory without calling the destructor could lead
57 /// to Undefined Behaviour.
59 /// [`mem::zeroed`]: crate::mem::zeroed
60 /// [`MaybeUninit<T>`]: crate::mem::MaybeUninit
61 /// [pinned]: crate::pin
62 #[stable(feature = "manually_drop", since = "1.20.0")]
63 #[lang = "manually_drop"]
64 #[derive(Copy, Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
66 pub struct ManuallyDrop<T: ?Sized> {
70 impl<T> ManuallyDrop<T> {
71 /// Wrap a value to be manually dropped.
76 /// use std::mem::ManuallyDrop;
77 /// ManuallyDrop::new(Box::new(()));
79 #[stable(feature = "manually_drop", since = "1.20.0")]
80 #[rustc_const_stable(feature = "const_manually_drop", since = "1.36.0")]
82 pub const fn new(value: T) -> ManuallyDrop<T> {
83 ManuallyDrop { value }
86 /// Extracts the value from the `ManuallyDrop` container.
88 /// This allows the value to be dropped again.
93 /// use std::mem::ManuallyDrop;
94 /// let x = ManuallyDrop::new(Box::new(()));
95 /// let _: Box<()> = ManuallyDrop::into_inner(x); // This drops the `Box`.
97 #[stable(feature = "manually_drop", since = "1.20.0")]
98 #[rustc_const_stable(feature = "const_manually_drop", since = "1.36.0")]
100 pub const fn into_inner(slot: ManuallyDrop<T>) -> T {
104 /// Takes the value from the `ManuallyDrop<T>` container out.
106 /// This method is primarily intended for moving out values in drop.
107 /// Instead of using [`ManuallyDrop::drop`] to manually drop the value,
108 /// you can use this method to take the value and use it however desired.
110 /// Whenever possible, it is preferable to use [`into_inner`][`ManuallyDrop::into_inner`]
111 /// instead, which prevents duplicating the content of the `ManuallyDrop<T>`.
115 /// This function semantically moves out the contained value without preventing further usage,
116 /// leaving the state of this container unchanged.
117 /// It is your responsibility to ensure that this `ManuallyDrop` is not used again.
119 #[must_use = "if you don't need the value, you can use `ManuallyDrop::drop` instead"]
120 #[stable(feature = "manually_drop_take", since = "1.42.0")]
122 pub unsafe fn take(slot: &mut ManuallyDrop<T>) -> T {
123 // SAFETY: we are reading from a reference, which is guaranteed
124 // to be valid for reads.
125 unsafe { ptr::read(&slot.value) }
129 impl<T: ?Sized> ManuallyDrop<T> {
130 /// Manually drops the contained value. This is exactly equivalent to calling
131 /// [`ptr::drop_in_place`] with a pointer to the contained value. As such, unless
132 /// the contained value is a packed struct, the destructor will be called in-place
133 /// without moving the value, and thus can be used to safely drop [pinned] data.
135 /// If you have ownership of the value, you can use [`ManuallyDrop::into_inner`] instead.
139 /// This function runs the destructor of the contained value. Other than changes made by
140 /// the destructor itself, the memory is left unchanged, and so as far as the compiler is
141 /// concerned still holds a bit-pattern which is valid for the type `T`.
143 /// However, this "zombie" value should not be exposed to safe code, and this function
144 /// should not be called more than once. To use a value after it's been dropped, or drop
145 /// a value multiple times, can cause Undefined Behavior (depending on what `drop` does).
146 /// This is normally prevented by the type system, but users of `ManuallyDrop` must
147 /// uphold those guarantees without assistance from the compiler.
149 /// [pinned]: crate::pin
150 #[stable(feature = "manually_drop", since = "1.20.0")]
152 pub unsafe fn drop(slot: &mut ManuallyDrop<T>) {
153 // SAFETY: we are dropping the value pointed to by a mutable reference
154 // which is guaranteed to be valid for writes.
155 // It is up to the caller to make sure that `slot` isn't dropped again.
156 unsafe { ptr::drop_in_place(&mut slot.value) }
160 #[stable(feature = "manually_drop", since = "1.20.0")]
161 impl<T: ?Sized> Deref for ManuallyDrop<T> {
164 fn deref(&self) -> &T {
169 #[stable(feature = "manually_drop", since = "1.20.0")]
170 impl<T: ?Sized> DerefMut for ManuallyDrop<T> {
172 fn deref_mut(&mut self) -> &mut T {