diff options
| -rw-r--r-- | src/libcore/marker.rs | 28 |
1 files changed, 24 insertions, 4 deletions
diff --git a/src/libcore/marker.rs b/src/libcore/marker.rs index d18e167fc3f..e73d998fde8 100644 --- a/src/libcore/marker.rs +++ b/src/libcore/marker.rs @@ -603,15 +603,35 @@ unsafe impl<T: ?Sized> Freeze for *mut T {} unsafe impl<'a, T: ?Sized> Freeze for &'a T {} unsafe impl<'a, T: ?Sized> Freeze for &'a mut T {} -/// Types which can be moved out of a `PinMut`. +/// Types which can be safely moved after being pinned. /// -/// The `Unpin` trait is used to control the behavior of the [`PinMut`] type. If a -/// type implements `Unpin`, it is safe to move a value of that type out of the -/// `PinMut` pointer. +/// Since Rust itself has no notion of immovable types, and will consider moves to always be safe, +/// this trait cannot prevent types from moving by itself. +/// +/// Instead it can be used to prevent moves through the type system, +/// by controlling the behavior of special pointer types like [`PinMut`], +/// which "pin" the type in place by not allowing it to be moved out of them. +/// +/// Implementing this trait lifts the restrictions of pinning off a type, +/// which then allows it to move out with functions such as [`replace`]. +/// +/// So this, for example, can only be done on types implementing `Unpin`: +/// +/// ```rust +/// #![feature(pin)] +/// use std::mem::{PinMut, replace}; +/// +/// let mut string = "this".to_string(); +/// let mut pinned_string = PinMut::new(&mut string); +/// +/// // dereferencing the pointer mutably is only possible because String implements Unpin +/// replace(&mut *pinned_string, "other".to_string()); +/// ``` /// /// This trait is automatically implemented for almost every type. /// /// [`PinMut`]: ../mem/struct.PinMut.html +/// [`replace`]: ../mem/fn.replace.html #[unstable(feature = "pin", issue = "49150")] pub auto trait Unpin {} |