# tokio-rs/loom architecture

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

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

## Overview

Loom is a Rust library for checking concurrent code by modeling and exploring possible executions. A user writes a model closure using Loom’s thread and synchronization APIs; the model runtime schedules permutations and detects invalid behaviors such as races or leaks. The graph includes the public primitive families and the internal execution, scheduling, and object-state layers. Relationships among unsampled runtime subsystems are omitted where the supplied excerpts and reference index do not establish a call.

Main entry points: [`src/sync/mod.rs`](https://github.com/tokio-rs/loom/blob/master/src/sync/mod.rs) (Sync primitives), [`src/rt/execution.rs`](https://github.com/tokio-rs/loom/blob/master/src/rt/execution.rs) (Execution state), [`src/rt/mod.rs`](https://github.com/tokio-rs/loom/blob/master/src/rt/mod.rs) (Runtime coordination), [`src/model.rs`](https://github.com/tokio-rs/loom/blob/master/src/model.rs) (Model runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Modeling API"]
  node_model["Model runner<br/>[model.rs]"]
  node_thread_api["Thread API<br/>[thread.rs]"]
  node_future_api["Future utilities<br/>[mod.rs]"]
  node_cell_api["Cell API<br/>[unsafe_cell.rs]"]
  node_hint["Scheduling hints<br/>[hint.rs]"]
end

subgraph group_engine["Exploration Engine"]
  node_runtime["Runtime coordination<br/>[mod.rs]"]
  node_execution["Execution state<br/>[execution.rs]"]
  node_path["Path exploration<br/>[path.rs]"]
  node_scheduler["Thread scheduler<br/>[scheduler.rs]"]
  node_runtime_thread["Thread state<br/>[thread.rs]"]
  node_locations["Operation locations<br/>[location.rs]"]
end

subgraph group_state["Modeled State"]
  node_objects[("Modeled object store<br/>[object.rs]")]
  node_atomic_model["Atomic model<br/>[atomic.rs]"]
  node_allocation["Allocation tracking<br/>[alloc.rs]"]
  node_lazy_model["Lazy static state<br/>[lazy_static.rs]"]
end

subgraph group_primitives["Concurrency Primitives"]
  node_sync_api["Sync primitives<br/>[mod.rs]"]
  node_atomics["Atomic types<br/>[mod.rs]"]
  node_arc["Reference counting<br/>[arc.rs]"]
  node_mutex["Mutexes<br/>[mutex.rs]"]
  node_rwlock["Read-write locks<br/>[rwlock.rs]"]
  node_channels["Channels<br/>[mpsc.rs]"]
  node_notify["Notifications<br/>[notify.rs]"]
  node_condvar["Condition variables<br/>[condvar.rs]"]
  node_barrier["Barriers<br/>[barrier.rs]"]
  node_cells["Modeled cells<br/>[cell.rs]"]
end

node_user(("Concurrent test author"))

node_user -->|"defines model"| node_model
node_model -->|"starts execution"| node_runtime
node_thread_api -->|"uses runtime"| node_runtime
node_future_api -->|"waits via runtime"| node_runtime
node_cell_api -->|"models access"| node_runtime
node_hint -->|"yields through"| node_thread_api
node_runtime -->|"runs closures"| node_execution
node_execution -->|"branches through"| node_path
node_execution -->|"tracks threads"| node_runtime_thread
node_execution -->|"tracks objects"| node_objects
node_execution -.->|"dispatches scheduling"| node_scheduler
node_runtime -->|"switches threads"| node_scheduler
node_execution -->|"uses locations"| node_locations
node_atomics -->|"models operations"| node_atomic_model
node_atomic_model -->|"updates state"| node_objects
node_sync_api -->|"exports type"| node_arc
node_sync_api -->|"exports types"| node_atomics
node_sync_api -->|"exports type"| node_mutex
node_sync_api -->|"exports type"| node_rwlock
node_sync_api -->|"exports type"| node_channels
node_sync_api -->|"exports type"| node_notify
node_sync_api -->|"exports type"| node_condvar
node_sync_api -->|"exports type"| node_barrier
node_cells -->|"uses cell implementation"| node_cell_api
node_lazy_model -->|"stores per execution"| node_execution
node_allocation -->|"tracks allocations"| node_execution

click node_model "https://github.com/tokio-rs/loom/blob/master/src/model.rs"
click node_thread_api "https://github.com/tokio-rs/loom/blob/master/src/thread.rs"
click node_future_api "https://github.com/tokio-rs/loom/blob/master/src/future/mod.rs"
click node_cell_api "https://github.com/tokio-rs/loom/blob/master/src/cell/unsafe_cell.rs"
click node_hint "https://github.com/tokio-rs/loom/blob/master/src/hint.rs"
click node_runtime "https://github.com/tokio-rs/loom/blob/master/src/rt/mod.rs"
click node_execution "https://github.com/tokio-rs/loom/blob/master/src/rt/execution.rs"
click node_path "https://github.com/tokio-rs/loom/blob/master/src/rt/path.rs"
click node_scheduler "https://github.com/tokio-rs/loom/blob/master/src/rt/scheduler.rs"
click node_runtime_thread "https://github.com/tokio-rs/loom/blob/master/src/rt/thread.rs"
click node_locations "https://github.com/tokio-rs/loom/blob/master/src/rt/location.rs"
click node_objects "https://github.com/tokio-rs/loom/blob/master/src/rt/object.rs"
click node_atomic_model "https://github.com/tokio-rs/loom/blob/master/src/rt/atomic.rs"
click node_allocation "https://github.com/tokio-rs/loom/blob/master/src/rt/alloc.rs"
click node_lazy_model "https://github.com/tokio-rs/loom/blob/master/src/rt/lazy_static.rs"
click node_sync_api "https://github.com/tokio-rs/loom/blob/master/src/sync/mod.rs"
click node_atomics "https://github.com/tokio-rs/loom/blob/master/src/sync/atomic/mod.rs"
click node_arc "https://github.com/tokio-rs/loom/blob/master/src/sync/arc.rs"
click node_mutex "https://github.com/tokio-rs/loom/blob/master/src/sync/mutex.rs"
click node_rwlock "https://github.com/tokio-rs/loom/blob/master/src/sync/rwlock.rs"
click node_channels "https://github.com/tokio-rs/loom/blob/master/src/sync/mpsc.rs"
click node_notify "https://github.com/tokio-rs/loom/blob/master/src/sync/notify.rs"
click node_condvar "https://github.com/tokio-rs/loom/blob/master/src/sync/condvar.rs"
click node_barrier "https://github.com/tokio-rs/loom/blob/master/src/sync/barrier.rs"
click node_cells "https://github.com/tokio-rs/loom/blob/master/src/cell/cell.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_model,node_thread_api,node_future_api,node_cell_api,node_hint toneBlue
class node_runtime,node_execution,node_path,node_scheduler,node_runtime_thread,node_locations toneAmber
class node_objects,node_atomic_model,node_allocation,node_lazy_model toneMint
class node_sync_api,node_atomics,node_arc,node_mutex,node_rwlock,node_channels,node_notify,node_condvar,node_barrier,node_cells toneRose
class node_user toneIndigo
```

## Components

### Modeling API

- [Model runner](https://github.com/tokio-rs/loom/blob/master/src/model.rs): `src/model.rs`
- [Thread API](https://github.com/tokio-rs/loom/blob/master/src/thread.rs): `src/thread.rs`
- [Future utilities](https://github.com/tokio-rs/loom/blob/master/src/future/mod.rs): `src/future/mod.rs`
- [Cell API](https://github.com/tokio-rs/loom/blob/master/src/cell/unsafe_cell.rs): `src/cell/unsafe_cell.rs`
- [Scheduling hints](https://github.com/tokio-rs/loom/blob/master/src/hint.rs): `src/hint.rs`

### Exploration Engine

- [Runtime coordination](https://github.com/tokio-rs/loom/blob/master/src/rt/mod.rs): `src/rt/mod.rs`
- [Execution state](https://github.com/tokio-rs/loom/blob/master/src/rt/execution.rs): `src/rt/execution.rs`
- [Path exploration](https://github.com/tokio-rs/loom/blob/master/src/rt/path.rs): `src/rt/path.rs`
- [Thread scheduler](https://github.com/tokio-rs/loom/blob/master/src/rt/scheduler.rs): `src/rt/scheduler.rs`
- [Thread state](https://github.com/tokio-rs/loom/blob/master/src/rt/thread.rs): `src/rt/thread.rs`
- [Operation locations](https://github.com/tokio-rs/loom/blob/master/src/rt/location.rs): `src/rt/location.rs`

### Modeled State

- [Modeled object store](https://github.com/tokio-rs/loom/blob/master/src/rt/object.rs): `src/rt/object.rs`
- [Atomic model](https://github.com/tokio-rs/loom/blob/master/src/rt/atomic.rs): `src/rt/atomic.rs`
- [Allocation tracking](https://github.com/tokio-rs/loom/blob/master/src/rt/alloc.rs): `src/rt/alloc.rs`
- [Lazy static state](https://github.com/tokio-rs/loom/blob/master/src/rt/lazy_static.rs): `src/rt/lazy_static.rs`

### Concurrency Primitives

- [Sync primitives](https://github.com/tokio-rs/loom/blob/master/src/sync/mod.rs): `src/sync/mod.rs`
- [Atomic types](https://github.com/tokio-rs/loom/blob/master/src/sync/atomic/mod.rs): `src/sync/atomic/mod.rs`
- [Reference counting](https://github.com/tokio-rs/loom/blob/master/src/sync/arc.rs): `src/sync/arc.rs`
- [Mutexes](https://github.com/tokio-rs/loom/blob/master/src/sync/mutex.rs): `src/sync/mutex.rs`
- [Read-write locks](https://github.com/tokio-rs/loom/blob/master/src/sync/rwlock.rs): `src/sync/rwlock.rs`
- [Channels](https://github.com/tokio-rs/loom/blob/master/src/sync/mpsc.rs): `src/sync/mpsc.rs`
- [Notifications](https://github.com/tokio-rs/loom/blob/master/src/sync/notify.rs): `src/sync/notify.rs`
- [Condition variables](https://github.com/tokio-rs/loom/blob/master/src/sync/condvar.rs): `src/sync/condvar.rs`
- [Barriers](https://github.com/tokio-rs/loom/blob/master/src/sync/barrier.rs): `src/sync/barrier.rs`
- [Modeled cells](https://github.com/tokio-rs/loom/blob/master/src/cell/cell.rs): `src/cell/cell.rs`

### Other components

- **Concurrent test author**

## Connections

- Concurrent test author → Model runner: defines model (evidence: `README.md`)
- Model runner → Runtime coordination: starts execution (evidence: `src/model.rs`)
- Thread API → Runtime coordination: uses runtime (evidence: `src/thread.rs`)
- Future utilities → Runtime coordination: waits via runtime (evidence: `src/future/mod.rs`)
- Cell API → Runtime coordination: models access (evidence: `src/cell/unsafe_cell.rs`)
- Scheduling hints → Thread API: yields through (evidence: `src/hint.rs`)
- Runtime coordination → Execution state: runs closures (evidence: `src/rt/mod.rs`)
- Execution state → Path exploration: branches through (evidence: `src/rt/execution.rs`)
- Execution state → Thread state: tracks threads (evidence: `src/rt/execution.rs`)
- Execution state → Modeled object store: tracks objects (evidence: `src/rt/execution.rs`)
- Execution state → Thread scheduler: dispatches scheduling
- Runtime coordination → Thread scheduler: switches threads (evidence: `src/rt/mod.rs`)
- Execution state → Operation locations: uses locations (evidence: `src/rt/execution.rs`)
- Atomic types → Atomic model: models operations (evidence: `src/sync/atomic/mod.rs`)
- Atomic model → Modeled object store: updates state (evidence: `src/rt/atomic.rs`)
- Sync primitives → Reference counting: exports type (evidence: `src/sync/mod.rs`)
- Sync primitives → Atomic types: exports types (evidence: `src/sync/mod.rs`)
- Sync primitives → Mutexes: exports type (evidence: `src/sync/mod.rs`)
- Sync primitives → Read-write locks: exports type (evidence: `src/sync/mod.rs`)
- Sync primitives → Channels: exports type (evidence: `src/sync/mod.rs`)
- Sync primitives → Notifications: exports type (evidence: `src/sync/mod.rs`)
- Sync primitives → Condition variables: exports type (evidence: `src/sync/mod.rs`)
- Sync primitives → Barriers: exports type (evidence: `src/sync/mod.rs`)
- Modeled cells → Cell API: uses cell implementation (evidence: `src/cell/mod.rs`)
- Lazy static state → Execution state: stores per execution (evidence: `src/rt/lazy_static.rs`)
- Allocation tracking → Execution state: tracks allocations (evidence: `src/rt/execution.rs`)
