From c52560d788e69677826964f9f25f28687ef5c70c Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Wed, 20 Feb 2019 09:45:28 +0100 Subject: [PATCH] tweaks --- src/libcore/pin.rs | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/src/libcore/pin.rs b/src/libcore/pin.rs index 2395dce9693..6d3c3af17f5 100644 --- a/src/libcore/pin.rs +++ b/src/libcore/pin.rs @@ -16,7 +16,7 @@ //! [`Pin`] wraps a pointer type, so `Pin>` functions much like a regular `Box` //! (when a `Pin>` gets dropped, so do its contents, and the memory gets deallocated). //! Similarily, `Pin<&mut T>` is a lot like `&mut T`. However, [`Pin`] does not let clients actually -//! obtain a `Box` or reference to pinned data, which implies that you cannot use +//! obtain a `Box` or `&mut T` to pinned data, which implies that you cannot use //! operations such as [`mem::swap`]: //! ``` //! use std::pin::Pin; @@ -29,9 +29,10 @@ //! ``` //! //! It is worth reiterating that [`Pin`] does *not* change the fact that a Rust compiler -//! considers all types movable. [`mem::swap`] remains callable for any `T`. Instead, `Pin` +//! considers all types movable. [`mem::swap`] remains callable for any `T`. Instead, `Pin` //! prevents certain *values* (pointed to by pointers wrapped in `Pin`) from being -//! moved by making it impossible to call methods like [`mem::swap`] on them. +//! moved by making it impossible to call methods that require `&mut T` on them +//! (like [`mem::swap`]). //! //! [`Pin`] can be used to wrap any pointer type, and as such it interacts with //! [`Deref`] and [`DerefMut`]. A `Pin

` where `P: Deref` should be considered @@ -221,7 +222,7 @@ //! reference we got later. //! //! On the other hand, if you decide *not* to offer any pinning projections, you -//! are free to `impl Unpin for Container`. In the standard library, +//! are free to `impl Unpin for Container`. In the standard library, //! this is done for all pointer types: `Box: Unpin` holds for all `T`. //! It makes sense to do this for pointer types, because moving the `Box` //! does not actually move the `T`: the `Box` can be freely movable even if the `T` @@ -341,7 +342,7 @@ impl Pin

{ /// pointed to by `pointer` is pinned, meaning that the data will not be moved or /// its storage invalidated until it gets dropped. If the constructed `Pin

` does /// not guarantee that the data `P` points to is pinned, constructing a - /// `Pin

` is unsafe. In particular, + /// `Pin

` is unsafe. /// /// By using this method, you are making a promise about the `P::Deref` and /// `P::DerefMut` implementations, if they exist. Most importantly, they @@ -353,9 +354,9 @@ impl Pin

{ /// must not be possible to obtain a `&mut P::Target` and then /// move out of that reference (using, for example [`mem::swap`]). /// - /// For example, calling `Pin::new_unchecked` - /// on an `&'a mut T` is unsafe because while you are able to pin it for the given - /// lifetime `'a`, you have no control over whether it is kept pinned once `'a` ends: + /// For example, calling `Pin::new_unchecked` on an `&'a mut T` is unsafe because + /// while you are able to pin it for the given lifetime `'a`, you have no control + /// over whether it is kept pinned once `'a` ends: /// ``` /// use std::mem; /// use std::pin::Pin; @@ -395,10 +396,10 @@ pub unsafe fn new_unchecked(pointer: P) -> Pin

{ /// Gets a pinned shared reference from this pinned pointer. /// - /// This is a generic method to go from `&Pin>` to `Pin<&T>`. + /// This is a generic method to go from `&Pin>` to `Pin<&T>`. /// It is safe because, as part of the contract of `Pin::new_unchecked`, - /// the pointee cannot move after `Pin>` got created. - /// "Malicious" implementations of `SmartPointer::Deref` are likewise + /// the pointee cannot move after `Pin>` got created. + /// "Malicious" implementations of `Pointer::Deref` are likewise /// ruled out by the contract of `Pin::new_unchecked`. #[stable(feature = "pin", since = "1.33.0")] #[inline(always)] @@ -410,10 +411,10 @@ pub fn as_ref(self: &Pin

) -> Pin<&P::Target> { impl Pin

{ /// Gets a pinned mutable reference from this pinned pointer. /// - /// This is a generic method to go from `&mut Pin>` to `Pin<&mut T>`. + /// This is a generic method to go from `&mut Pin>` to `Pin<&mut T>`. /// It is safe because, as part of the contract of `Pin::new_unchecked`, - /// the pointee cannot move after `Pin>` got created. - /// "Malicious" implementations of `SmartPointer::DerefMut` are likewise + /// the pointee cannot move after `Pin>` got created. + /// "Malicious" implementations of `Pointer::DerefMut` are likewise /// ruled out by the contract of `Pin::new_unchecked`. #[stable(feature = "pin", since = "1.33.0")] #[inline(always)] -- 2.44.0