|
126 | 126 | //! for such a type to be implemented soundly, the pointer which points into `self`'s data must be
|
127 | 127 | //! proven valid whenever it is accessed. But if that value is *moved*, the pointer will still
|
128 | 128 | //! point to the old address where the value was located and not into the new location of `self`,
|
129 |
| -//! thus becoming invalid. A key example of such self-referrential types are the state machines |
| 129 | +//! thus becoming invalid. A key example of such self-referential types are the state machines |
130 | 130 | //! generated by the compiler to implement [`Future`] for `async fn`s.
|
131 | 131 | //!
|
132 | 132 | //! Such types that have an *address-sensitive* state usually follow a lifecycle
|
|
141 | 141 | //! * e.g. subsequent calls to [`poll`]
|
142 | 142 | //! 4. Before the value is invalidated (e.g. deallocated), it is *dropped*, giving it a chance to
|
143 | 143 | //! notify anything with pointers to itself that those pointers will be invalidated
|
144 |
| -//! * e.g. [`drop`]ping the [`Future`] |
| 144 | +//! * e.g. [`drop`]ping the [`Future`] [^pin-drop-future] |
145 | 145 | //!
|
146 | 146 | //! There are two possible ways to ensure the invariants required for 2. and 3. above (which
|
147 | 147 | //! apply to any address-sensitive type, not just self-referrential types) do not get broken.
|
|
196 | 196 | //! discussed with the second option by building a *shared contractual language* around the
|
197 | 197 | //! guarantees of "pinning" data.
|
198 | 198 | //!
|
| 199 | +//! [^pin-drop-future]: Futures themselves do not ever need to notify other bits of code that |
| 200 | +//! they are being dropped, however data structures like stack-based intrusive linked lists do. |
| 201 | +//! |
199 | 202 | //! ## Using [`Pin<Ptr>`] to pin values
|
200 | 203 | //!
|
201 | 204 | //! In order to pin a value, we wrap a *pointer to that value* (of some type `Ptr`) in a
|
|
0 commit comments