squiid/rust
1
0
Fork 0
Code Issues Pull requests Projects Activity

Unconfuse Unpin docs a bit

Browse source 
* Don't say that Unpin is used to prevent moves, because it is used
  to *allow* moves
* Be more precise about kindedness of things, it is
  `Pin<Pointer<Data>>`, rather than just `Pin<Pointer>`.
This commit is contained in:
Aleksey Kladov 2020-08-21 19:48:29 +02:00
parent b51651ae9d
commit daa6620c95
1 changed files with 14 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
library/core/src/marker.rs
View file

@ -728,23 +728,23 @@ unsafe impl<T: ?Sized> Freeze for &mut T {}
/// Types that can be safely moved after being pinned. /// Types that can be safely moved after being pinned.
/// ///
/// Since Rust itself has no notion of immovable types, and considers moves /// Rust itself has no notion of immovable types, and considers moves (e.g.,
/// (e.g., through assignment or [`mem::replace`]) to always be safe, /// through assignment or [`mem::replace`]) to always be safe.
/// this trait cannot prevent types from moving by itself.
/// ///
/// Instead it is used to prevent moves through the type system, /// The [`Pin`][Pin] type is used instead to prevent moves through the type
/// by controlling the behavior of pointers `P` wrapped in the [`Pin<P>`] wrapper, /// system. Pointers `P<T>` wrapped in the [`Pin<P<T>>`][Pin] wrapper can't be
/// which "pin" the type in place by not allowing it to be moved out of them. /// moved out of. See the [`pin module`] documentation for more information on
/// See the [`pin module`] documentation for more information on pinning. /// pinning.
/// ///
/// Implementing this trait lifts the restrictions of pinning off a type, /// Implementing the `Unpin` trait for `T` lifts the restrictions of pinning off
/// which then allows it to move out with functions such as [`mem::replace`]. /// the type, which then allows moving `T` out of [`Pin<P<T>>`][Pin] with
/// functions such as [`mem::replace`].
/// ///
/// `Unpin` has no consequence at all for non-pinned data. In particular, /// `Unpin` has no consequence at all for non-pinned data. In particular,
/// [`mem::replace`] happily moves `!Unpin` data (it works for any `&mut T`, not /// [`mem::replace`] happily moves `!Unpin` data (it works for any `&mut T`, not
/// just when `T: Unpin`). However, you cannot use /// just when `T: Unpin`). However, you cannot use [`mem::replace`] on data
/// [`mem::replace`] on data wrapped inside a [`Pin<P>`] because you cannot get the /// wrapped inside a [`Pin<P<T>>`][Pin] because you cannot get the `&mut T` you
/// `&mut T` you need for that, and *that* is what makes this system work. /// need for that, and *that* is what makes this system work.
/// ///
/// So this, for example, can only be done on types implementing `Unpin`: /// So this, for example, can only be done on types implementing `Unpin`:
/// ///
@ -765,8 +765,8 @@ unsafe impl<T: ?Sized> Freeze for &mut T {}
/// This trait is automatically implemented for almost every type. /// This trait is automatically implemented for almost every type.
/// ///
/// [`mem::replace`]: ../../std/mem/fn.replace.html /// [`mem::replace`]: ../../std/mem/fn.replace.html
/// [`Pin<P>`]: ../pin/struct.Pin.html /// [Pin]: crate::pin::Pin
/// [`pin module`]: ../../std/pin/index.html /// [`pin module`]: crate::pin
#[stable(feature = "pin", since = "1.33.0")] #[stable(feature = "pin", since = "1.33.0")]
#[rustc_on_unimplemented( #[rustc_on_unimplemented(
on(_Self = "std::future::Future", note = "consider using `Box::pin`",), on(_Self = "std::future::Future", note = "consider using `Box::pin`",),