|
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