core/mem/
manually_drop.rs

1use crate::cmp::Ordering;
2use crate::hash::{Hash, Hasher};
3use crate::marker::{Destruct, StructuralPartialEq};
4use crate::mem::MaybeDangling;
5use crate::ops::{Deref, DerefMut, DerefPure};
6use crate::ptr;
7
8/// A wrapper to inhibit the compiler from automatically calling `T`’s
9/// destructor. This wrapper is 0-cost.
10///
11/// `ManuallyDrop<T>` is guaranteed to have the same layout and bit validity as
12/// `T`, and is subject to the same layout optimizations as `T`. As a
13/// consequence, it has *no effect* on the assumptions that the compiler makes
14/// about its contents. For example, initializing a `ManuallyDrop<&mut T>` with
15/// [`mem::zeroed`] is undefined behavior. If you need to handle uninitialized
16/// data, use [`MaybeUninit<T>`] instead.
17///
18/// Note that accessing the value inside a `ManuallyDrop<T>` is safe. This means
19/// that a `ManuallyDrop<T>` whose content has been dropped must not be exposed
20/// through a public safe API. Correspondingly, `ManuallyDrop::drop` is unsafe.
21///
22/// # `ManuallyDrop` and drop order
23///
24/// Rust has a well-defined [drop order] of values. To make sure that fields or
25/// locals are dropped in a specific order, reorder the declarations such that
26/// the implicit drop order is the correct one.
27///
28/// It is possible to use `ManuallyDrop` to control the drop order, but this
29/// requires unsafe code and is hard to do correctly in the presence of
30/// unwinding.
31///
32/// For example, if you want to make sure that a specific field is dropped after
33/// the others, make it the last field of a struct:
34///
35/// ```
36/// struct Context;
37///
38/// struct Widget {
39///     children: Vec<Widget>,
40///     // `context` will be dropped after `children`.
41///     // Rust guarantees that fields are dropped in the order of declaration.
42///     context: Context,
43/// }
44/// ```
45///
46/// # Safety hazards when storing `ManuallyDrop` in a struct or an enum.
47///
48/// Special care is needed when all of the conditions below are met:
49/// * A struct or enum contains a `ManuallyDrop`.
50/// * The `ManuallyDrop` is not inside a `union`.
51/// * The struct or enum is part of public API, or is stored in a struct or an
52///   enum that is part of public API.
53/// * There is a _safe_ function that drops the contents of the `ManuallyDrop`
54///   field, and it can be called outside the struct or enum's `Drop` implementation.
55///
56/// In particular, deriving `Debug`, `Clone`, `PartialEq`, `PartialOrd`, `Ord`,
57/// or `Hash` on the struct or enum could be unsound, since the derived
58/// implementations of these traits would access the `ManuallyDrop` field.
59///
60/// For example, in the following code, `derive(Debug)` is unsound in combination
61/// with the `ManuallyDrop::drop` call in `Foo::new`:
62///
63/// ```no_run
64/// # use std::mem::ManuallyDrop;
65/// #[derive(Debug)]
66/// pub struct Foo {
67///     /// Invariant: this value may have been dropped!
68///     value: ManuallyDrop<String>,
69/// }
70/// impl Foo {
71///     pub fn new() -> Self {
72///         let mut temp = Self {
73///             value: ManuallyDrop::new(String::from("Unsafe rust is hard."))
74///         };
75///         unsafe {
76///             // SAFETY: `value` hasn't been dropped yet.
77///             ManuallyDrop::drop(&mut temp.value);
78///         }
79///         temp
80///     }
81/// }
82/// ```
83///
84/// As one could use the `Debug` implementation to access an already dropped
85/// field:
86///
87/// ```rust,ignore (uses-type-from-separate-snippet)
88/// let foo = Foo::new();
89/// println!("{foo:?}"); // Undefined behavior!
90/// ```
91///
92/// Note that similar unsoundness can arise without `derive`. The cause of the
93/// unsoundness are public APIs which allow to access an already dropped value
94/// inside `ManuallyDrop`.
95///
96/// # Pre-`1.96` Interaction with `Box`
97///
98/// Before Rust `1.96.0`, if you had a `ManuallyDrop<T>`, where the type `T`
99/// was a `Box` or contained a `Box` inside, then dropping the `T` followed by
100/// moving the `ManuallyDrop<T>` was [considered to be undefined
101/// behavior](https://github.com/rust-lang/unsafe-code-guidelines/issues/245).
102/// That is, the following code caused undefined behavior:
103///
104/// ```no_run
105/// use std::mem::ManuallyDrop;
106///
107/// let mut x = ManuallyDrop::new(Box::new(42));
108/// unsafe {
109///     ManuallyDrop::drop(&mut x);
110/// }
111/// let y = x; // Undefined behavior! (pre 1.96.0)
112/// ```
113///
114/// Note that this could also have happen with a generic type where the user of
115/// the library providing it could substitute the generic for a `Box<_>` and
116/// then move the library type:
117///
118/// ```no_run
119/// use std::mem::ManuallyDrop;
120///
121/// pub struct BadOption<T> {
122///     // Invariant: Has been dropped if `is_some` is false.
123///     value: ManuallyDrop<T>,
124///     is_some: bool,
125/// }
126/// impl<T> BadOption<T> {
127///     pub fn new(value: T) -> Self {
128///         Self { value: ManuallyDrop::new(value), is_some: true }
129///     }
130///     pub fn change_to_none(&mut self) {
131///         if self.is_some {
132///             self.is_some = false;
133///             unsafe {
134///                 // SAFETY: `value` hasn't been dropped yet, as per the invariant
135///                 // (This is actually unsound pre rust 1.96.0!)
136///                 ManuallyDrop::drop(&mut self.value);
137///             }
138///         }
139///     }
140/// }
141///
142/// // In another crate:
143///
144/// let mut option = BadOption::new(Box::new(42));
145/// option.change_to_none();
146/// let option2 = option; // Undefined behavior! (pre 1.96)
147/// ```
148///
149/// [drop order]: https://doc.rust-lang.org/reference/destructors.html
150/// [`mem::zeroed`]: crate::mem::zeroed
151/// [`MaybeUninit<T>`]: crate::mem::MaybeUninit
152/// [`MaybeUninit`]: crate::mem::MaybeUninit
153#[stable(feature = "manually_drop", since = "1.20.0")]
154#[lang = "manually_drop"]
155#[derive(Copy, Clone, Debug, Default)]
156#[repr(transparent)]
157#[rustc_pub_transparent]
158#[ferrocene::prevalidated]
159pub struct ManuallyDrop<T: ?Sized> {
160    value: MaybeDangling<T>,
161}
162
163impl<T> ManuallyDrop<T> {
164    /// Wrap a value to be manually dropped.
165    ///
166    /// # Examples
167    ///
168    /// ```rust
169    /// use std::mem::ManuallyDrop;
170    /// let mut x = ManuallyDrop::new(String::from("Hello World!"));
171    /// x.truncate(5); // You can still safely operate on the value
172    /// assert_eq!(*x, "Hello");
173    /// // But `Drop` will not be run here
174    /// # // FIXME(https://github.com/rust-lang/miri/issues/3670):
175    /// # // use -Zmiri-disable-leak-check instead of unleaking in tests meant to leak.
176    /// # let _ = ManuallyDrop::into_inner(x);
177    /// ```
178    #[must_use = "if you don't need the wrapper, you can use `mem::forget` instead"]
179    #[stable(feature = "manually_drop", since = "1.20.0")]
180    #[rustc_const_stable(feature = "const_manually_drop", since = "1.32.0")]
181    #[inline(always)]
182    #[rustc_no_writable]
183    #[ferrocene::prevalidated]
184    pub const fn new(value: T) -> ManuallyDrop<T> {
185        ManuallyDrop { value: MaybeDangling::new(value) }
186    }
187
188    /// Extracts the value from the `ManuallyDrop` container.
189    ///
190    /// This allows the value to be dropped again.
191    ///
192    /// # Examples
193    ///
194    /// ```rust
195    /// use std::mem::ManuallyDrop;
196    /// let x = ManuallyDrop::new(Box::new(()));
197    /// let _: Box<()> = ManuallyDrop::into_inner(x); // This drops the `Box`.
198    /// ```
199    #[stable(feature = "manually_drop", since = "1.20.0")]
200    #[rustc_const_stable(feature = "const_manually_drop", since = "1.32.0")]
201    #[inline(always)]
202    #[ferrocene::prevalidated]
203    pub const fn into_inner(slot: ManuallyDrop<T>) -> T {
204        // Cannot use `MaybeDangling::into_inner` as that does not yet have the desired semantics.
205        // SAFETY: We know this is a valid `T`. `slot` will not be dropped.
206        unsafe { (&raw const slot).cast::<T>().read() }
207    }
208
209    /// Takes the value from the `ManuallyDrop<T>` container out.
210    ///
211    /// This method is primarily intended for moving out values in drop.
212    /// Instead of using [`ManuallyDrop::drop`] to manually drop the value,
213    /// you can use this method to take the value and use it however desired.
214    ///
215    /// Whenever possible, it is preferable to use [`into_inner`][`ManuallyDrop::into_inner`]
216    /// instead, which prevents duplicating the content of the `ManuallyDrop<T>`.
217    ///
218    /// # Safety
219    ///
220    /// This function semantically moves out the contained value without preventing further usage,
221    /// leaving the state of this container unchanged.
222    /// It is your responsibility to ensure that this `ManuallyDrop` is not used again.
223    ///
224    #[must_use = "if you don't need the value, you can use `ManuallyDrop::drop` instead"]
225    #[stable(feature = "manually_drop_take", since = "1.42.0")]
226    #[rustc_const_unstable(feature = "const_manually_drop_take", issue = "148773")]
227    #[inline]
228    #[ferrocene::prevalidated]
229    pub const unsafe fn take(slot: &mut ManuallyDrop<T>) -> T {
230        // SAFETY: we are reading from a reference, which is guaranteed
231        // to be valid for reads.
232        unsafe { ptr::read(slot.value.as_ref()) }
233    }
234}
235
236impl<T: ?Sized> ManuallyDrop<T> {
237    /// Manually drops the contained value.
238    ///
239    /// This is exactly equivalent to calling [`ptr::drop_in_place`] with a
240    /// pointer to the contained value. As such, unless the contained value is a
241    /// packed struct, the destructor will be called in-place without moving the
242    /// value, and thus can be used to safely drop [pinned] data.
243    ///
244    /// If you have ownership of the value, you can use [`ManuallyDrop::into_inner`] instead.
245    ///
246    /// # Safety
247    ///
248    /// This function runs the destructor of the contained value. Other than changes made by
249    /// the destructor itself, the memory is left unchanged, and so as far as the compiler is
250    /// concerned still holds a bit-pattern which is valid for the type `T`.
251    ///
252    /// However, this "zombie" value should not be exposed to safe code, and this function
253    /// should not be called more than once. To use a value after it's been dropped, or drop
254    /// a value multiple times, can cause Undefined Behavior (depending on what `drop` does).
255    /// This is normally prevented by the type system, but users of `ManuallyDrop` must
256    /// uphold those guarantees without assistance from the compiler.
257    ///
258    /// [pinned]: crate::pin
259    #[stable(feature = "manually_drop", since = "1.20.0")]
260    #[inline]
261    #[rustc_const_unstable(feature = "const_drop_in_place", issue = "109342")]
262    #[ferrocene::prevalidated]
263    pub const unsafe fn drop(slot: &mut ManuallyDrop<T>)
264    where
265        T: [const] Destruct,
266    {
267        // SAFETY: we are dropping the value pointed to by a mutable reference
268        // which is guaranteed to be valid for writes.
269        // It is up to the caller to make sure that `slot` isn't dropped again.
270        unsafe { ptr::drop_in_place(slot.value.as_mut()) }
271    }
272}
273
274#[stable(feature = "manually_drop", since = "1.20.0")]
275#[rustc_const_unstable(feature = "const_convert", issue = "143773")]
276const impl<T: ?Sized> Deref for ManuallyDrop<T> {
277    type Target = T;
278    #[inline(always)]
279    #[ferrocene::prevalidated]
280    fn deref(&self) -> &T {
281        self.value.as_ref()
282    }
283}
284
285#[stable(feature = "manually_drop", since = "1.20.0")]
286#[rustc_const_unstable(feature = "const_convert", issue = "143773")]
287const impl<T: ?Sized> DerefMut for ManuallyDrop<T> {
288    #[inline(always)]
289    #[ferrocene::prevalidated]
290    fn deref_mut(&mut self) -> &mut T {
291        self.value.as_mut()
292    }
293}
294
295#[unstable(feature = "deref_pure_trait", issue = "87121")]
296unsafe impl<T: ?Sized> DerefPure for ManuallyDrop<T> {}
297
298#[stable(feature = "manually_drop", since = "1.20.0")]
299impl<T: ?Sized + Eq> Eq for ManuallyDrop<T> {}
300
301#[stable(feature = "manually_drop", since = "1.20.0")]
302impl<T: ?Sized + PartialEq> PartialEq for ManuallyDrop<T> {
303    #[ferrocene::prevalidated]
304    fn eq(&self, other: &Self) -> bool {
305        self.value.as_ref().eq(other.value.as_ref())
306    }
307}
308
309#[stable(feature = "manually_drop", since = "1.20.0")]
310impl<T: ?Sized> StructuralPartialEq for ManuallyDrop<T> {}
311
312#[stable(feature = "manually_drop", since = "1.20.0")]
313impl<T: ?Sized + Ord> Ord for ManuallyDrop<T> {
314    fn cmp(&self, other: &Self) -> Ordering {
315        self.value.as_ref().cmp(other.value.as_ref())
316    }
317}
318
319#[stable(feature = "manually_drop", since = "1.20.0")]
320impl<T: ?Sized + PartialOrd> PartialOrd for ManuallyDrop<T> {
321    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
322        self.value.as_ref().partial_cmp(other.value.as_ref())
323    }
324}
325
326#[stable(feature = "manually_drop", since = "1.20.0")]
327impl<T: ?Sized + Hash> Hash for ManuallyDrop<T> {
328    fn hash<H: Hasher>(&self, state: &mut H) {
329        self.value.as_ref().hash(state);
330    }
331}
core/mem/manually_drop.rs

core/mem/
manually_drop.rs
