# google/highway architecture

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

- Interactive diagram: https://gitdiagram.com/google/highway
- Repository: https://github.com/google/highway

## Overview

##### Main Components
- Library Core (Highway API): Represent the central SIMD operations API and its various functions (e.g., Zero/Set/Load, math operations, and others).
- Target-Specific Implementations: Show that the library supports many CPU targets (e.g., SSE2, AVX2, AVX3 variants, NEON, SVE, RVV, WASM). Indicate that multiple source files (inside the “hwy” directory and “hwy/ops”) implement these variants.
- Dispatch Mechanism: Separate static dispatch (via HWY_STATIC_DISPATCH) from dynamic dispatch (via HWY_DYNAMIC_DISPATCH) that generates function pointer tables along with target detection mechanisms.
- Utility and Contrib Modules: Display the “contrib” directory modules (such as image processing, math libraries, sorting, random, etc.) that provide additional high-level or domain-specific utilities built on top of the core.
- Build Infrastructure: Include components for building and testing (CMake, Bazel, debian packaging, and the CI/CD workflows defined in .github). This shows how the library is consistently built and validated via continuous integration.
- Examples and Tests: Illustrate the examples (under hwy/examples and tests directory) which demonstrate usage and serve as references for both benchmarking (like nanobenchmark.cc) and verifying correctness with unit tests (using googletest).

##### Relationships and Interactions
- That the Dispatch Layer detects the current CPU’s available instruction sets and dynamically maps to the appropriate implementation.
- Integration between contributor modules and the main Highway core, indicating dependency on common types and utilities.
- Build system as a standalone component that “drives” the core library compilation, testing, and documentation (with separate paths for CMake, Bazel, and packaging).
- External dependencies such as Google Test (for unit tests) and linking with external resources (vcpkg, package managers etc.).

##### Architectural Patterns and Design Principles
- Abstraction layer that decouples the API from the architecture-specific details. This abstraction is crucial to enabling both static and dynamic dispatch without changing the API from the user's perspective.
- Use of modular design by separating vector operations into different submodules (e.g., in “hwy/ops”, “hwy/contrib”).
- Use of configuration/build scripts (CMakeLists.txt, MODULE.bazel, WORKSPACE) that encapsulate environmental dependencies and setup.
- That testing and documentation are first-class citizens, with dedicated directories (tests, docs, g3doc) ensuring that changes are continuously verified across multiple architectures.

##### Relevant Technologies, Frameworks, and Libraries
- CMake as the primary build system (with scripts in cmake/).
- Bazel as an alternative build mechanism.
- GoogleTest for unit testing.
- Continuous integration tools defined in the .github/workflows (showing multi-platform build/test strategies).
- The use of different CPU dispatch macros and the interplay between compile-time and runtime target selection.
- Use of vcpkg and other packaging systems (as referenced in the README) for managing installation.

##### Additional Recommendations
- Being detailed is key: try to separate as many components as possible, for example, showing sub-components within the “hwy” directory (like “ops”, “contrib”, “tests”) and linking them with the core.
- Visual emphasis on the dual-dispatch method (static vs. dynamic) not only clarifies usage for the consumer but also the internal design trade-offs.
- Including notes or callouts for the build caveats mentioned in the README (such as special flags for Armv7, differences in handling 32-bit systems, etc.) to clarify environment-specific parts of the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Library"
        HCore("Highway Core API"):::core
        Dispatch("Dispatch Mechanism (Static_vs.Dynamic)"):::dispatch
        TS("Target-Specific Implementations"):::target
        HCore -->|"calls_dispatch"| Dispatch
        Dispatch -->|"selects"| TS
    end

    subgraph "Utility Modules"
        Contrib("Utility & Contrib Modules"):::contrib
        HCore -->|"uses_utilities"| Contrib
    end

    subgraph "Build & Test"
        Build("Build Infrastructure"):::build
        Examples("Examples"):::example
        Tests("Unit Tests"):::example
        Build -->|"builds_core"| HCore
        Build -->|"builds_dispatch"| Dispatch
        Build -->|"builds_targets"| TS
        Build -->|"builds_utilities"| Contrib
        Examples -->|"demonstrates"| HCore
        Tests -->|"verifies"| HCore
    end

    subgraph "External Dependencies"
        GT("GoogleTest_&_Packages"):::external
        Tests -->|"runs_on"| GT
    end

    click HCore "https://github.com/google/highway/blob/master/hwy/highway.h"
    click TS "https://github.com/google/highway/tree/master/hwy/ops"
    click Dispatch "https://github.com/google/highway/blob/master/hwy/targets.cc"
    click Contrib "https://github.com/google/highway/tree/master/hwy/contrib"
    click Build "https://github.com/google/highway/blob/master/CMakeLists.txt"
    click Examples "https://github.com/google/highway/tree/master/hwy/examples"
    click Tests "https://github.com/google/highway/tree/master/hwy/tests"

    classDef core stroke:#333,stroke-width:2px,fill:#AED6F1;
    classDef dispatch stroke:#333,stroke-width:2px,fill:#F9E79F;
    classDef target stroke:#333,stroke-width:2px,fill:#F5B7B1;
    classDef contrib stroke:#333,stroke-width:2px,fill:#D7BDE2;
    classDef build stroke:#333,stroke-width:2px,fill:#ABEBC6;
    classDef example stroke:#333,stroke-width:2px,fill:#FAD7A0;
    classDef external stroke:#333,stroke-width:2px,fill:#D6EAF8;
```
