Skip to content

Commit 2fe6415

Browse files
committed
justify motivation of Unpin better
1 parent 721b5fa commit 2fe6415

File tree

2 files changed

+30
-14
lines changed

2 files changed

+30
-14
lines changed

library/core/src/marker.rs

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -890,6 +890,13 @@ marker_impls! {
890890
/// to the pointee value like it normally would, thus allowing the user to do anything that they
891891
/// normally could with a non-[`Pin`]-wrapped `Ptr` to that value.
892892
///
893+
/// The idea of this trait is to alleviate the reduced ergonomics of APIs that require the use
894+
/// of [`Pin`] for soundness for some types, but which also want to be used by other types that
895+
/// don't care about pinning. The prime example of such an API is [`Future::poll`]. There are many
896+
/// [`Future`] types that don't care about pinning. These futures can implement `Unpin` and
897+
/// therefore get around the pinning related restrictions in the API, while still allowing the
898+
/// subset of [`Future`]s which *do* require pinning to be implemented soundly.
899+
///
893900
/// For more discussion on the consequences of [`Unpin`] within the wider scope of the pinning
894901
/// system, see [the section about `Unpin`] in the [`pin` module].
895902
///
@@ -927,6 +934,8 @@ marker_impls! {
927934
/// by adding [`PhantomPinned`] field. For more details, see the [`pin` module] docs.
928935
///
929936
/// [`mem::replace`]: crate::mem::replace "mem replace"
937+
/// [`Future`]: crate::future::Future "Future"
938+
/// [`Future::poll`]: crate::future::Future::poll "Future poll"
930939
/// [`Pin`]: crate::pin::Pin "Pin"
931940
/// [`Pin<Ptr>`]: crate::pin::Pin "Pin"
932941
/// [`pin` module]: crate::pin "pin module"

library/core/src/pin.rs

Lines changed: 21 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -349,7 +349,15 @@
349349
//! implement the [`Unpin`] auto-trait, which cancels the restrictive effects of
350350
//! [`Pin`] when the *pointee* type `T` is [`Unpin`]. When [`T: Unpin`][Unpin],
351351
//! <code>[Pin]<[Box]\<T>></code> functions identically to a non-pinning [`Box<T>`]; similarly,
352-
//! <code>[Pin]<[&mut] T></code> would impose no additional restrictions above a regular [`&mut T`].
352+
//! <code>[Pin]<[&mut] T></code> would impose no additional restrictions above a regular
353+
//! [`&mut T`].
354+
//!
355+
//! The idea of this trait is to alleviate the reduced ergonomics of APIs that require the use
356+
//! of [`Pin`] for soundness for some types, but which also want to be used by other types that
357+
//! don't care about pinning. The prime example of such an API is [`Future::poll`]. There are many
358+
//! [`Future`] types that don't care about pinning. These futures can implement [`Unpin`] and
359+
//! therefore get around the pinning related restrictions in the API, while still allowing the
360+
//! subset of [`Future`]s which *do* require pinning to be implemented soundly.
353361
//!
354362
//! Note that the interaction between a [`Pin<Ptr>`] and [`Unpin`] is through the type of the
355363
//! **pointee** value, [`<Ptr as Deref>::Target`][Target]. Whether the `Ptr` type itself
@@ -946,15 +954,14 @@ use crate::{
946954
///
947955
/// In order to pin a value, we wrap a *pointer to that value* (of some type `Ptr`) in a
948956
/// [`Pin<Ptr>`]. [`Pin<Ptr>`] can wrap any pointer type, forming a promise that the **pointee**
949-
/// will not be *moved* or [otherwise invalidated][subtle-details]. Note that it is
950-
/// impossible to create or misuse a [`Pin<Ptr>`] to violate this promise without using [`unsafe`].
951-
/// If the pointee value's type implements [`Unpin`], we are free to disregard these requirements
952-
/// entirely and can wrap any pointer to that value in [`Pin`] directly via [`Pin::new`].
953-
/// If the pointee value's type does not implement [`Unpin`], then Rust will not let us use the
954-
/// [`Pin::new`] function directly and we'll need to construct a [`Pin`]-wrapped pointer in one of
955-
/// the more specialized manners discussed below.
957+
/// will not be *moved* or [otherwise invalidated][subtle-details]. If the pointee value's type
958+
/// implements [`Unpin`], we are free to disregard these requirements entirely and can wrap any
959+
/// pointer to that value in [`Pin`] directly via [`Pin::new`]. If the pointee value's type does
960+
/// not implement [`Unpin`], then Rust will not let us use the [`Pin::new`] function directly and
961+
/// we'll need to construct a [`Pin`]-wrapped pointer in one of the more specialized manners
962+
/// discussed below.
956963
///
957-
/// We call such a [`Pin`]-wrapped pointer a **pinning pointer,** (or pinning ref, or pinning
964+
/// We call such a [`Pin`]-wrapped pointer a **pinning pointer** (or pinning ref, or pinning
958965
/// [`Box`], etc.) because its existince is the thing that is pinning the underlying pointee in
959966
/// place: it is the metaphorical "pin" securing the data in place on the pinboard (in memory).
960967
///
@@ -963,18 +970,18 @@ use crate::{
963970
/// the pointer's ***pointee** value*.
964971
///
965972
/// The most common set of types which require pinning related guarantees for soundness are the
966-
/// state machines that implement [`Future`] for the return value of `async fn`s under the
967-
/// hood. These compiler-generated [`Future`]s may contain self-referrential pointers, one of the
968-
/// most common use cases for [`Pin`]. More details on this point are provided in the
973+
/// compiler-generated state machines that implement [`Future`] for the return value of
974+
/// `async fn`s. These compiler-generated [`Future`]s may contain self-referrential pointers, one
975+
/// of the most common use cases for [`Pin`]. More details on this point are provided in the
969976
/// [`pin` module] docs, but suffice it to say they require the guarantees provided by pinning to
970977
/// be implemented soundly.
971978
///
972-
/// This requirement from the implementation of `async fn`s means that the [`Future`] trait
979+
/// This requirement for the implementation of `async fn`s means that the [`Future`] trait
973980
/// requires all calls to [`poll`] to use a <code>self: [Pin]\<&mut Self></code> parameter instead
974981
/// of the usual `&mut self`. Therefore, when manually polling a future, you will need to pin it
975982
/// first.
976983
///
977-
/// You may notice that `async fn`-generated [`Future`]s are only a small percentage of all
984+
/// You may notice that `async fn`-sourced [`Future`]s are only a small percentage of all
978985
/// [`Future`]s that exist, yet we had to modify the signature of [`poll`] for all [`Future`]s
979986
/// to accommodate them. This is unfortunate, but there is a way that the language attempts to
980987
/// alleviate the extra friction that this API choice incurs: the [`Unpin`] trait.

0 commit comments

Comments
 (0)