v1.1.3
首頁 GitHub

架構

最後更新


本頁以一張概覽圖呈現 go-queue 各元件的層級關係；模組級的細部圖、時序圖與狀態機見 doc/architecture.zh.md。

系統概覽


graph TB
    C[呼叫端] -->|New / Start / Shutdown| Q[Queue]
    C -->|Enqueue + 選項| Q
    Q -->|解析 Preset 優先權與逾時| PR[優先權與逾時計算]
    Q -->|Push| P[pending]
    P --> H[taskHeap 最小堆]
    P -->|promoteLocked| H
    Q -->|啟動 N 個| W[Worker]
    W -->|Pop| P
    W --> E[execute]
    E -->|失敗且可重試| P
    E -->|成功| CB[Callback goroutine]
    E --> L[slog 事件]
    S[atomic.Uint32 狀態] -.-> Q
    S -.-> P
  1. graph TB
  2.     C[呼叫端] -->|New / Start / Shutdown| Q[Queue]
  3.     C -->|Enqueue + 選項| Q
  4.     Q -->|解析 Preset 優先權與逾時| PR[優先權與逾時計算]
  5.     Q -->|Push| P[pending]
  6.     P --> H[taskHeap 最小堆]
  7.     P -->|promoteLocked| H
  8.     Q -->|啟動 N 個| W[Worker]
  9.     W -->|Pop| P
  10.     W --> E[execute]
  11.     E -->|失敗且可重試| P
  12.     E -->|成功| CB[Callback goroutine]
  13.     E --> L[slog 事件]
  14.     S[atomic.Uint32 狀態] -.-> Q
  15.     S -.-> P

分層


層檔案職責
公開介面core/new.go、core/option.goNew／Start／Enqueue／Shutdown 與四個 EnqueueOption
執行core/new.go（worker、execute、setRetry）Worker 迴圈、逾時、panic 恢復、重試判斷、slog 事件
排程core/pending.go有界佇列：容量檢查、關閉判斷、sync.Cond 喚醒、自動升級
資料結構core/task.gocontainer/heap 最小堆與底層 slice 縮減
規則core/priority.go、core/pending.go（getPromotion）優先權常數、逾時倍率與升級門檻

跨切原則


原則實作方式
生命週期無鎖Queue 狀態為 atomic.Uint32，Start／Shutdown 以 CAS 轉換；pending 讀同一個狀態判斷是否拒絕入列
堆操作單一鎖Push、Pop、升級都在 pending.mu 內完成，Worker 空閒時以 cond.Wait 休眠，不輪詢
任務故障隔離任務在獨立 goroutine 中執行並 recover，逾時由 select 判斷，Worker 不會被卡住或崩潰
有界記憶體堆長度上限為 Config.Size；容量超過下限 max(16, min(Size/8, Size/Workers)) 的 4 倍後，長度低於容量 1/8 時底層 slice 縮為四分之一（不低於下限）
可觀測性所有結果都經由 log/slog 輸出，事件名稱固定（task.completed、task.retrying 等）

延伸閱讀


EN