poll: Ready con el valor o Pending con un todavía no

Un future no se ejecuta: se conduce. Y conducirlo consiste en una sola operación repetida —poll— cuya respuesta es siempre uno de dos veredictos. O bien Poll::Ready(v), “he terminado, aquí tienes el valor”, o bien Poll::Pending, “todavía no”. Toda la programación asíncrona de Rust, por debajo de la sintaxis async/.await, es este diálogo escueto entre un runtime que pregunta “¿ya?” y un future que responde con el resultado o con una promesa de avisar. En esta lección abrimos la firma de poll símbolo a símbolo y, sobre todo, el protocolo que la gobierna: un contrato tácito cuyo incumplimiento no lo atrapa el compilador, pero sí arruina el programa.

El enum Poll: dos veredictos y nada más

El valor que devuelve poll es de un tipo sorprendentemente humilde, un enum de dos variantes:

pub enum Poll<T> {
    Ready(T),  // terminado: aqui esta el valor de tipo T
    Pending,   // todavia no hay resultado
}

Eso es todo lo que un future puede contestar. Poll::Ready(v) transporta el resultado —el mismo tipo T que el Output del future— y sella el cálculo: ya está. Poll::Pending no lleva nada; es la palabra “aún no”, un veredicto sin carga útil. No hay una tercera variante para errores: un future falible simplemente tiene Output = Result<T, E>, de modo que el error viaja dentro del Ready. Fallar es haber terminado con un Err, no una forma distinta de estar pendiente.

La economía del enum es deliberada. Sondear un future es preguntar por su estado en un instante, y solo hay dos estados posibles que le importen a quien lo conduce: ha producido el valor o no lo ha producido. Cualquier matiz adicional —por qué no está listo, cuánto falta— sería información que el runtime no necesita para hacer su trabajo, que es decidir entre “recojo el resultado” y “aparco esta tarea”.

Un matiz importante: los futures falibles no estrenan una tercera variante. El error viaja dentro del Ready, porque fallar es una forma de terminar.

// type Output = Result<Vec<u8>, std::io::Error>;
// Poll::Ready(Ok(datos))  -> termine bien
// Poll::Ready(Err(error)) -> termine mal, pero termine
// Poll::Pending           -> aun no se el desenlace

La firma de poll, símbolo a símbolo

Recuperemos la firma exacta y leamos cada pieza:

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;

• self: Pin<&mut Self> — el receptor. Necesita &mut Self porque sondear avanza la máquina de estados: cada poll puede mutar el estado interno del future. El envoltorio Pin es la promesa, estudiada en el nivel 28, de que la dirección del future no cambiará entre sondeos; hace falta porque la máquina puede guardar referencias a sí misma, y moverla las invalidaría. Por eso no recibes un &mut Self desnudo sino uno fijado.
• cx: &mut Context<'_> — el contexto de la llamada. Hoy su única carga es el Waker, accesible con cx.waker(): el mango que el future usará, si devuelve Pending, para pedir que lo vuelvan a sondear cuando haya progreso. Es el tema de la lección siguiente; aquí basta saber que poll siempre recibe un canal para decir “avísame”.
• -> Poll<Self::Output> — el veredicto: Ready con el Output del future, o Pending.

Fíjate en la asimetría: poll recibe todo lo necesario para intentar avanzar (acceso mutable fijado, un waker que registrar) y devuelve lo mínimo para informar del resultado (terminado o no). No hay parámetros de tiempo, ni de reintentos, ni de prioridad. Esa desnudez es lo que permite que el mismo trait sirva a un runtime gigante multihilo y a un bucle block_on de veinte líneas.

El protocolo: preguntar hasta Ready

poll no se llama una vez: se llama las veces que haga falta hasta arrancarle un Ready. Ese bucle de preguntas obedece un contrato con dos cláusulas que el compilador no vigila y que, por tanto, debes respetar tú al implementar un future:

1. Si devuelves Pending, te comprometes a que alguien llame al Waker. No es opcional. Devolver Pending sin haber dispuesto un aviso significa que el runtime aparcará la tarea y jamás la volverá a sondear: se cuelga para siempre, en silencio. Pending es una promesa, no una excusa.
2. Una vez que devuelves Ready, no se te debe volver a sondear. El future ya entregó su valor y puede haber consumido su estado; sondearlo de nuevo es comportamiento indefinido a nivel de contrato —muchos futures hacen panic! con “polled after completion”—. Un future se completa una vez.

De la primera cláusula sale la lección clave sobre el significado de Pending. No quiere decir “vuelve a preguntarme enseguida”, sino justo lo opuesto: “no vuelvas hasta que yo te avise”. Un runtime que, al recibir Pending, reintentara poll en un bucle cerrado estaría haciendo espera activa —quemando un núcleo preguntando “¿ya? ¿ya? ¿ya?”—, que es precisamente lo que el modelo evita. El runtime correcto aparca la tarea y se duerme; solo la resucita cuando el Waker dispara.

// Esqueleto de un poll que respeta el protocolo:
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<u32> {
    if self.hay_resultado() {
        Poll::Ready(self.tomar_resultado())   // termino: entrega el valor
    } else {
        self.registrar_waker(cx.waker());      // CLAUSULA 1: dispon el aviso...
        Poll::Pending                          // ...y solo entonces cede
    }
}

Visto desde el otro lado, el del runtime que conduce, sondear “hasta Ready” es literalmente un bucle. Un block_on mínimo —el executor más simple que existe— sondea y, ante Pending, aparca el hilo:

use std::pin::pin;
use std::task::Context;

fn block_on<F: Future>(futuro: F) -> F::Output {
    let mut futuro = pin!(futuro);                // fija el future (Rust 2024)
    let waker = waker_que_desbloquea_este_hilo();
    let mut cx = Context::from_waker(&waker);
    loop {
        match futuro.as_mut().poll(&mut cx) {
            Poll::Ready(v) => return v,            // termino: sal del bucle
            Poll::Pending => aparcar_hasta_wake(), // duerme; el waker despierta
        }
    }
}

No hay más misterio en “conducir un future”: preguntar poll, y ante Pending, dormir el hilo hasta que el Waker lo desbloquee y reintentar. Un runtime real como Tokio hace esto mismo multiplicado por miles de tareas sobre varios hilos, pero el corazón es este bucle.

flowchart TD
P[El runtime llama a poll] --> V{Que veredicto}
V -->|Ready v| DONE[Recoge el valor y no vuelve a sondear]
V -->|Pending| W[El future registro el waker]
W --> SLEEP[El runtime aparca la tarea y duerme]
SLEEP -->|el waker dispara| P
style P fill:#cba6f7,color:#11111b
style DONE fill:#a6e3a1,color:#11111b
style SLEEP fill:#fab387,color:#11111b