# amanieu/asyncplusplus architecture

> Architecture diagram of the GitHub repository amanieu/asyncplusplus, 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/amanieu/asyncplusplus
- Repository: https://github.com/amanieu/asyncplusplus

## Overview

##### Main Components
- API Layer: Represented by header files in the include directory (async++.h and the async++ subfolder). This is the public interface for the user.
- Task Management: This component abstracts the creation, chaining, and synchronization of tasks. It covers entities like task, task_base, and continuation_vector. These parts are central to executing user-defined operations.
- Scheduler Infrastructure: Key classes include scheduler.h, scheduler_fwd.h, and their respective implementation in src/scheduler.cpp. Moreover, the threadpool_scheduler (src/threadpool_scheduler.cpp) and related utilities like work_steal_queue are crucial for scheduling and load balancing.
- Parallel Algorithms: Components such as parallel_for, parallel_invoke, and parallel_reduce offer high-level parallelism. These depend on the underlying task and scheduler infrastructure.
- Internal Utilities: Lower-level details such as fifo_queue, aligned_alloc, and ref_count are part of the internal support system to manage memory allocation and synchronization.

##### Relationships and Interactions
- The API Layer exposes functions like async::spawn, when_all, or parallel algorithms that internally instantiate tasks.
- Task Management interacts with the Scheduler Infrastructure by queuing and dispatching tasks. This involves scheduling tasks across available threads, often using work stealing or FIFO queues.
- The Scheduler interacts with the thread pool scheduler and may use a work stealing mechanism to balance the load across threads.
- Parallel algorithms leverage both the Task Management and Scheduler Infrastructure to distribute work and reduce results across tasks.
- The internal components (e.g., aligned_alloc, ref_count, partitioner) support both task management and the scheduler.

##### Architectural Patterns and Design Principles
- Asynchronous Task Chaining: The design allows spawning tasks and chaining them with continuation patterns (see examples using then).
- Scheduler Abstraction: Provides flexibility to use different scheduling strategies (FIFO, threadpool, work stealing).
- Modular Design: Separation of concerns is evident–public API (headers), implementation (src), examples to illustrate usage.
- Concurrency & Parallelism: Emphasis on low-overhead, scalable concurrency mechanisms and parallel algorithms.

##### Including Relevant Technologies and Libraries
- C++11 standard features, including lambda expressions and thread support.
- Usage of CMake (CMakeLists.txt and Async++Config.cmake.in) for configuration and building.
- Platform-specific adaptations, e.g., workarounds for iOS threading.

- Clarity and capturing the essential architectural concepts; every component mentioned in the file structure and README should be represented.
- Use the documentation hinted at in the README (e.g., Tasks, Schedulers) to verify that no significant component is omitted.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "User API"
        A1("async++.h"):::api
        A2("async++ (Public Headers)"):::api
    end

    subgraph "Task Management"
        T1("task.h"):::task
        T2("task_base.h"):::task
        T3("continuation_vector.h"):::task
    end

    subgraph "Scheduler Infrastructure"
        S1("scheduler.h"):::scheduler
        S2("scheduler_fwd.h"):::scheduler
        S3("scheduler.cpp"):::scheduler
        S4("threadpool_scheduler.cpp"):::scheduler
        S5("work_steal_queue.h"):::scheduler
    end

    subgraph "Parallel Algorithms"
        P1("parallel_for.h"):::parallel
        P2("parallel_invoke.h"):::parallel
        P3("parallel_reduce.h"):::parallel
    end

    subgraph "Internal Utilities"
        I1("aligned_alloc.h"):::utilities
        I2("ref_count.h"):::utilities
        I3("partitioner.h"):::utilities
        I4("fifo_queue.h"):::utilities
    end

    A1 -->|"spawn_tasks"| T1
    A2 -->|"invokes"| P1
    T1 -->|"schedules"| S1
    P1 -->|"builds_on"| T1
    P1 -->|"builds_on"| S1
    S2 <-->|"internal_support"| I2

    classDef api fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef task fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef scheduler fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef parallel fill:#ffe6cc,stroke:#333,stroke-width:2px;
    classDef utilities fill:#e6ffe6,stroke:#333,stroke-width:2px;

    click A1 "https://github.com/amanieu/asyncplusplus/blob/master/include/async++.h"
    click A2 "https://github.com/amanieu/asyncplusplus/tree/master/include/async++"
    click T1 "https://github.com/amanieu/asyncplusplus/blob/master/include/async++/task.h"
    click T2 "https://github.com/amanieu/asyncplusplus/blob/master/include/async++/task_base.h"
    click T3 "https://github.com/amanieu/asyncplusplus/blob/master/include/async++/continuation_vector.h"
    click S1 "https://github.com/amanieu/asyncplusplus/blob/master/include/async++/scheduler.h"
    click S2 "https://github.com/amanieu/asyncplusplus/blob/master/include/async++/scheduler_fwd.h"
    click S3 "https://github.com/amanieu/asyncplusplus/blob/master/src/scheduler.cpp"
    click S4 "https://github.com/amanieu/asyncplusplus/blob/master/src/threadpool_scheduler.cpp"
    click S5 "https://github.com/amanieu/asyncplusplus/blob/master/src/work_steal_queue.h"
    click P1 "https://github.com/amanieu/asyncplusplus/blob/master/include/async++/parallel_for.h"
    click P2 "https://github.com/amanieu/asyncplusplus/blob/master/include/async++/parallel_invoke.h"
    click P3 "https://github.com/amanieu/asyncplusplus/blob/master/include/async++/parallel_reduce.h"
    click I1 "https://github.com/amanieu/asyncplusplus/blob/master/include/async++/aligned_alloc.h"
    click I2 "https://github.com/amanieu/asyncplusplus/blob/master/include/async++/ref_count.h"
    click I3 "https://github.com/amanieu/asyncplusplus/blob/master/include/async++/partitioner.h"
    click I4 "https://github.com/amanieu/asyncplusplus/blob/master/src/fifo_queue.h"
```
