# alexanderlu09/coroutine-runtime architecture

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

- Interactive diagram: https://gitdiagram.com/alexanderlu09/coroutine-runtime
- Repository: https://github.com/alexanderlu09/coroutine-runtime

## Overview

Coroutine-Runtime is an early-stage C++ async runtime. Its current workflow queues tasks in a scheduler, runs their callbacks, and can poll a pluggable I/O driver; the kqueue driver can requeue tasks when descriptors become readable. Socket helpers create nonblocking listening and accepted sockets. The README also describes work stealing and deterministic simulation as goals, but the sampled source shows neither; ManualClock exists, but no simulator wiring is shown.

Main entry points: [`include/coro/scheduler.hpp`](https://github.com/alexanderlu09/coroutine-runtime/blob/main/include/coro/scheduler.hpp) (Scheduler), [`src/kqueue_driver.cpp`](https://github.com/alexanderlu09/coroutine-runtime/blob/main/src/kqueue_driver.cpp) (Kqueue driver), [`src/socket.cpp`](https://github.com/alexanderlu09/coroutine-runtime/blob/main/src/socket.cpp) (Socket helpers), [`src/clock.cpp`](https://github.com/alexanderlu09/coroutine-runtime/blob/main/src/clock.cpp) (System clock)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scheduling["Task scheduling"]
  node_scheduler["Scheduler<br/>[scheduler.hpp]"]
  node_task["Task<br/>[task.hpp]"]
  node_ready_list["Ready list<br/>[intrusive_list.hpp]"]
end

subgraph group_io["I/O and sockets"]
  node_io_driver["I/O driver API<br/>[io_driver.hpp]"]
  node_kqueue_driver["Kqueue driver<br/>[kqueue_driver.cpp]"]
  node_socket_api["Socket helpers<br/>[socket.cpp]"]
end

subgraph group_time["Time"]
  node_clock_api["Clock API<br/>[clock.hpp]"]
  node_system_clock["System clock<br/>[clock.cpp]"]
  node_manual_clock["Manual clock<br/>[clock.hpp]"]
end

node_application(("Application"))
node_kernel["OS kernel"]
node_steady_clock["C++ steady clock"]

node_application -->|"spawns tasks"| node_scheduler
node_scheduler -->|"queues tasks"| node_ready_list
node_scheduler -->|"runs callback"| node_task
node_scheduler -->|"polls driver"| node_io_driver
node_kqueue_driver -->|"waits for events"| node_kernel
node_kqueue_driver -->|"requeues ready tasks"| node_scheduler
node_application -->|"creates sockets"| node_socket_api
node_socket_api -->|"creates and accepts"| node_kernel
node_system_clock -->|"reads time"| node_steady_clock
node_application -->|"advances time"| node_manual_clock

click node_scheduler "https://github.com/alexanderlu09/coroutine-runtime/blob/main/include/coro/scheduler.hpp"
click node_task "https://github.com/alexanderlu09/coroutine-runtime/blob/main/include/coro/task.hpp"
click node_ready_list "https://github.com/alexanderlu09/coroutine-runtime/blob/main/include/coro/intrusive_list.hpp"
click node_io_driver "https://github.com/alexanderlu09/coroutine-runtime/blob/main/include/coro/io_driver.hpp"
click node_kqueue_driver "https://github.com/alexanderlu09/coroutine-runtime/blob/main/src/kqueue_driver.cpp"
click node_socket_api "https://github.com/alexanderlu09/coroutine-runtime/blob/main/src/socket.cpp"
click node_clock_api "https://github.com/alexanderlu09/coroutine-runtime/blob/main/include/coro/clock.hpp"
click node_system_clock "https://github.com/alexanderlu09/coroutine-runtime/blob/main/src/clock.cpp"
click node_manual_clock "https://github.com/alexanderlu09/coroutine-runtime/blob/main/include/coro/clock.hpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scheduler,node_task,node_ready_list toneBlue
class node_io_driver,node_kqueue_driver,node_socket_api toneAmber
class node_clock_api,node_system_clock,node_manual_clock toneMint
class node_application,node_kernel,node_steady_clock toneIndigo
```

## Components

### Task scheduling

- [Scheduler](https://github.com/alexanderlu09/coroutine-runtime/blob/main/include/coro/scheduler.hpp): `include/coro/scheduler.hpp`
- [Task](https://github.com/alexanderlu09/coroutine-runtime/blob/main/include/coro/task.hpp): `include/coro/task.hpp`
- [Ready list](https://github.com/alexanderlu09/coroutine-runtime/blob/main/include/coro/intrusive_list.hpp): `include/coro/intrusive_list.hpp`

### I/O and sockets

- [I/O driver API](https://github.com/alexanderlu09/coroutine-runtime/blob/main/include/coro/io_driver.hpp): `include/coro/io_driver.hpp`
- [Kqueue driver](https://github.com/alexanderlu09/coroutine-runtime/blob/main/src/kqueue_driver.cpp): `src/kqueue_driver.cpp`
- [Socket helpers](https://github.com/alexanderlu09/coroutine-runtime/blob/main/src/socket.cpp): `src/socket.cpp`

### Time

- [Clock API](https://github.com/alexanderlu09/coroutine-runtime/blob/main/include/coro/clock.hpp): `include/coro/clock.hpp`
- [System clock](https://github.com/alexanderlu09/coroutine-runtime/blob/main/src/clock.cpp): `src/clock.cpp`
- [Manual clock](https://github.com/alexanderlu09/coroutine-runtime/blob/main/include/coro/clock.hpp): `include/coro/clock.hpp`

### Other components

- **Application**
- **OS kernel**
- **C++ steady clock**

## Connections

- Application → Scheduler: spawns tasks
- Scheduler → Ready list: queues tasks
- Scheduler → Task: runs callback
- Scheduler → I/O driver API: polls driver
- Kqueue driver → OS kernel: waits for events
- Kqueue driver → Scheduler: requeues ready tasks
- Application → Socket helpers: creates sockets
- Socket helpers → OS kernel: creates and accepts
- System clock → C++ steady clock: reads time
- Application → Manual clock: advances time