How klen/curio works
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