# tokio-rs/tokio architecture

> Architecture diagram of the GitHub repository tokio-rs/tokio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tokio-rs/tokio
- Repository: https://github.com/tokio-rs/tokio

## Overview

Tokio is a Rust asynchronous runtime and a family of companion crates. An application enters through a runtime (often via `#[tokio::main]`), schedules async work, and uses nonblocking I/O; the runtime combines task scheduling with an OS-backed I/O driver. The repository also supplies synchronization, timers, filesystem and process APIs, and companion stream and utility crates. Relationships among the runtime’s core parts are supported by the README and indexed excerpts; unsampled feature implementations are represented only at their existing subsystem paths.

Main entry points: [`tokio/src/runtime/mod.rs`](https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/mod.rs) (Runtime API), [`tokio/src/runtime/scheduler/multi_thread/worker.rs`](https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/scheduler/multi_thread/worker.rs) (Worker execution), [`tokio/src/runtime/scheduler/mod.rs`](https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/scheduler/mod.rs) (Task scheduler), [`tokio/src/runtime/task/mod.rs`](https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/task/mod.rs) (Task lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime core"]
  node_runtime_api["Runtime API<br/>[mod.rs]"]
  node_builder["Runtime builder<br/>[builder.rs]"]
  node_context["Task context<br/>[context.rs]"]
  node_scheduler["Task scheduler<br/>[mod.rs]"]
  node_workers["Worker execution<br/>[worker.rs]"]
  node_task["Task lifecycle<br/>[mod.rs]"]
  node_metrics["Runtime metrics<br/>[runtime.rs]"]
end

subgraph group_io["I/O and resources"]
  node_driver["I/O driver<br/>[driver.rs]"]
  node_net["TCP and UDP<br/>[mod.rs]"]
  node_async_io["Async I/O<br/>[mod.rs]"]
  node_filesystem["Filesystem<br/>[mod.rs]"]
  node_process["Process management<br/>[mod.rs]"]
  node_signals["OS signals<br/>[mod.rs]"]
end

subgraph group_coord["Async coordination"]
  node_timers["Timers<br/>[mod.rs]"]
  node_sync["Synchronization<br/>[mod.rs]"]
  node_macros["Async macros<br/>[entry.rs]"]
end

subgraph group_companions["Companion crates"]
  node_streams["Stream adapters<br/>[stream_ext.rs]"]
  node_codecs["Framed codecs<br/>[mod.rs]"]
  node_util_future["Future utilities<br/>[future.rs]"]
  node_delay_queue["Delay queue<br/>[delay_queue.rs]"]
end

node_app(("Application"))

node_app -->|"runs on"| node_runtime_api
node_runtime_api -->|"configures"| node_builder
node_runtime_api -->|"drives tasks"| node_scheduler
node_runtime_api -->|"uses driver"| node_driver
node_context -->|"tracks scheduler"| node_scheduler
node_scheduler -->|"spawns tasks"| node_task
node_workers -->|"polls tasks"| node_task
node_workers -->|"checks events"| node_driver
node_runtime_api -->|"hosts networking"| node_net
node_app -->|"accepts sockets"| node_net
node_app -->|"spawns work"| node_task
node_app -->|"reads and writes"| node_async_io
node_runtime_api -->|"provides async FS"| node_filesystem
node_runtime_api -->|"provides processes"| node_process
node_runtime_api -->|"provides signals"| node_signals
node_runtime_api -->|"provides timers"| node_timers
node_runtime_api -->|"provides sync"| node_sync
node_app -->|"uses entry macro"| node_macros
node_app -->|"adapts streams"| node_streams
node_async_io -->|"frames I/O"| node_codecs
node_streams -.->|"uses utilities"| node_util_future
node_util_future -.->|"schedules delays"| node_delay_queue
node_workers -.->|"records runtime data"| node_metrics

click node_runtime_api "https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/mod.rs"
click node_builder "https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/builder.rs"
click node_context "https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/context.rs"
click node_scheduler "https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/scheduler/mod.rs"
click node_workers "https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/scheduler/multi_thread/worker.rs"
click node_task "https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/task/mod.rs"
click node_metrics "https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/metrics/runtime.rs"
click node_driver "https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/driver.rs"
click node_net "https://github.com/tokio-rs/tokio/blob/master/tokio/src/net/mod.rs"
click node_async_io "https://github.com/tokio-rs/tokio/blob/master/tokio/src/io/mod.rs"
click node_filesystem "https://github.com/tokio-rs/tokio/blob/master/tokio/src/fs/mod.rs"
click node_process "https://github.com/tokio-rs/tokio/blob/master/tokio/src/process/mod.rs"
click node_signals "https://github.com/tokio-rs/tokio/blob/master/tokio/src/signal/mod.rs"
click node_timers "https://github.com/tokio-rs/tokio/blob/master/tokio/src/time/mod.rs"
click node_sync "https://github.com/tokio-rs/tokio/blob/master/tokio/src/sync/mod.rs"
click node_macros "https://github.com/tokio-rs/tokio/blob/master/tokio-macros/src/entry.rs"
click node_streams "https://github.com/tokio-rs/tokio/blob/master/tokio-stream/src/stream_ext.rs"
click node_codecs "https://github.com/tokio-rs/tokio/blob/master/tokio-util/src/codec/mod.rs"
click node_util_future "https://github.com/tokio-rs/tokio/blob/master/tokio-util/src/future.rs"
click node_delay_queue "https://github.com/tokio-rs/tokio/blob/master/tokio-util/src/time/delay_queue.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runtime_api,node_builder,node_context,node_scheduler,node_workers,node_task,node_metrics toneBlue
class node_driver,node_net,node_async_io,node_filesystem,node_process,node_signals toneAmber
class node_timers,node_sync,node_macros toneMint
class node_streams,node_codecs,node_util_future,node_delay_queue toneRose
class node_app toneIndigo
```

## Components

### Runtime core

- [Runtime API](https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/mod.rs): `tokio/src/runtime/mod.rs`
- [Runtime builder](https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/builder.rs): `tokio/src/runtime/builder.rs`
- [Task context](https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/context.rs): `tokio/src/runtime/context.rs`
- [Task scheduler](https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/scheduler/mod.rs): `tokio/src/runtime/scheduler/mod.rs`
- [Worker execution](https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/scheduler/multi_thread/worker.rs): `tokio/src/runtime/scheduler/multi_thread/worker.rs`
- [Task lifecycle](https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/task/mod.rs): `tokio/src/runtime/task/mod.rs`
- [Runtime metrics](https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/metrics/runtime.rs): `tokio/src/runtime/metrics/runtime.rs`

### I/O and resources

- [I/O driver](https://github.com/tokio-rs/tokio/blob/master/tokio/src/runtime/driver.rs): `tokio/src/runtime/driver.rs`
- [TCP and UDP](https://github.com/tokio-rs/tokio/blob/master/tokio/src/net/mod.rs): `tokio/src/net/mod.rs`
- [Async I/O](https://github.com/tokio-rs/tokio/blob/master/tokio/src/io/mod.rs): `tokio/src/io/mod.rs`
- [Filesystem](https://github.com/tokio-rs/tokio/blob/master/tokio/src/fs/mod.rs): `tokio/src/fs/mod.rs`
- [Process management](https://github.com/tokio-rs/tokio/blob/master/tokio/src/process/mod.rs): `tokio/src/process/mod.rs`
- [OS signals](https://github.com/tokio-rs/tokio/blob/master/tokio/src/signal/mod.rs): `tokio/src/signal/mod.rs`

### Async coordination

- [Timers](https://github.com/tokio-rs/tokio/blob/master/tokio/src/time/mod.rs): `tokio/src/time/mod.rs`
- [Synchronization](https://github.com/tokio-rs/tokio/blob/master/tokio/src/sync/mod.rs): `tokio/src/sync/mod.rs`
- [Async macros](https://github.com/tokio-rs/tokio/blob/master/tokio-macros/src/entry.rs): `tokio-macros/src/entry.rs`

### Companion crates

- [Stream adapters](https://github.com/tokio-rs/tokio/blob/master/tokio-stream/src/stream_ext.rs): `tokio-stream/src/stream_ext.rs`
- [Framed codecs](https://github.com/tokio-rs/tokio/blob/master/tokio-util/src/codec/mod.rs): `tokio-util/src/codec/mod.rs`
- [Future utilities](https://github.com/tokio-rs/tokio/blob/master/tokio-util/src/future.rs): `tokio-util/src/future.rs`
- [Delay queue](https://github.com/tokio-rs/tokio/blob/master/tokio-util/src/time/delay_queue.rs): `tokio-util/src/time/delay_queue.rs`

### Other components

- **Application**

## Connections

- Application → Runtime API: runs on
- Runtime API → Runtime builder: configures (evidence: `tokio/src/runtime/mod.rs`)
- Runtime API → Task scheduler: drives tasks (evidence: `tokio/src/runtime/mod.rs`)
- Runtime API → I/O driver: uses driver (evidence: `tokio/src/runtime/mod.rs`)
- Task context → Task scheduler: tracks scheduler (evidence: `tokio/src/runtime/context.rs`)
- Task scheduler → Task lifecycle: spawns tasks (evidence: `tokio/src/runtime/scheduler/mod.rs`)
- Worker execution → Task lifecycle: polls tasks (evidence: `tokio/src/runtime/scheduler/multi_thread/worker.rs`)
- Worker execution → I/O driver: checks events (evidence: `tokio/src/runtime/scheduler/multi_thread/worker.rs`)
- Runtime API → TCP and UDP: hosts networking
- Application → TCP and UDP: accepts sockets
- Application → Task lifecycle: spawns work
- Application → Async I/O: reads and writes
- Runtime API → Filesystem: provides async FS (evidence: `tokio/src/lib.rs`)
- Runtime API → Process management: provides processes (evidence: `tokio/src/lib.rs`)
- Runtime API → OS signals: provides signals (evidence: `tokio/src/lib.rs`)
- Runtime API → Timers: provides timers (evidence: `tokio/src/lib.rs`)
- Runtime API → Synchronization: provides sync (evidence: `tokio/src/lib.rs`)
- Application → Async macros: uses entry macro
- Application → Stream adapters: adapts streams
- Async I/O → Framed codecs: frames I/O (evidence: `tokio-util/src/codec/mod.rs`)
- Stream adapters → Future utilities: uses utilities
- Future utilities → Delay queue: schedules delays
- Worker execution → Runtime metrics: records runtime data
