A min-heap based priority task queue with automatic promotion, retry, and panic recovery, designed for Go concurrency workloads.

• Features
• Architecture
• File Structure
• License
• Author
• Stars

go get github.com/pardnchiu/go-queue · Documentation

Tasks are scheduled through a min-heap across five priority levels: Immediate, High, Retry, Normal, and Low. Low-priority tasks automatically promote to higher levels after exceeding a configurable wait threshold, eliminating starvation without manual intervention.

Queue state transitions from Created to Running to Closed are driven entirely by atomic.CompareAndSwap, avoiding mutexes on the Start and Shutdown paths. This ensures safe concurrent access from multiple goroutines with minimal latency.

Each task supports a configurable retry limit; failed tasks re-enter the heap at Retry priority. Workers automatically recover from panics and convert them to error reports, preventing a single task crash from taking down the entire worker pool.

graph TB
    E[Enqueue] -->|Push| H[Min-Heap]
    H -->|Pop| W[Worker Pool]
    W -->|Execute| T[Task]
    T -->|Fail + Retry| H
    H -->|Promote| H
    T -->|Success| CB[Callback]
    T -->|Panic| R[Recovery → Error]

go-queue/
├── new.go              # Queue construction, worker startup and shutdown
├── task.go             # Task struct and min-heap implementation
├── pending.go          # Pending queue, push/pop and auto-promotion
├── priority.go         # Priority level definitions and timeout calculation
├── option.go           # Enqueue options (TaskID, Timeout, Callback, Retry)
├── main_test.go        # Tests
├── go.mod
└── LICENSE

This project is licensed under the MIT LICENSE.

©️ 2025 邱敬幃 Pardn Chiu