FerrousPath

Nivel 4 · Experto· Lección 4 de 9 · 35 min

Pin y tipos autorreferenciales

Por qué mover rompe las autorreferencias, qué garantiza Pin, Unpin, el pinning estructural, y cómo las máquinas de estados de async dependen de todo ello.

El problema: los movimientos son copias bit a bit

Todo valor de Rust se puede mover, y un movimiento es un memcpy a una dirección nueva seguido de olvidar la antigua. Para casi todos los tipos eso es inofensivo. Es fatal para un valor que contiene un puntero hacia sí mismo:

struct SelfRef {
    data: String,
    ptr: *const String, // pensado para apuntar a `self.data`
}

fn main() {
    let mut a = SelfRef { data: String::from("hello"), ptr: std::ptr::null() };
    a.ptr = &a.data;
    println!("before move: ptr == &data ? {}", std::ptr::eq(a.ptr, &a.data));

    let b = a; // un movimiento bit a bit a un nuevo hueco de la pila
    println!("after move:  ptr == &data ? {}", std::ptr::eq(b.ptr, &b.data));
    // b.ptr sigue guardando la dirección ANTIGUA. Desreferenciarlo sería un uso después de mover.
}

El Rust seguro ni siquiera puede expresar un tipo así con referencias: no hay ningún lifetime que escribir. Pero el compilador los genera constantemente:

async fn example() {
    let buf = [0u8; 64];
    let view = &buf[..8];        // una referencia a otra variable local…
    some_io().await;             // …mantenida a través de un await
    println!("{}", view.len());
}

async fn some_io() {}

El futuro de example es un struct con los campos buf y view, y view apunta dentro de buf. Antes del primer sondeo es inerte y se puede mover libremente. Después del primer sondeo no debe volver a moverse nunca.

Pin<P>

Pin<P> envuelve un tipo puntero P (como &mut T o Box<T>) y restringe su API para que el valor apuntado no se pueda mover a través de él.

El contrato, para un valor apuntado T que no implementa Unpin:

Una vez que un valor está fijado (pinned), su memoria no se moverá, no se invalidará ni se reutilizará hasta que se haya ejecutado su destructor.

El mecanismo es sencillamente la ausencia de una forma segura de obtener un &mut T:

Operación Disponible cuando
Pin::new(ptr) T: Unpin
pin.get_mut() -> &mut T T: Unpin
pin.as_ref() -> Pin<&T>, &*pin (acceso compartido) siempre
pin.as_mut() -> Pin<&mut T> (nuevo préstamo) siempre
pin.set(value) (libera en el sitio el valor antiguo y escribe el nuevo) siempre
unsafe Pin::new_unchecked(ptr) prometes no mover nunca el valor apuntado
unsafe pin.get_unchecked_mut() prometes no mover nada fuera del resultado

Con un &mut T podrías llamar a mem::swap o a mem::replace y mover el valor. Pin te niega exactamente eso.

Unpin

Unpin es un auto trait que significa «a este tipo no le importa que lo muevan, ni siquiera estando fijado». Casi todos los tipos son Unpin: los enteros, String, Vec, Box<T> para cualquier T. Para esos tipos, Pin<&mut T> y &mut T se convierten libremente entre sí y fijar no hace nada.

Los tipos que no son Unpin son los futuros y las corrutinas generados por el compilador, y los tipos que renuncian a él conteniendo un PhantomPinned.

Una confusión frecuente: Box<T> es siempre Unpin, aunque T no lo sea. Mover el box mueve un puntero; el T del heap se queda donde está. Por eso precisamente funciona Pin<Box<T>>.

Fijar en la práctica

use std::future::Future;
use std::pin::{pin, Pin};
use std::task::{Context, Poll, Waker};

async fn compute() -> u32 {
    40 + 2
}

fn main() {
    let mut cx = Context::from_waker(Waker::noop());

    // 1. Fijar en el heap: el futuro se puede guardar, devolver y meter en colecciones.
    let mut boxed: Pin<Box<dyn Future<Output = u32>>> = Box::pin(compute());
    println!("{:?}", boxed.as_mut().poll(&mut cx));

    // 2. Fijar en la pila: sin reservar memoria; el futuro no puede escapar de este ámbito.
    let mut local = pin!(compute());
    println!("{:?}", local.as_mut().poll(&mut cx));

    // `local` es un Pin<&mut impl Future>. El futuro en sí vive en una variable local oculta que
    // nada más puede nombrar, así que nada puede moverlo: eso es lo que hace correcto a pin!.
    let _: Poll<u32> = Poll::Pending; // (Poll es el tipo de retorno de poll)
}

Future::poll recibe self: Pin<&mut Self>. Esa firma es la razón de ser de Pin: para cuando alguien puede sondear, el futuro ya ha sido fijado, así que la máquina de estados puede contener autorreferencias sin peligro.

Un tipo autorreferencial correcto

use std::marker::PhantomPinned;
use std::pin::Pin;

struct Parser {
    input: String,
    cursor: *const u8,     // apunta dentro del búfer en el heap de `input`
    owner: *const String,  // apunta al propio CAMPO `input`: una verdadera autorreferencia
    _pin: PhantomPinned,   // renuncia a Unpin
}

impl Parser {
    fn new(input: &str) -> Pin<Box<Parser>> {
        let mut boxed = Box::pin(Parser {
            input: input.to_string(),
            cursor: std::ptr::null(),
            owner: std::ptr::null(),
            _pin: PhantomPinned,
        });
        // SAFETY: solo escribimos campos; nunca movemos el Parser fuera del Box.
        unsafe {
            let this = boxed.as_mut().get_unchecked_mut();
            this.cursor = this.input.as_ptr();
            this.owner = &this.input;
        }
        boxed
    }

    fn input_via_self_pointer(self: Pin<&Self>) -> &str {
        // SAFETY: `owner` apunta a nuestro propio campo `input`, y estamos fijados, así que sigue ahí.
        unsafe { &*self.owner }
    }

    fn advance(self: Pin<&mut Self>) -> Option<u8> {
        // SAFETY: modificamos un campo en el sitio y no movemos `self`.
        let this = unsafe { self.get_unchecked_mut() };
        let end = this.input.as_ptr().wrapping_add(this.input.len());
        if this.cursor == end {
            return None;
        }
        // SAFETY: cursor está dentro del búfer de input, que nunca se reubica.
        let byte = unsafe { *this.cursor };
        this.cursor = this.cursor.wrapping_add(1);
        Some(byte)
    }
}

fn main() {
    let mut p = Parser::new("pin");
    while let Some(b) = p.as_mut().advance() {
        print!("{} ", b as char);
    }
    println!("| {}", p.as_ref().input_via_self_pointer());

    // let moved = *p; // ❌ no compilaría: no se puede mover fuera de un Pin<Box<Parser>> (Parser: !Unpin)
}

Los métodos reciben self: Pin<&mut Self>, y la única forma de construir un Parser produce uno que ya está fijado. Quien lo use desde código seguro nunca podrá moverlo.

Pinning estructural y proyección

Dado un Pin<&mut Struct>, ¿qué puedes hacer con un campo? Tienes que decidirlo campo por campo y ser coherente:

  • Campo fijado estructuralmente: proyectas Pin<&mut Struct> → Pin<&mut Field>. Entonces nunca debes mover ese campo, no debes ofrecer un &mut Field y tu Drop debe tratar el campo como fijado.
  • No fijado estructuralmente: proyectas a un &mut Field normal. Entonces el tipo del campo no debe depender de estar fijado.

Las proyecciones escritas a mano son unsafe y fáciles de hacer mal (un impl de Drop recibe &mut self, y #[repr(packed)] rompe la garantía). Usa los crates pin-project-lite o pin-project, que generan proyecciones comprobadas:

// crate: pin-project-lite
use pin_project_lite::pin_project;
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use std::time::{Duration, Instant};

pin_project! {
    /// Wraps a future and reports how long it took to complete.
    struct Timed<F> {
        #[pin]
        inner: F,                 // fijado estructuralmente: lo sondeamos
        started: Option<Instant>, // campo normal
    }
}

impl<F: Future> Future for Timed<F> {
    type Output = (F::Output, Duration);

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        let this = self.project(); // inner: Pin<&mut F>, started: &mut Option<Instant>
        let start = *this.started.get_or_insert_with(Instant::now);
        match this.inner.poll(cx) {
            Poll::Ready(v) => Poll::Ready((v, start.elapsed())),
            Poll::Pending => Poll::Pending,
        }
    }
}

Esta es la forma de todo combinador de futuros escrito a mano.

La garantía de Drop

Fijar promete más que «sin movimientos»: la memoria debe seguir siendo válida hasta que se ejecute drop. No puedes devolver ni sobrescribir el almacenamiento de un valor fijado sin llamar a su destructor. Las estructuras de datos intrusivas dependen de esto: un nodo de una lista enlazada intrusiva se desenlaza a sí mismo en drop, y la lista solo es correcta porque el nodo no puede desaparecer sin hacerlo. (Perder el valor sigue estando permitido: entonces la memoria simplemente sigue siendo válida para siempre.)

Ejercicios

  1. Toma el primer ejemplo e imprime las dos direcciones antes y después del movimiento. Después envuelve el valor en Box::pin y muestra que mover el box deja la dirección sin cambios.
  2. Implementa Future a mano para un struct Countdown(u32) que devuelva Pending n veces (despertándose a sí mismo cada vez) y después Ready. ¿Es Unpin? ¿Por qué eso simplifica la implementación?
  3. Escribe un struct Join2<A: Future, B: Future> que sondee dos futuros y se complete con las dos salidas, usando pin-project-lite y dos huecos Option<Output>.
  4. Explica por qué es inofensivo que Pin<&mut T> sea Deref<Target = T>, pero DerefMut solo se implementa para T: Unpin.

Comprueba lo que has entendido

Elige una respuesta para ver la explicación.

  1. 1.¿Qué garantiza Pin<&mut T> cuando T: !Unpin?

  2. 2.¿Por qué Pin::get_mut solo está disponible cuando T: Unpin?

  3. 3.¿Por qué los futuros producidos por bloques async generalmente no implementan Unpin?

Términos clave de esta lección

¿Has terminado la lección y los ejercicios?