文件
首頁 GitHub

API 參考

github.com/pardnchiu/go-queue/core 的匯出型別與函式。

Package

import goQueue "github.com/pardnchiu/go-queue/core"

需要 Go 1.23+。

型別

Queue

type Queue struct {
    // unexported fields
}

對外 API 與生命週期入口。持有設定、pending 佇列與 worker 協調。

Config

type Config struct {
    Workers int
    Size    int
    Timeout time.Duration
    Preset  map[string]PresetConfig
}
欄位 型別 預設 說明
Workers int runtime.NumCPU() * 2 Worker 數量
Size int Workers * 64 待處理佇列容量
Timeout time.Duration 30 * time.Second 基準逾時
Preset map[string]PresetConfig empty 具名優先級／逾時設定

PresetConfig

type PresetConfig struct {
    Priority Priority
    Timeout  time.Duration
}
欄位 說明
Priority 優先級；零值為 PriorityImmediate（iota 0）
Timeout 0 時依 Priority 由基準 Timeout 推算

Priority

type Priority int

const (
    PriorityImmediate Priority = iota // 0
    PriorityHigh                      // 1
    PriorityRetry                     // 2
    PriorityNormal                    // 3
    PriorityLow                       // 4
)
常數 值 說明
PriorityImmediate 0 最高，立刻執行
PriorityHigh 1 高優先
PriorityRetry 2 重試任務
PriorityNormal 3 一般
PriorityLow 4 最低；逾時後可晉升

EnqueueOption

type EnqueueOption func(*enqueueConfig)

在 Enqueue 內套用的 functional option。

建構子

New

func New(config *Config) *Queue

建立佇列。config 可為 nil，此時使用預設值。狀態初始化為 Created，並依 config.Timeout 建立含晉升規則的 pending heap。

方法

Start

func (q *Queue) Start(ctx context.Context) error

啟動 worker 池。僅能透過 CAS 從 Created 轉為 Running。

條件 結果
首次自 Created 呼叫 nil，產生 Workers 個 goroutine
已 Running error: queue already started
已 Closed error: queue already closed

傳入的 ctx 成為所有任務執行 context 的父層。

Enqueue

func (q *Queue) Enqueue(
    ctx context.Context,
    presetName string,
    action func(ctx context.Context) error,
    options ...EnqueueOption,
) (string, error)

將任務入隊並回傳 ID。

條件 結果
成功 (taskID, nil)
ctx 已取消 ("", ctx.Err())
佇列已關閉 ("", error wrapping "staging queue is closed")
佇列已滿 ("", error wrapping "staging queue is full")

presetName 選取 Config.Preset[name] 的優先級與逾時基準。空字串或未知名稱使用零值 preset（PriorityImmediate，逾時來自基準設定）。

Shutdown

func (q *Queue) Shutdown(ctx context.Context) error

關閉佇列、排空待處理任務並等待 worker。

條件 結果
在 ctx 期限前排空完成 nil
已 Closed nil（冪等）
ctx 逾時 error: shutdown timeout: N tasks remaining

選項

選項 簽章 說明
WithTaskID func WithTaskID(id string) EnqueueOption 自訂 task ID；省略則自動 UUID
WithTimeout func WithTimeout(d time.Duration) EnqueueOption 覆寫本次任務逾時
WithCallback func WithCallback(fn func(id string)) EnqueueOption 成功完成後非同步回呼
WithRetry func WithRetry(retryMax ...int) EnqueueOption 啟用重試；省略參數時預設最多 3 次

WithTaskID

func WithTaskID(id string) EnqueueOption

設定自訂任務識別碼。選項套用後仍為空時，Enqueue 會產生 UUID v4 風格字串。

WithTimeout

func WithTimeout(d time.Duration) EnqueueOption

取代本次任務的推算逾時。不受 15s–120s 推算上下限限制。

WithCallback

func WithCallback(fn func(id string)) EnqueueOption

註冊僅成功時觸發的回呼。在 action 回傳 nil 後以 go fn(task.ID) 呼叫。失敗、逾時、panic 或重試耗盡時不呼叫。

WithRetry

func WithRetry(retryMax ...int) EnqueueOption

在失敗／逾時／panic 時啟用重試。

逾時推算規則

基準為 Config.Timeout（或 preset 覆寫），再依優先級調整，並限制在 15s–120s：

Priority 計算
Immediate timeout / 4
High / Retry timeout / 2
Normal timeout
Low timeout * 2

優先級晉升

來源 等待時間 目標
Low clamp(Timeout, 30s, 120s) Normal
Normal clamp(Timeout*2, 30s, 120s) High

另見

EN