Pin in std::pin - Rust (original) (raw)

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

In order to pin a value, we wrap a pointer to that value (of some type Ptr) in aPin. Pin can wrap any pointer type, forming a promise that the pointeewill 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 pinningBox, 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 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 ofasync fns. These compiler-generated Futures may contain self-referential pointers, one of the most common use cases for Pin. More details on this point are provided in thepin 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 fns means that the Future trait requires all calls to poll to use a self: [Pin](struct.Pin.html "struct std::pin::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 Futures are only a small percentage of allFutures that exist, yet we had to modify the signature of poll for all Futures 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 aPin will have no actual effect.

The reason this distinction exists is exactly to allow APIs like Future::poll to take aPin 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](struct.Pin.html "struct std::pin::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, 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 is guaranteed to have the same memory layout and ABI1 as Ptr.

Pin in std::pin - Rust (original) (raw)

Struct Pin

§Pinning values with Pin

§Pinning a value of a type that implements Unpin

§Pinning a value inside a Box

§Pinning a value on the stack using pin!

§Layout and ABI

§Examples

§Examples

§Safety

§Pinning of closure captures

§Example

§Example

§Safety

§Safety

§Safety

§Safety