Architecture
Last updated
This page shows go-scheduler's component layers and cross-cutting principles in a single overview diagram.
System Overview
graph TB
App[Caller] --> Cron[cron scheduler]
Cron --> Parser[Expression parser]
Cron --> Heap[Task min-heap]
Heap --> Loop[Event loop goroutine]
Loop -->|no deps| Direct[Direct goroutine run]
Loop -->|has deps| Queue[Wait queue]
Queue --> Workers[Dependency worker pool]
Workers --> Manager[dependManager]
Direct --> State[Task state]
Manager --> State- graph TB
- App[Caller] --> Cron[cron scheduler]
- Cron --> Parser[Expression parser]
- Cron --> Heap[Task min-heap]
- Heap --> Loop[Event loop goroutine]
- Loop -->|no deps| Direct[Direct goroutine run]
- Loop -->|has deps| Queue[Wait queue]
- Queue --> Workers[Dependency worker pool]
- Workers --> Manager[dependManager]
- Direct --> State[Task state]
- Manager --> State
Layers
| Layer | Component | Files | Responsibility |
|---|---|---|---|
| Public interface | cron | core/instance.go, core/add.go, core/remove.go, core/task.go | New / Start / Stop / Add / Remove / RemoveAll / List |
| Parsing | parser | core/schedule.go | Turns a spec into scheduleResult (cron, descriptors) or delayScheduleResult (@every) |
| Scheduling | taskHeap | core/task.go | Min-heap ordered by next; the event loop only waits on the top entry |
| Execution | cron.runAfter | core/instance.go | Tasks without dependencies: goroutine run, timeout, panic recovery |
| Dependencies | depend, dependManager | core/depend.go, core/dependManager.go | Queue (capacity 1024), worker pool, prerequisite polling, result updates |
Cross-Cutting Principles
| Principle | Implementation |
|---|---|
| One event loop owns the heap | After Start, add, remove, and clear go through the add / remove / removeAll channels; before Start the heap is modified directly |
| Per-task locking | Each task holds a sync.RWMutex; dependency checks read prerequisite state under a read lock |
| Dependent and plain tasks are split | cron.run runs directly or enqueues to the worker pool based on whether after is empty |
| Bounded worker count | runtime.NumCPU() when greater than 2, otherwise 2 |
| Shutdown does not interrupt actions | Stop waits for the WaitGroup and workers; actions do not receive a context |
Further Reading
- Task Model — task states
- Task Dependencies — dependency evaluation rules
- Full architecture document — per-module diagrams, data flow, and state machine