# dermesser/uvco architecture

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

- Interactive diagram: https://gitdiagram.com/dermesser/uvco
- Repository: https://github.com/dermesser/uvco

## Overview

This project, “uvco”, is a C++20 library that provides ergonomic asynchronous abstractions by combining standard library coroutines with libuv’s event loop. Essentially, it’s an experimentation in building a high-performance async framework, with integrations for HTTP downloads (via libcurl), PostgreSQL interactions (via libpqxx), and standard asynchronous I/O (TCP, UDP, file operations, etc.).

##### Project Type and Purpose
- Project Type: A C++ asynchronous coroutine library.
- Purpose: To abstract libuv’s event-loop model using coroutines and promises, offering a low-overhead, intuitive asynchronous programming interface. This includes seamless integration with external libraries (for HTTP and database access) and support for various I/O operations.

##### File Structure
- Top-level files like CMakeLists.txt, Doxyfile, and configuration scripts indicate that this is a well-documented, build-managed library.
- The “uvco” directory contains the core source:
– Modules for asynchronous operations (e.g., async_work.cc, bounded_queue.h).
– The promise implementation is under uvco/promise (with multipromise and promise_core components).
– The event loop and scheduler reside in uvco/loop (loop.cc, scheduler.cc) and are central to the library’s operation.
– I/O abstractions such as TCP, UDP, stream, and file system operations are in their respective files.
- The “uvco/integrations” directory encapsulates external library integrations (curl, pqxx).
- The “test” directory offers numerous end-to-end examples and unit tests that demonstrate the usage of different asynchronous components.

##### README for Additional Insights
- The README outlines several example scenarios including running an event loop, using promises, HTTP(S) downloads, and a TCP echo server.
- It emphasizes the library’s design through its coroutine-based approach, highlighting key abstractions like the event loop, promises, and integration with libuv callbacks.
- There is clear mention of design decisions (e.g., “Promises run eagerly”, explicit “close” handling) and dependency management.

a. Main Components to Include:
– Event Loop: Represented by uvco/loop (loop.cc, scheduler.cc). This component orchestrates I/O and orchestrates when to resume coroutines.
– Promise Mechanism: Capture the logic in uvco/promise that enables coroutines to yield and resume.
– I/O Abstractions: Group components for TCP/UDP sockets, file system, DNS name resolution, and inter-process communication (e.g., anonymous pipes and Unix Domain Sockets).
– External Integrations: Separate blocks for libcurl and libpqxx integrations (found in uvco/integrations).
– Tests and Examples: Optionally note that the “test” directory contains deployments of usage scenarios (e.g., HTTP client, TCP echo server).

b. Relationships and Interactions:
– Within the event loop, tasks (promises) are scheduled and resumed as I/O callbacks are triggered.
– Indicate that various I/O operations (TCP, UDP, etc.) are initiated through corresponding uvco modules, and then suspend or resume via the promise mechanism.
– Highlight data flow from external libraries (libuv for I/O; libcurl/libpqxx for integrations) up into the uvco abstractions.

c. Architectural Patterns and Design Principles:
– Asynchronous Programming Model: Leverage C++20 coroutines to provide a non-blocking, callback-driven design.
– Separation of Concerns: The library cleanly separates I/O handling (uvco/loop) from promise management (uvco/promise) and external integrations.
– Modularity: Different components such as name resolution, TCP/UDP, file operations, and third-party integrations are encapsulated in their modules.
– Explicit Resource Management: Note the emphasis on explicit closing of resources (e.g., calling co_await on close methods).

d. Relevant Technologies, Frameworks, or Libraries:
– C++20 (for coroutine support)
– libuv (the underlying event loop)
– libcurl and libpqxx (for HTTP and database interactions, respectively)
– libfmt (for formatted output)
– CMake (for build configuration)

##### Diagrammatic Elements
- Annotations: Include small callouts summarizing key responsibilities, such as “Handles scheduling and I/O events”, “Manages coroutine suspension/resumption”, “Wraps libcurl for HTTP downloads”, etc.

##### Final Detailing
- That component relationships (like dependency flows from uvco modules to external libraries, and the control flow through the event loop) are clearly marked.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: Tests & Examples
    A("Test Application"):::test

    %% Middle Layer: Core Modules
    subgraph "Core Modules"
        direction TB
        E1("Event Loop (uvco/loop)"):::core
        P1("Promise Mechanism (uvco/promise)"):::core
        AW("Async Work Handler (uvco/async_work)"):::core
        IO_F("Filesystem I/O (uvco/fs)"):::io
        IO_T("TCP I/O (uvco/tcp)"):::io
        IO_U("UDP I/O (uvco/udp)"):::io
        IO_S("Stream Operations (uvco/stream)"):::io
        IO_N("Name Resolution I/O (uvco/name_resolution)"):::io
        IO_P("Pipe I/O (uvco/pipe)"):::io
        ExtCurl("libcurl Integration (uvco/integrations/curl)"):::integration
        ExtPQXX("libpqxx Integration (uvco/integrations/pqxx)"):::integration
    end

    %% Bottom Layer: External Libraries
    subgraph "External Libraries"
        direction TB
        Libuv("libuv (Event Loop Library)"):::external
        Libcurl("libcurl (HTTP Library)"):::external
        Libpqxx("libpqxx (PostgreSQL Library)"):::external
    end

    %% Connections - Application invoking the event loop
    A -->|"calls"| E1

    %% Core interactions: Scheduling and promise resolution
    E1 -->|"schedules"| P1
    P1 -->|"handles"| AW

    %% Event Loop triggers I/O operations
    E1 -->|"triggers"| IO_F
    E1 -->|"triggers"| IO_T
    E1 -->|"triggers"| IO_U
    E1 -->|"triggers"| IO_S
    E1 -->|"triggers"| IO_N
    E1 -->|"triggers"| IO_P

    %% I/O callbacks resume Promises
    IO_F -->|"resumes"| P1
    IO_T -->|"resumes"| P1
    IO_U -->|"resumes"| P1
    IO_S -->|"resumes"| P1
    IO_N -->|"resumes"| P1
    IO_P -->|"resumes"| P1

    %% External integrations with core modules and external libraries
    E1 -->|"integrates"| ExtCurl
    E1 -->|"integrates"| ExtPQXX
    ExtCurl -->|"wraps"| Libcurl
    ExtPQXX -->|"wraps"| Libpqxx

    %% Event Loop uses libuv
    E1 -->|"uses"| Libuv

    %% Styles
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef io fill:#ffb,stroke:#333,stroke-width:2px;
    classDef integration fill:#bfb,stroke:#333,stroke-width:2px;
    classDef external fill:#fdd,stroke:#333,stroke-width:2px;
    classDef test fill:#dfd,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mappings
    click E1 "https://github.com/dermesser/uvco/blob/master/uvco/loop/loop.cc"
    click E1 "https://github.com/dermesser/uvco/blob/master/uvco/loop/scheduler.cc"

    click P1 "https://github.com/dermesser/uvco/blob/master/uvco/promise/promise.cc"
    click P1 "https://github.com/dermesser/uvco/blob/master/uvco/promise/multipromise.cc"
    click P1 "https://github.com/dermesser/uvco/blob/master/uvco/promise/promise_core.cc"

    click AW "https://github.com/dermesser/uvco/blob/master/uvco/async_work.cc"
    click AW "https://github.com/dermesser/uvco/blob/master/uvco/async_work.h"

    click IO_F "https://github.com/dermesser/uvco/blob/master/uvco/fs.cc"
    click IO_F "https://github.com/dermesser/uvco/blob/master/uvco/fs.h"

    click IO_T "https://github.com/dermesser/uvco/blob/master/uvco/tcp.cc"
    click IO_T "https://github.com/dermesser/uvco/blob/master/uvco/tcp.h"
    click IO_T "https://github.com/dermesser/uvco/blob/master/uvco/tcp_stream.cc"
    click IO_T "https://github.com/dermesser/uvco/blob/master/uvco/tcp_stream.h"

    click IO_U "https://github.com/dermesser/uvco/blob/master/uvco/udp.cc"
    click IO_U "https://github.com/dermesser/uvco/blob/master/uvco/udp.h"

    click IO_S "https://github.com/dermesser/uvco/blob/master/uvco/stream.cc"
    click IO_S "https://github.com/dermesser/uvco/blob/master/uvco/stream.h"

    click IO_N "https://github.com/dermesser/uvco/blob/master/uvco/name_resolution.cc"
    click IO_N "https://github.com/dermesser/uvco/blob/master/uvco/name_resolution.h"

    click IO_P "https://github.com/dermesser/uvco/blob/master/uvco/pipe.cc"
    click IO_P "https://github.com/dermesser/uvco/blob/master/uvco/pipe.h"

    click ExtCurl "https://github.com/dermesser/uvco/blob/master/uvco/integrations/curl/curl.cc"
    click ExtCurl "https://github.com/dermesser/uvco/blob/master/uvco/integrations/curl/curl.h"

    click ExtPQXX "https://github.com/dermesser/uvco/blob/master/uvco/integrations/pqxx/pqxx.cc"
    click ExtPQXX "https://github.com/dermesser/uvco/blob/master/uvco/integrations/pqxx/pqxx.h"

    click A "https://github.com/dermesser/uvco/tree/master/test"
```
