tokio-docs

tokio (1.54.1)

Vue d'ensemble

Cette compétence contient ce que la documentation officielle de tokio indique comme étant facile à mal comprendre : la sécurité d'annulation, le blocage du runtime, les valeurs par défaut surprenantes, les paniques et les API qui remplacent les anciennes. Les bases que tout développeur async Rust connaît sont omises. Chaque affirmation dans references/ se termine par l'URL de la documentation dont elle provient, afin que vous puissiez rouvrir la page. https://docs.rs/tokio/latest/tokio/index.html

Version couverte

tokio 1.54.1, tel que servi par docs.rs/tokio/latest, plus les pages du tutoriel et des sujets tokio.rs. Les API instables nécessitent --cfg tokio_unstable et peuvent casser en 1.x, donc ne les suggérez pas sauf si le projet les active déjà. https://docs.rs/tokio/latest/tokio/index.html#unstable-features

Comment naviguer

1. Trouvez le domaine du code que vous écrivez ou révisez dans le tableau ci-dessous.
2. Ouvrez uniquement ce fichier de référence. Chacun est autonome, avec une table des matières en haut.
3. Appliquez sa règle par défaut. N'utilisez l'échappatoire que si la condition énoncée est remplie.
4. Lors d'une relecture, vérifiez également le tableau « Anciens motifs » à la fin du fichier, s'il y en a un, et suggérez le remplacement.
5. Dans votre réponse, donnez l'URL de la documentation qui suit chaque règle que vous appliquez, afin que le lecteur puisse la vérifier.

Règles à plus forte valeur

• Un runtime construit avec Builder n'a pas de pilote d'E/S ni de temporisateur. Appelez enable_all(), sinon les types de réseau et de temps échouent. https://docs.rs/tokio/latest/tokio/runtime/index.html#resource-drivers
• #[tokio::test] s'exécute sur un runtime à thread courant, #[tokio::main] sur un runtime multi-thread. #[tokio::main] sur une fonction appelée fréquemment construit un nouveau runtime par appel. https://docs.rs/tokio/latest/tokio/attr.test.html et https://docs.rs/tokio/latest/tokio/attr.main.html
• rt.block_on(sleep(d)) panique : le futur est créé en dehors du runtime. Enveloppez-le : rt.block_on(async { sleep(d).await }). https://docs.rs/tokio/latest/tokio/time/fn.sleep.html
• Sur un runtime à thread courant, les tâches lancées s'exécutent uniquement pendant que Runtime::block_on est en cours. Handle::block_on ne l'entraîne pas. https://docs.rs/tokio/latest/tokio/runtime/index.html#driving-the-runtime
• Par défaut, utilisez std::sync::Mutex dans le code async, sans jamais le maintenir à travers un .await. Terminez le verrou dans un bloc, car drop(guard) ne satisfait pas la vérification Send. Utilisez tokio::sync::Mutex uniquement lorsque le verrou doit traverser un .await. https://tokio.rs/tokio/tutorial/shared-state
• Exécutez le code bloquant ou gourmand en CPU avec spawn_blocking, et une boucle infinie sur un std::thread. abort n'arrête pas une tâche bloquante en cours. https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html
• Dans select!, les branches perdantes sont abandonnées. read_exact, read_to_end, write_all et mpsc::Sender::send y perdent des données. Utilisez reserve() pour les envois, et épinglez les futurs de longue durée en dehors de la boucle et sélectionnez sur &mut fut. https://docs.rs/tokio/latest/tokio/macro.select.html et https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.Sender.html#method.send
• select! panique lorsque chaque branche est désactivée et qu'il n'y a pas de else. https://docs.rs/tokio/latest/tokio/macro.select.html
• Préférez mpsc::channel(n) bornée pour la contre-pression. recv ne retourne None qu'une fois que tous les Sender sont abandonnés. https://tokio.rs/tokio/tutorial/channels et https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html
• Un récepteur broadcast lent reçoit RecvError::Lagged(n) et reste ouvert. Gérez-le au lieu de traiter chaque erreur comme une fermeture. https://docs.rs/tokio/latest/tokio/sync/broadcast/struct.Receiver.html#method.recv
• Dans une boucle changed() de watch, utilisez borrow_and_update(), et ne maintenez jamais borrow() à travers un .await. https://docs.rs/tokio/latest/tokio/sync/watch/index.html
• Abandonner un JoinHandle détache la tâche. Abandonner un JoinSet annule toutes ses tâches. https://docs.rs/tokio/latest/tokio/task/struct.JoinSet.html
• interval tique immédiatement la première fois et, par défaut, émet des tiques manqués en rafale. Définissez MissedTickBehavior::Delay ou Skip lorsque les rafales de rattrapage ne sont pas appropriées. https://docs.rs/tokio/latest/tokio/time/enum.MissedTickBehavior.html
• timeout interroge le futur avant de vérifier l'échéance, donc un futur qui ne cède jamais la main peut se terminer après l'échéance avec Ok. https://docs.rs/tokio/latest/tokio/time/fn.timeout.html
• Testez les temporisateurs avec #[tokio::test(start_paused = true)] (fonctionnalité test-util) et sleep avec avancement automatique plutôt qu'avec advance. https://docs.rs/tokio/latest/tokio/time/fn.advance.html
• Videz un BufWriter et un tokio::fs::File avant l'abandon, sinon les données sont perdues ou écrites tardivement. https://docs.rs/tokio/latest/tokio/io/index.html et https://docs.rs/tokio/latest/tokio/fs/struct.File.html
• Un read() retournant Ok(0) signifie fermé. Une boucle qui l'ignore tourne à 100 % du CPU. https://tokio.rs/tokio/tutorial/io
• Chaque appel à tokio::fs est un spawn_blocking. Regroupez-les avec fs::read / fs::write ou BufWriter. https://docs.rs/tokio/latest/tokio/fs/index.html
• Un Child abandonné continue de s'exécuter sauf si kill_on_drop(true) est défini. output() force la redirection de stdout et stderr. https://docs.rs/tokio/latest/tokio/process/index.html et https://docs.rs/tokio/latest/tokio/process/struct.Command.html#method.output
• Sous Unix, le premier écouteur ctrl_c() remplace définitivement le gestionnaire SIGINT par défaut. https://docs.rs/tokio/latest/tokio/signal/fn.ctrl_c.html
• Un serveur de tube nommé doit créer l'instance suivante avant de remettre l'instance connectée, sinon les clients reçoivent NotFound. Un client ne réessaie qu'en cas de ERROR_PIPE_BUSY. NotFound signifie qu'aucun serveur n'existe, donc retournez l'erreur plutôt que de réessayer. https://docs.rs/tokio/latest/tokio/net/windows/named_pipe/struct.NamedPipeServer.html et https://docs.rs/tokio/latest/tokio/net/windows/named_pipe/struct.NamedPipeClient.html

Références

Fichier	Couvre
references/runtime.md	Indicateurs de fonctionnalité, Builder et pilotes, LocalRuntime, shutdown, #[tokio::main] et #[tokio::test]
references/block-on-bridging.md	Entraîner un runtime, block_on et Handle::block_on, EnterGuard et Handle::current, appeler du code async depuis du code synchrone, fork Unix
references/tasks.md	spawn et ses limites, JoinHandle, abort, JoinSet, spawn_blocking, block_in_place, budget coop, LocalSet, spawn_local, task_local
references/sync-locks.md	Mutex std vs tokio, verrous à travers .await, RwLock, Semaphore, Notify, OnceCell, SetOnce, Barrier
references/channels.md	Contre-pression mpsc, permis et fermeture, oneshot, retard broadcast, règles d'emprunt watch
references/select-cancellation.md	Règles de select!, listes de sécurité d'annulation, épinglage à travers les boucles, biased, join!, try_join!, arrêt gracieux
references/time-testing.md	sleep, interval et MissedTickBehavior, timeout, Instant, temps suspendu, simulation d'E/S dans les tests
references/io-net.md	Traits d'extension AsyncRead/AsyncWrite, BufWriter, split, io::copy, framing, TcpListener, TcpStream, TcpSocket, UdpSocket
references/fs-process.md	tokio::fs et son pool bloquant, vidage et abandon de File, Command, Child, kill_on_drop, tubes stdio
references/signals-named-pipes.md	ctrl_c, signaux Unix, événements console Windows, serveur et client de tube nommé Windows

Toutes les pages lues sont listées dans SOURCES.md.