/// `mem::drop` function in that it **does not run the destructor**, leaking the
/// value and any resources that it owns.
///
+/// There's only a few reasons to use this function. They mainly come
+/// up in unsafe code or FFI code.
+///
+/// * You have an uninitialized value, perhaps for performance reasons, and
+/// need to prevent the destructor from running on it.
+/// * You have two copies of a value (like when writing something like
+/// [`mem::swap`][swap]), but need the destructor to only run once to
+/// prevent a double `free`.
+/// * Transferring resources across [FFI][ffi] boundries.
+///
+/// [swap]: fn.swap.html
+/// [ffi]: ../../book/ffi.html
+///
/// # Safety
///
/// This function is not marked as `unsafe` as Rust does not guarantee that the
/// * `mpsc::{Sender, Receiver}` cycles (they use `Arc` internally)
/// * Panicking destructors are likely to leak local resources
///
-/// # When To Use
-///
-/// There's only a few reasons to use this function. They mainly come
-/// up in unsafe code or FFI code.
-///
-/// * You have an uninitialized value, perhaps for performance reasons, and
-/// need to prevent the destructor from running on it.
-/// * You have two copies of a value (like `std::mem::swap`), but need the
-/// destructor to only run once to prevent a double free.
-/// * Transferring resources across FFI boundries.
-///
/// # Example
///
-/// Leak some heap memory by never deallocating it.
+/// Leak some heap memory by never deallocating it:
///
/// ```rust
/// use std::mem;
/// mem::forget(heap_memory);
/// ```
///
-/// Leak an I/O object, never closing the file.
+/// Leak an I/O object, never closing the file:
///
/// ```rust,no_run
/// use std::mem;
/// mem::forget(file);
/// ```
///
-/// The swap function uses forget to good effect.
+/// The `mem::swap` function uses `mem::forget` to good effect:
///
/// ```rust
/// use std::mem;
/// This function is expected to be deprecated with the transition
/// to non-zeroing drop.
#[inline]
-#[unstable(feature = "filling_drop")]
+#[unstable(feature = "filling_drop", issue = "5016")]
pub unsafe fn dropped<T>() -> T {
#[inline(always)]
unsafe fn dropped_impl<T>() -> T { intrinsics::init_dropped() }
/// println!("{:?}", &data[0]);
/// ```
///
-/// Hopefully this example emphasizes to you exactly how delicate
-/// and dangerous doing this is. Note that the `vec!` macro
-/// *does* let you initialize every element with a value that
-/// is only `Clone`, so the following is equivalent and vastly
-/// less dangerous, as long as you can live with an extra heap
+/// This example emphasizes exactly how delicate and dangerous doing this is.
+/// Note that the `vec!` macro *does* let you initialize every element with a
+/// value that is only `Clone`, so the following is semantically equivalent and
+/// vastly less dangerous, as long as you can live with an extra heap
/// allocation:
///
/// ```
/// let data: Vec<Vec<u32>> = vec![Vec::new(); 1000];
/// println!("{:?}", &data[0]);
/// ```
-///
-/// For large arrays this is probably advisable
-/// anyway to avoid blowing the stack.
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub unsafe fn uninitialized<T>() -> T {
/// While this does call the argument's implementation of `Drop`, it will not
/// release any borrows, as borrows are based on lexical scope.
///
+/// This effectively does nothing for
+/// [types which implement `Copy`](../../book/ownership.html#copy-types),
+/// e.g. integers. Such values are copied and _then_ moved into the function,
+/// so the value persists after this function call.
+///
/// # Examples
///
/// Basic usage:
/// let borrow = x.borrow();
/// println!("{}", *borrow);
/// ```
+///
+/// Integers and other types implementing `Copy` are unaffected by `drop()`
+///
+/// ```
+/// #[derive(Copy, Clone)]
+/// struct Foo(u8);
+///
+/// let x = 1;
+/// let y = Foo(2);
+/// drop(x); // a copy of `x` is moved and dropped
+/// drop(y); // a copy of `y` is moved and dropped
+///
+/// println!("x: {}, y: {}", x, y.0); // still available
+/// ```
+///
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn drop<T>(_x: T) { }
// But having the sign bit set is a pain, so 0x1d is probably better.
//
// And of course, 0x00 brings back the old world of zero'ing on drop.
-#[unstable(feature = "filling_drop")]
+#[unstable(feature = "filling_drop", issue = "5016")]
#[allow(missing_docs)]
pub const POST_DROP_U8: u8 = 0x1d;
-#[unstable(feature = "filling_drop")]
+#[unstable(feature = "filling_drop", issue = "5016")]
#[allow(missing_docs)]
pub const POST_DROP_U32: u32 = repeat_u8_as_u32!(POST_DROP_U8);
-#[unstable(feature = "filling_drop")]
+#[unstable(feature = "filling_drop", issue = "5016")]
#[allow(missing_docs)]
pub const POST_DROP_U64: u64 = repeat_u8_as_u64!(POST_DROP_U8);
#[cfg(target_pointer_width = "32")]
-#[unstable(feature = "filling_drop")]
+#[unstable(feature = "filling_drop", issue = "5016")]
#[allow(missing_docs)]
pub const POST_DROP_USIZE: usize = POST_DROP_U32 as usize;
#[cfg(target_pointer_width = "64")]
-#[unstable(feature = "filling_drop")]
+#[unstable(feature = "filling_drop", issue = "5016")]
#[allow(missing_docs)]
pub const POST_DROP_USIZE: usize = POST_DROP_U64 as usize;
#![allow(trivial_casts)]
ptr::read(src as *const T as *const U)
}
-
-/// Transforms lifetime of the second pointer to match the first.
-#[inline]
-#[unstable(feature = "copy_lifetime",
- reason = "this function may be removed in the future due to its \
- questionable utility")]
-#[deprecated(since = "1.2.0",
- reason = "unclear that this function buys more safety and \
- lifetimes are generally not handled as such in unsafe \
- code today")]
-pub unsafe fn copy_lifetime<'a, S: ?Sized, T: ?Sized + 'a>(_ptr: &'a S,
- ptr: &T) -> &'a T {
- transmute(ptr)
-}
-
-/// Transforms lifetime of the second mutable pointer to match the first.
-#[inline]
-#[unstable(feature = "copy_lifetime",
- reason = "this function may be removed in the future due to its \
- questionable utility")]
-#[deprecated(since = "1.2.0",
- reason = "unclear that this function buys more safety and \
- lifetimes are generally not handled as such in unsafe \
- code today")]
-pub unsafe fn copy_mut_lifetime<'a, S: ?Sized, T: ?Sized + 'a>(_ptr: &'a S,
- ptr: &mut T)
- -> &'a mut T
-{
- transmute(ptr)
-}
projects / rust.git / blobdiff