footnote on dropping futures

This commit is contained in:
Manish Goregaokar 2024-01-06 16:37:58 -08:00
parent 6a54ed71c0
commit a573c7c409

View file

@ -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<Ptr>`] to pin values
//!
//! In order to pin a value, we wrap a *pointer to that value* (of some type `Ptr`) in a