diff --git a/library/core/src/pin.rs b/library/core/src/pin.rs index 18113c6def8..3af02343307 100644 --- a/library/core/src/pin.rs +++ b/library/core/src/pin.rs @@ -126,7 +126,7 @@ //! for such a type to be implemented soundly, the pointer which points into `self`'s data must be //! proven valid whenever it is accessed. But if that value is *moved*, the pointer will still //! point to the old address where the value was located and not into the new location of `self`, -//! thus becoming invalid. A key example of such self-referrential types are the state machines +//! thus becoming invalid. A key example of such self-referential types are the state machines //! generated by the compiler to implement [`Future`] for `async fn`s. //! //! Such types that have an *address-sensitive* state usually follow a lifecycle @@ -141,7 +141,7 @@ //! * e.g. subsequent calls to [`poll`] //! 4. Before the value is invalidated (e.g. deallocated), it is *dropped*, giving it a chance to //! notify anything with pointers to itself that those pointers will be invalidated -//! * e.g. [`drop`]ping the [`Future`] +//! * e.g. [`drop`]ping the [`Future`] [^pin-drop-future] //! //! There are two possible ways to ensure the invariants required for 2. and 3. above (which //! apply to any address-sensitive type, not just self-referrential types) do not get broken. @@ -196,6 +196,9 @@ //! discussed with the second option by building a *shared contractual language* around the //! guarantees of "pinning" data. //! +//! [^pin-drop-future]: Futures themselves do not ever need to notify other bits of code that +//! they are being dropped, however data structures like stack-based intrusive linked lists do. +//! //! ## Using [`Pin`] to pin values //! //! In order to pin a value, we wrap a *pointer to that value* (of some type `Ptr`) in a