Text of rust.docs.kernel.org › next › src › core › pin.rs.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

pin.rs - source

Skip to main content core/ pin.rs 1 //! Types that pin data to a location in memory. 2 //! 3 //! It is sometimes useful to be able to rely upon a certain value not being able to *move*, 4 //! in the sense that its address in memory cannot change. This is useful especially when there 5 //! are one or more [*pointers*][pointer] pointing at that value. The ability to rely on this 6 //! guarantee that the value a [pointer] is pointing at (its **pointee**) will 7 //!

8 //! 1. Not be *moved* out of its memory location 9 //! 2. More generally, remain *valid* at that same memory location 10 //! 11 //! is called "pinning." We would say that a value which satisfies these guarantees has been 12 //! "pinned," in that it has been permanently (until the end of its lifespan) attached to its 13 //! location in memory, as though pinned to a pinboard. Pinning a value is an incredibly useful 14 //! building block for [`unsafe`] code to be able to reason about whether a raw pointer to the 15 //! pinned value is still valid. [As we'll see later][drop-guarantee], once a value is pinned, 16 //! it is necessarily valid at its memory location until the end of its lifespan.

This concept 17 //! of "pinning" is necessary to implement safe interfaces on top of things like self-referential 18 //! types and intrusive data structures which cannot currently be modeled in fully safe Rust using 19 //! only borrow-checked [references][reference]. 20 //! 21 //! "Pinning" allows us to put a *value* which exists at some location in memory into a state where 22 //! safe code cannot *move* that value to a different location in memory or otherwise invalidate it 23 //! at its current location (unless it implements [`Unpin`], which we will 24 //! [talk about below][self#unpin]).

Anything that wants to interact with the pinned value in a way 25 //! that has the potential to violate these guarantees must promise that it will not actually 26 //! violate them, using the [`unsafe`] keyword to mark that such a promise is upheld by the user 27 //! and not the compiler. In this way, we can allow other [`unsafe`] code to rely on any pointers 28 //! that point to the pinned value to be valid to dereference while it is pinned.

29 //! 30 //! Note that as long as you don't use [`unsafe`], it's impossible to create or misuse a pinned 31 //! value in a way that is unsound. See the documentation of [`Pin<Ptr>`] for more 32 //! information on the practicalities of how to pin a value and how to use that pinned value from a 33 //! user's perspective without using [`unsafe`]. 34 //! 35 //! The rest of this documentation is intended to be the source of truth for users of [`Pin<Ptr>`] 36 //! that are implementing the [`unsafe`] pieces of an interface that relies on pinning for validity; 37 //! users of [`Pin<Ptr>`] in safe code do not need to read it in detail.

38 //! 39 //! There are several sections to this documentation: 40 //! 41 //! * [What is "*moving*"?][what-is-moving] 42 //! * [What is "pinning"?][what-is-pinning] 43 //! * [Address sensitivity, AKA "when do we need pinning?"][address-sensitive-values] 44 //! * [Examples of types with address-sensitive states][address-sensitive-examples] 45 //! * [Self-referential struct][self-ref] 46 //! * [Intrusive, doubly-linked list][linked-list] 47 //! * [Subtle details and the `Drop` guarantee][subtle-details] 48 //!

49 //! # What is "*moving*"? 50 //! [what-is-moving]: self#what-is-moving 51 //! 52 //! When we say a value is *moved*, we mean that the compiler copies, byte-for-byte, the 53 //! value from one location to another. In a purely mechanical sense, this is identical to 54 //! [`Copy`]ing a value from one place in memory to another. In Rust, "move" carries with it the 55 //! semantics of ownership transfer from one variable to another, which is the key difference 56 //! between a [`Copy`] and a move.

For the purposes of this module's documentation, however, when 57 //! we write *move* in italics, we mean *specifically* that the value has *moved* in the mechanical 58 //! sense of being located at a new place in memory. 59 //! 60 //! All values in Rust are trivially *moveable*. This means that the address at which a value is 61 //! located is not necessarily stable in between borrows. The compiler is allowed to *move* a value 62 //! to a new address without running any code to notify that value that its address 63 //! has changed.

Although the compiler will not insert memory *moves* where no semantic move has 64 //! occurred, there are many places where a value *may* be moved. For example, when doing 65 //! assignment or passing a value into a function. 66 //! 67 //! ``` 68 //! #[derive(Default)] 69 //! struct AddrTracker(Option<usize>); 70 //! 71 //! impl AddrTracker { 72 //! // If we haven't checked the addr of self yet, store the current 73 //! // address.

If we have, confirm that the current address is the same 74 //! // as it was last time, or else panic. 75 //! fn check_for_move(&mut self) { 76 //! let current_addr = self as *mut Self as usize; 77 //! match self.0 { 78 //! None => self.0 = Some(current_addr), 79 //! Some(prev_addr) => assert_eq!(prev_addr, current_addr), 80 //! } 81 //! } 82 //! } 83 //! 84 //! // Create a tracker and store the initial address 85 //! let mut tracker = AddrTracker::default(); 86 //! tracker.check_for_move(); 87 //!

88 //! // Here we shadow the variable. This carries a semantic move, and may therefore also 89 //! // come with a mechanical memory *move* 90 //! let mut tracker = tracker; 91 //! 92 //! // May panic! 93 //! // tracker.check_for_move(); 94 //! ``` 95 //! 96 //! In this sense, Rust does not guarantee that `check_for_move()` will never panic, because the 97 //! compiler is permitted to *move* `tracker` in many situations.

98 //! 99 //! Common smart-pointer types such as [`Box<T>`] and [`&mut T`] also allow *moving* the underlying 100 //! *value* they point at: you can move out of a [`Box<T>`], or you can use [`mem::replace`] to 101 //! move a `T` out of a [`&mut T`]. Therefore, putting a value (such as `tracker` above) behind a 102 //! pointer isn't enough on its own to ensure that its address does not change. 103 //! 104 //! # What is "pinning"?

105 //! [what-is-pinning]: self#what-is-pinning 106 //! 107 //! We say that a value has been *pinned* when it has been put into a state where it is guaranteed 108 //! to remain *located at the same place in memory* from the time it is pinned until its 109 //! [`drop`] is called. 110 //! 111 //! ## Address-sensitive values, AKA "when we need pinning" 112 //! [address-sensitive-values]: self#address-sensitive-values-aka-when-we-need-pinning 113 //!

114 //! Most values in Rust are entirely okay with being *moved* around at-will. 115 //! Types for which it is *always* the case that *any* value of that type can be 116 //! *moved* at-will should implement [`Unpin`], which we will discuss more [below][self#unpin]. 117 //! 118 //! [`Pin`] is specifically targeted at allowing the implementation of *safe interfaces* around 119 //! types which have some state during which they become "address-sensitive." A value in such an 120 //!

"address-sensitive" state is *not* okay with being *moved* around at-will. Such a value must 121 //! stay *un-moved* and valid during the address-sensitive portion of its lifespan because some 122 //! interface is relying on those invariants to be true in order for its implementation to be sound. 123 //! 124 //! As a motivating example of a type which may become address-sensitive, consider a type which 125 //! contains a pointer to another piece of its own data, *i.e.* a "self-referential" type.

In order 126 //! for such a type to be implemented soundly, the pointer which points into `self`'s data must be 127 //! proven valid whenever it is accessed. But if that value is *moved*, the pointer will still 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 suc

The rest of this page is on the live site.