|
129 | 129 | //!
|
130 | 130 | //! To make this work, every element has pointers to its predecessor and successor in
|
131 | 131 | //! the list. Elements can only be added when they are pinned, because moving the elements
|
132 |
| -//! around would invalidate the pointers. Moreover, the [`Drop`] implementation of a linked |
| 132 | +//! around would invalidate the pointers. Moreover, the [`Drop`][Drop] implementation of a linked |
133 | 133 | //! list element will patch the pointers of its predecessor and successor to remove itself
|
134 | 134 | //! from the list.
|
135 | 135 | //!
|
|
165 | 165 | //! # `Drop` implementation
|
166 | 166 | //!
|
167 | 167 | //! If your type uses pinning (such as the two examples above), you have to be careful
|
168 |
| -//! when implementing [`Drop`]. The [`drop`] function takes <code>[&mut] self</code>, but this |
| 168 | +//! when implementing [`Drop`][Drop]. The [`drop`] function takes <code>[&mut] self</code>, but this |
169 | 169 | //! is called *even if your type was previously pinned*! It is as if the
|
170 | 170 | //! compiler automatically called [`Pin::get_unchecked_mut`].
|
171 | 171 | //!
|
172 | 172 | //! This can never cause a problem in safe code because implementing a type that
|
173 | 173 | //! relies on pinning requires unsafe code, but be aware that deciding to make
|
174 | 174 | //! use of pinning in your type (for example by implementing some operation on
|
175 |
| -//! <code>[Pin]<[&]Self></code> or <code>[Pin]<[&mut] Self></code>) has consequences for your [`Drop`] |
| 175 | +//! <code>[Pin]<[&]Self></code> or <code>[Pin]<[&mut] Self></code>) has consequences for your [`Drop`][Drop] |
176 | 176 | //! implementation as well: if an element of your type could have been pinned,
|
177 |
| -//! you must treat [`Drop`] as implicitly taking <code>[Pin]<[&mut] Self></code>. |
| 177 | +//! you must treat [`Drop`][Drop] as implicitly taking <code>[Pin]<[&mut] Self></code>. |
178 | 178 | //!
|
179 |
| -//! For example, you could implement [`Drop`] as follows: |
| 179 | +//! For example, you could implement [`Drop`][Drop] as follows: |
180 | 180 | //!
|
181 | 181 | //! ```rust,no_run
|
182 | 182 | //! # use std::pin::Pin;
|
|
284 | 284 | //! 2. The destructor of the struct must not move structural fields out of its argument. This
|
285 | 285 | //! is the exact point that was raised in the [previous section][drop-impl]: [`drop`] takes
|
286 | 286 | //! <code>[&mut] self</code>, but the struct (and hence its fields) might have been pinned before.
|
287 |
| -//! You have to guarantee that you do not move a field inside your [`Drop`] implementation. |
| 287 | +//! You have to guarantee that you do not move a field inside your [`Drop`][Drop] implementation. |
288 | 288 | //! In particular, as explained previously, this means that your struct must *not*
|
289 | 289 | //! be `#[repr(packed)]`.
|
290 | 290 | //! See that section for how to write [`drop`] in a way that the compiler can help you
|
|
294 | 294 | //! content is not overwritten or deallocated without calling the content's destructors.
|
295 | 295 | //! This can be tricky, as witnessed by <code>[VecDeque]\<T></code>: the destructor of <code>[VecDeque]\<T></code>
|
296 | 296 | //! can fail to call [`drop`] on all elements if one of the destructors panics. This violates
|
297 |
| -//! the [`Drop`] guarantee, because it can lead to elements being deallocated without |
| 297 | +//! the [`Drop`][Drop] guarantee, because it can lead to elements being deallocated without |
298 | 298 | //! their destructor being called. (<code>[VecDeque]\<T></code> has no pinning projections, so this
|
299 | 299 | //! does not cause unsoundness.)
|
300 | 300 | //! 4. You must not offer any other operations that could lead to data being moved out of
|
|
0 commit comments