# jbaldwin/libcoro architecture

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

- Interactive diagram: https://gitdiagram.com/jbaldwin/libcoro
- Repository: https://github.com/jbaldwin/libcoro

## Overview

##### Project type and purpose
- This is **libcoro**, a C++20 **open-source coroutine library** focused on providing low-level coroutine primitives, schedulers, and high-performance networking support.
- It is not a full-stack application; rather it is a **library/toolkit** for building asynchronous coroutines, I/O schedulers, thread pools, and networking/TLS clients and servers.

##### File structure
- Top-level build/config files: CMakeLists.txt, Makefile, .github workflows, git submodules.
- Source code broken into:
- **include/coro/** – public headers defining API (task, generator, event, mutex, net, etc.)
- **src/** – implementation of the above APIs
- **examples/** – sample applications (TCP echo server, HTTP server, etc.)
- **test/** – Catch2 tests for each primitive and networking module
- **vendor/libc-ares** submodule for async DNS
- Key modules apparent from directory names:
- **core coroutine machinery** (task, promise, awaitable)
- **schedulers** (thread_pool, io_scheduler)
- **primitives** (event, latch, mutex, semaphore, queue, ring_buffer, condition_variable)
- **networking** (net::dns, net::tcp, net::tls, net::udp)
- **examples** and **tests** exercising all of the above.

##### README for additional insights
- The README explains the API surface, usage examples for each primitive, and the architecture:
- core constructs → schedulers → networking.
- External dependencies: pthreads, epoll (Linux), libc-ares, OpenSSL.

##### Detailed coverage
- **External Dependencies** outside the library: libc-ares, OpenSSL, Linux Kernel epoll, pthreads.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Code
    User["User Code (<coro/...> headers)"]:::user

    %% Core Engine
    subgraph "Core Coroutine Engine" 
        direction TB
        Task["coro::task"]:::core
        Generator["coro::generator"]:::core
        Expected["coro::expected"]:::core
        Concepts["Concepts\n(awaitable, executor, promise, buffer,\nrange_of)"]:::core
        Poll["poll & attribute"]:::core
    end

    %% Synchronization Primitives
    subgraph "Synchronization Primitives"
        direction TB
        Event["event"]:::sync
        Latch["latch"]:::sync
        CV["condition_variable"]:::sync
        Mutex["mutex/shared_mutex"]:::sync
        Semaphore["semaphore"]:::sync
        Queue["queue"]:::sync
        RingBuffer["ring_buffer"]:::sync
        SyncWait["sync_wait"]:::sync
    end

    %% Executors / Schedulers
    subgraph "Executors / Schedulers"
        direction TB
        ThreadPool["thread_pool"]:::exec
        IOScheduler["io_scheduler"]:::exec
        DefaultExec["default_executor"]:::exec
    end

    %% Networking Layer
    subgraph "Networking Layer"
        direction TB
        subgraph CoreNet
            Connect["connect, hostname, ip_address,\nrecv_status, send_status, socket"]:::net
        end
        subgraph DNS
            Resolver["DNS resolver (libc-ares)"]:::net
        end
        subgraph TCP
            TCPClient["TCP client"]:::net
            TCPServer["TCP server"]:::net
        end
        subgraph TLS
            TLSClient["TLS client"]:::net
            TLSServer["TLS server"]:::net
            TLSContext["TLS context"]:::net
        end
        subgraph UDP
            UDPPeer["UDP peer"]:::net
        end
    end

    %% Examples & Tests
    subgraph "Examples / Tests"
        direction TB
        Examples["examples & tests"]:::example
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Epoll["Linux epoll"]:::ext
        PThreads["pthreads"]:::ext
        LibCAres["libc-ares"]:::ext
        OpenSSL["OpenSSL"]:::ext
    end

    %% Connections
    User -->|"includes API"| Task
    User -->|"includes API"| Generator
    User -->|"includes API"| Expected
    User -->|"co_awaits"| Concepts

    Task -->|"uses poll"| Poll
    Generator --> Poll
    Expected --> Poll

    Task -->|"uses sync primitives"| Event
    Generator --> Event

    Concepts --> ThreadPool
    Concepts --> IOScheduler

    Event --> ThreadPool
    Latch --> ThreadPool
    CV --> ThreadPool
    Mutex --> ThreadPool
    Semaphore --> ThreadPool
    Queue --> ThreadPool
    RingBuffer --> ThreadPool
    SyncWait --> ThreadPool

    Event --> IOScheduler
    Latch --> IOScheduler
    CV --> IOScheduler
    Mutex --> IOScheduler
    Semaphore --> IOScheduler
    Queue --> IOScheduler
    RingBuffer --> IOScheduler
    SyncWait --> IOScheduler

    ThreadPool -->|"executes coroutines"| CoreNet
    IOScheduler -->|"executes I/O coroutines"| CoreNet

    CoreNet --> DNS
    CoreNet --> TCPClient
    CoreNet --> TCPServer
    CoreNet --> TLSClient
    CoreNet --> TLSServer
    CoreNet --> TLSContext
    CoreNet --> UDPPeer

    DNS --> LibCAres
    TLSClient --> OpenSSL
    TLSServer --> OpenSSL

    CoreNet --> Epoll
    IOScheduler --> Epoll

    ThreadPool --> PThreads

    Examples --> User

    %% Click Events - Core
    click Task "https://github.com/jbaldwin/libcoro/blob/main/include/coro/task.hpp"
    click Generator "https://github.com/jbaldwin/libcoro/blob/main/include/coro/generator.hpp"
    click Expected "https://github.com/jbaldwin/libcoro/blob/main/include/coro/expected.hpp"
    click Concepts "https://github.com/jbaldwin/libcoro/blob/main/include/coro/concepts/awaitable.hpp"
    click Poll "https://github.com/jbaldwin/libcoro/blob/main/include/coro/poll.hpp"

    %% Click Events - Executors
    click ThreadPool "https://github.com/jbaldwin/libcoro/blob/main/include/coro/thread_pool.hpp"
    click IOScheduler "https://github.com/jbaldwin/libcoro/blob/main/include/coro/io_scheduler.hpp"
    click DefaultExec "https://github.com/jbaldwin/libcoro/blob/main/include/coro/default_executor.hpp"

    %% Click Events - Synchronization
    click Event "https://github.com/jbaldwin/libcoro/blob/main/include/coro/event.hpp"
    click Latch "https://github.com/jbaldwin/libcoro/blob/main/include/coro/latch.hpp"
    click CV "https://github.com/jbaldwin/libcoro/blob/main/include/coro/condition_variable.hpp"
    click Mutex "https://github.com/jbaldwin/libcoro/blob/main/include/coro/mutex.hpp"
    click Semaphore "https://github.com/jbaldwin/libcoro/blob/main/include/coro/semaphore.hpp"
    click Queue "https://github.com/jbaldwin/libcoro/blob/main/include/coro/queue.hpp"
    click RingBuffer "https://github.com/jbaldwin/libcoro/blob/main/include/coro/ring_buffer.hpp"
    click SyncWait "https://github.com/jbaldwin/libcoro/blob/main/include/coro/sync_wait.hpp"

    %% Click Events - Networking Core
    click Connect "https://github.com/jbaldwin/libcoro/blob/main/include/coro/net/connect.hpp"
    click Resolver "https://github.com/jbaldwin/libcoro/blob/main/include/coro/net/dns/resolver.hpp"
    click TCPClient "https://github.com/jbaldwin/libcoro/blob/main/include/coro/net/tcp/client.hpp"
    click TCPServer "https://github.com/jbaldwin/libcoro/blob/main/include/coro/net/tcp/server.hpp"
    click TLSClient "https://github.com/jbaldwin/libcoro/blob/main/include/coro/net/tls/client.hpp"
    click TLSServer "https://github.com/jbaldwin/libcoro/blob/main/include/coro/net/tls/server.hpp"
    click TLSContext "https://github.com/jbaldwin/libcoro/blob/main/include/coro/net/tls/context.hpp"
    click UDPPeer "https://github.com/jbaldwin/libcoro/blob/main/include/coro/net/udp/peer.hpp"

    %% Click Events - Examples & Tests
    click Examples "https://github.com/jbaldwin/libcoro/blob/main/examples/coro_task.cpp"

    %% Styles
    classDef core fill:#d0e1f9,stroke:#333,stroke-width:1px;
    classDef sync fill:#f9e0d0,stroke:#333,stroke-width:1px;
    classDef exec fill:#d0f9d0,stroke:#333,stroke-width:1px;
    classDef net fill:#f9f1d0,stroke:#333,stroke-width:1px;
    classDef ext fill:#e0e0e0,stroke:#333,stroke-width:1px;
    classDef example fill:#ffffff,stroke:#666,stroke-dasharray: 2 2;
    classDef user fill:#ffe0e0,stroke:#333,stroke-width:1px;
```
