# mitchellh/libxev architecture

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

- Interactive diagram: https://gitdiagram.com/mitchellh/libxev
- Repository: https://github.com/mitchellh/libxev

## Overview

##### Main Components

a. Core Event Loop Layer
- Main Loop implementation (src/loop.zig)
- Completion handling system

b. Backend Implementations (src/backend/)
- io_uring (Linux)
- epoll (Linux)
- kqueue (macOS)
- IOCP (Windows)
- WASI poll (WebAssembly)

c. High-Level Watchers Layer (src/watcher/)
- Following watchers:
- Timer
- TCP
- UDP
- File
- Process
- Async
- Their relationship to the core event loop

d. Thread Pool Component
- ThreadPool implementation (src/ThreadPool.zig)
- Optional nature
- Connection to file operations for platforms without async I/O

e. C API Bridge
- C API layer (src/c_api.zig)
- How it wraps the Zig implementation

##### Relationship Flows

- Application → C API / Zig API
- C API → Core Event Loop
- Core Event Loop → Backend Implementations
- Core Event Loop → Watchers
- Watchers → Thread Pool (when needed)

**[Application Layer]**
- ↓
**[C API Layer] ← → [Zig API Layer]**
- ↓
**[Core Event Loop]**
- ↓
**┌─────────────────────────────────┐**
- Watchers Layer          │
- Timer │ TCP │ UDP │ File │ ... │
- ┘
- ↓
**┌─────────────────────────────────┐**
- Backend Implementations    │
- io_uring │ epoll │ kqueue │ ... │
- ┘
- ↔
**[Thread Pool] (Optional Component)**

##### Additional Elements

- Version/platform support matrix
- Notes about zero-allocation design
- Completion callback flow indicators
- Thread pool interaction paths

##### Implementation Details to Highlight

- Proactor pattern implementation
- Platform-specific optimizations
- Tree-shaking capability
- Zero-dependency nature
- Cross-platform compatibility

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px
    classDef api fill:#e1f5fe,stroke:#0288d1
    classDef core fill:#e8f5e9,stroke:#388e3c
    classDef backend fill:#fff3e0,stroke:#f57c00
    classDef watcher fill:#f3e5f5,stroke:#7b1fa2
    classDef threadpool fill:#fce4ec,stroke:#c2185b
    classDef queue fill:#efebe9,stroke:#5d4037

    %% Application Layer
    APP[Application]
    CAPI[C API Bridge]:::api
    ZIGAPI[Zig API]:::api

    %% Core Layer
    LOOP[Event Loop]:::core
    QUEUE[Queue Management]:::queue
    QMPSC[MPSC Queue]:::queue

    %% Watchers Layer
    subgraph Watchers
        TIMER[Timer Watcher]:::watcher
        TCP[TCP Watcher]:::watcher
        UDP[UDP Watcher]:::watcher
        FILE[File Watcher]:::watcher
        PROC[Process Watcher]:::watcher
        ASYNC[Async Watcher]:::watcher
        COMMON[Common Watcher]:::watcher
    end

    %% Backend Layer
    subgraph Backends
        IOURING[IO_uring]:::backend
        EPOLL[Epoll]:::backend
        KQUEUE[Kqueue]:::backend
        IOCP[IOCP]:::backend
        WASI[WASI Poll]:::backend
    end

    %% Platform Specific
    WINDOWS[Windows Support]:::backend
    LINUXTIMER[Linux Timer]:::backend

    %% Thread Pool
    TPOOL[Thread Pool]:::threadpool

    %% Relationships
    APP --> CAPI & ZIGAPI
    CAPI & ZIGAPI --> LOOP
    LOOP --> QUEUE
    QUEUE --> QMPSC
    LOOP --> Watchers
    LOOP --> Backends
    Watchers --> TPOOL
    IOCP --> WINDOWS
    TIMER --> LINUXTIMER

    %% Click Events
    click LOOP "https://github.com/mitchellh/libxev/blob/main/src/loop.zig"
    click CAPI "https://github.com/mitchellh/libxev/blob/main/src/c_api.zig"
    click TIMER "https://github.com/mitchellh/libxev/blob/main/src/watcher/timer.zig"
    click TCP "https://github.com/mitchellh/libxev/blob/main/src/watcher/tcp.zig"
    click UDP "https://github.com/mitchellh/libxev/blob/main/src/watcher/udp.zig"
    click FILE "https://github.com/mitchellh/libxev/blob/main/src/watcher/file.zig"
    click PROC "https://github.com/mitchellh/libxev/blob/main/src/watcher/process.zig"
    click ASYNC "https://github.com/mitchellh/libxev/blob/main/src/watcher/async.zig"
    click COMMON "https://github.com/mitchellh/libxev/blob/main/src/watcher/common.zig"
    click IOURING "https://github.com/mitchellh/libxev/blob/main/src/backend/io_uring.zig"
    click EPOLL "https://github.com/mitchellh/libxev/blob/main/src/backend/epoll.zig"
    click KQUEUE "https://github.com/mitchellh/libxev/blob/main/src/backend/kqueue.zig"
    click IOCP "https://github.com/mitchellh/libxev/blob/main/src/backend/iocp.zig"
    click WASI "https://github.com/mitchellh/libxev/blob/main/src/backend/wasi_poll.zig"
    click TPOOL "https://github.com/mitchellh/libxev/blob/main/src/ThreadPool.zig"
    click WINDOWS "https://github.com/mitchellh/libxev/blob/main/src/windows.zig"
    click LINUXTIMER "https://github.com/mitchellh/libxev/blob/main/src/linux/timerfd.zig"
    click QUEUE "https://github.com/mitchellh/libxev/blob/main/src/queue.zig"
    click QMPSC "https://github.com/mitchellh/libxev/blob/main/src/queue_mpsc.zig"
```
