文件
首頁 GitHub

API 參考

本頁說明 core 套件提供的公開設定型別，以及生命週期、任務、依賴與排程方法。

套件

import "github.com/pardnchiu/go-scheduler/core"

建構函式回傳的排程器具體型別是套件內部型別；但透過回傳值仍可呼叫其公開方法。

Config

type Config struct {
    Location *time.Location
}
欄位 型別 說明
Location *time.Location 計算排程觸發時間時使用的時區。nil 時使用 time.Local。

New

func New(c Config) (*cron, error)

建立排程器，並初始化任務 heap、解析器、依賴管理器、通道與 logger。logger 優先使用 syslog；無法建立 syslog 時回退至資訊等級的 stderr logger。

loc, err := time.LoadLocation("Asia/Taipei")
if err != nil {
    return err
}

scheduler, err := core.New(core.Config{Location: loc})

Start 與 Stop

func (c *cron) Start()
func (c *cron) Stop() context.Context

scheduler.Start()
// ... 執行應用程式 ...
shutdown := scheduler.Stop()
<-shutdown.Done()

Add

func (c *cron) Add(spec string, action interface{}, arg ...interface{}) (int64, error)

解析 spec、註冊任務，並回傳單調遞增的 int64 任務 ID。可以在 Start 前或後新增排程。

參數 型別 說明
spec string 五欄位 Cron 表達式、支援的描述符，或 @every <duration>。
action func() 或 func() error 任務本體。需要依賴或明確回報失敗時使用 func() error。
arg variadic 可選的描述、逾時、逾時回呼或依賴列表。

支援的選用參數：

參數型別 用途
string 儲存於任務中的描述，會用於 logger。
time.Duration 任務本體的最長執行時間。
func() 設定的執行逾時到期時呼叫（onDelay）。
[]core.Wait 前置任務與其失敗策略。
[]int64 已棄用的前置任務 ID 列表；會轉換成預設 Stop 策略的 Wait。

含依賴的任務必須使用 func() error，否則 Add 會回傳錯誤。排程表達式無效或傳入不支援的 action 型別時，Add 也會回傳錯誤。

id, err := scheduler.Add("*/5 * * * *", func() error {
    return poll()
}, "poll", 10*time.Second, func() {
    log.Println("poll timed out")
})

Remove、RemoveAll 與 List

func (c *cron) Remove(id int64)
func (c *cron) RemoveAll()
func (c *cron) List() []*task
方法 說明
Remove 停用並移除指定 ID 的啟用中任務。
RemoveAll 從 heap 移除所有排程項目。
List 回傳目前由排程器 heap 持有且啟用中的任務指標。每個任務可讀取公開的 ID 欄位。

排程器執行中時，新增與移除操作會透過通道交給事件迴圈處理；Start 前則直接更新 heap。

Wait 與 WaitState

type Wait struct {
    ID    int64
    Delay time.Duration
    State WaitState
}

type WaitState int

const (
    Stop WaitState = iota
    Skip
)
欄位 說明
ID 前置任務 ID。
Delay 等待依賴完成的最長時間。零值時使用依賴 worker 預設的一分鐘。
State 失敗策略：Stop 會讓相依任務失敗，Skip 會忽略該失敗的前置任務。 
parentID, _ := scheduler.Add("@every 1m", func() error {
    return prepare()
})

_, err := scheduler.Add("@every 1m", func() error {
    return process()
}, []core.Wait{{
    ID: parentID,
    Delay: 10 * time.Second,
    State: core.Stop,
}})

任務狀態

const (
    TaskPending int = iota
    TaskRunning
    TaskCompleted
    TaskFailed
)

這些常數描述內部任務生命週期。週期任務在一次觸發派送後會再次排程；action 回傳錯誤、發生 panic 或逾時時，該次執行會標記為失敗。

排程語法

格式 範例 說明
五欄位 Cron */5 9-17 * * 1-5 分、時、日、月、週
描述符 @hourly、@daily、@weekly、@monthly、@yearly 內建排程捷徑；也接受 @annually 與 @midnight。
固定間隔 @every 30s 依解析出的 duration 重複；最小間隔為 30 秒。
欄位語法 *、n、n-m、a,b,c、*/n 萬用字元、單值、範圍、列表與步進

Cron 欄位範圍為：分鐘 0-59、小時 0-23、日 1-31、月 1-12、星期 0-6；其中星期日為 0。

EN