Pinning to the stack can be somewhat difficult. In Chapter 5, we saw how the stack worked and we know that it grows and shrinks as values are popped and pushed to the stack.

So, if we’re going to pin to the stack, we have to pin it somewhere “high” on the stack. This means that if we pin a value to the stack inside a function call, we can’t return from that function, and expect the value to still be pinned there. That would be impossible.

Pinning to the stack is hard since we pin by taking &mut T, and we have to guarantee that we won’t move T until it’s dropped. If we’re not careful, this is easy to get wrong. Rust can’t help us here, so it’s up to us to uphold that guarantee. This is why stack pinning is unsafe.

Let’s look at the same example using stack pinning:

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

The noticeable difference here is that it’s unsafe to pin to the stack, so now, we need unsafe both as users of MaybeSelfRef and as implementors.

If we run the example with cargo run, the output will be the same as in our first example:
    Finished dev [unoptimized + debuginfo] target(s) in 0.58s
     Running `target\debug\x-pin-experiments.exe`
0
2

The reason stack pinning requires unsafe is that it’s rather easy to accidentally break the guarantees that Pin is supposed to provide. Let’s take a look at this example:

ch09/d-pin/src/main.rs
use std::mem::swap;
fn stack_pinning_manual_problem() {
    let mut x = MaybeSelfRef::default();
    let mut y = MaybeSelfRef::default();
    {
        let mut x = unsafe { Pin::new_unchecked(&mut x) };
        x.as_mut().init();
        *x.as_mut().b().unwrap() = 2;
    }
    swap(&mut x, &mut y);
    println!(“
     x: {{
  +—–>a: {:p},
  |      b: {:?},
  |  }}
  |
  |  y: {{
  |      a: {:p},
  +—–|b: {:?},
     }}”,
        &x.a,
        x.b,
        &y.a,
        y.b,
    );
}

In this example, we create two instances of MaybeSelfRef called x and y. Then, we create a scope where we pin x and set the value of x.a to 2 by dereferencing the self-reference in b, as we did previously.

Now, when we exit the scope, x isn’t pinned anymore, which means we can take a mutable reference to it without needing unsafe.

Since this is safe Rust and we should be able to do what we want, we swap x and y.

The output prints out the pointer address of the a field of both structs and the value of the pointer stored in b.

When we look at the output, we should see the problem immediately:
Finished dev [unoptimized + debuginfo] target(s) in 0.58s
     Running `target\debug\x-pin-experiments.exe`
     x: {
  +—–>a: 0xe45fcff558,
  |      b: None,
  |  }
  |
  |  y: {
  |      a: 0xe45fcff570,
  +—–|b: Some(0xe45fcff558),
     }

Although the pointer values will differ from run to run, it’s pretty evident that y doesn’t hold a pointer to self anymore.

Right now, it points somewhere in x. This is very bad and will cause the exact memory safety issues Rust is supposed to prevent.

Note

For this reason, the standard library has a pin! macro that helps us with safe stack pinning. The macro uses unsafe under the hood but makes it impossible for us to reach the pinned value again.

Now that we’ve seen all the pitfalls of stack pinning, my clear recommendation is to avoid it unless you need to use it. If you have to use it, then use the pin! macro so that you avoid the issues we’ve described here.

Tip

In this book’s GitHub repository, you’ll find a function called stack_pinning_macro() in the ch09/d-pin/src/main.rs file. This function shows the preceding example but using Rust’s pin! macro.