A few months ago we introduced the concept of “pinned” references - pointers which “pin” the data they refer to in a particular memory location, guaranteeing that it will never move again. These are an important building block for certain patterns that had previously been hard for Rust to handle, like self-referential structs and intrusive lists, and we’ve in the process of considering stabilizing the API.

One thing has always nagged about the API we have right now though: the proliferation of different reference types that it implies. Today, the pin feature adds the PinMut and PinBox types, but in theory there ought to be a “pinned” version of every pointer in the standard library: PinRc and PinArc and so on. This is a very unfortunate consequence, but so far we have not found a good way to make pinning work compositionally - to have a single adapter that could be combined with any pointer.

Last night, a bit of inspiration struck me, and I realized that it is possible to make a compositional Pin type. This isn’t a fundamental change to the pinning model, just an API refactoring, but I’ve put a blocking concern on the proposal to stabilize Pin so that we can consider this possibility.

The Pin wrapper

In this new API, PinBox and PinMut would both disappear, and be replaced by a single type: Pin<P>. I’ve named the parameter to Pin P instead of T to help readers remember that Pin is generic over a pointer type, not any type at all. So PinBox<T> is replaced by Pin<Box<T>>, and PinMut<'a, T> by Pin<&'a mut T>. Similarly, this can be extended to Pin<&'a T>, Pin<Rc<T>> and Pin<Arc<T>>.

Here’s a bit of code:

pub struct Pin<P> {
    pointer: P,
}

impl<P, T> Deref for Pin<P> where
    P: Deref<Target = T>,
{
    type Target = T;
    fn deref(&self) -> &T {
        &*self.pointer
    }
}

impl<P, T> DerefMut for Pin<P> where
    P: DerefMut<Target = T>,
    T: Unpin,
{
    fn deref_mut(&mut self) -> &mut T {
        &mut *self.pointer
    }
}

Like the previous PinBox and PinMut types, Pin implements Deref and DerefMut. It only implements DerefMut if the target type implements Unpin. This is what makes the whole pinning system safe at all.

impl<P, T> Pin<P> where
    P: Deref<Target = T>,
{
    pub fn as_ref(&self) -> Pin<&T> {
        Pin { pointer: &*self.pointer }
    }
}

impl<P, T> Pin<P> where
    P: DerefMut<Target = T>,
{
    pub fn as_mut(&mut self) -> Pin<&mut T> {
        Pin { pointer: &mut *self.pointer }
    }

    pub unsafe fn get_mut_unchecked(&mut self) -> &mut T {
        &mut *self.pointer
    }
}

It’s also possible to convert a Pin<P> to a Pin<&T> and Pin<&mut T>, regardless of whether or not the target is Unpin. This subsumes both PinBox::as_pin_mut and PinMut::reborrow: they are both the same underlying operation on the Pin type, allowing you to borrow access to the pinned data (mutably and immutably) without taking it out of the Pin.

All of the API above is essentially the same as the API of PinBox and PinMut: nothing new has been added here. The real trick to make this work is in the constructors for Pin.

Constructing a Pin

The big problem with the idea of compositional Pin before was that different pointers are safe to pin in different ways. For example, this implementation is perfectly safe:

impl<T> From<Box<T>> for Pin<Box<T>> {
    fn from(b: Box<T>) -> Pin<Box<T>> {
        Pin { pointer: b }
    }
}

But the same impl with Rc replacing Box would not be - a user could clone two aliased Rc’s, pin one, drop it, and then move the value again out of the other Rc they’ve been holding onto.

We can make this work by implementing a single core unsafe constructor, and for each pointer type we implement an appropriate constructor on top of it:

impl<P> Pin<P> {
    unsafe fn new_unchecked(pointer: P) -> Pin<P> {
        Pin { pointer: pointer }
    }
}

impl<T> Pin<Box<T>> {
    pub fn new_box(data: T) -> Pin<Box<T>> {
        unsafe { Pin::new_unchecked(Box::new(data)) }
    }
}

impl<T> Pin<Rc<T>> {
    pub fn new_rc(data: T) -> Pin<Rc<T>> {
        unsafe { Pin::new_unchecked(Rc::new(data)) }
    }
}

// etc

If end users want to be able to pin their own pointer types, they can create a new constructor that returns a Pin<MyPointer<T>>, reusing all of the rest of the pin API with their type. And if you want to abstract over multiple kinds of pinned pointers, its possible with something like Pin<P> where P: DerefMut.

An unsafe Own trait

We can even go a step further: while some constructors (like Box<T> -> Pin<Box<T>>) are not generally safe for different pointer types, there are some that we could reasonably abstract. T -> Pin<Box<T>> and T -> Pin<Rc<T>> have the same shape after all.

We can do this with an unsafe trait, which I’ll call Own. A pointer implements Own if it takes ownership of the data and never moves it from that address again until it is destroyed, even if the pointer type is moved. All of Box, Rc and Arc meet this requirement.

unsafe trait Own: Deref {
    fn own(data: Self::Target) -> Self;

    fn pinned(data: Self::Target) -> Pin<Self> {
        unsafe { Pin::new_unchecked(Self::own(data)) }
    }
}

With this trait, there’s a uniform interface for creating pinned, owned pointers. PinBox::new becomes Box::pinned, and you can also write Rc::pinned and Arc::pinned. If you define a pointer that meets these requirements, you can unsafe impl Own for your own type as well.

Conclusion

I’ve written up a gist as well containing the full API (less various helpers and impl like Debug and map_unchecked) that I’d propose to replace PinBox and PinMut. I’m interested in hearing peoples’ thoughts!