Before we leave the topic of pinning, we’ll quickly explain what pin projections and structural pinning are. Both sound complex, but they are very simple in practice. The following diagram shows how these terms are connected:

Figure 9.5 – Pin projection and structural pinning

Structural pinning means that if a struct is pinned, so is the field. We expose this through pin projections, as we’ll see in the following code example.

If we continue with our example and create a struct called Foo that holds both MaybeSelfRef (field a) and a String type (field b), we could write two projections that return a pinned version of a and a regular mutable reference to b:

ch09/d-pin/src/main.rs
    #[derive(Default)]
    struct Foo {
        a: MaybeSelfRef,
        b: String,
    }
    impl Foo {
        fn a(self: Pin<&mut Self>) -> Pin<&mut MaybeSelfRef> {
            unsafe {
                self.map_unchecked_mut(|s| &mut s.a)
            }
        }
        fn b(self: Pin<&mut Self>) -> &mut String {
            unsafe {
                &mut self.get_unchecked_mut().b
            }
        }
    }

Note that these methods will only be callable when Foo is pinned. You won’t be able to call either of these methods on a regular instance of Foo.

Pin projections do have a few subtleties that you should be aware of, but they’re explained in quite some detail in the official documentation (https://doc.rust-lang.org/stable/std/pin/index.html), so I’ll refer you there for more information about the precautions you must take when writing projections.

Note

Since pin projections can be a bit error-prone to create yourself, there is a popular create for making pin projections called pin_project (https://docs.rs/pin-project/latest/pin_project/). If you ever end up having to make pin projections, it’s worth checking out.

With that, we’ve pretty much covered all the advanced topics in async Rust. However, before we go on to our last chapter, let’s see how pinning will prevent us from making the big mistake we made in the last iteration of our coroutine example.

Improving our example 4 – pinning to the rescue

Fortunately, the changes we need to make are small, but before we continue and make the changes, let’s create a new folder and copy everything we had in our previous example over to that folder:

• Copy the entire c-coroutines-problem folder and name the new copy e-coroutines-pin
• Open Cargo.toml and rename the name of the package e-coroutines-pin

Tip

You’ll find the example code we’ll go through here in this book’s GitHub repository under the ch09/e-coroutines-pin folder.

Now that we have a new folder set up, let’s start making the necessary changes. The logical place to start is our Future definition in future.rs.

future.rs

The first thing we’ll do is pull in Pin from the standard library at the very top:

ch09/e-coroutines-pin/src/future.rs
use std::pin::Pin;

The only other change we need to make is in the definition of poll in our Future trait:
fn poll(
self: Pin<&mut Self>
, waker: &Waker) -> PollState<Self::Output>;

That’s pretty much it.

However, the implications of this change are noticeable pretty much everywhere poll is called, so we need to fix that as well.

Let’s start with http.rs.