Skip to content

Commit db5b19e

Browse files
fu5haManishearth
authored andcommittedJan 7, 2024
improve intro and Unpin-related discussion
·
1.88.01.77.0
1 parent 46f9d77 commit db5b19e

File tree

2 files changed

+145
-67
lines changed

2 files changed

+145
-67
lines changed
 

‎library/core/src/marker.rs

Lines changed: 32 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -899,25 +899,28 @@ marker_impls! {
899899
{T: ?Sized} &mut T,
900900
}
901901

902-
/// Types that can be safely moved after being pinned.
902+
/// Types that do not need to follow the rules of pinning.
903903
///
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.
906905
///
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.
911912
///
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].
915915
///
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.
921924
///
922925
/// So this, for example, can only be done on types implementing `Unpin`:
923926
///
@@ -935,11 +938,20 @@ marker_impls! {
935938
/// mem::replace(&mut *pinned_string, "other".to_string());
936939
/// ```
937940
///
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"
943955
#[stable(feature = "pin", since = "1.33.0")]
944956
#[diagnostic::on_unimplemented(
945957
note = "consider using the `pin!` macro\nconsider using `Box::pin` if you need to access the pinned value outside of the current scope",

0 commit comments

Comments
 (0)
Please sign in to comment.