# klen/curio architecture

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

- Interactive diagram: https://gitdiagram.com/klen/curio
- Repository: https://github.com/klen/curio

## Overview

##### Project Type and Purpose
- Curio is a coroutine-based concurrency library for Python (pure-Python, no external dependencies).
- Purpose: provide an event-driven “kernel” for async/await programming with explicit separation between synchronous and asynchronous code.

##### File-Structure Analysis
- Top-level directories:
- curio/            ← core library package
- docs/             ← documentation sources
- examples/         ← sample code illustrating usage
- tests/            ← unit and integration tests
- Key files:
- curio/kernel.py   ← the event-loop (“kernel”) and scheduler
- curio/task.py     ← task abstraction, cancellation, task groups
- curio/traps.py    ← low-level I/O and scheduling primitives
- curio/io.py, file.py, network.py, socket.py, ssl.py
← async interfaces for OS I/O
- curio/sync.py, queue.py, channel.py
← synchronization primitives and inter-task communication
- curio/workers.py  ← running sync code in thread/process pools

##### Core Architecture Overview
a. Components
- Kernel / Scheduler (curio/kernel.py, sched.py)
- Task abstraction (curio/task.py)
- Trap layer / Reactor interface (curio/traps.py)
- I/O subsystems:
- File I/O (curio/file.py)
- Network I/O (curio/network.py, socket.py, ssl.py)
- Synchronization & Communication:
- Locks, Events, Semaphores (curio/sync.py)
- Queues (curio/queue.py), Channels (curio/channel.py)
- Worker Pools (threads/processes) (curio/workers.py)
- Auxiliary modules: debugging, monitoring, time management

b. Relationships & Data Flow
1. User code calls async API →
2. Task abstraction wraps coroutine →
3. Kernel schedules tasks via scheduler →
4. When I/O is requested, trap calls OS reactor (select/epoll/etc) →
5. Reactor notifies kernel →
6. Kernel resumes tasks on readiness →
7. Synchronization primitives coordinate between tasks →
8. Worker pool for blocking operations funnels results back via queues/traps

c. Architectural Patterns
- Reactor/event-loop pattern in `kernel` + `traps`
- Structured concurrency (task groups, explicit spawn/cancel)
- Clear separation between async environment (everything in curio) vs synchronous Python
- Modular subsystems for I/O, sync primitives, and worker off-loading

d. Key Technologies/Frameworks
- Python 3.5+ async/await syntax
- No external dependencies (stdlib only)
- CI integrations (.github/workflows) for tests and releases

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User API" 
        direction TB
        UserAPI["User Code / Async API"]:::user
    end

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        Kernel["Kernel / Scheduler"]:::core
        Task["Task Abstraction"]:::core
        Trap["Traps / Reactor Interface"]:::core
    end

    %% I/O Subsystems
    subgraph "I/O Subsystems"
        direction TB
        GenericIO["Generic I/O API"]:::io
        FileIO["File I/O Subsystem"]:::io
        NetIO["Network I/O Subsystem"]:::io
        Socket["Socket Interface"]:::io
        SSL["SSL Interface"]:::io
    end

    %% Sync Primitives
    subgraph "Sync Primitives"
        direction TB
        SyncPrims["Locks/Events/Semaphores"]:::sync
        Queue["Queue Primitive"]:::sync
        Channel["Channel Primitive"]:::sync
    end

    %% Worker Pools
    subgraph "Worker Pools"
        direction TB
        Workers["Worker Pools (thread/process)"]:::worker
        ThreadSupport["Thread Support"]:::worker
    end

    %% Auxiliary Modules
    subgraph "Auxiliary Modules"
        direction TB
        TimeMgmt["Time Management"]:::aux
        Monitoring["Monitoring/Debugging"]:::aux
        Debug["Debug Utilities"]:::aux
        Errors["Errors & Meta Utilities"]:::aux
    end

    %% OS Reactor at bottom
    OSReactor[/"OS Reactor (select/epoll/...)"\]:::os

    %% Flow Relationships
    UserAPI -->|"spawn()/run()"| Task
    Task -->|"schedule()"| Kernel
    Kernel -->|"I/O wait"| Trap
    Trap -->|"calls"| OSReactor
    OSReactor -->|"event ready"| Trap
    Trap -->|"resume()"| Kernel
    Kernel -->|"resume task"| Task

    Task -->|"use"| SyncPrims
    SyncPrims -->|"notify"| Task

    Task -->|"offload"| Workers
    Workers -->|"result via queue"| Task

    Kernel -->|"uses"| GenericIO
    GenericIO --> FileIO
    GenericIO --> NetIO
    NetIO --> Socket
    NetIO --> SSL

    Kernel --> TimeMgmt
    Kernel --> Monitoring
    Kernel --> Debug
    Kernel --> Errors

    %% Click Events
    click Kernel "https://github.com/klen/curio/blob/develop/curio/kernel.py"
    click Task "https://github.com/klen/curio/blob/develop/curio/task.py"
    click Trap "https://github.com/klen/curio/blob/develop/curio/traps.py"
    click GenericIO "https://github.com/klen/curio/blob/develop/curio/io.py"
    click FileIO "https://github.com/klen/curio/blob/develop/curio/file.py"
    click NetIO "https://github.com/klen/curio/blob/develop/curio/network.py"
    click Socket "https://github.com/klen/curio/blob/develop/curio/socket.py"
    click SSL "https://github.com/klen/curio/blob/develop/curio/ssl.py"
    click SyncPrims "https://github.com/klen/curio/blob/develop/curio/sync.py"
    click Queue "https://github.com/klen/curio/blob/develop/curio/queue.py"
    click Channel "https://github.com/klen/curio/blob/develop/curio/channel.py"
    click Workers "https://github.com/klen/curio/blob/develop/curio/workers.py"
    click ThreadSupport "https://github.com/klen/curio/blob/develop/curio/thread.py"
    click TimeMgmt "https://github.com/klen/curio/blob/develop/curio/time.py"
    click Monitoring "https://github.com/klen/curio/blob/develop/curio/monitor.py"
    click Debug "https://github.com/klen/curio/blob/develop/curio/debug.py"
    click Errors "https://github.com/klen/curio/blob/develop/curio/errors.py"
    click UserAPI "https://github.com/klen/curio/blob/develop/curio/__main__.py"

    %% Styles
    classDef user fill:#ffe699,stroke:#cc7a00,color:#000;
    classDef core fill:#cfe2f3,stroke:#0b5394,color:#000;
    classDef io fill:#d9ead3,stroke:#38761d,color:#000;
    classDef sync fill:#f4cccc,stroke:#cc0000,color:#000;
    classDef worker fill:#ead1dc,stroke:#a64d79,color:#000;
    classDef aux fill:#fbe5d6,stroke:#b45f06,color:#000;
    classDef os fill:#d0e0e3,stroke:#134f5c,color:#000
```
