核心概念
本頁說明任務模型、排程語法、依賴策略、逾時處理與生命週期規則。
任務模型
排程任務包含排程、action、可選描述、可選執行逾時與啟用狀態。Add 接受 func() 或 func() error。任務參與依賴處理或需要回報失敗時，請使用 func() error。
每個任務會取得單調遞增的 int64 ID。List 回傳目前由排程器 heap 持有且啟用中的任務。Remove 依 ID 停用一個任務；RemoveAll 清除所有排程項目。
Cron 排程
解析器接受正好五個欄位，順序如下：
| 欄位 | 範圍 | 意義 |
|---|---|---|
| 分鐘 | 0–59 | 小時中的分鐘 |
| 小時 | 0–23 | 每日的小時 |
| 日 | 1–31 | 月曆日期 |
| 月 | 1–12 | 月份 |
| 星期 | 0–6 | 星期日到星期六 |
每個欄位支援萬用字元（*）、單值、範圍（9-17）、逗號分隔列表（9,12,18）或步進（*/5）。例如 */5 9-17 * * 1-5 會在工作日的辦公時間內每五分鐘執行一次。
描述符與間隔
排程器支援 @yearly、@annually、@monthly、@weekly、@daily、@midnight 與 @hourly。@every <duration> 會建立固定間隔排程，最小間隔為 30 秒。
c.Add("@hourly", func() error { return nil })
c.Add("@every 5m", func() error { return refreshCache() })
Cron 表達式會從目前時間往後搜尋下一個符合的分鐘。固定間隔則將設定的 duration 加到目前時間，計算下一次執行時間。
依賴
將 []core.Wait 傳給 Add 以宣告前置任務：
parentID, _ := c.Add("@every 1m", func() error {
return prepare()
})
_, err := c.Add("@every 1m", func() error {
return process()
}, []core.Wait{{ID: parentID, Delay: 10 * time.Second, State: core.Stop}})
相依任務會等待所有前置任務完成。Wait.Delay 控制依賴 worker 等待的時間；為零時使用一分鐘。Stop 會在前置任務失敗時讓相依任務失敗；Skip 忽略失敗的前置任務，繼續評估其他依賴。
逾時與回呼
傳入 time.Duration 可設定執行逾時，並傳入 func() 接收逾時回呼：
c.Add("@every 1m", func() error {
return slowJob()
}, 3*time.Second, func() {
log.Println("task timed out")
})
逾時會將任務標記為失敗，並呼叫 onDelay。action 回傳錯誤或發生 panic 也會產生失敗狀態。排程器會在內部記錄任務的開始時間、結束時間、執行時間與錯誤，供依賴更新與 logger 使用。
生命週期與並行
Start 啟動事件迴圈與依賴 worker；排程器已執行時重複呼叫不會產生作用。排程器使用最小堆等待最近的下一次觸發。啟動後的新增與移除操作會透過通道傳送，讓事件迴圈安全地重新計算 timer。
Stop 停止排程新的觸發與依賴 worker，並回傳一個在排程器管理的執行中任務完成後才取消的 context，讓呼叫端等待優雅關閉。
狀態轉換
任務會經過以下狀態：
Pending -> Running -> Completed
\-> Failed
週期任務在一次觸發派送後會被放回 heap，等待下一次排程。移除任務會停用其 heap 項目，避免未來再次執行。