v1.1.3
Home GitHub

Architecture

Last updated


This page shows how go-queue's components relate in a single overview diagram; per-module diagrams, sequence diagrams, and state machines live in doc/architecture.md.

System Overview


graph TB
    C[Caller] -->|New / Start / Shutdown| Q[Queue]
    C -->|Enqueue + options| Q
    Q -->|Resolve preset priority and timeout| PR[Priority and Timeout]
    Q -->|Push| P[pending]
    P --> H[taskHeap min-heap]
    P -->|promoteLocked| H
    Q -->|Spawns N| W[Worker]
    W -->|Pop| P
    W --> E[execute]
    E -->|Failed and retryable| P
    E -->|Success| CB[Callback goroutine]
    E --> L[slog Events]
    S[atomic.Uint32 state] -.-> Q
    S -.-> P
  1. graph TB
  2.     C[Caller] -->|New / Start / Shutdown| Q[Queue]
  3.     C -->|Enqueue + options| Q
  4.     Q -->|Resolve preset priority and timeout| PR[Priority and Timeout]
  5.     Q -->|Push| P[pending]
  6.     P --> H[taskHeap min-heap]
  7.     P -->|promoteLocked| H
  8.     Q -->|Spawns N| W[Worker]
  9.     W -->|Pop| P
  10.     W --> E[execute]
  11.     E -->|Failed and retryable| P
  12.     E -->|Success| CB[Callback goroutine]
  13.     E --> L[slog Events]
  14.     S[atomic.Uint32 state] -.-> Q
  15.     S -.-> P

Layers


LayerFilesResponsibility
Public interfacecore/new.go, core/option.goNew / Start / Enqueue / Shutdown and the four EnqueueOption helpers
Executioncore/new.go (worker, execute, setRetry)Worker loop, timeout, panic recovery, retry decision, slog events
Schedulingcore/pending.goBounded queue: capacity check, closure check, sync.Cond wake-ups, auto-promotion
Data structurecore/task.gocontainer/heap min-heap and backing-slice shrinking
Rulescore/priority.go, core/pending.go (getPromotion)Priority constants, timeout multipliers, and promotion thresholds

Cross-Cutting Principles


PrincipleImplementation
Lock-free lifecycleQueue state is an atomic.Uint32; Start / Shutdown transition via CAS, and pending reads the same state to reject enqueues
One lock for heap workPush, Pop, and promotion all run under pending.mu; idle workers sleep on cond.Wait instead of polling
Task fault isolationTasks run in their own goroutine with recover, and select enforces the timeout, so a worker never hangs or crashes
Bounded memoryHeap length is capped at Config.Size; once capacity exceeds 4 times the floor max(16, min(Size/8, Size/Workers)), the backing slice shrinks to a quarter (never below the floor) when length drops below 1/8 of capacity
ObservabilityEvery outcome goes through log/slog with fixed event names (task.completed, task.retrying, and so on)

Further Reading


  • Exact values and behavior of each rule → Core Concepts, which links to one page per rule
  • Full module diagrams, sequence diagram, and state machines → doc/architecture.md
中文