ThreadRace README

README проекта с github.com/AhmadHassan-BTed/ThreadRace. Одним файлом markdown: README.md.

ThreadRace

A C++ Concurrency Telemetry Framework & Execution Speed Tester

License: MIT C++11 Build

Time is a non-renewable, precious human resource. ThreadRace is designed to measure, analyze, and visualize the performance differential between sequential and parallel execution paradigms.

Philosophy • Demonstration • Architecture • Workflow • Repository Structure • Build & Run • Contributing


Philosophy

In daily human life, tasks are split and executed simultaneously to conserve time-cooking while listening to audio, or thinking about future plans while walking. ThreadRace is an engineering reflection of this fundamental human urge: the quest for concurrency.

By comparing Typical (Sequential) execution with Threaded (Parallel) execution, ThreadRace measures the efficiency of digital cooperation. The Ackermann Function-a deeply recursive mathematical operation-is utilized as a benchmark task to represent high-complexity, processor-intensive operations that demand efficient thread synchronization and compute optimization.


Visual Showcase & Demonstration

ThreadRace provides high-precision CLI timing telemetry alongside a 60 FPS Native C++ SDL2 + OpenGL Hardware-Accelerated Visualizer Suite (bin/ackermann_visualizer).

Visualizer Suite Modes

Mode 1: Quantum Branching Network (2D/3D Force Tree)
Quantum Branching Network Mode

Displays the dynamic recursive execution tree with glowing OpenGL nodes, Bezier branch curves, starburst particles on base-case evaluations, and real-time camera tracking.


Mode 2: Hyper-Logarithmic 3D Landscape (OpenGL Terrain Height Map)
Hyper-Logarithmic 3D Landscape Mode

Visualizes Ackermann growth $A(m, n)$ on a 3D height field terrain log-compressed using $Z(m, n) = \ln(1 + \ln(1 + A(m, n)))$.


Mode 3: Golden Spiral Phase Orbit
Golden Spiral Phase Orbit Mode

Maps call stack depth and frame steps onto a logarithmic golden ratio $\phi$ particle galaxy with glowing orbit trails and depth rings.


Mode 4: Head-to-Head Thread Race Arena
Head-to-Head Thread Race Arena Mode

Direct side-by-side competition comparing Sequential (1 Thread) vs. Parallel Execution, showing active threads, memory footprint, speedup telemetry, step progress bars, and finish line detection.


Execution Benchmark CLI Outputs

Regular Execution Benchmark Output
Regular Execution Speed (Typical vs Threaded)

Ackermann Function Benchmark Telemetry (m=4, n=1)
Sequential Ackermann Run Threaded Ackermann Run


Native C++ Ackermann Visualizer Suite

The native visualizer suite (bin/ackermann_visualizer) bridges pure math, real-time audio synthesis, OpenGL graphic rendering, and threading telemetry into an immersive interactive application.

Key Features:

Build & Run Native C++ Visualizer:

make all
./bin/ackermann_visualizer [m] [n]

Keyboard & Mouse Controls:


Architecture Overview

The codebase uses clean object-oriented patterns isolating telemetry capture, computational task definitions, execution strategies, and visual rendering modules.

Static Structure (Class Relationships)

classDiagram
    class ITask {
        <<interface>>
        +execute()*
        +getName()* string
    }

    class IExecutionStrategy {
        <<interface>>
        +run(ITask, iterations)*
        +getStrategyName()* string
    }

    class AckermannTask {
        -int m
        -int n
        +execute()
        +getName() string
        -ackermann(m, n) int
    }

    class SequentialStrategy {
        +run(ITask, iterations)
    }

    class ThreadedStrategy {
        +run(ITask, iterations)
    }

    class Benchmarker {
        -IExecutionStrategy strategy
        +runBenchmark(ITask, iterations)
    }

    class AckermannStackEngine {
        -int m
        -int n
        +step()
        +getNodes()
        +getMetrics()
        +setEventCallback()
    }

    class RaceEngine {
        -int m
        -int n
        -int parallelWorkers
        +step(stepDelayMs, isPlaying)
        +getSequentialTelemetry()
        +getParallelTelemetry()
    }

    class AudioSynthesizer {
        +init()
        +playNote(depth, isResolve)
        +playComplete()
    }

    class QuantumTreeRenderer {
        +render(engine, camera)
        +spawnStarburst(x, y, r, g, b)
    }

    class Landscape3DRenderer {
        +render(m, n, camera)
    }

    class SpiralOrbitRenderer {
        +render(engine, camera)
    }

    class RaceArenaRenderer {
        +render(raceEngine, fontRenderer)
    }

    ITask <|-- AckermannTask : implements
    IExecutionStrategy <|-- SequentialStrategy : implements
    IExecutionStrategy <|-- ThreadedStrategy : implements
    Benchmarker --> IExecutionStrategy : uses
    IExecutionStrategy ..> ITask : executes
    RaceEngine --> AckermannStackEngine : uses
    QuantumTreeRenderer ..> AckermannStackEngine : renders
    Landscape3DRenderer ..> AckermannStackEngine : renders
    SpiralOrbitRenderer ..> AckermannStackEngine : renders
    RaceArenaRenderer ..> RaceEngine : renders
    AckermannStackEngine ..> AudioSynthesizer : triggers audio events

Internal Module Structure

%%{init: {'flowchart': {'curve': 'ortho'}}}%%
flowchart TD
    subgraph CoreAbstractions ["Core Abstractions & Drivers"]
        ITask["ITask Interface"]
        IExecutionStrategy["IExecutionStrategy Interface"]
        Benchmarker["Benchmarker Telemetry"]
        Main["main.cpp (time_tester)"]
    end

    subgraph StrategiesAndTasks ["Strategies & Benchmark Tasks"]
        AckermannTask["AckermannTask"]
        SequentialStrategy["SequentialStrategy"]
        ThreadedStrategy["ThreadedStrategy"]
    end

    subgraph VisualizerSuite ["Native C++ OpenGL/SDL2 Visualizer Suite"]
        VisMain["visualizer_main.cpp (ackermann_visualizer)"]
        StackEngine["AckermannStackEngine"]
        RaceEngine["RaceEngine"]
        AudioSynth["AudioSynthesizer (SDL Audio Callback)"]
        FontRenderer["FontRenderer (Bitmap Text HUD)"]
        
        TreeRender["QuantumTreeRenderer (Mode 1)"]
        LandRender["Landscape3DRenderer (Mode 2)"]
        OrbitRender["SpiralOrbitRenderer (Mode 3)"]
        ArenaRender["RaceArenaRenderer (Mode 4)"]
    end

    AckermannTask -.-> ITask
    SequentialStrategy -.-> IExecutionStrategy
    ThreadedStrategy -.-> IExecutionStrategy
    Benchmarker --> IExecutionStrategy
    Main --> Benchmarker

    VisMain --> StackEngine
    VisMain --> RaceEngine
    VisMain --> AudioSynth
    VisMain --> FontRenderer
    VisMain --> TreeRender
    VisMain --> LandRender
    VisMain --> OrbitRender
    VisMain --> ArenaRender

System Workflow & Request Lifecycle

When a run is initiated via the command line, the execution flows through parsing, strategy instantiation, timed processing, and telemetry reporting.

sequenceDiagram
    participant User as Terminal CLI
    participant Main as main.cpp
    participant Bench as Benchmarker
    participant Strategy as IExecutionStrategy
    participant Task as ITask

    User->>Main: Execute program with mode & iterations
    Main->>Strategy: Instantiate (Sequential or Threaded)
    Main->>Task: Instantiate AckermannTask(4, 1)
    Main->>Bench: Instantiate with selected Strategy
    Main->>Bench: runBenchmark(Task, iterations)

    rect rgb(28, 30, 36)
        Note over Bench, Task: Telemetry Capture Span
        Bench->>Bench: Start high_resolution_clock timer
        Bench->>Strategy: run(Task, iterations)

        loop For each Iteration
            Strategy->>Task: execute()
            Task->>Task: Compute Ackermann value
            Task-->>Strategy: Return Result (65533)
        end

        Strategy-->>Bench: Return Control
        Bench->>Bench: Stop high_resolution_clock timer
    end

    Bench-->>User: Output timings (Real, User, System, CPU%)

Concurrency and Telemetry Specifications


Data & Request Lifecycle Flow

The parameters and runtime performance data flow through the framework as detailed below:

%%{init: {'flowchart': {'curve': 'ortho'}}}%%
flowchart LR
    Args[CLI Arguments] --> Parse[main.cpp Parse]
    Parse -->|Config Object| Strategy[Strategy Config]
    Parse -->|Parameters| Task[Task Config]

    subgraph TelemetryContext ["Telemetry & Performance Evaluation"]
        Strategy --> RunStrategy[Execute Strategy::run]
        Task --> RunStrategy

        RunStrategy --> Timer[Start Chrono Clock]
        Timer --> CoreComputation[Task::execute Iterations]
        CoreComputation --> TimerStop[Stop Chrono Clock]
    end

    TimerStop --> Metrics[Compute Telemetry Metrics]
    Metrics --> Terminal[Format & Output Terminal Report]

Repository Structure

The physical layout isolates public include headers, logic implementations, graphics assets, and compiled targets:

ThreadRace/
├── .editorconfig
├── .gitignore
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── Makefile
├── README.md
├── SECURITY.md
├── assets/
│   ├── Visualization1.png    # Mode 1: Quantum Tree Screenshot
│   ├── Visualization2.png    # Mode 2: 3D Landscape Screenshot
│   ├── Visualization3.png    # Mode 3: Spiral Orbit Screenshot
│   ├── Visualization4.png    # Mode 4: Thread Race Arena Screenshot
│   ├── ack-1.png             # Sequential Ackermann CLI Output
│   ├── ack-2.png             # Threaded Ackermann CLI Output
│   └── reg.png               # Regular Benchmark CLI Output
├── docs/
│   ├── architecture.md       # High-Level Design & Visualizer System Architecture
│   └── development.md        # Build Instructions & Test Protocols
├── include/
│   ├── Benchmarker.hpp
│   ├── core/
│   │   ├── IExecutionStrategy.hpp
│   │   └── ITask.hpp
│   ├── strategies/
│   │   ├── SequentialStrategy.hpp
│   │   └── ThreadedStrategy.hpp
│   ├── tasks/
│   │   └── AckermannTask.hpp
│   └── visualizer/
│       ├── AckermannStackEngine.hpp
│       ├── AudioSynthesizer.hpp
│       ├── FontRenderer.hpp
│       ├── Landscape3DRenderer.hpp
│       ├── QuantumTreeRenderer.hpp
│       ├── RaceArenaRenderer.hpp
│       ├── RaceEngine.hpp
│       └── SpiralOrbitRenderer.hpp
├── bin/                      # Compiled Executables (time_tester, ackermann_visualizer)
├── obj/                      # Compiled Object Files
└── src/
    ├── Benchmarker.cpp
    ├── main.cpp
    ├── strategies/
    │   ├── SequentialStrategy.cpp
    │   └── ThreadedStrategy.cpp
    ├── tasks/
    │   └── AckermannTask.cpp
    └── visualizer/
        ├── AckermannStackEngine.cpp
        ├── AudioSynthesizer.cpp
        ├── FontRenderer.cpp
        ├── Landscape3DRenderer.cpp
        ├── QuantumTreeRenderer.cpp
        ├── RaceArenaRenderer.cpp
        ├── RaceEngine.cpp
        ├── SpiralOrbitRenderer.cpp
        └── visualizer_main.cpp

Build & Execution Pipeline

The compilation process is managed by a POSIX-compliant Makefile, compiling C++ files with production optimizations (-O2).

%%{init: {'flowchart': {'curve': 'ortho'}}}%%
flowchart TD
    SrcMain["src/main.cpp"] -->|g++ -c| ObjMain["obj/main.o"]
    SrcBench["src/Benchmarker.cpp"] -->|g++ -c| ObjBench["obj/Benchmarker.o"]
    SrcStrat["src/strategies/*.cpp"] -->|g++ -c| ObjStrat["obj/*.o"]
    SrcTasks["src/tasks/*.cpp"] -->|g++ -c| ObjTasks["obj/*.o"]

    ObjMain -->|g++ Linker| Bin["bin/time_tester"]
    ObjBench -->|g++ Linker| Bin
    ObjStrat -->|g++ Linker| Bin
    ObjTasks -->|g++ Linker| Bin

Compilation

Compile the source code using the provided Makefile:

make all

Running Benchmarks

Run the binary with execution strategy modes and iteration count:

Command Execution Model Description
./bin/time_tester 1 Sequential (Typical) Tasks run sequentially in a single execution thread.
./bin/time_tester 2 Parallel (Threaded) Tasks run concurrently across multiple threads.

Custom iterations can be appended as a trailing argument (defaults to 3):

# Execute threaded strategy with 5 iterations
./bin/time_tester 2 5

Development Workflow

Contributors are welcome to submit improvements or add new performance benchmarks. The following pipeline ensures stability:

1. Functional Verification

Ensure the core Ackermann output calculation remains functional and math-accurate:

  • Ackermann(4, 1) must return 65533.
2. Concurrency Stress Testing

Verify stability under threaded loads:

  • Execute mode 2 with a high number of iterations to test against thread leaks or runtime race conditions.
3. CI/CD Integration

On every push or pull request to the main branch, a GitHub Action is triggered to:

  • Configure a clean Ubuntu runner.
  • Validate system compilation with make.
  • Execute regression benchmarks with make test.

Credits & Dedication

ThreadRace was created and engineered by Ahmad Hassan (B-Ted).
Dedicated to the beauty and clarity of highly efficient, low-overhead systems.

ThreadRace (AhmadHassan-BTed/ThreadRace)

Ищем в базе…

Что это такое?ThreadRace — это фреймворк на C++, который измеряет и визуализирует, насколько параллельное (многопоточное) выполнение быстрее последовательного. В качестве нагрузки используется рекурсивная функция Аккермана.
Это просто бенчмарк для командной строки или у него есть и графическая часть?Есть и то, и другое: инструмент для замера времени в командной строке и отдельное нативное приложение-визуализатор на C++ (bin/ackermannvisualizer), которое в реальном времени отрисовывает рекурсию и гонку потоков с помощью SDL2 и OpenGL.
Как собрать и запустить это?Соберите программу с помощью прилагаемого POSIX-совместимого Makefile, затем запустите полученный бинарный файл с флагом режима выполнения, например './bin/timetester 1' для последовательного или './bin/timetester 2' для параллельного режима, с необязательным аргументом количества итераций.
Что нужно установить, чтобы собрать и запустить визуализатор?Для самого бенчмарка нужен только компилятор с поддержкой C++11 (std::thread, std::chrono, умные указатели), а для отдельного набора визуализатора дополнительно требуются SDL2 и OpenGL для отрисовки и звука.
Бенчмарк отражает реальные нагрузки или это скорее стресс-тест?Он построен на функции Аккермана — глубоко рекурсивной синтетической функции, которую выбрали специально, чтобы проверять синхронизацию потоков и оптимизацию вычислений, а не чтобы имитировать типичные нагрузки приложений.
Это собирается и тестируется только под Linux?Сборка выполняется по POSIX-совместимому Makefile, а CI-конвейер собирает и тестирует проект на раннере Ubuntu; о поддержке Windows или macOS не упоминается.
Что на самом деле показывают четыре режима визуализатора?Режим 1 рисует двумерное или трёхмерное силовое дерево рекурсивного стека вызовов. Режим 2 показывает рост функции Аккермана в виде логарифмически сжатого трёхмерного рельефа. Режим 3 отображает глубину вызовов на орбиту по спирали золотого сечения. Режим 4 — это арена бок о бок, где последовательное и параллельное выполнение соревнуются друг с другом, с телеметрией ускорения в реальном времени.
Издаёт ли программа какие-нибудь звуки во время работы?Да, в визуализаторе есть полифоническая звуковая сонификация: он в реальном времени синтезирует ноты до мажорной пентатоники по мере того, как рекурсивный стек наращивается и разрешается. Переключается клавишей M.
Как проверяется корректность бенчмарка?Функциональная проверка проекта требует, чтобы Ackermann(4, 1) возвращала ровно 65533, а GitHub Action запускает эту проверку на регрессию при каждом push или pull request в ветку main.
Какие есть похожие проекты?taichi, conc, concurrentqueue, Gource, taskflow, CPlusPlusThings, locust, ps2-web-recomp
Размер
3.1 MB
Звёзды
4.7K
Обновлён
КоммитAug 07
Возраст
2 г
Коммиты · 90 дней