Text of rust.docs.kernel.org › core › pin › struct.Pin.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 in core::pin - Rust

Skip to main content Pin core :: pin Struct Pin 1.33.0 · Source #[repr(transparent)] pub struct Pin<Ptr> { /* private fields */ } Expand description A pointer which pins its pointee in place. Pin is a wrapper around some kind of pointer Ptr which makes that pointer “pin” its pointee value in place, thus preventing the value referenced by that pointer from being moved or otherwise invalidated at that place in memory unless it implements Unpin .

See the pin module documentation for a more thorough exploration of pinning. § Pinning values with Pin<Ptr> In order to pin a value, we wrap a pointer to that value (of some type Ptr ) in a Pin<Ptr> . Pin<Ptr> can wrap any pointer type, forming a promise that the pointee will not be moved or otherwise invalidated . If the pointee value’s type implements Unpin , we are free to disregard these requirements entirely and can wrap any pointer to that value in Pin directly via Pin::new .

If the pointee value’s type does not implement Unpin , then Rust will not let us use the Pin::new function directly and we’ll need to construct a Pin -wrapped pointer in one of the more specialized manners discussed below. We call such a Pin -wrapped pointer a pinning pointer (or pinning ref, or pinning Box , etc.) because its existence is the thing that is pinning the underlying pointee in place: it is the metaphorical “pin” securing the data in place on the pinboard (in memory).

It is important to stress that the thing in the Pin is not the value which we want to pin itself, but rather a pointer to that value! A Pin<Ptr> does not pin the Ptr but rather the pointer’s pointee value . The most common set of types which require pinning related guarantees for soundness are the compiler-generated state machines that implement Future for the return value of async fn s. These compiler-generated Future s may contain self-referential pointers, one of the most common use cases for Pin .

More details on this point are provided in the pin module docs, but suffice it to say they require the guarantees provided by pinning to be implemented soundly. This requirement for the implementation of async fn s means that the Future trait requires all calls to poll to use a self: Pin <&mut Self> parameter instead of the usual &mut self . Therefore, when manually polling a future, you will need to pin it first. You may notice that async fn -sourced Future s are only a small percentage of all Future s that exist, yet we had to modify the signature of poll for all Future s to accommodate them.

This is unfortunate, but there is a way that the language attempts to alleviate the extra friction that this API choice incurs: the Unpin trait. The vast majority of Rust types have no reason to ever care about being pinned. These types implement the Unpin trait, which entirely opts all values of that type out of pinning-related guarantees. For values of these types, pinning a value by pointing to it with a Pin<Ptr> will have no actual effect.

The reason this distinction exists is exactly to allow APIs like Future::poll to take a Pin<Ptr> as an argument for all types while only forcing Future types that actually care about pinning guarantees pay the ergonomics cost. For the majority of Future types that don’t have a reason to care about being pinned and therefore implement Unpin , the Pin <&mut Self> will act exactly like a regular &mut Self , allowing direct access to the underlying value.

Only types that don’t implement Unpin will be restricted. § Pinning a value of a type that implements Unpin If the type of the value you need to “pin” implements Unpin , you can trivially wrap any pointer to that value in a Pin by calling Pin::new . use std::pin::Pin; // Create a value of a type that implements `Unpin` let mut unpin_future = std::future::ready( 5 ); // Pin it by creating a pinning mutable reference to it (ready to be `poll`ed!) let my_pinned_unpin_future: Pin< &mut _ > = Pin::new( &mut unpin_future); § Pinning a value inside a Box The simplest and most flexible way to pin a value that does not implement Unpin is to put that value inside a Box and then turn that Box into a “pinning Box ” by wrapping it in a Pin .

You can do both of these in a single step using Box::pin . Let’s see an example of using this flow to pin a Future returned from calling an async fn , a common use case as described above. use std::pin::Pin; async fn add_one(x: u32) -> u32 { x + 1 } // Call the async function to get a future back let fut = add_one( 42 ); // Pin the future inside a pinning box let pinned_fut: Pin<Box< _ >> = Box::pin(fut); If you have a value which is already boxed, for example a Box<dyn Future> , you can pin that value in-place at its current memory address using Box::into_pin . use std::pin::Pin; use std::future::Future; async fn add_one(x: u32) -> u32 { x + 1 } fn boxed_add_one(x: u32) -> Box< dyn Future<Output = u32>> { Box::new(add_one(x)) } let boxed_fut = boxed_add_one( 42 ); // Pin the future inside the existing box let pinned_fut: Pin<Box< _ >> = Box::into_pin(boxed_fut); There are similar pinning methods offered on the other standard library smart pointer types as well, like Rc and Arc . § Pinning a value on the stack using pin!

There are some situations where it is desirable or even required (for example, in a #[no_std] context where you don’t have access to the standard library or allocation in general) to pin a value which does not implement Unpin to its location on the stack. Doing so is possible using the pin! macro. See its documentation for more. § Layout and ABI Pin<Ptr> is guaranteed to have the same memory layout and ABI 1 as Ptr .

There is a bit of nuance here that is still being decided about whether the aliasing semantics of Pin<&mut T> should be different than &mut T , but this is true as of today. ↩ Implementations § Source § impl<Ptr: Deref <Target: Unpin >> Pin <Ptr> 1.33.0 (const: 1.84.0) · Source pub const fn new (pointer: Ptr) -> Pin <Ptr> Constructs a new Pin<Ptr> around a pointer to some data of a type that implements Unpin . Unlike Pin::new_unchecked , this method is safe because the pointer Ptr dereferences to an Unpin type, which cancels the pinning guarantees. § Examples use std::pin::Pin; let mut val: u8 = 5 ; // Since `val` doesn't care about being moved, we can safely create a "facade" `Pin` // which will allow `val` to participate in `Pin`-bound apis without checking that // pinning guarantees are actually upheld. let mut pinned: Pin< &mut u8> = Pin::new( &mut val); 1.39.0 (const: 1.84.0) · Source pub const fn into_inner (pin: Pin <Ptr>) -> Ptr Unwraps this Pin<Ptr> , returning the underlying pointer.

Doing this operation safely requires that the data pointed at by this pinning pointer implements Unpin so that we can ignore the pinning invariants when unwrapping it. § Examples use std::pin::Pin; let mut val: u8 = 5 ; let pinned: Pin< &mut u8> = Pin::new( &mut val); // Unwrap the pin to get the underlying mutable reference to the value. We can do // this because `val` doesn't care about being moved, so the `Pin` was just // a "facade" anyway. let r = Pin::into_inner(pinned); assert_eq! ( * r, 5 ); Source § impl<Ptr: Deref > Pin <Ptr> 1.33.0 (const: 1.84.0) · Source pub const unsafe fn new_unchecked (pointer: Ptr) -> Pin <Ptr> Constructs a new Pin<Ptr> around a reference to some data of a type that may or may not implement Unpin .

If pointer dereferences to an Unpin type, Pin::new should be used instead. § Safety This constructor is unsafe because we cannot guarantee that the data pointed to by pointer is pinned. At its core, pinning a value means making the guarantee that the value’s data will not be moved nor have its storage invalidated until it gets dropped. For a more thorough explanation of pinning, see the pin module docs . If the caller that is constructing this Pin<Ptr> does not ensure that the data Ptr points to is pinned, that is a violation of the API contract and may lead to

The rest of this page is on the live site.