Note

The small code snippets we’ll present here can be found in this book’s GitHub repository in the ch09/d-pin folder. The different examples are implemented as different methods that you comment/uncomment in the main function.

Let’s write a small example to illustrate the different ways of pinning a value:

ch09/d-pin/src/main.rs
use std::{marker::PhantomPinned, pin::Pin};
   #[derive(Default)]
    struct Foo {
    a: MaybeSelfRef,
    b: String,
}

So, we want to be able to create an instance using MaybeSelfRef::default() that we can move around as we wish, but then at some point initialize it to a state where it references itself; moving it would cause problems.

This is very much like futures that are not self-referential until they’re polled, as we saw in our previous example. Let’s write the impl block for MaybeSelfRef and take a look at the code::

ch09/d-pin/src/main.rs
impl MaybeSelfRef {
    fn init(self: Pin<&mut Self>) {
        unsafe {
            let Self { a, b, ..
} = self.get_unchecked_mut();
            *b = Some(a);
        }
    }
    fn b(self: Pin<&mut Self>) -> Option<&mut usize> {
        unsafe { self.get_unchecked_mut().b.map(|b| &mut *b) }
    }
}

As you can see, MaybeStelfRef will only be self-referential after we call init on it.

We also define one more method that casts the pointer stored in b to Option<&mut usize>, which is a mutable reference to a.

One thing to note is that both our functions require unsafe. Without Pin, the only method requiring unsafe would be b since we dereference a pointer there. Acquiring a mutable reference to a pinned value always require unsafe, since there is nothing preventing us from moving the pinned value at that point.

Pinning to the heap is usually done by pinning a Box. There is even a convenient method on Box that allows us to get Pin<Box<…>>. Let’s look at a short example:

ch09/d-pin/src/main.rs
fn main() {
    let mut x = Box::
pin
(MaybeSelfRef::default());
    x.as_mut().init();
    println!(“{}”, x.as_ref().a);
    *x.as_mut().b().unwrap() = 2;
    println!(“{}”, x.as_ref().a);
}

Here, we pin MaybeSelfRef to the heap and initialize it. We print out the value of a and then mutate the data through the self-reference in b, and set its value to 2. If we look at the output, we’ll see that everything looks as expected:
    Finished dev [unoptimized + debuginfo] target(s) in 0.56s
     Running `target\debug\x-pin-experiments.exe`
0
2

The pinned value can never move and as users of MaybeSelfRef, we didn’t have to write any unsafe code. Rust can guarantee that we never (in safe Rust) get a mutable reference to MaybeSelfRef since Box took ownership of it.

Heap pinning being safe is not so surprising since, in contrast to the stack, a heap allocation will be stable throughout the program, regardless of where we create it.

Important

This is the preferred way to pin values in Rust. Stack pinning is for those cases where you don’t have a heap to work with or can’t accept the cost of that extra allocation.

Let’s take a look at stack pinning while we’re at it.