# rayon-rs/rayon architecture

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

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

## Overview

##### High-level components
- Rayon API crate (“rayon” in the top-level `src/`)
- Core runtime crate (`rayon-core/`)
- Demo application crate (`rayon-demo/`)
- CI/tooling crates (`ci/alt-core/`, `ci/highlander/`)
- Build & test orchestrator (Cargo + GitHub Actions)
- External environment: OS threads, target platforms (native, WASM)

##### Relationships and data flow
- The **Demo app** (rayon-demo) depends on the **Rayon API** crate.
- The **API crate** (top-level) exports the public `par_iter`, `join`, `scope`, etc., and depends on **rayon-core**.
- **rayon-core** implements the work-stealing **thread pool**, **job scheduler**, **task registry**, **latches**, etc., and issues OS-thread calls.
- CI crates (`alt-core`, `highlander`) are alternate or supplementary build/test harnesses that also depend on **rayon-core** or provide custom build logic.
- **GitHub Actions** workflows invoke `cargo build`, `cargo test`, run the CI crates, and deploy documentation.
- The **WASM adapter** (not in tree but documented) would sit alongside the core runtime, routing threading calls to a JS thread pool or fall back to sequential.

##### Architectural patterns
- **Layered**
– Presentation/API layer (public prelude, iterator adapters in `src/iter`, `src/collections`)
– Runtime layer (`rayon-core` thread_pool, scheduler, job, registry modules)
– OS layer (actual threads, synchronization primitives)
- **Modular**: each parallel operator (map, filter, join, scope) is its own module under `src/iter` or `rayon-core/src`
- **Work-stealing** scheduler pattern in `rayon-core/src/thread_pool`
- **Zero-cost abstraction**: most of the API is compile-time plumbing, falling back to no-op or sequential execution on unsupported targets.

##### Relevant technologies & tools
- Rust & Cargo (crate-based compilation, workspace)
- GitHub Actions CI (`.github/workflows/*.yaml`)
- Shell scripts (`ci/highlander.sh`, `scripts/analyze.sh`)
- Platform adapters (Unix vs. Windows in `rayon-demo/src/cpu_time`)
- Testing harness (`tests/` directories in each crate)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Crates and Layers
    subgraph "API Crate (Public API)" 
        direction TB
        API_lib["lib.rs"]:::api
        API_prelude["prelude.rs"]:::api
        API_private["private.rs"]:::api
        API_iter["iter/*"]:::api
        API_collections["collections/*"]:::api
        API_join["join.rs"]:::api
        API_scope["scope.rs"]:::api
    end

    subgraph "Core Runtime Crate" 
        direction TB
        Core_lib["lib.rs"]:::core
        Core_private["private.rs"]:::core
        subgraph "thread_pool"
            direction TB
            Core_tp_mod["mod.rs"]:::core
            Core_tp_test["test.rs"]:::core
        end
        Core_registry["registry.rs"]:::core
        Core_job["job.rs"]:::core
        Core_latch["latch.rs"]:::core
        subgraph "spawn"
            direction TB
            Core_spawn_mod["mod.rs"]:::core
            Core_spawn_test["test.rs"]:::core
        end
        subgraph "sleep"
            direction TB
            Core_sleep_mod["mod.rs"]:::core
            Core_sleep_counters["counters.rs"]:::core
        end
        Core_unwind["unwind.rs"]:::core
        subgraph "join"
            direction TB
            Core_join_mod["mod.rs"]:::core
            Core_join_test["test.rs"]:::core
        end
        subgraph "scope"
            direction TB
            Core_scope_mod["mod.rs"]:::core
            Core_scope_test["test.rs"]:::core
        end
        subgraph "broadcast"
            direction TB
            Core_bcast_mod["mod.rs"]:::core
            Core_bcast_test["test.rs"]:::core
        end
    end

    subgraph "Demo App Crate" 
        direction TB
        Demo_main["main.rs"]:::demo
        Demo_lib["lib.rs"]:::demo
        subgraph "cpu_time"
            direction TB
            Demo_cpu_mod["mod.rs"]:::demo
            Demo_cpu_unix["unix.rs"]:::demo
            Demo_cpu_win["win.rs"]:::demo
        end
        Demo_examples["examples/*"]:::demo
        Demo_mods["example modules"]:::demo
    end

    subgraph "CI/Tooling Crates" 
        direction TB
        subgraph "alt-core"
            direction TB
            Alt_toml["Cargo.toml"]:::ci
            Alt_build["build.rs"]:::ci
            Alt_lib["lib.rs"]:::ci
        end
        subgraph "highlander"
            direction TB
            Hi_toml["Cargo.toml"]:::ci
            Hi_main["main.rs"]:::ci
            Hi_script["highlander.sh"]:::ci
        end
    end

    subgraph "Build & Test Orchestrator"
        direction TB
        GH_ci[".github/workflows/ci.yaml"]:::orchestrator
        GH_main[".github/workflows/main.yaml"]:::orchestrator
        GH_pr[".github/workflows/pr.yaml"]:::orchestrator
        Workspace_toml["Cargo.toml"]:::orchestrator
        Script_analyze["scripts/analyze.sh"]:::orchestrator
    end

    %% External Environment
    OS_threads["OS Threads"]:::external

    %% Connections
    Demo_main -->|"calls par_iter"| API_iter
    Demo_mods -->|"uses API"| API_lib
    API_lib -->|"depends on"| Core_lib
    API_iter -->|"compiles to runtime calls"| Core_spawn_mod
    Core_tp_mod -->|"spawns threads"| OS_threads
    Core_spawn_mod -->|"invokes"| OS_threads

    %% CI & Orchestrator dependencies
    GH_ci -->|"build/test"| API_lib
    GH_ci -->|"build/test"| Core_lib
    GH_ci -->|"build/test"| Demo_main
    GH_ci -->|"runs"| Alt_lib
    GH_ci -->|"runs"| Hi_main

    Script_analyze -->|"analyzes"| API_lib
    Script_analyze -->|"analyzes"| Core_lib

    %% Click Events
    click API_lib "https://github.com/rayon-rs/rayon/blob/main/src/lib.rs"
    click API_prelude "https://github.com/rayon-rs/rayon/blob/main/src/prelude.rs"
    click API_private "https://github.com/rayon-rs/rayon/blob/main/src/private.rs"
    click API_iter "https://github.com/rayon-rs/rayon/tree/main/src/iter/"
    click API_collections "https://github.com/rayon-rs/rayon/tree/main/src/collections/"
    click API_join "https://github.com/rayon-rs/rayon/blob/main/src/join.rs"
    click API_scope "https://github.com/rayon-rs/rayon/blob/main/src/scope.rs"

    click Core_lib "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/lib.rs"
    click Core_private "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/private.rs"
    click Core_tp_mod "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/thread_pool/mod.rs"
    click Core_tp_test "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/thread_pool/test.rs"
    click Core_registry "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/registry.rs"
    click Core_job "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/job.rs"
    click Core_latch "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/latch.rs"
    click Core_spawn_mod "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/spawn/mod.rs"
    click Core_spawn_test "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/spawn/test.rs"
    click Core_sleep_mod "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/sleep/mod.rs"
    click Core_sleep_counters "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/sleep/counters.rs"
    click Core_unwind "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/unwind.rs"
    click Core_join_mod "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/join/mod.rs"
    click Core_join_test "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/join/test.rs"
    click Core_scope_mod "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/scope/mod.rs"
    click Core_scope_test "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/scope/test.rs"
    click Core_bcast_mod "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/broadcast/mod.rs"
    click Core_bcast_test "https://github.com/rayon-rs/rayon/blob/main/rayon-core/src/broadcast/test.rs"

    click Demo_main "https://github.com/rayon-rs/rayon/blob/main/rayon-demo/src/main.rs"
    click Demo_lib "https://github.com/rayon-rs/rayon/blob/main/rayon-demo/src/lib.rs"
    click Demo_cpu_mod "https://github.com/rayon-rs/rayon/blob/main/rayon-demo/src/cpu_time/mod.rs"
    click Demo_cpu_unix "https://github.com/rayon-rs/rayon/blob/main/rayon-demo/src/cpu_time/unix.rs"
    click Demo_cpu_win "https://github.com/rayon-rs/rayon/blob/main/rayon-demo/src/cpu_time/win.rs"
    click Demo_examples "https://github.com/rayon-rs/rayon/tree/main/rayon-demo/examples/"
    click Demo_mods "https://github.com/rayon-rs/rayon/tree/main/rayon-demo/src/"

    click Alt_toml "https://github.com/rayon-rs/rayon/blob/main/ci/alt-core/Cargo.toml"
    click Alt_build "https://github.com/rayon-rs/rayon/blob/main/ci/alt-core/build.rs"
    click Alt_lib "https://github.com/rayon-rs/rayon/blob/main/ci/alt-core/src/lib.rs"
    click Hi_toml "https://github.com/rayon-rs/rayon/blob/main/ci/highlander/Cargo.toml"
    click Hi_main "https://github.com/rayon-rs/rayon/blob/main/ci/highlander/src/main.rs"
    click Hi_script "https://github.com/rayon-rs/rayon/blob/main/ci/highlander.sh"

    click GH_ci "https://github.com/rayon-rs/rayon/blob/main/.github/workflows/ci.yaml"
    click GH_main "https://github.com/rayon-rs/rayon/blob/main/.github/workflows/main.yaml"
    click GH_pr "https://github.com/rayon-rs/rayon/blob/main/.github/workflows/pr.yaml"
    click Workspace_toml "https://github.com/rayon-rs/rayon/blob/main/Cargo.toml"
    click Script_analyze "https://github.com/rayon-rs/rayon/blob/main/scripts/analyze.sh"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#0066CC,color:#000
    classDef core fill:#D6F5D6,stroke:#009900,color:#000
    classDef demo fill:#FFE5CC,stroke:#FF6600,color:#000
    classDef ci fill:#F2F2F2,stroke:#999,color:#000
    classDef orchestrator fill:#E5CCFF,stroke:#9933CC,color:#000
    classDef external fill:#FFFFFF,stroke:#666666,color:#000,stroke-dasharray: 5 5
```
