tokio-rs/tokio
github.com/tokio-rs/tokio ↗ · 883 files · 6.0 MB
Tokio A runtime for writing reliable, asynchronous, and slim applications with the Rust programming language.
Overview
Tokio is a Rust library workspace for developers building asynchronous applications, providing task execution, operating-system I/O integration, timers, synchronization, filesystem operations, and subprocess control. Its distinctive architecture combines feature-gated APIs, current-thread and work-stealing runtimes, readiness-driven networking, and a separate blocking pool. Companion crates add procedural macros, streams, framing, cancellation, and testing utilities. This brief describes source inspected at commit 2746c3ae26f8ac0af6023843a7f23d419c334efe; it is a bounded investigation, not exhaustive coverage.
System map
The repository is a Cargo workspace organized around a public runtime crate and companion libraries. Applications enter through Rust APIs or generated main/test wrappers; scheduler and driver implementations remain internal. State lives primarily in memory, while filesystem and subprocess APIs cross into operating-system resources. CI and documentation hosting are separate operational surfaces.
- Cargo.toml defines five public crates and five internal workspace members, with crates.io patches redirecting companion dependencies to local source.
- The tokio facade exposes feature-gated fs, process, runtime, signal, sync, task, and time modules; spawn is re-exported when rt is enabled.
- Builder::build selects current-thread or multi-thread construction; Runtime::block_on enters runtime context before dispatching to that scheduler.
- The multi-thread scheduler owns workers with transferable cores; its implementation explicitly describes work stealing and core handoff during block_in_place.
- Driver::new assembles I/O, signal, clock, and timer components; disabled I/O or timer access produces explicit enable_io/enable_time panic messages.
- The blocking pool handles non-async work, growing to a configured thread limit and queuing further requests; task::spawn_blocking delegates to runtime infrastructure.
- Companion boundaries separate stream adapters, feature-gated utility modules, procedural runtime wrappers, and testing helpers rather than embedding them all in tokio.
- CI defines nextest and doctest commands across Windows, Linux, and macOS; Netlify builds nightly API documentation into target/doc and redirects / to /tokio.
Feature catalog
User-facing functionality consists of composable Rust APIs rather than application routes or screens. Tokio provides execution, communication, I/O, timing, and operating-system control, with availability determined by features and targets. Companion libraries expose higher-level framing, cancellation, delayed queues, and stream composition. This catalog groups the inspected API families without claiming every public symbol was examined.
- Execution APIs include spawn, spawn_blocking, yield_now, LocalSet/spawn_local, JoinSet, JoinHandle, and AbortHandle; main/test macros generate runtime construction.
- Networking exposes TCP streams/listeners/sockets, UDP, Unix sockets and FIFO pipes, Windows named pipes, and AsyncFd integration for other I/O resources.
- AsyncRead and AsyncWrite define nonblocking poll interfaces; extension APIs provide operations such as write_all and flush, while filesystem APIs include whole-file writes and synchronization.
- Synchronization exports broadcast, mpsc, oneshot, watch, Mutex, RwLock, Semaphore, Notify, Barrier, OnceCell, and SetOnce.
- Timing APIs include sleep/sleep_until, interval/interval_at with MissedTickBehavior, and timeout/timeout_at; Timeout polls its wrapped future before checking expiration.
- Command supports subprocess spawning and captured output; Child exposes wait-with-output, while signal::ctrl_c provides portable notification through platform implementations.
- tokio-util provides codec, compatibility, I/O, task, and time modules; CancellationToken offers child propagation, and DelayQueue returns keyed values after deadlines.
- tokio-stream supplies StreamExt adapters and resource wrappers; StreamMap merges dynamically inserted streams while preserving each emitted item's source key.
Data flow
Inputs enter as futures, addresses, buffers, channel values, paths, or subprocess commands. Runtime handles and registered I/O state connect pending work to scheduler wakeups. Channels and codecs own intermediate memory, while files and processes connect that memory to external resources. Completion returns through Future, Stream, JoinHandle, and standard I/O result types.
- spawn accepts a Send + 'static future and output, optionally boxes the future, assigns a task ID, and submits through the current runtime handle.
- String socket addresses first attempt direct SocketAddr parsing; unresolved strings are owned and resolved through std::net::ToSocketAddrs on spawn_blocking.
- PollEvented creates Registration against the current scheduler; add_source allocates ScheduledIo, registers its token with Mio, and removes allocation if registration fails.
- The I/O driver polls Mio events, translates readiness, updates ScheduledIo, and wakes interested tasks; socket reads then advance initialized bytes in ReadBuf.
- Bounded mpsc owns a semaphore sized to channel capacity; send awaits a permit before publishing, and ReceiverStream forwards stream polling to Receiver::poll_recv.
- Broadcast stores each value once and clones for receivers; its rounded power-of-two ring overwrites oldest values and reports skipped messages through RecvError::Lagged.
- LengthDelimitedCodec parses a header, validates and adjusts its length, reserves BytesMut capacity, then splits a complete payload and resets from Data to Head.
- Filesystem fallback moves an owned path and buffer into std::fs::write; subprocess output concurrently joins exit status with stdout/stderr reads into Vec buffers.
Behavior traces
Three principal flows were followed through implementation: runtime startup, TCP connection handling, and filesystem writing. Startup selects an executor and creates its drivers before running user futures. Networking follows resolution, registration, readiness, and socket operations. Filesystem writing branches between blocking and experimental io-uring execution, with additional completion boundaries for buffered File writes.
- Startup: parse_knobs removes asyncness, chooses the configured Builder flavor, applies options, then emits enable_all → build/build_local → expect → block_on.
- Multi-thread startup: build → build_threaded_runtime → Driver::new → create_blocking_pool → MultiThread::new → handle.enter → launch.launch → Runtime::from_parts.
- Execution: Runtime::block_on → block_on_inner → enter → scheduler.block_on; MultiThread enters runtime context and drives the root future on the calling thread.
- TCP bind: TcpListener::bind → to_socket_addrs → sequential bind_addr attempts → Mio bind → TcpListener::new → PollEvented registration; empty resolution returns InvalidInput.
- TCP accept: accept → Registration::async_io(READABLE) → readiness and cooperative budget → Mio accept → new_accepted; WouldBlock clears readiness, and accepted streams initially assume read/write readiness.
- Echo flow: echo_server binds loopback, spawns a client performing write_all/read_exact, accepts and splits the server stream, copies read-to-write, then checks byte count and completion.
- Whole-file persistence: fs::write upgrades contents; eligible Linux builds probe io-uring Write support, otherwise write_spawn_blocking → asyncify → spawn_blocking → std::fs::write.
- Buffered persistence: File::poll_write copies bytes and starts mandatory blocking work before returning; poll_flush joins Busy work, while sync_all first completes in-flight work and calls std.sync_all.
Testing signals
Tests and CI were inspected, not executed; no passing result is asserted. The inspected suites use Rust tests, tokio::test, trybuild, deterministic I/O mocks, and Loom concurrency modeling. CI defines nextest, separate doctests, Miri, stress testing, platform checks, and Linux-kernel-specific execution. Coverage observations are bounded: feature guards, target exclusions, and model limits prevent treating these definitions as exhaustive verification.
- tcp_echo uses tokio::test and real loopback sockets to verify repeated client round trips, split-stream copying, total byte count, and oneshot completion; Miri uses fewer iterations.
- fs_file verifies reads, flushed writes, shutdown writes, and conversion to standard files; its suite is feature-gated and excludes WASI.
- length_delimited tests use scripted framed I/O to check incomplete headers/payloads and oversized frames; separate cases verify encoding buffer growth and length-field limits.
- tests-build uses trybuild pass and compile_fail fixtures for macro argument forwarding, invalid inputs, joins, and type mismatches; the harness is ignored under Miri.
- Loom models scheduler shutdown races involving block_in_place; CI bounds exploration with two preemptions and 10,000 branches and conditionally selects suites by PR labels.
- Workspace CI runs nextest on three operating systems, repeats companion tests after removing local patches, and runs doctests separately; feature-powerset checks are limited to depth two.
- CI defines Miri with strict provenance and disabled isolation; stress-test defines release compilation and Valgrind leak checking for simple_echo_tcp.
- io-uring tests are Linux/unstable/feature-gated; CI builds filesystem and library tests for QEMU kernels, including 4.19.325, and requires a completion marker beyond failure-summary checks.
Risk map
These are source-observed contracts and explicitly identified hypotheses, not confirmed vulnerabilities. The most sensitive boundaries involve unsafe buffer access, reactor pointer lifetimes, scheduler shutdown, and externally visible filesystem/process effects. Cancellation and completion differ substantially between async tasks, blocking work, children, and buffered files. Changes to these areas require precise ownership and lifecycle reasoning beyond compilation.
- Reactor event tokens become ScheduledIo pointers through unsafe dereferencing; safety requires deregistration and exclusion of concurrent polling before those allocations can be freed.
- PollEvented casts uninitialized ReadBuf storage to a byte slice and assumes the returned bytes were initialized; TcpStream::poll_read_priv explicitly relies on the socket read contract.
- Started spawn_blocking tasks cannot be aborted, and shutdown can wait indefinitely; shutdown_timeout stops waiting without cancelling the underlying work.
- fs::write forwards caller paths to create/truncate or standard filesystem operations without a repository-root policy; File write acknowledgement, flush completion, and sync_all are distinct boundaries.
- Child drop leaves processes running by default, Unix reaping is best effort, and wait_with_output accumulates each output stream in a Vec without a limit in that implementation.
- On Unix, registering a signal replaces its default handler for the process lifetime; dropping the listener does not restore default SIGINT termination behavior.
- Allocation hypothesis: LengthDelimitedCodec checks the wire length before applying length_adjustment, then reserves the adjusted size; configuration therefore needs review when reasoning about memory bounds. (inferred)
- Scheduler shutdown depends on closing both OwnedTasks and the injection queue; documented races otherwise permit stranded task references, and a Loom test exercises core handoff during shutdown.
Extension points
The principal extension mechanism is Rust trait composition, supplemented by builders and adapters. Custom transports implement async I/O traits; custom protocols implement codec traits. Runtime hooks permit instrumentation, while stream wrappers and maps integrate additional event sources. Feature and platform gates define extension boundaries, and some interfaces are deliberately sealed or unstable.
- Custom transports implement AsyncRead::poll_read and AsyncWrite::poll_write/poll_flush, including arranging waker notifications when returning Pending.
- Protocol codecs implement Decoder with Item/Error and Encoder<Item>; Decoder provides EOF handling, while Encoder writes into the framing layer's BytesMut buffer.
- Builder instrumentation stores Send + Sync thread-start callbacks; on_before_task_poll receives TaskMeta and is additionally gated by tokio_unstable.
- TcpStream::from_std bridges externally created sockets into Mio/PollEvented; callers must provide nonblocking sockets and an entered runtime with I/O enabled.
- ReceiverStream adapts an mpsc Receiver by forwarding poll_next to poll_recv; StreamMap accepts replacement streams by key and emits keyed Stream items.
- Command::spawn_with permits custom standard-process spawning while reusing child wrapping; the implementation notes this API is behind tokio_unstable.
- New public capability wiring belongs in crate feature tables and gated module exports; tokio-util independently maps features to Tokio dependencies and utility modules.
- ToSocketAddrs inherits a sealed private trait, so address resolution is not an open downstream implementation hook; inspected string implementations choose immediate parsing or blocking DNS.
Contributor handoff
Begin with the owning manifest, public exports, implementation, and exact feature-gated test. Preserve scheduler, readiness, cancellation, and persistence contracts when making focused changes. Tests and CI were inspected, not executed, and the investigation is bounded rather than exhaustive. The suggested checks below are for a later authorized implementation session; this read-only investigation did not run repository code or modify files.
- Read workspace patches and owning feature tables first: local dependency substitution and empty default features materially affect which implementations and APIs are built.
- For startup changes, read entry::parse_knobs, Builder::build, threaded construction, and Runtime::block_on together; generated wrappers and runtime context must remain coherent.
- For scheduler changes, preserve dual queue/task-list closure and draining order; use the existing Loom racy_shutdown scenario as a relevant lifecycle regression target.
- For networking changes, preserve WouldBlock readiness clearing, accepted-stream readiness initialization, and from_std nonblocking/runtime requirements; tcp_echo is a focused integration target.
- For filesystem changes, inspect both the blocking fallback and unstable Linux io-uring branch; retain the distinction between File::poll_write acknowledgement, flush, and sync_all.
- In an authorized coding session, start with cargo test -p tokio --features full --test tcp_echo or --test fs_file as appropriate; inspect file cfg guards before selecting flags.
- Tests and CI were inspected, not executed: use the defined nextest/doctest split, trybuild harness, and bounded Loom jobs as verification plans rather than recorded passing results.
- Follow the documented Rust 2021 rustfmt invocation rather than cargo fmt; preserve Rust 1.85 compatibility, public documentation, regression tests, and patch/minor versioning expectations.
Languages
| Language | Files | Share of source |
|---|---|---|
| Rust | 808 | 98% |
| Markdown | 29 | docs/config |
| TOML | 18 | 2% |
| YAML | 11 | docs/config |
| JSON | 1 | docs/config |
Start reading here
Probable source entrypoint: Cargo.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
tokio/ (578 files)
Source layout — tokio/
| Path | Files |
|---|---|
tokio/tests/ | 131 |
tokio/CHANGELOG.md | 1 |
tokio/Cargo.toml | 1 |
tokio/LICENSE | 1 |
Repository structure
| Top-level path | Files |
|---|---|
tokio/ | 578 |
tokio-util/ | 94 |
tokio-stream/ | 78 |
tests-build/ | 22 |
examples/ | 22 |
benches/ | 19 |
.github/ | 16 |
tokio-test/ | 14 |
Docs found: CONTRIBUTING.mdREADME.mddocs/contributing/README.mddocs/contributing/contributing-in-issues.mddocs/contributing/how-to-specify-crates-dependencies-versions.mddocs/contributing/keeping-track-of-issues-and-prs.mddocs/contributing/pull-requests.mddocs/contributing/reviewing-pull-requests.md
Package
Cargo.toml — , 0 declared dependencies.
CI & config entrypoints
README.md— Repository readme.github/workflows/uring-kernel-version-test.yml— GitHub Actions workflow.github/workflows/labeler.yml— GitHub Actions workflow.github/workflows/audit.yml— GitHub Actions workflow.github/workflows/stress-test.yml— GitHub Actions workflow.github/workflows/pr-audit.yml— GitHub Actions workflow.github/workflows/loom.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflow
Structural health signals
Average score 5.7/10 across 96 analyzed source files; 81 hotspots surfaced.
tokio/src/runtime/scheduler/multi_thread/worker.rs— 1353 lines, score 4 (Large file, Deep nesting)tokio/src/fs/file.rs— 1175 lines, score 4 (Large file, Deep nesting)tokio/src/task/join_set.rs— 851 lines, score 4.5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
2746c3ae26f82026-10-02 — ci: update macros_type_mismatch for Rust 1.99.0 (#8533)e6e84a4d4a5e2026-09-30 — net: treat `ENOTCONN` as success in `UnixStream::shutdown` (#8526)e133b6fec0552026-09-29 — task: test task builder spawn locations (#8499)38631ed3de292026-09-29 — rt: fix spurious failure in queue `stress1` test (#8524)40b8779482362026-09-29 — sync: revert `Box::leak` usage (#8522)