# colinianking/stress-ng architecture

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

- Interactive diagram: https://gitdiagram.com/colinianking/stress-ng
- Repository: https://github.com/colinianking/stress-ng

## Overview

##### Project type and purpose
- Project “stress‑ng” is a POSIX/UNIX cross‑platform command‑line stress test tool written in C.
- It is an open‑source utility designed to exercise various physical subsystems (CPU, VM, I/O, etc.) and kernel interfaces by dispatching dozens of built‑in “stressors.”

##### File structure
- Top‑level build/config files: Dockerfile, Makefile*, Configure scripts, .github workflows, Debian packaging under debian/
- Core engine code under files prefixed core‑*.c/.h
- Stressor implementations under stress‑*.c/h
- Bash completion, example jobs, test/ unit tests, presentations, syscalls.txt
- No “frontend/backend” but a plugin‑style architecture: core engine + many stressor modules

##### README insights
- Describes features, supported platforms, build instructions, stressor classes (CPU, VM, I/O, etc.)

##### Components
a. Main components
- CLI Frontend – parses command‑line options (core-opts, core-parse-opts)
- Core Engine – dispatch loop, stressor scheduler, metrics collector (core-job, core-log, core-time, core-metrics)
- Stressor Modules – ~360 individual stressors (each stress‑*.c implements a stressor API)
- Build System – Makefiles, autoconf, platform detection, packaging (Dockerfile, Debian scripts)
- OS Kernel – syscalls and kernel interfaces (e.g., futex, mmap, perf events, io_uring)
- Hardware Subsystems – CPU, memory, caches, disks, network, thermal sensors, power/rapl

b. Relationships and interactions
- CLI Frontend → Core Engine: passes parsed parameters (class, count, timeout, metrics)
- Core Engine → Stressor Modules: “register” and “dispatch” calls to module init/run/teardown
- Stressor Modules → OS Kernel: invoke syscalls (sched, mmap, I/O, ftrace, cap, seccomp, etc.)
- OS Kernel → Hardware: executes instructions, drives peripherals
- Core Engine ← Metrics Collector ← Kernel counters/perf APIs
- Build System → Produces single unified binary embedding core + modules (static or dynamic)

c. Architectural patterns/design principles
- Plugin‑style modularization: each stressor is self‑contained and binds into core at compile‑time
- Layered design: CLI layer → engine layer → stressor layer → kernel → hardware
- Separation of concerns: parsing, scheduling, stress logic, logging, metrics
- Portable build tuning: conditional compilation via configure checks detects kernel features

d. Technologies/frameworks
- C/C++ compiler toolchain (gcc, clang, icc, musl-gcc, tcc, pcc)
- GNU Make, autoconf‑style scripts, cross‑compile support
- Debian packaging, GitHub Actions, Travis CI, Docker for container images
- POSIX APIs, Linux‑specific features (io_uring, perf, ftrace, cap, namespace)

##### Detailed capture of essential elements
- How core‑*.c/.h files implement the engine (job scheduler, option parsing, logging)
- How stress‑*.c files implement individual plug‑in modules
- Platform‑detection and conditional compilation paths in build system
- Runtime flow: parse → dispatch → stressor run → collect metrics → report

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Build & Config"
        BS[Build System]:::build
    end

    subgraph "User Space"
        CLI[CLI Parser]:::userspace
        Core[Core Engine]:::userspace
        subgraph "Stressor Modules"
            SM[Stressors]:::userspace
        end
        MC[Metrics Collector]:::userspace
    end

    Kernel[OS Kernel]:::kernel
    Hardware[Hardware Subsystems]:::hardware

    BS -->|"compile/link"| Core
    BS -->|"compile/link"| SM
    CLI -->|"parameters"| Core
    Core -->|"dispatch"| SM
    SM -->|"syscalls"| Kernel
    Kernel -->|"hardware ops"| Hardware
    Kernel -->|"perf data"| MC
    MC -->|"metrics"| Core

    click CLI "https://github.com/colinianking/stress-ng/blob/master/core-opts.c"
    click CLI "https://github.com/colinianking/stress-ng/blob/master/core-parse-opts.c"
    click Core "https://github.com/colinianking/stress-ng/blob/master/core-job.c"
    click Core "https://github.com/colinianking/stress-ng/blob/master/core-log.c"
    click Core "https://github.com/colinianking/stress-ng/blob/master/core-time.c"
    click Core "https://github.com/colinianking/stress-ng/blob/master/core-module.c"
    click Core "https://github.com/colinianking/stress-ng/blob/master/core-perf-event.c"
    click Core "https://github.com/colinianking/stress-ng/blob/master/core-perf.h"
    click SM "https://github.com/colinianking/stress-ng/blob/master/stress-cpu.c"
    click SM "https://github.com/colinianking/stress-ng/blob/master/stress-io-uring.c"
    click SM "https://github.com/colinianking/stress-ng/blob/master/stress-futex.c"
    click SM "https://github.com/colinianking/stress-ng/blob/master/stress-ng.c"
    click BS "https://github.com/colinianking/stress-ng/tree/master/Makefile"
    click BS "https://github.com/colinianking/stress-ng/tree/master/Dockerfile"
    click BS "https://github.com/colinianking/stress-ng/tree/master/debian/"
    click BS "https://github.com/colinianking/stress-ng/tree/master/.github/workflows/"
    click Kernel "https://github.com/colinianking/stress-ng/blob/master/syscalls.txt"

    classDef userspace fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef build fill:#90EE90,stroke:#000,stroke-width:1px
    classDef kernel fill:#FFA500,stroke:#000,stroke-width:1px
    classDef hardware fill:#D3D3D3,stroke:#000,stroke-width:1px
```
