# dabeaz/curio architecture

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

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

## Overview

##### Project type and purpose
- From the file tree and README, this project (“Curio”) is an open-source Python library implementing a coroutine‐based asynchronous runtime and set of concurrency primitives. It is *not* a full-stack web app or compiler but a standalone library whose core function is to provide async tasks, scheduling, I/O, networking, synchronization primitives, and structured concurrency.

##### File structure
- Top-level directories:
- curio/         ← The library’s source code
- docs/          ← Documentation (Sphinx)
- examples/      ← Sample programs demonstrating usage
- tests/         ← Unit and integration tests
- Key source modules in curio/:
- kernel.py      ← The event‐loop (task scheduler)
- sched.py       ← Scheduling policies and ready/wait queues
- task.py        ← Task object abstraction (lifecycle, cancellation)
- traps.py       ← Async “syscalls” interface to kernel services
- io.py, file.py, network.py, socket.py, ssl.py
← Async I/O and networking layers built on traps
- sync.py, queue.py, channel.py
← Async synchronization and communication primitives
- thread.py, workers.py
← Bridges to thread‐ and process‐based execution
- No front-end/back-end split—this is purely a library offering components.

##### README for additional insights
- Emphasis on *separation* of synchronous vs asynchronous environments
- Core features: tasks, cancellation, locks, events, queues, subprocess/thread integration, structured concurrency
- No external dependencies—interfaces directly with OS via low-level I/O

a. Main components to represent
1. User code (async functions & tasks)
2. Curio Kernel / Event Loop (curio/kernel.py)
3. Scheduler (curio/sched.py)
4. Trap layer (curio/traps.py) – the syscalls interface
5. Async I/O subsystems
- File I/O (file.py)
- Network sockets & SSL (socket.py, ssl.py, network.py)
6. Sync primitives & channels (sync.py, queue.py, channel.py)
7. Worker subsystem for threads/processes (thread.py, workers.py)
8. Underlying OS / system calls
b. Relationships and interactions
- User code invokes `await` on tasks & primitives
- Tasks are managed by the Kernel which uses the Scheduler to enqueue/dequeue task runs
- When a task performs I/O or waits on a lock, it issues a Trap call
- The Trap layer marshals requests to the appropriate subsystem (I/O, sync, etc.)
- I/O subsystems interact with the OS (selectors, epoll/kqueue, socket APIs)
- Sync primitives may block tasks by re‐queuing them until an event/unlock occurs
- Worker threads or processes are used when user code opts in—tasks can be off‐loaded via workers
c. Architectural patterns & design principles
- Layered design: user code → traps → kernel/scheduler → OS
- Separation of concerns: pure async code never mixes sync primitives except through defined traps
- Event‐driven loop tackling concurrency without OS threads
- Structured concurrency support (task groups, cancellation scopes)
d. Key technologies & frameworks
- Python 3.7+ async/await syntax
- Selector‐based event loop (platform‐specific multiplexing)
- Zero external dependencies beyond Python stdlib

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Layer"
        UC["User Code\n(async/await)"]
    end

    subgraph "Curio Core"
        K["Kernel / Event Loop"]:::core
        S["Scheduler"]:::core
        TSK["Task Abstraction"]:::core
        TR["Trap Layer"]:::core
    end

    subgraph "Async I/O Subsystems"
        IOE["Core I/O Engine"]:::io
        FIO["File I/O"]:::io
    end

    subgraph "Async Networking Subsystems"
        NET["Network Operations"]:::net
        SOCK["Socket API"]:::net
        SSL["SSL Support"]:::net
    end

    subgraph "Sync Primitives & Messaging"
        SY["Locks/Events/Semaphores"]:::sync
        Q["FIFO Queues"]:::sync
        CH["Channels"]:::sync
    end

    subgraph "Worker Subsystem"
        TH["Thread Integration"]:::worker
        WP["Worker Pool"]:::worker
    end

    subgraph "Timing & Scheduling Support"
        TM["Time Utilities"]:::time
        TQ["Timer Queue"]:::time
    end

    OS["Operating System"]:::external

    UC -->|"spawn/run"| K
    K -->|"dispatch tasks"| S
    S -->|"enqueue/dequeue"| K
    K -->|"manage task life"| TSK
    K -->|"syscall traps"| TR

    TR --> IOE
    TR --> FIO
    TR --> NET
    TR --> SOCK
    TR --> SSL
    TR --> SY
    TR --> Q
    TR --> CH
    TR --> TH
    TR --> WP
    TR --> TM
    TR --> TQ

    IOE --> OS
    FIO --> OS
    NET --> OS
    SOCK --> OS
    SSL --> OS
    TH --> OS
    WP --> OS
    TM --> OS
    TQ --> OS

    IOE -->|"I/O callback"| K
    NET -->|"net ready"| K
    SY -->|"unlock wakes"| K
    WP -->|"task offload"| K
    TQ -->|"timeout callback"| K

    click K "https://github.com/dabeaz/curio/blob/master/curio/kernel.py"
    click S "https://github.com/dabeaz/curio/blob/master/curio/sched.py"
    click TSK "https://github.com/dabeaz/curio/blob/master/curio/task.py"
    click TR "https://github.com/dabeaz/curio/blob/master/curio/traps.py"
    click IOE "https://github.com/dabeaz/curio/blob/master/curio/io.py"
    click FIO "https://github.com/dabeaz/curio/blob/master/curio/file.py"
    click NET "https://github.com/dabeaz/curio/blob/master/curio/network.py"
    click SOCK "https://github.com/dabeaz/curio/blob/master/curio/socket.py"
    click SSL "https://github.com/dabeaz/curio/blob/master/curio/ssl.py"
    click SY "https://github.com/dabeaz/curio/blob/master/curio/sync.py"
    click Q "https://github.com/dabeaz/curio/blob/master/curio/queue.py"
    click CH "https://github.com/dabeaz/curio/blob/master/curio/channel.py"
    click TH "https://github.com/dabeaz/curio/blob/master/curio/thread.py"
    click WP "https://github.com/dabeaz/curio/blob/master/curio/workers.py"
    click TM "https://github.com/dabeaz/curio/blob/master/curio/time.py"
    click TQ "https://github.com/dabeaz/curio/blob/master/curio/timequeue.py"

    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef io fill:#90EE90,stroke:#000,stroke-width:1px
    classDef net fill:#FFFACD,stroke:#000,stroke-width:1px
    classDef sync fill:#FFB6C1,stroke:#000,stroke-width:1px
    classDef worker fill:#F08080,stroke:#000,stroke-width:1px
    classDef time fill:#E0FFFF,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
