1.0.0[−][src]Function core::mem::forget
pub fn forget<T>(t: T)
Takes ownership and "forgets" about the value without running its destructor.
Any resources the value manages, such as heap memory or a file handle, will linger forever in an unreachable state. However, it does not guarantee that pointers to this memory will remain valid.
- If you want to leak memory, see
Box::leak. - If you want to obtain a raw pointer to the memory, see
Box::into_raw. - If you want to dispose of a value properly, running its destructor, see
mem::drop.
Safety
forget is not marked as unsafe, because Rust's safety guarantees
do not include a guarantee that destructors will always run. For example,
a program can create a reference cycle using Rc, or call
process::exit to exit without running destructors. Thus, allowing
mem::forget from safe code does not fundamentally change Rust's safety
guarantees.
That said, leaking resources such as memory or I/O objects is usually undesirable.
The need comes up in some specialized use cases for FFI or unsafe code, but even
then, ManuallyDrop is typically preferred.
Because forgetting a value is allowed, any unsafe code you write must
allow for this possibility. You cannot return a value and expect that the
caller will necessarily run the value's destructor.
Examples
Leak an I/O object, never closing the file:
use std::mem; use std::fs::File; let file = File::open("foo.txt").unwrap(); mem::forget(file);Run
The practical use cases for forget are rather specialized and mainly come
up in unsafe or FFI code. However, ManuallyDrop is usually preferred
for such cases, e.g.:
use std::mem::ManuallyDrop; let v = vec![65, 122]; // Before we disassemble `v` into its raw parts, make sure it // does not get dropped! let mut v = ManuallyDrop::new(v); // Now disassemble `v`. These operations cannot panic, so there cannot be a leak. let ptr = v.as_mut_ptr(); let cap = v.capacity(); // Finally, build a `String`. let s = unsafe { String::from_raw_parts(ptr, 2, cap) }; assert_eq!(s, "Az"); // `s` is implicitly dropped and its memory deallocated.Run
Using ManuallyDrop here has two advantages:
- We do not "touch"
vafter disassembling it. For some types, operations such as passing ownership (to a function likemem::forget) requires them to actually be fully owned right now; that is a promise we do not want to make here as we are in the process of transferring ownership to the newStringwe are building. - In case of an unexpected panic,
ManuallyDropis not dropped, but if the panic occurs beforemem::forgetwas called we might end up dropping invalid data, or double-dropping. In other words,ManuallyDroperrs on the side of leaking instead of erring on the side of dropping.