tokio-docs

tokio (1.54.1)

Resumen

Esta habilidad contiene lo que la documentación oficial de tokio dice que es fácil de hacer mal: seguridad de cancelación, bloqueo del runtime, valores predeterminados sorprendentes, panics y las APIs que reemplazan a las antiguas. Los conceptos básicos que todo desarrollador async Rust conoce se omiten. Cada afirmación en references/ termina con la URL de la documentación de la que proviene, para que puedas volver a abrir la página. https://docs.rs/tokio/latest/tokio/index.html

Versión cubierta

tokio 1.54.1, tal como se sirve en docs.rs/tokio/latest, además del tutorial y las páginas de temas de tokio.rs. Las APIs inestables necesitan --cfg tokio_unstable y pueden romperse en 1.x, así que no las sugieras a menos que el proyecto ya lo tenga habilitado. https://docs.rs/tokio/latest/tokio/index.html#unstable-features

Cómo navegar

1. Encuentra el dominio del código que escribes o revisas en la tabla de abajo.
2. Abre solo ese archivo de referencia. Cada uno es independiente, con una tabla de contenidos al inicio.
3. Aplica su comportamiento predeterminado. Toma la vía de escape solo cuando se cumpla la condición indicada.
4. En una revisión, también revisa la tabla "Patrones antiguos" al final del archivo cuando exista, y sugiere el reemplazo.
5. En tu respuesta, proporciona la URL de la documentación que sigue cada regla que apliques, para que el lector pueda verificarlo.

Reglas de mayor valor

• Un runtime construido con Builder no tiene controlador de E/S ni de temporizador. Llama a enable_all(), o los tipos de red y tiempo fallarán. https://docs.rs/tokio/latest/tokio/runtime/index.html#resource-drivers
• #[tokio::test] se ejecuta en un runtime de un solo hilo, #[tokio::main] en uno de múltiples hilos. #[tokio::main] en una función que se llama a menudo crea un nuevo runtime por cada llamada. https://docs.rs/tokio/latest/tokio/attr.test.html y https://docs.rs/tokio/latest/tokio/attr.main.html
• rt.block_on(sleep(d)) entra en pánico: el future se crea fuera del runtime. Envuélvelo: rt.block_on(async { sleep(d).await }). https://docs.rs/tokio/latest/tokio/time/fn.sleep.html
• En un runtime de un solo hilo, las tareas generadas (spawned) se ejecutan solo mientras Runtime::block_on se esté ejecutando. Handle::block_on no lo impulsa. https://docs.rs/tokio/latest/tokio/runtime/index.html#driving-the-runtime
• Por defecto, usa std::sync::Mutex en código async, nunca mantenido a través de un .await. Finaliza el guard en un ámbito de bloque, ya que drop(guard) no satisface la verificación de Send. Usa tokio::sync::Mutex solo cuando el guard deba cruzar un .await. https://tokio.rs/tokio/tutorial/shared-state
• Ejecuta código bloqueante o pesado en CPU con spawn_blocking, y un bucle infinito en un std::thread. abort no detiene una tarea bloqueante en ejecución. https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html
• En select!, las ramas perdedoras se descartan. read_exact, read_to_end, write_all y mpsc::Sender::send pierden datos allí. Usa reserve() para envíos, y fija futures de larga duración fuera del bucle y selecciona con &mut fut. https://docs.rs/tokio/latest/tokio/macro.select.html y https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.Sender.html#method.send
• select! entra en pánico cuando todas las ramas están deshabilitadas y no hay else. https://docs.rs/tokio/latest/tokio/macro.select.html
• Prefiere un mpsc::channel(n) con límite para contrapresión. recv devuelve None solo una vez que todos los Sender se han descartado. https://tokio.rs/tokio/tutorial/channels y https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html
• Un receptor broadcast lento recibe RecvError::Lagged(n) y permanece abierto. Manéjalo en lugar de tratar cada error como cerrado. https://docs.rs/tokio/latest/tokio/sync/broadcast/struct.Receiver.html#method.recv
• En un bucle de changed() de watch, usa borrow_and_update(), y nunca mantengas un borrow() a través de .await. https://docs.rs/tokio/latest/tokio/sync/watch/index.html
• Descartar un JoinHandle desvincula la tarea. Descartar un JoinSet aborta todas sus tareas. https://docs.rs/tokio/latest/tokio/task/struct.JoinSet.html
• interval hace tick inmediatamente la primera vez y, por defecto, acumula ticks perdidos. Establece MissedTickBehavior::Delay o Skip cuando las ráfagas de recuperación sean incorrectas. https://docs.rs/tokio/latest/tokio/time/enum.MissedTickBehavior.html
• timeout sondea el future antes de verificar el plazo, por lo que un future que nunca cede puede terminar después del plazo con Ok. https://docs.rs/tokio/latest/tokio/time/fn.timeout.html
• Prueba temporizadores con #[tokio::test(start_paused = true)] (característica test-util) y sleep con avance automático en lugar de advance. https://docs.rs/tokio/latest/tokio/time/fn.advance.html
• Vacia (flush) un BufWriter y un tokio::fs::File antes de descartarlos, o los datos se pierden o se escriben tarde. https://docs.rs/tokio/latest/tokio/io/index.html y https://docs.rs/tokio/latest/tokio/fs/struct.File.html
• Un read() que devuelve Ok(0) significa cerrado. Un bucle que lo ignora gira al 100% de CPU. https://tokio.rs/tokio/tutorial/io
• Cada llamada a tokio::fs es un spawn_blocking. Agrupa con fs::read / fs::write o BufWriter. https://docs.rs/tokio/latest/tokio/fs/index.html
• Un Child descartado sigue ejecutándose a menos que kill_on_drop(true). output() fuerza la tubería (pipe) de stdout y stderr. https://docs.rs/tokio/latest/tokio/process/index.html y https://docs.rs/tokio/latest/tokio/process/struct.Command.html#method.output
• En Unix, el primer listener de ctrl_c() reemplaza el manejador SIGINT predeterminado de forma permanente. https://docs.rs/tokio/latest/tokio/signal/fn.ctrl_c.html
• Un servidor de named pipe debe crear la siguiente instancia antes de entregar la conectada, o los clientes obtienen NotFound. Un cliente reintenta solo en ERROR_PIPE_BUSY. NotFound significa que no hay servidor, así que devuelve el error en lugar de reintentar. https://docs.rs/tokio/latest/tokio/net/windows/named_pipe/struct.NamedPipeServer.html y https://docs.rs/tokio/latest/tokio/net/windows/named_pipe/struct.NamedPipeClient.html

Referencias

Archivo	Cubre
references/runtime.md	Banderas de características, Builder y controladores, LocalRuntime, shutdown, #[tokio::main] y #[tokio::test]
references/block-on-bridging.md	Impulsar un runtime, block_on y Handle::block_on, EnterGuard y Handle::current, llamar código async desde código síncrono, Unix fork
references/tasks.md	spawn y sus límites, JoinHandle, abort, JoinSet, spawn_blocking, block_in_place, presupuesto coop, LocalSet, spawn_local, task_local
references/sync-locks.md	std vs tokio Mutex, guards a través de .await, RwLock, Semaphore, Notify, OnceCell, SetOnce, Barrier
references/channels.md	Contrapresión mpsc, permisos y cierre, oneshot, lag de broadcast, reglas de borrow de watch
references/select-cancellation.md	Reglas de select!, listas de seguridad de cancelación, fijación a través de bucles, biased, join!, try_join!, apagado graceful
references/time-testing.md	sleep, interval y MissedTickBehavior, timeout, Instant, tiempo pausado, simulación de E/S en pruebas
references/io-net.md	Traits de extensión AsyncRead/AsyncWrite, BufWriter, split, io::copy, framing, TcpListener, TcpStream, TcpSocket, UdpSocket
references/fs-process.md	tokio::fs y su pool bloqueante, flush y drop de File, Command, Child, kill_on_drop, tuberías stdio
references/signals-named-pipes.md	ctrl_c, señales Unix, eventos de consola Windows, servidor y cliente de named pipe Windows

Todas las páginas leídas se enumeran en SOURCES.md.