架構

go-queue 系統概覽：公開 API、pending 優先 heap、worker 池與生命週期。

概覽

graph TB
    App[應用程式] --> Enqueue[Enqueue]
    App --> Start[Start]
    App --> Shutdown[Shutdown]
    Enqueue --> Pending[待處理 Heap]
    Start --> Workers[Worker 池]
    Pending --> Workers
    Workers --> Execute[執行 / 逾時 / 重試]
    Shutdown --> Pending
    Shutdown --> Workers

元件	職責
`Queue`	公開 API；持有設定、pending 佇列、worker 與 CAS 狀態
`pending`	mutex + cond 保護的優先 heap，支援晉升與關閉廣播
`taskHeap`	`container/heap`，依 priority 再依 `startAt` 排序
Workers	負責 `Pop`、逾時執行、重試或 callback 的 goroutine

資料流

呼叫端以 New 建立佇列，再以 Start 啟動 Workers 個 goroutine。
Enqueue 組出 task（preset 優先級、逾時、選項）並 pending.Push。
Worker 在晉升後 Pop 最高優先任務，於逾時 context 下 execute。
成功則非同步 callback；失敗可 setRetry 並以 PriorityRetry 重新入隊。
Shutdown 以 CAS 關閉狀態、關閉 pending，並等待 worker WaitGroup。

模組配置

檔案	職責
`core/new.go`	`Queue`、`Config`、`New`、`Start`、`Enqueue`、`Shutdown`、執行／重試
`core/option.go`	`EnqueueOption` 輔助函式
`core/pending.go`	pending 佇列、晉升規則、關閉
`core/priority.go`	`Priority` 常數與逾時推算
`core/task.go`	`task` 與 `taskHeap` heap 介面

生命週期狀態

stateDiagram-v2
    [*] --> Created
    Created --> Running: Start CAS
    Running --> Closed: Shutdown CAS
    Created --> Closed: Shutdown CAS
    Closed --> Closed: Shutdown 冪等

Start 僅允許 Created → Running。
Shutdown 可從 Created 或 Running 關閉；重複呼叫為 no-op。
關閉且 heap 為空時 worker 結束；shutdown 逾時則回報剩餘長度。

架構

概覽

資料流

模組配置

生命週期狀態

相關頁面