349
349
//! implement the [`Unpin`] auto-trait, which cancels the restrictive effects of
350
350
//! [`Pin`] when the *pointee* type `T` is [`Unpin`]. When [`T: Unpin`][Unpin],
351
351
//! <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.
353
361
//!
354
362
//! Note that the interaction between a [`Pin<Ptr>`] and [`Unpin`] is through the type of the
355
363
//! **pointee** value, [`<Ptr as Deref>::Target`][Target]. Whether the `Ptr` type itself
@@ -946,15 +954,14 @@ use crate::{
946
954
///
947
955
/// In order to pin a value, we wrap a *pointer to that value* (of some type `Ptr`) in a
948
956
/// [`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.
956
963
///
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
958
965
/// [`Box`], etc.) because its existince is the thing that is pinning the underlying pointee in
959
966
/// place: it is the metaphorical "pin" securing the data in place on the pinboard (in memory).
960
967
///
@@ -963,18 +970,18 @@ use crate::{
963
970
/// the pointer's ***pointee** value*.
964
971
///
965
972
/// 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
969
976
/// [`pin` module] docs, but suffice it to say they require the guarantees provided by pinning to
970
977
/// be implemented soundly.
971
978
///
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
973
980
/// requires all calls to [`poll`] to use a <code>self: [Pin]\<&mut Self></code> parameter instead
974
981
/// of the usual `&mut self`. Therefore, when manually polling a future, you will need to pin it
975
982
/// first.
976
983
///
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
978
985
/// [`Future`]s that exist, yet we had to modify the signature of [`poll`] for all [`Future`]s
979
986
/// to accommodate them. This is unfortunate, but there is a way that the language attempts to
980
987
/// alleviate the extra friction that this API choice incurs: the [`Unpin`] trait.
0 commit comments