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.
18 /// # `ManuallyDrop` and drop order.
20 /// Rust has a well-defined [drop order] of values. To make sure that fields or
21 /// locals are dropped in a specific order, reorder the declarations such that
22 /// the implicit drop order is the correct one.
24 /// It is possible to use `ManuallyDrop` to control the drop order, but this
25 /// requires unsafe code and is hard to do correctly in the presence of
28 /// For example, if you want to make sure that a specific field is dropped after
29 /// the others, make it the last field of a struct:
35 /// children: Vec<Widget>,
36 /// // `context` will be dropped after `children`.
37 /// // Rust guarantees that fields are dropped in the order of declaration.
42 /// [drop order]: https://doc.rust-lang.org/reference/destructors.html
43 /// [`mem::zeroed`]: crate::mem::zeroed
44 /// [`MaybeUninit<T>`]: crate::mem::MaybeUninit
45 #[stable(feature = "manually_drop", since = "1.20.0")]
46 #[lang = "manually_drop"]
47 #[derive(Copy, Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
49 pub struct ManuallyDrop<T: ?Sized> {
53 impl<T> ManuallyDrop<T> {
54 /// Wrap a value to be manually dropped.
59 /// use std::mem::ManuallyDrop;
60 /// let mut x = ManuallyDrop::new(String::from("Hello World!"));
61 /// x.truncate(5); // You can still safely operate on the value
62 /// assert_eq!(*x, "Hello");
63 /// // But `Drop` will not be run here
65 #[must_use = "if you don't need the wrapper, you can use `mem::forget` instead"]
66 #[stable(feature = "manually_drop", since = "1.20.0")]
67 #[rustc_const_stable(feature = "const_manually_drop", since = "1.32.0")]
69 pub const fn new(value: T) -> ManuallyDrop<T> {
70 ManuallyDrop { value }
73 /// Extracts the value from the `ManuallyDrop` container.
75 /// This allows the value to be dropped again.
80 /// use std::mem::ManuallyDrop;
81 /// let x = ManuallyDrop::new(Box::new(()));
82 /// let _: Box<()> = ManuallyDrop::into_inner(x); // This drops the `Box`.
84 #[stable(feature = "manually_drop", since = "1.20.0")]
85 #[rustc_const_stable(feature = "const_manually_drop", since = "1.32.0")]
87 pub const fn into_inner(slot: ManuallyDrop<T>) -> T {
91 /// Takes the value from the `ManuallyDrop<T>` container out.
93 /// This method is primarily intended for moving out values in drop.
94 /// Instead of using [`ManuallyDrop::drop`] to manually drop the value,
95 /// you can use this method to take the value and use it however desired.
97 /// Whenever possible, it is preferable to use [`into_inner`][`ManuallyDrop::into_inner`]
98 /// instead, which prevents duplicating the content of the `ManuallyDrop<T>`.
102 /// This function semantically moves out the contained value without preventing further usage,
103 /// leaving the state of this container unchanged.
104 /// It is your responsibility to ensure that this `ManuallyDrop` is not used again.
106 #[must_use = "if you don't need the value, you can use `ManuallyDrop::drop` instead"]
107 #[stable(feature = "manually_drop_take", since = "1.42.0")]
109 pub unsafe fn take(slot: &mut ManuallyDrop<T>) -> T {
110 // SAFETY: we are reading from a reference, which is guaranteed
111 // to be valid for reads.
112 unsafe { ptr::read(&slot.value) }
116 impl<T: ?Sized> ManuallyDrop<T> {
117 /// Manually drops the contained value. This is exactly equivalent to calling
118 /// [`ptr::drop_in_place`] with a pointer to the contained value. As such, unless
119 /// the contained value is a packed struct, the destructor will be called in-place
120 /// without moving the value, and thus can be used to safely drop [pinned] data.
122 /// If you have ownership of the value, you can use [`ManuallyDrop::into_inner`] instead.
126 /// This function runs the destructor of the contained value. Other than changes made by
127 /// the destructor itself, the memory is left unchanged, and so as far as the compiler is
128 /// concerned still holds a bit-pattern which is valid for the type `T`.
130 /// However, this "zombie" value should not be exposed to safe code, and this function
131 /// should not be called more than once. To use a value after it's been dropped, or drop
132 /// a value multiple times, can cause Undefined Behavior (depending on what `drop` does).
133 /// This is normally prevented by the type system, but users of `ManuallyDrop` must
134 /// uphold those guarantees without assistance from the compiler.
136 /// [pinned]: crate::pin
137 #[stable(feature = "manually_drop", since = "1.20.0")]
139 pub unsafe fn drop(slot: &mut ManuallyDrop<T>) {
140 // SAFETY: we are dropping the value pointed to by a mutable reference
141 // which is guaranteed to be valid for writes.
142 // It is up to the caller to make sure that `slot` isn't dropped again.
143 unsafe { ptr::drop_in_place(&mut slot.value) }
147 #[stable(feature = "manually_drop", since = "1.20.0")]
148 #[rustc_const_unstable(feature = "const_deref", issue = "88955")]
149 impl<T: ?Sized> const Deref for ManuallyDrop<T> {
152 fn deref(&self) -> &T {
157 #[stable(feature = "manually_drop", since = "1.20.0")]
158 #[rustc_const_unstable(feature = "const_deref", issue = "88955")]
159 impl<T: ?Sized> const DerefMut for ManuallyDrop<T> {
161 fn deref_mut(&mut self) -> &mut T {