1.0.0[−][src]Function std::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,
so forget is only recommended for specialized use cases like those shown below.
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.
Use case 1
You have created an uninitialized value using mem::uninitialized.
You must either initialize or forget it on every computation path before
Rust drops it automatically, like at the end of a scope or after a panic.
Running the destructor on an uninitialized value would be undefined behavior.
use std::mem; use std::ptr; unsafe { let mut uninit_vec: Vec<u32> = mem::uninitialized(); if some_condition { // Initialize the variable. ptr::write(&mut uninit_vec, Vec::new()); } else { // Forget the uninitialized value so its destructor doesn't run. mem::forget(uninit_vec); } }Run
Use case 2
You have duplicated the bytes making up a value, without doing a proper
Clone. You need the value's destructor to run only once,
because a double free is undefined behavior.
An example is a possible implementation of mem::swap:
use std::mem; use std::ptr; fn swap<T>(x: &mut T, y: &mut T) { unsafe { // Give ourselves some scratch space to work with let mut t: T = mem::uninitialized(); // Perform the swap, `&mut` pointers never alias ptr::copy_nonoverlapping(&*x, &mut t, 1); ptr::copy_nonoverlapping(&*y, x, 1); ptr::copy_nonoverlapping(&t, y, 1); // y and t now point to the same thing, but we need to completely // forget `t` because we do not want to run the destructor for `T` // on its value, which is still owned somewhere outside this function. mem::forget(t); } }Run