# carbonengine/scheduler architecture

> Architecture diagram of the GitHub repository carbonengine/scheduler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/carbonengine/scheduler
- Repository: https://github.com/carbonengine/scheduler

## Overview

carbon-scheduler is a Python-accessible cooperative scheduler for Greenlet coroutines, with scheduling behavior intended to resemble Stackless Python. The principal workflow is to create and bind tasklets, run or yield through a thread-local schedule manager, and exchange values or exceptions through channels; QueueChannel adds buffered, nonblocking sends. The graph also shows the Python extension boundary and C API. Source excerpts are partial, so some internal links and documented capabilities are not wired where the caller could not be confirmed.

Main entry points: [`src/SchedulerModule.cpp`](https://github.com/carbonengine/scheduler/blob/main/src/SchedulerModule.cpp) (Extension module), [`src/Tasklet.cpp`](https://github.com/carbonengine/scheduler/blob/main/src/Tasklet.cpp) (Tasklet runtime), [`src/ScheduleManager.cpp`](https://github.com/carbonengine/scheduler/blob/main/src/ScheduleManager.cpp) (Schedule manager), [`src/Channel.cpp`](https://github.com/carbonengine/scheduler/blob/main/src/Channel.cpp) (Channel runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python interface"]
  node_package["Scheduler package<br/>[__init__.py]"]
  node_extension["Extension module"]
  node_tasklet_binding["Tasklet binding<br/>[PyTasklet.cpp]"]
  node_channel_binding["Channel binding<br/>[PyChannel.cpp]"]
  node_manager_binding["Manager binding"]
  node_c_api["C API<br/>[Scheduler.h]"]
end

subgraph group_runtime["Scheduling runtime"]
  node_manager["Schedule manager"]
  node_tasklet["Tasklet runtime<br/>[Tasklet.cpp]"]
end

subgraph group_communication["Tasklet communication"]
  node_channel["Channel runtime<br/>[Channel.cpp]"]
  node_queue_channel["QueueChannel<br/>[__init__.py]"]
end

subgraph group_integration["Runtime integrations"]
  node_greenlet["Greenlet runtime"]
end

node_python_user(("Python caller"))
node_c_api_client(("C API client"))

node_python_user -->|"uses"| node_package
node_package -->|"imports"| node_extension
node_extension -->|"calls"| node_manager
node_extension -->|"exposes"| node_tasklet_binding
node_extension -->|"exposes"| node_channel_binding
node_extension -->|"exposes"| node_manager_binding
node_tasklet_binding -->|"delegates to"| node_tasklet
node_channel_binding -->|"delegates to"| node_channel
node_manager_binding -->|"wraps"| node_manager
node_manager -->|"switches"| node_tasklet
node_tasklet -->|"schedules with"| node_manager
node_tasklet -->|"switches context"| node_greenlet
node_tasklet -->|"unblocks through"| node_channel
node_channel -->|"resumes scheduler"| node_manager
node_queue_channel -->|"extends"| node_channel
node_c_api_client -.->|"uses"| node_c_api
node_c_api -.->|"imports capsule"| node_extension

click node_package "https://github.com/carbonengine/scheduler/blob/main/python/scheduler/__init__.py"
click node_extension "https://github.com/carbonengine/scheduler/blob/main/src/SchedulerModule.cpp"
click node_tasklet_binding "https://github.com/carbonengine/scheduler/blob/main/src/PyTasklet.cpp"
click node_channel_binding "https://github.com/carbonengine/scheduler/blob/main/src/PyChannel.cpp"
click node_manager_binding "https://github.com/carbonengine/scheduler/blob/main/src/PyScheduleManager.cpp"
click node_c_api "https://github.com/carbonengine/scheduler/blob/main/include/Scheduler.h"
click node_manager "https://github.com/carbonengine/scheduler/blob/main/src/ScheduleManager.cpp"
click node_tasklet "https://github.com/carbonengine/scheduler/blob/main/src/Tasklet.cpp"
click node_channel "https://github.com/carbonengine/scheduler/blob/main/src/Channel.cpp"
click node_queue_channel "https://github.com/carbonengine/scheduler/blob/main/python/scheduler/__init__.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_package,node_extension,node_tasklet_binding,node_channel_binding,node_manager_binding,node_c_api,node_c_api_client toneBlue
class node_manager,node_tasklet toneAmber
class node_channel,node_queue_channel toneMint
class node_greenlet toneRose
class node_python_user toneIndigo
```

## Components

### Python interface

- [Scheduler package](https://github.com/carbonengine/scheduler/blob/main/python/scheduler/__init__.py): `python/scheduler/__init__.py`
- [Extension module](https://github.com/carbonengine/scheduler/blob/main/src/SchedulerModule.cpp): `src/SchedulerModule.cpp`
- [Tasklet binding](https://github.com/carbonengine/scheduler/blob/main/src/PyTasklet.cpp): `src/PyTasklet.cpp`
- [Channel binding](https://github.com/carbonengine/scheduler/blob/main/src/PyChannel.cpp): `src/PyChannel.cpp`
- [Manager binding](https://github.com/carbonengine/scheduler/blob/main/src/PyScheduleManager.cpp): `src/PyScheduleManager.cpp`
- [C API](https://github.com/carbonengine/scheduler/blob/main/include/Scheduler.h): `include/Scheduler.h`

### Scheduling runtime

- [Schedule manager](https://github.com/carbonengine/scheduler/blob/main/src/ScheduleManager.cpp): `src/ScheduleManager.cpp`
- [Tasklet runtime](https://github.com/carbonengine/scheduler/blob/main/src/Tasklet.cpp): `src/Tasklet.cpp`

### Tasklet communication

- [Channel runtime](https://github.com/carbonengine/scheduler/blob/main/src/Channel.cpp): `src/Channel.cpp`
- [QueueChannel](https://github.com/carbonengine/scheduler/blob/main/python/scheduler/__init__.py): `python/scheduler/__init__.py`

### Runtime integrations

- **Greenlet runtime**

### Other components

- **Python caller**
- **C API client**

## Connections

- Python caller → Scheduler package: uses
- Scheduler package → Extension module: imports
- Extension module → Schedule manager: calls
- Extension module → Tasklet binding: exposes
- Extension module → Channel binding: exposes
- Extension module → Manager binding: exposes
- Tasklet binding → Tasklet runtime: delegates to
- Channel binding → Channel runtime: delegates to
- Manager binding → Schedule manager: wraps
- Schedule manager → Tasklet runtime: switches
- Tasklet runtime → Schedule manager: schedules with
- Tasklet runtime → Greenlet runtime: switches context
- Tasklet runtime → Channel runtime: unblocks through
- Channel runtime → Schedule manager: resumes scheduler
- QueueChannel → Channel runtime: extends
- C API client → C API: uses
- C API → Extension module: imports capsule