tokio-docs

tokio (1.54.1)

Überblick

Dieser Skill enthält, was die offizielle tokio-Dokumentation sagt und was leicht falsch gemacht wird: Cancel Safety, Blockieren der Runtime, überraschende Voreinstellungen, Panics und APIs, die alte ersetzen. Grundlagen, die jeder Async-Rust-Entwickler kennt, werden weggelassen. Jede Behauptung in references/ endet mit der Docs-URL, von der sie stammt, damit du die Seite erneut öffnen kannst. https://docs.rs/tokio/latest/tokio/index.html

Abgedeckte Version

tokio 1.54.1, wie von docs.rs/tokio/latest ausgeliefert, plus die tokio.rs-Tutorial- und Themenseiten. Instabile APIs benötigen --cfg tokio_unstable und können in 1.x brechen; schlage sie daher nicht vor, es sei denn, das Projekt aktiviert sie bereits. https://docs.rs/tokio/latest/tokio/index.html#unstable-features

So navigierst du

1. Finde den Bereich des Codes, den du schreibst oder reviewst, in der folgenden Tabelle.
2. Öffne nur diese Referenzdatei. Jede steht für sich allein und hat oben ein Inhaltsverzeichnis.
3. Wende den darin genannten Standard an. Nutze die Ausnahme nur, wenn die angegebene Bedingung zutrifft.
4. Überprüfe bei einem Review auch die Tabelle „Alte Muster“ am Ende der Datei, falls vorhanden, und schlage den Ersatz vor.
5. Gib in deiner Antwort die Docs-URL an, die jeder von dir angewandten Regel folgt, damit der Leser sie überprüfen kann.

Wichtigste Regeln

• Eine mit Builder erstellte Runtime hat keinen I/O- oder Timer-Treiber. Rufe enable_all() auf, sonst schlagen Netzwerk- und Zeittypen fehl. https://docs.rs/tokio/latest/tokio/runtime/index.html#resource-drivers
• #[tokio::test] läuft auf einer Current-Thread-Runtime, #[tokio::main] auf einer Multi-Thread-Runtime. Wird #[tokio::main] auf einer häufig aufgerufenen Funktion verwendet, erstellt es pro Aufruf eine neue Runtime. https://docs.rs/tokio/latest/tokio/attr.test.html und https://docs.rs/tokio/latest/tokio/attr.main.html
• rt.block_on(sleep(d)) führt zu einem Panic: Das Future wird außerhalb der Runtime erstellt. Wickle es ein: rt.block_on(async { sleep(d).await }). https://docs.rs/tokio/latest/tokio/time/fn.sleep.html
• Auf einer Current-Thread-Runtime laufen gespawnte Tasks nur, während Runtime::block_on läuft. Handle::block_on treibt sie nicht an. https://docs.rs/tokio/latest/tokio/runtime/index.html#driving-the-runtime
• Verwende standardmäßig std::sync::Mutex in Async-Code, niemals über ein .await hinweg. Beende den Guard in einem Blockbereich, da drop(guard) die Send-Prüfung nicht erfüllt. Verwende tokio::sync::Mutex nur, wenn der Guard ein .await überqueren muss. https://tokio.rs/tokio/tutorial/shared-state
• Führe blockierenden oder CPU-intensiven Code mit spawn_blocking aus und eine Endlosschleife auf einem std::thread. abort stoppt keine laufende blockierende Aufgabe. https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html
• In select! werden verlierende Zweige verworfen. read_exact, read_to_end, write_all und mpsc::Sender::send verlieren dort Daten. Verwende für Sends reserve() und pinne langlebige Futures außerhalb der Schleife und selektiere auf &mut fut. https://docs.rs/tokio/latest/tokio/macro.select.html und https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.Sender.html#method.send
• select! führt zu einem Panic, wenn jeder Zweig deaktiviert ist und es kein else gibt. https://docs.rs/tokio/latest/tokio/macro.select.html
• Bevorzuge einen begrenzten mpsc::channel(n) für Backpressure. recv gibt nur dann None zurück, wenn jeder Sender verworfen wurde. https://tokio.rs/tokio/tutorial/channels und https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html
• Ein langsamer Broadcast-Empfänger erhält RecvError::Lagged(n) und bleibt geöffnet. Behandle es, anstatt jeden Fehler als geschlossen zu behandeln. https://docs.rs/tokio/latest/tokio/sync/broadcast/struct.Receiver.html#method.recv
• Verwende in einer Watch-changed()-Schleife borrow_and_update() und halte niemals ein borrow() über ein .await hinweg. https://docs.rs/tokio/latest/tokio/sync/watch/index.html
• Das Verwerfen eines JoinHandle löst den Task ab. Das Verwerfen eines JoinSet bricht alle seine Tasks ab. https://docs.rs/tokio/latest/tokio/task/struct.JoinSet.html
• interval tickt standardmäßig sofort zuerst und liefert verpasste Ticks gebündelt nach. Setze MissedTickBehavior::Delay oder Skip, wenn Aufhol-Bündelungen falsch sind. https://docs.rs/tokio/latest/tokio/time/enum.MissedTickBehavior.html
• timeout pollt das Future, bevor es die Frist prüft, sodass ein Future, das niemals nachgibt, nach der Frist mit Ok abschließen kann. https://docs.rs/tokio/latest/tokio/time/fn.timeout.html
• Teste Timer mit #[tokio::test(start_paused = true)] (Feature test-util) und sleep mit automatischer Weiterstellung anstelle von advance. https://docs.rs/tokio/latest/tokio/time/fn.advance.html
• Leere einen BufWriter und eine tokio::fs::File vor dem Verwerfen, sonst gehen Daten verloren oder werden spät geschrieben. https://docs.rs/tokio/latest/tokio/io/index.html und https://docs.rs/tokio/latest/tokio/fs/struct.File.html
• Ein read(), das Ok(0) zurückgibt, bedeutet geschlossen. Eine Schleife, die dies ignoriert, dreht mit 100 % CPU. https://tokio.rs/tokio/tutorial/io
• Jeder tokio::fs-Aufruf ist ein spawn_blocking. Bündele mit fs::read/fs::write oder BufWriter. https://docs.rs/tokio/latest/tokio/fs/index.html
• Ein verworfenes Child läuft weiter, sofern nicht kill_on_drop(true). output() erzwingt gepipte stdout und stderr. https://docs.rs/tokio/latest/tokio/process/index.html und https://docs.rs/tokio/latest/tokio/process/struct.Command.html#method.output
• Unter Unix ersetzt der erste ctrl_c()-Listener den standardmäßigen SIGINT-Handler dauerhaft. https://docs.rs/tokio/latest/tokio/signal/fn.ctrl_c.html
• Ein Named-Pipe-Server muss die nächste Instanz erstellen, bevor er die verbundene übergibt, sonst erhalten Clients NotFound. Ein Client wiederholt nur bei ERROR_PIPE_BUSY. NotFound bedeutet keinen Server; gib daher den Fehler zurück, anstatt zu wiederholen. https://docs.rs/tokio/latest/tokio/net/windows/named_pipe/struct.NamedPipeServer.html und https://docs.rs/tokio/latest/tokio/net/windows/named_pipe/struct.NamedPipeClient.html

Referenzen

Datei	Deckt ab
references/runtime.md	Feature-Flags, Builder und Treiber, LocalRuntime, Shutdown, #[tokio::main] und #[tokio::test]
references/block-on-bridging.md	Antreiben einer Runtime, block_on und Handle::block_on, EnterGuard und Handle::current, Aufrufen von Async-Code aus sync-Code, Unix fork
references/tasks.md	spawn und seine Grenzen, JoinHandle, abort, JoinSet, spawn_blocking, block_in_place, coop-Budget, LocalSet, spawn_local, task_local
references/sync-locks.md	std vs tokio Mutex, Guards über .await, RwLock, Semaphore, Notify, OnceCell, SetOnce, Barrier
references/channels.md	mpsc Backpressure, Permits und Schließen, oneshot, broadcast-Verzögerung, watch-Borrow-Regeln
references/select-cancellation.md	select!-Regeln, Cancel-Safety-Listen, Pinning über Schleifen hinweg, biased, join!, try_join!, Graceful Shutdown
references/time-testing.md	sleep, interval und MissedTickBehavior, timeout, Instant, gepauste Zeit, Mocken von I/O in Tests
references/io-net.md	AsyncRead/AsyncWrite-Ext-Traits, BufWriter, split, io::copy, Framing, TcpListener, TcpStream, TcpSocket, UdpSocket
references/fs-process.md	tokio::fs und sein Blocking-Pool, File-Flush und Drop, Command, Child, kill_on_drop, stdio-Pipes
references/signals-named-pipes.md	ctrl_c, Unix-Signale, Windows-Konsolenereignisse, Windows Named Pipe Server und Client

Alle gelesenen Seiten sind in SOURCES.md aufgelistet.