Documentation
Home GitHub

Architecture

System overview of go-queue: public API, pending priority heap, worker pool, and lifecycle.

Overview

graph TB
    App[Application] --> Enqueue[Enqueue]
    App --> Start[Start]
    App --> Shutdown[Shutdown]
    Enqueue --> Pending[Pending Heap]
    Start --> Workers[Worker Pool]
    Pending --> Workers
    Workers --> Execute[Execute / Timeout / Retry]
    Shutdown --> Pending
    Shutdown --> Workers
Component Role
Queue Public API; owns config, pending queue, workers, and CAS state
pending Mutex + cond-protected priority heap with promotion and close broadcast
taskHeap container/heap ordered by priority then startAt
Workers Goroutines that Pop, execute with timeout, retry or callback

Data flow

  1. Caller creates a queue with New, then Start spawns Workers goroutines.
  2. Enqueue builds a task (preset priority, timeout, options) and pending.Push.
  3. A worker Pops the highest-priority task (after promotion), then executes it under a timeout context.
  4. Success runs an optional async callback; failure may setRetry and re-push at PriorityRetry.
  5. Shutdown CAS-closes state, closes pending, and waits on the worker WaitGroup.

Module layout

File Responsibility
core/new.go Queue, Config, New, Start, Enqueue, Shutdown, execute/retry
core/option.go EnqueueOption helpers
core/pending.go pending queue, promotion rules, close
core/priority.go Priority constants and timeout derivation
core/task.go task and taskHeap heap interface

Lifecycle states

stateDiagram-v2
    [*] --> Created
    Created --> Running: Start CAS
    Running --> Closed: Shutdown CAS
    Created --> Closed: Shutdown CAS
    Closed --> Closed: Shutdown idempotent
中文