# sustrik/libmill architecture

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

- Interactive diagram: https://gitdiagram.com/sustrik/libmill
- Repository: https://github.com/sustrik/libmill

## Overview

##### Main Components

a. Core Concurrency Components:
- Coroutine Management System (cr.c/h)
- Channel System (chan.c/h)
- Go-style Scheduling (represented by go.c in perf/)

b. I/O Subsystems:
- Network Stack
- TCP Implementation (tcp.c)
- UDP Implementation (udp.c)
- Unix Sockets (unix.c)
- DNS Resolution (dns/dns.c)
- IP Handling (ip.c/h)
- SSL/TLS Support (ssl.c)

c. Event Handling:
- Poller Subsystem (poller.c/h)
- Platform-specific Event Mechanisms
- epoll (Linux) - epoll.inc
- kqueue (BSD/macOS) - kqueue.inc
- poll (Fallback) - poll.inc

d. Support Systems:
- Timer Management (timer.c/h)
- Debug Facilities (debug.c/h)
- Memory Management (stack.c/h)
- Handling (list.c/h, slist.c/h)

**┌─────────────────────────────────────────┐**
- Application Layer             │
- ┘
- ↕
**┌─────────────────────────────────────────┐**
- Coroutine Management            │
- (Scheduling, Channels, Go-style APIs)  │
- ┘
- ↕
**┌─────────────────────────────────────────┐**
- I/O Subsystems               │
- (TCP, UDP, Unix Sockets, DNS, SSL)    │
- ┘
- ↕
**┌─────────────────────────────────────────┐**
- Event Handling Layer            │
- (Poller, epoll/kqueue/poll)       │
- ┘
- ↕
**┌─────────────────────────────────────────┐**
- Operating System                │
- ┘

##### Important Relationships

- How coroutines interact with channels
- Demonstrate how the scheduling system interfaces with the event polling mechanism
- Relationship between network operations and the event system
- Platform-specific implementations as alternatives in the event handling layer

##### Implementation Details to Highlight

- How the library integrates with existing C code
- Zero-copy design where applicable
- Demonstrate the relationship between coroutines and system threads
- How the timer system integrates with the event loop

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef core fill:#b3d1ff,stroke:#333
    classDef io fill:#90EE90,stroke:#333
    classDef event fill:#FFE5B4,stroke:#333
    classDef support fill:#D3D3D3,stroke:#333
    classDef os fill:#f9f9f9,stroke:#333
    classDef api fill:#FFB6C1,stroke:#333

    %% Application Layer
    APP["Application Code"]
    LIBMILL["libmill.h"]:::api
    click LIBMILL "https://github.com/sustrik/libmill/blob/master/libmill.h"

    %% Core Layer
    subgraph CoreLayer["Core Concurrency Layer"]
        CR["Coroutine Management"]:::core
        CHAN["Channel System"]:::core
        SCHED["Go-style Scheduler"]:::core
    end
    click CR "https://github.com/sustrik/libmill/blob/master/cr.c"
    click CHAN "https://github.com/sustrik/libmill/blob/master/chan.c"
    click SCHED "https://github.com/sustrik/libmill/blob/master/perf/go.c"

    %% I/O Layer
    subgraph IOLayer["I/O Subsystems"]
        TCP["TCP Stack"]:::io
        UDP["UDP Stack"]:::io
        UNIX["Unix Sockets"]:::io
        DNS["DNS Resolution"]:::io
        IP["IP Handler"]:::io
        SSL["SSL/TLS"]:::io
    end
    click TCP "https://github.com/sustrik/libmill/blob/master/tcp.c"
    click UDP "https://github.com/sustrik/libmill/blob/master/udp.c"
    click UNIX "https://github.com/sustrik/libmill/blob/master/unix.c"
    click DNS "https://github.com/sustrik/libmill/blob/master/dns/dns.c"
    click IP "https://github.com/sustrik/libmill/blob/master/ip.c"
    click SSL "https://github.com/sustrik/libmill/blob/master/ssl.c"

    %% Event Handling Layer
    subgraph EventLayer["Event Handling"]
        POLL["Poller Subsystem"]:::event
        EPOLL["epoll (Linux)"]:::event
        KQUEUE["kqueue (BSD/macOS)"]:::event
        POLLBASE["poll (Fallback)"]:::event
    end
    click POLL "https://github.com/sustrik/libmill/blob/master/poller.c"
    click EPOLL "https://github.com/sustrik/libmill/blob/master/epoll.inc"
    click KQUEUE "https://github.com/sustrik/libmill/blob/master/kqueue.inc"
    click POLLBASE "https://github.com/sustrik/libmill/blob/master/poll.inc"

    %% Support Systems
    subgraph SupportLayer["Support Systems"]
        TIMER["Timer Management"]:::support
        DEBUG["Debug Facilities"]:::support
        MEM["Memory Management"]:::support
        LIST["List Handling"]:::support
    end
    click TIMER "https://github.com/sustrik/libmill/blob/master/timer.c"
    click DEBUG "https://github.com/sustrik/libmill/blob/master/debug.c"
    click MEM "https://github.com/sustrik/libmill/blob/master/stack.c"
    click LIST "https://github.com/sustrik/libmill/blob/master/list.c"

    %% OS Layer
    OS["Operating System"]:::os

    %% Relationships
    APP --> LIBMILL
    LIBMILL --> CR
    LIBMILL --> CHAN
    CR --> SCHED
    CHAN --> SCHED
    SCHED --> POLL
    
    TCP & UDP & UNIX & DNS & IP & SSL --> POLL
    
    POLL --> EPOLL & KQUEUE & POLLBASE
    EPOLL & KQUEUE & POLLBASE --> OS
    
    TIMER --> POLL
    DEBUG --> CR
    MEM --> CR
    LIST --> CR

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["I/O Systems"]:::io
        L3["Event Handling"]:::event
        L4["Support Systems"]:::support
        L5["API Interface"]:::api
    end
```
