@@ -899,25 +899,28 @@ marker_impls! {
899
899
{ T : ?Sized } & mut T ,
900
900
}
901
901
902
- /// Types that can be safely moved after being pinned .
902
+ /// Types that do not need to follow the rules of pinning .
903
903
///
904
- /// Rust itself has no notion of immovable types, and considers moves (e.g.,
905
- /// through assignment or [`mem::replace`]) to always be safe.
904
+ /// For information on what "pinning" is, see the [`pin` module] documentation.
906
905
///
907
- /// The [`Pin`][Pin] type is used instead to prevent moves through the type
908
- /// system. Pointers `P<T>` wrapped in the [`Pin<P<T>>`][Pin] wrapper can't be
909
- /// moved out of. See the [`pin` module] documentation for more information on
910
- /// pinning.
906
+ /// Implementing the `Unpin` trait for `T` lifts the restrictions of pinning off that type.
907
+ /// This means that, if `T: Unpin`, it cannot be assumed that a value of type `T` will be bound
908
+ /// by the invariants that pinning infers, *even* when "pinned" by a [`Pin<Ptr>`] pointing at it.
909
+ /// When a value of type `T` is pointed at by a [`Pin<Ptr>`], [`Pin`] will not restrict access
910
+ /// to the pointee value like it normally would, thus allowing the user to do anything that they
911
+ /// normally could with a non-[`Pin`]-wrapped `Ptr` to that value.
911
912
///
912
- /// Implementing the `Unpin` trait for `T` lifts the restrictions of pinning off
913
- /// the type, which then allows moving `T` out of [`Pin<P<T>>`][Pin] with
914
- /// functions such as [`mem::replace`].
913
+ /// For more discussion on the consequences of [`Unpin`] within the wider scope of the pinning
914
+ /// system, see [the section about `Unpin`] in the [`pin` module].
915
915
///
916
- /// `Unpin` has no consequence at all for non-pinned data. In particular,
917
- /// [`mem::replace`] happily moves `!Unpin` data (it works for any `&mut T`, not
918
- /// just when `T: Unpin`). However, you cannot use [`mem::replace`] on data
919
- /// wrapped inside a [`Pin<P<T>>`][Pin] because you cannot get the `&mut T` you
920
- /// need for that, and *that* is what makes this system work.
916
+ /// `Unpin` has no consequence at all for non-pinned data. In particular, [`mem::replace`] happily
917
+ /// moves `!Unpin` data, which would be immovable when pinned ([`mem::replace`] works for any
918
+ /// `&mut T`, not just when `T: Unpin`).
919
+ ///
920
+ /// *However*, you cannot use [`mem::replace`] on `!Unpin` data which is *pinned* by being wrapped
921
+ /// inside a [`Pin<Ptr>`] pointing at it. This is because you cannot (safely) use a
922
+ /// [`Pin<Ptr>`] to get an `&mut T` to its pointee value, which you would need to call
923
+ /// [`mem::replace`], and *that* is what makes this system work.
921
924
///
922
925
/// So this, for example, can only be done on types implementing `Unpin`:
923
926
///
@@ -935,11 +938,20 @@ marker_impls! {
935
938
/// mem::replace(&mut *pinned_string, "other".to_string());
936
939
/// ```
937
940
///
938
- /// This trait is automatically implemented for almost every type.
939
- ///
940
- /// [`mem::replace`]: crate::mem::replace
941
- /// [Pin]: crate::pin::Pin
942
- /// [`pin` module]: crate::pin
941
+ /// This trait is automatically implemented for almost every type. The compiler (and you!) is free
942
+ /// to take the conservative stance of marking types as [`Unpin`] by default. This is because if a
943
+ /// type implements [`Unpin`], then it is unsound for [`unsafe`] code to assume that type is truly
944
+ /// pinned, *even* when viewed through a "pinning" pointer! It is the responsibility of the
945
+ /// implementor of [`unsafe`] code that relies upon pinning for soundness to ensure that all the
946
+ /// types it expects to be truly pinned do not implement [`Unpin`]. For more details, see the
947
+ /// [`pin` module] docs!
948
+ ///
949
+ /// [`mem::replace`]: crate::mem::replace "mem replace"
950
+ /// [`Pin`]: crate::pin::Pin "Pin"
951
+ /// [`Pin<Ptr>`]: crate::pin::Pin "Pin"
952
+ /// [`pin` module]: crate::pin "pin module"
953
+ /// [section about `Unpin`]: crate::pin#unpin "pin module docs about unpin"
954
+ /// [`unsafe`]: ../../std/keyword.unsafe.html "keyword unsafe"
943
955
#[ stable( feature = "pin" , since = "1.33.0" ) ]
944
956
#[ diagnostic:: on_unimplemented(
945
957
note = "consider using the `pin!` macro\n consider using `Box::pin` if you need to access the pinned value outside of the current scope" ,
0 commit comments