# bandicm/asynco architecture

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

## Overview

##### Main Components
- Library Core / Asynchronous Engine: Represent the heart of the library that initializes and runs the asynchronous engine (see _asynco_engine.run() in the examples). This core component will manage the overall asynchronous workflow.
- Timers / Scheduler: Identify components for periodic and delayed actions. This part is responsible for scheduling asynchronous timer-based callbacks and keeping track of ticks or expiration states.
- Asynchronous File I/O: Represent a module (or external subsystem) for asynchronous file read and write operations, which internally can leverage ASIO functionality.
- External Dependencies / ASIO: Note that the library is based on Boost ASIO; include a block or annotation that the asynchronous operations and the event loops rely on underlying ASIO services.

##### Relationships and Interactions
- How asynchronous timer requests pass to a Scheduler component, which, in turn, signals the designated Event Loop in a particular thread.
- For events, show callbacks being registered with Trigger objects, and then events (ticks) being emitted and delivered to those callbacks.

##### Architectural Patterns and Design Principles
- Modular, header-only design which means that while some logic lives in headers (lib folder), the core mechanics (implementation in src) can be thought of as a “behind the scenes” engine managing asynchronous operations.
- The design follows a decoupled pattern where different aspects (thread management, event scheduling, asynchronous operations) are separate yet interrelated – similar in spirit to microservice modules within a single library.
- Mention the use of callbacks/lambda functions, promises & futures (for await_), and the inheritance pattern for extending event triggers (as seen in the examples with custom classes).

##### Essential Elements to Capture
- That the client uses functions like async_ and await_ to interact with the engine.
- The engine’s output is the resulting asynchronous operations managing callbacks, timer executions, and file I/O events distributed across multiple parallel threads.
- The interplay between event triggers and their registered callbacks.
- Parameterization such as NUM_OF_RUNNERS as a configuration aspect for the thread pool.

- The Asynchronous Engine core that orchestrates the flow.
- A Thread Pool containing multiple Event Loops.
- A Scheduler for managing timer-based actions.
- An event-driven system (Triggers/Event Emitters) receiving and dispatching events.
- An Async File I/O component interfacing with the engine and ASIO.

## Diagram (Mermaid)

```mermaid
flowchart TD
    client["Client (async_/await_)"]:::client
    engine["Asynchronous Engine"]:::engine
    threadPool["Thread Pool Manager & Event Loops"]:::threadpool
    timers["Timers / Scheduler"]:::timers
    trigger["Event Emitter / Trigger System"]:::event
    fileIO["Asynchronous File I/O Module"]:::fileio
    asio["Boost ASIO Service"]:::asio

    client -->|"uses"| engine
    engine -->|"delegates"| threadPool
    engine -->|"schedules"| timers
    engine -->|"emits"| trigger
    engine -->|"handles"| fileIO
    timers -->|"signals"| threadPool
    trigger -->|"delivers"| engine
    fileIO -->|"utilizes"| asio
    threadPool -->|"runs"| asio

    click engine "https://github.com/bandicm/asynco/blob/dev/lib/engine.hpp"
    click engine "https://github.com/bandicm/asynco/blob/dev/src/engine.cpp"
    click threadPool "https://github.com/bandicm/asynco/blob/dev/lib/engine.hpp"
    click timers "https://github.com/bandicm/asynco/blob/dev/lib/timers.hpp"
    click timers "https://github.com/bandicm/asynco/blob/dev/src/timers.cpp"
    click trigger "https://github.com/bandicm/asynco/blob/dev/lib/trigger.hpp"
    click fileIO "https://github.com/bandicm/asynco/blob/dev/lib/filesystem.hpp"

    classDef client fill:#85C1E9,stroke:#154360,stroke-width:2px;
    classDef engine fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef threadpool fill:#A9DFBF,stroke:#117A65,stroke-width:2px;
    classDef timers fill:#FAD7A0,stroke:#BA4A00,stroke-width:2px;
    classDef event fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef fileio fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef asio fill:#E8DAEF,stroke:#6C3483,stroke-dasharray: 5 5,stroke-width:2px;
```
