# snowdeenn/weave architecture

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

- Interactive diagram: https://gitdiagram.com/snowdeenn/weave
- Repository: https://github.com/snowdeenn/weave

## Overview

Weave is a Rust parallel-computing library. Its principal workflow builds a thread pool, submits work or installs a parallel iterator computation, and returns results through handles or iterator terminals. The scheduler supports priorities, work stealing, scoped borrowed tasks, and worker-local state; separate capabilities describe hardware topology and allocate NUMA-aware buffers. The graph preserves documented platform backends and iterator stages. Some runtime wiring is documented only in the README; unsampled implementation details are not inferred.

Main entry points: [`src/pool.rs`](https://github.com/snowdeenn/weave/blob/main/src/pool.rs) (Thread pool), [`src/topology/mod.rs`](https://github.com/snowdeenn/weave/blob/main/src/topology/mod.rs) (Topology model), [`src/layout.rs`](https://github.com/snowdeenn/weave/blob/main/src/layout.rs) (Worker layout), [`src/memory/buffer.rs`](https://github.com/snowdeenn/weave/blob/main/src/memory/buffer.rs) (NUMA buffer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Task execution"]
  node_builder["Pool builder<br/>[builder.rs]"]
  node_pool["Thread pool<br/>[pool.rs]"]
  node_job["Jobs and priorities<br/>[job.rs]"]
  node_queues["Work scheduler<br/>[pool.rs]"]
  node_deque["Task deque<br/>[deque.rs]"]
  node_scope["Scoped tasks<br/>[scope.rs]"]
  node_handle["Join handles<br/>[handle.rs]"]
  node_steal["Steal policy<br/>[steal.rs]"]
end

subgraph group_parallel["Parallel iteration"]
  node_iterator["Parallel sources<br/>[range.rs]"]
  node_slices["Slice sources<br/>[slice.rs]"]
  node_adapters["Lazy adapters<br/>[adaptator.rs]"]
  node_terminals["Iterator terminals<br/>[mod.rs]"]
end

subgraph group_hardware["Hardware placement"]
  node_topology["Topology model<br/>[mod.rs]"]
  node_linux_topology["Linux discovery<br/>[linux.rs]"]
  node_windows_topology["Windows discovery<br/>[windows.rs]"]
  node_layout["Worker layout<br/>[layout.rs]"]
  node_affinity_linux["Linux affinity<br/>[linux.rs]"]
  node_affinity_windows["Windows affinity<br/>[windows.rs]"]
end

subgraph group_memory["NUMA memory"]
  node_numa_buffer["NUMA buffer<br/>[buffer.rs]"]
  node_memory_linux["Linux memory<br/>[linux.rs]"]
  node_memory_windows["Windows memory<br/>[windows.rs]"]
end

subgraph group_state["Worker state"]
  node_worker_local[("Worker-local storage<br/>[local.rs]")]
end

node_user(("Rust caller"))
node_sysfs["Linux sysfs"]
node_windows_api["Windows APIs"]

node_user -->|"configures"| node_builder
node_builder -->|"builds"| node_pool
node_user -->|"submits work"| node_pool
node_pool -->|"schedules"| node_job
node_pool -->|"dispatches"| node_queues
node_queues -.->|"uses"| node_deque
node_pool -->|"returns handle"| node_handle
node_user -->|"starts scope"| node_scope
node_scope -->|"submits descendants"| node_pool
node_pool -->|"uses policy"| node_steal
node_user -->|"creates range"| node_iterator
node_user -->|"iterates slice"| node_slices
node_iterator -->|"transforms lazily"| node_adapters
node_slices -->|"transforms lazily"| node_adapters
node_adapters -->|"drives computation"| node_terminals
node_terminals -->|"uses current pool"| node_pool
node_user -->|"discovers topology"| node_topology
node_topology -->|"dispatches to"| node_linux_topology
node_topology -->|"dispatches to"| node_windows_topology
node_linux_topology -->|"reads topology"| node_sysfs
node_windows_topology -->|"queries processor data"| node_windows_api
node_topology -->|"informs placement"| node_layout
node_layout -->|"pins workers"| node_affinity_linux
node_layout -.->|"pins workers"| node_affinity_windows
node_layout -->|"guides steal order"| node_steal
node_user -->|"allocates buffer"| node_numa_buffer
node_numa_buffer -->|"maps storage"| node_memory_linux
node_numa_buffer -->|"maps storage"| node_memory_windows
node_memory_linux -->|"checks nodes"| node_topology
node_memory_windows -->|"allocates on node"| node_windows_api
node_user -->|"creates local state"| node_worker_local
node_worker_local -->|"binds to pool"| node_pool

click node_builder "https://github.com/snowdeenn/weave/blob/main/src/builder.rs"
click node_pool "https://github.com/snowdeenn/weave/blob/main/src/pool.rs"
click node_job "https://github.com/snowdeenn/weave/blob/main/src/job.rs"
click node_queues "https://github.com/snowdeenn/weave/blob/main/src/pool.rs"
click node_deque "https://github.com/snowdeenn/weave/blob/main/src/deque.rs"
click node_scope "https://github.com/snowdeenn/weave/blob/main/src/scope.rs"
click node_handle "https://github.com/snowdeenn/weave/blob/main/src/handle.rs"
click node_steal "https://github.com/snowdeenn/weave/blob/main/src/steal.rs"
click node_iterator "https://github.com/snowdeenn/weave/blob/main/src/iterator/range.rs"
click node_slices "https://github.com/snowdeenn/weave/blob/main/src/iterator/slice.rs"
click node_adapters "https://github.com/snowdeenn/weave/blob/main/src/iterator/adaptator.rs"
click node_terminals "https://github.com/snowdeenn/weave/blob/main/src/iterator/mod.rs"
click node_topology "https://github.com/snowdeenn/weave/blob/main/src/topology/mod.rs"
click node_linux_topology "https://github.com/snowdeenn/weave/blob/main/src/topology/linux.rs"
click node_windows_topology "https://github.com/snowdeenn/weave/blob/main/src/topology/windows.rs"
click node_layout "https://github.com/snowdeenn/weave/blob/main/src/layout.rs"
click node_affinity_linux "https://github.com/snowdeenn/weave/blob/main/src/affinity/linux.rs"
click node_affinity_windows "https://github.com/snowdeenn/weave/blob/main/src/affinity/windows.rs"
click node_numa_buffer "https://github.com/snowdeenn/weave/blob/main/src/memory/buffer.rs"
click node_memory_linux "https://github.com/snowdeenn/weave/blob/main/src/memory/linux.rs"
click node_memory_windows "https://github.com/snowdeenn/weave/blob/main/src/memory/windows.rs"
click node_worker_local "https://github.com/snowdeenn/weave/blob/main/src/storage/local.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_builder,node_pool,node_job,node_queues,node_deque,node_scope,node_handle,node_steal toneBlue
class node_iterator,node_slices,node_adapters,node_terminals toneAmber
class node_topology,node_linux_topology,node_windows_topology,node_layout,node_affinity_linux,node_affinity_windows,node_windows_api toneMint
class node_numa_buffer,node_memory_linux,node_memory_windows toneRose
class node_worker_local,node_user,node_sysfs toneIndigo
```

## Components

### Task execution

- [Pool builder](https://github.com/snowdeenn/weave/blob/main/src/builder.rs): `src/builder.rs`
- [Thread pool](https://github.com/snowdeenn/weave/blob/main/src/pool.rs): `src/pool.rs`
- [Jobs and priorities](https://github.com/snowdeenn/weave/blob/main/src/job.rs): `src/job.rs`
- [Work scheduler](https://github.com/snowdeenn/weave/blob/main/src/pool.rs): `src/pool.rs`
- [Task deque](https://github.com/snowdeenn/weave/blob/main/src/deque.rs): `src/deque.rs`
- [Scoped tasks](https://github.com/snowdeenn/weave/blob/main/src/scope.rs): `src/scope.rs`
- [Join handles](https://github.com/snowdeenn/weave/blob/main/src/handle.rs): `src/handle.rs`
- [Steal policy](https://github.com/snowdeenn/weave/blob/main/src/steal.rs): `src/steal.rs`

### Parallel iteration

- [Parallel sources](https://github.com/snowdeenn/weave/blob/main/src/iterator/range.rs): `src/iterator/range.rs`
- [Slice sources](https://github.com/snowdeenn/weave/blob/main/src/iterator/slice.rs): `src/iterator/slice.rs`
- [Lazy adapters](https://github.com/snowdeenn/weave/blob/main/src/iterator/adaptator.rs): `src/iterator/adaptator.rs`
- [Iterator terminals](https://github.com/snowdeenn/weave/blob/main/src/iterator/mod.rs): `src/iterator/mod.rs`

### Hardware placement

- [Topology model](https://github.com/snowdeenn/weave/blob/main/src/topology/mod.rs): `src/topology/mod.rs`
- [Linux discovery](https://github.com/snowdeenn/weave/blob/main/src/topology/linux.rs): `src/topology/linux.rs`
- [Windows discovery](https://github.com/snowdeenn/weave/blob/main/src/topology/windows.rs): `src/topology/windows.rs`
- [Worker layout](https://github.com/snowdeenn/weave/blob/main/src/layout.rs): `src/layout.rs`
- [Linux affinity](https://github.com/snowdeenn/weave/blob/main/src/affinity/linux.rs): `src/affinity/linux.rs`
- [Windows affinity](https://github.com/snowdeenn/weave/blob/main/src/affinity/windows.rs): `src/affinity/windows.rs`

### NUMA memory

- [NUMA buffer](https://github.com/snowdeenn/weave/blob/main/src/memory/buffer.rs): `src/memory/buffer.rs`
- [Linux memory](https://github.com/snowdeenn/weave/blob/main/src/memory/linux.rs): `src/memory/linux.rs`
- [Windows memory](https://github.com/snowdeenn/weave/blob/main/src/memory/windows.rs): `src/memory/windows.rs`

### Worker state

- [Worker-local storage](https://github.com/snowdeenn/weave/blob/main/src/storage/local.rs): `src/storage/local.rs`

### Other components

- **Rust caller**
- **Linux sysfs**
- **Windows APIs**

## Connections

- Rust caller → Pool builder: configures (evidence: `README.md`)
- Pool builder → Thread pool: builds (evidence: `README.md`)
- Rust caller → Thread pool: submits work (evidence: `README.md`)
- Thread pool → Jobs and priorities: schedules (evidence: `src/pool.rs`)
- Thread pool → Work scheduler: dispatches (evidence: `README.md`)
- Work scheduler → Task deque: uses
- Thread pool → Join handles: returns handle (evidence: `src/pool.rs`)
- Rust caller → Scoped tasks: starts scope (evidence: `README.md`)
- Scoped tasks → Thread pool: submits descendants (evidence: `src/scope.rs`)
- Thread pool → Steal policy: uses policy (evidence: `src/pool.rs`)
- Rust caller → Parallel sources: creates range (evidence: `README.md`)
- Rust caller → Slice sources: iterates slice (evidence: `README.md`)
- Parallel sources → Lazy adapters: transforms lazily (evidence: `src/iterator/mod.rs`)
- Slice sources → Lazy adapters: transforms lazily (evidence: `src/iterator/mod.rs`)
- Lazy adapters → Iterator terminals: drives computation (evidence: `src/iterator/mod.rs`)
- Iterator terminals → Thread pool: uses current pool (evidence: `README.md`)
- Rust caller → Topology model: discovers topology (evidence: `README.md`)
- Topology model → Linux discovery: dispatches to (evidence: `src/topology/mod.rs`)
- Topology model → Windows discovery: dispatches to (evidence: `src/topology/mod.rs`)
- Linux discovery → Linux sysfs: reads topology (evidence: `README.md`)
- Windows discovery → Windows APIs: queries processor data (evidence: `src/topology/windows.rs`)
- Topology model → Worker layout: informs placement (evidence: `README.md`)
- Worker layout → Linux affinity: pins workers (evidence: `README.md`)
- Worker layout → Windows affinity: pins workers
- Worker layout → Steal policy: guides steal order (evidence: `README.md`)
- Rust caller → NUMA buffer: allocates buffer (evidence: `README.md`)
- NUMA buffer → Linux memory: maps storage (evidence: `src/memory/buffer.rs`)
- NUMA buffer → Windows memory: maps storage (evidence: `src/memory/buffer.rs`)
- Linux memory → Topology model: checks nodes (evidence: `src/memory/linux.rs`)
- Windows memory → Windows APIs: allocates on node (evidence: `src/memory/windows.rs`)
- Rust caller → Worker-local storage: creates local state (evidence: `README.md`)
- Worker-local storage → Thread pool: binds to pool (evidence: `src/storage/local.rs`)