Pin en la práctica: `Future::poll`, `pin!` y `Box::pin`

Toda la teoría del nivel converge en una sola firma, la del método más importante del async de Rust. Future::poll no recibe un &mut self corriente, sino un Pin<&mut Self>, y ahora tienes todo lo necesario para entender por qué esa P extra no es un capricho sino una necesidad estructural. Un futuro puede ser auto-referencial; un ejecutor lo sondea muchas veces con suspensiones en medio; y entre dos sondeos, si el futuro se moviera, sus punteros internos quedarían colgantes. Pin<&mut Self> es la firma diciéndole al ejecutor: para sondearme, prométeme en el sistema de tipos que no me has movido desde la última vez. Esta lección cierra el círculo: la firma, las dos formas de anclar un futuro —Box::pin y pin!— y por qué, pese a todo, apenas escribirás Pin con tus propias manos.

La firma que lo explica todo

Aquí está el trait Future, reducido a su esencia:

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

pub trait Future {
    type Output;
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}

Lo insólito es el self: Pin<&mut Self>: un self type explícito. En vez de tomar &mut self, poll toma un self que llega pinchado. Reconstruye el porqué con lo que ya sabes. Un async fn genera un futuro que puede ser auto-referencial (lección 2), es decir !Unpin (lección 4). Ese futuro no se ejecuta de una vez: el ejecutor llama a poll, el futuro avanza hasta el siguiente await, devuelve Poll::Pending y se suspende conservando su estado —incluidos sus punteros internos—; más tarde el ejecutor vuelve a llamar a poll, y así hasta Poll::Ready.

El peligro está en el entre. Si el ejecutor pudiera mover el futuro entre dos poll —meterlo en un Vec que realoja, pasarlo por valor—, invalidaría sus punteros internos y el siguiente poll leería basura. Al exigir Pin<&mut Self>, la firma hace imposible que el ejecutor tenga un &mut Futuro con el que moverlo: recibe un puntero pinchado, del que —si el futuro es !Unpin— no puede extraer un &mut para reubicarlo. La regla queda grabada en el tipo: una vez que empiezas a sondear un futuro, ya no puede moverse jamás. Pin es el mecanismo que traslada esa regla, sin excepción posible, a través de cada ejecutor que exista.

Anclar un futuro: Box::pin y pin!

Para poder llamar a poll necesitas primero un futuro pinchado. Hay dos herramientas, según dónde quieras que viva:

use std::pin::pin;
use std::future::Future;

async fn trabajo() -> u32 { 42 }

fn main() {
    // 1) En el stack, sin asignar heap: pin! ancla un local oculto.
    let en_stack = pin!(trabajo());
    // en_stack: Pin<&mut impl Future<Output = u32>>

    // 2) En el heap, como objeto de trait: Box::pin asigna y ancla.
    let en_heap: Pin<Box<dyn Future<Output = u32>>> = Box::pin(trabajo());

    let _ = (en_stack, en_heap);
}

Box::pin(fut) mueve el futuro al heap y te devuelve un Pin<Box<F>>. Como el valor vive en una dirección estable del heap, mover el Pin<Box> mueve solo el puntero, no el futuro; este se queda quieto. Cuesta una asignación, pero es la vía más flexible: es como obtienes un Pin<Box<dyn Future>> para guardar futuros heterogéneos en un Vec o devolverlos de una función.

La macro std::pin::pin!(fut) —estable desde Rust 1.68— ancla el futuro en el stack, sin asignar nada. Crea un local escondido y te entrega un Pin<&mut F> a él; el borrow checker garantiza que ese local no se pueda mover mientras el pin viva. Es más barato que Box::pin —cero asignaciones— a cambio de menos flexibilidad: el futuro vive atado al scope actual.

Por qué casi nunca lo tocas, pero debes entenderlo

Y ahora la paradoja que resuelve el nivel: después de todo este aparato, en tu código async cotidiano no escribirás Pin casi nunca. Cuando escribes algo.await, el compilador y el ejecutor orquestan todo el pinchado por debajo: el async fn genera el futuro, el runtime (Tokio y compañía, nivel 33) lo ancla antes de sondearlo, y la maquinaria de await mantiene la invariante sin que tú la menciones. Pin es como la fontanería tras la pared: sostiene el edificio, y precisamente por funcionar bien no la ves.

Solo asoma cuando bajas por debajo del .await: al conducir un futuro a mano llamando a poll, al almacenar un Pin<Box<dyn Future>>, al implementar un combinador como un select o un Stream, o al integrar código async de bajo nivel. Así se ve cuando sí lo tocas —el esqueleto de un ejecutor que sondea un futuro hasta que termina—, y fíjate en que pin! y as_mut son justo lo que hace falta para poder llamar a poll:

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

fn bloquear_hasta_listo<F: Future>(fut: F) -> F::Output {
    let mut fut = pin!(fut);                    // anclamos en el stack: Pin<&mut F>
    let waker = crear_waker();                  // un Waker que reprograma el poll
    let mut cx = Context::from_waker(&waker);
    loop {
        match fut.as_mut().poll(&mut cx) {      // poll exige Pin<&mut F>: as_mut lo entrega
            Poll::Ready(valor) => return valor, // el futuro produjo su Output
            Poll::Pending => aparcar(&waker),   // suspendido: esperar la notificacion
        }
    }
}

Sin pin! no tendrías un Pin<&mut F> con el que satisfacer la firma de poll; sin as_mut no podrías volver a sondear en la siguiente vuelta del bucle sin consumir el pin. Todo un runtime como Tokio es, en esencia, una versión industrial de este bucle. Y sobre todo, Pin asoma en los mensajes de error. El día que veas algo como the trait Unpin is not implemented for … o X cannot be unpinned en un contexto async, no será un jeroglífico: sabrás que el compilador te está diciendo que intentas mover —o pedir un &mut de— un futuro auto-referencial que ha de quedarse quieto, y que la salida suele ser Box::pin o pin!. Entender Pin no es para escribirlo a diario; es para que el async del nivel 33 sea un mecanismo comprensible en vez de magia que a veces falla con errores incomprensibles.

flowchart TD
A[async fn devuelve un futuro] --> B{Donde lo anclas}
B -->|pin en el stack| C[Pin de ref mut al futuro sin heap]
B -->|Box pin en el heap| D[Pin de Box del futuro con una asignacion]
C --> E[El ejecutor llama a poll con Pin de ref mut a Self]
D --> E
E --> F[Entre sondeos el futuro no puede moverse]
F --> G[Sus punteros internos siguen validos]
G --> H[async y await orquestan esto por ti en el nivel 33]
style A fill:#89b4fa,color:#11111b
style E fill:#cba6f7,color:#11111b
style F fill:#f9e2af,color:#11111b
style H fill:#a6e3a1,color:#11111b