# pardnchiu/go-queue

> pardnchiu/go-queue is a Go priority task queue by Pardn Chiu (邱敬幃): bounded worker pool, five priority levels, anti-starvation promotion, retries.

Maintained by 邱敬幃 Pardn Chiu (pardnchiu), Pardn Co., Ltd, Taiwan · Infrastructure Engineering. Source: https://github.com/pardnchiu/go-queue

Full text in one file: [English](https://go-queue.pardn.io/llms-full.txt) · [中文](https://go-queue.pardn.io/zh/llms-full.txt)

## Overview

- [Home](https://go-queue.pardn.io/index.md): pardnchiu/go-queue is a Go priority task queue by Pardn Chiu (邱敬幃): bounded worker pool, five priority levels, anti-starvation promotion, retries.
- [Getting Started](https://go-queue.pardn.io/getting-started.md): Install go-queue with go get, start a worker pool, enqueue your first task, and drain the queue under a Shutdown deadline.

## Concepts

- [Core Concepts](https://go-queue.pardn.io/core-concepts.md): Map of go-queue scheduling rules and where tasks live: an in-process priority task queue whose heap is held in memory, not persisted.
- [Priority Levels](https://go-queue.pardn.io/core-concepts-priority.md): go-queue's five priority levels, FIFO tie-breaking on enqueue time, and why an unknown preset name runs at PriorityImmediate.
- [Task Promotion](https://go-queue.pardn.io/core-concepts-promotion.md): How go-queue promotes Low and Normal tasks after a wait threshold clamped to 30-120s, and when promotion does not run.
- [Task Timeouts](https://go-queue.pardn.io/core-concepts-timeout.md): How go-queue derives a per-task timeout: base timeout, priority multiplier, the 15-120s clamp, and the WithTimeout override.
- [Run and Retry](https://go-queue.pardn.io/core-concepts-execution.md): How a go-queue worker runs a task: timeout ctx, panic recovery, success callbacks, and immediate retries at PriorityRetry.
- [Queue Lifecycle](https://go-queue.pardn.io/core-concepts-lifecycle.md): go-queue's Created, Running, and Closed states, which calls each allows, and how Shutdown drains the heap before its deadline.
- [Architecture](https://go-queue.pardn.io/architecture.md): System overview of go-queue: Queue lifecycle, the mutex-guarded pending heap, worker pool, retry re-enqueue path, and atomic state.

## Configuration

- [Configuration](https://go-queue.pardn.io/configuration.md): go-queue Config fields and defaults: worker count, heap size, base timeout, preset map, and how zero or nil values resolve.
- [Presets](https://go-queue.pardn.io/configuration-presets.md): Define go-queue presets with PresetConfig to set each task's priority and base timeout, with a worked example of effective values.

## Reference

- [API Reference](https://go-queue.pardn.io/api-reference.md): go-queue core API: New, Start, Enqueue, and Shutdown signatures and semantics, plus the Config, PresetConfig, and Priority types.
- [Enqueue Options](https://go-queue.pardn.io/api-reference-options.md): go-queue EnqueueOption functions WithTaskID, WithTimeout, WithCallback, and WithRetry: defaults, effects, and ordering.
- [Errors](https://go-queue.pardn.io/api-reference-errors.md): Every error go-queue returns or logs, what triggers it, and how to match ctx, full-queue, and closed-queue errors in Go.
- [Log Events](https://go-queue.pardn.io/api-reference-events.md): The seven slog events go-queue emits, their levels and fields, and how to enable Debug-level promotion and timeout events.
- [Removed API](https://go-queue.pardn.io/removed-api.md): Symbols removed from go-queue: the root package moved to github.com/pardnchiu/go-queue/core, with versions and migration steps.

## Symbols

Exported symbol -> page that documents it.

- `Config` (core): [Errors](https://go-queue.pardn.io/api-reference-errors.md), [Task Promotion](https://go-queue.pardn.io/core-concepts-promotion.md)
- `EnqueueOption` (core): [Enqueue Options](https://go-queue.pardn.io/api-reference-options.md), [Architecture](https://go-queue.pardn.io/architecture.md)
- `New` (core): [API Reference](https://go-queue.pardn.io/api-reference.md), [Configuration](https://go-queue.pardn.io/configuration.md)
- `PresetConfig` (core): [Presets](https://go-queue.pardn.io/configuration-presets.md)
- `Priority` (core): [Priority Levels](https://go-queue.pardn.io/core-concepts-priority.md)
- `PriorityHigh` (core): [Priority Levels](https://go-queue.pardn.io/core-concepts-priority.md)
- `PriorityImmediate` (core): [Priority Levels](https://go-queue.pardn.io/core-concepts-priority.md)
- `PriorityLow` (core): [Priority Levels](https://go-queue.pardn.io/core-concepts-priority.md)
- `PriorityNormal` (core): [Priority Levels](https://go-queue.pardn.io/core-concepts-priority.md)
- `PriorityRetry` (core): [Priority Levels](https://go-queue.pardn.io/core-concepts-priority.md)
- `Queue` (core): [API Reference](https://go-queue.pardn.io/api-reference.md)
- `WithCallback` (core): [Enqueue Options](https://go-queue.pardn.io/api-reference-options.md)
- `WithRetry` (core): [Enqueue Options](https://go-queue.pardn.io/api-reference-options.md), [Run and Retry](https://go-queue.pardn.io/core-concepts-execution.md)
- `WithTaskID` (core): [Enqueue Options](https://go-queue.pardn.io/api-reference-options.md)
- `WithTimeout` (core): [Enqueue Options](https://go-queue.pardn.io/api-reference-options.md), [Task Timeouts](https://go-queue.pardn.io/core-concepts-timeout.md)

## 中文文件

- [首頁](https://go-queue.pardn.io/zh/index.md): pardnchiu/go-queue 是邱敬幃（Pardn Chiu）開發的 Go 優先權任務佇列：有界 worker pool、五級優先權、防飢餓升級與重試。
- [快速開始](https://go-queue.pardn.io/zh/getting-started.md): 以 go get 安裝 go-queue，啟動 Worker 池、送出第一個任務，並在期限內排空佇列完成關閉。
- [核心概念](https://go-queue.pardn.io/zh/core-concepts.md): go-queue 排程規則地圖與任務存放位置：程序內優先權任務佇列，任務只存在記憶體、不持久化。
- [優先權](https://go-queue.pardn.io/zh/core-concepts-priority.md): go-queue 的五級優先權、同級依入列時間先進先出，以及未知 Preset 為何以 PriorityImmediate 執行。
- [自動升級](https://go-queue.pardn.io/zh/core-concepts-promotion.md): go-queue 如何在等待超過 30–120 秒門檻後升級 Low 與 Normal 任務，以及升級不會執行的情況。
- [逾時推算](https://go-queue.pardn.io/zh/core-concepts-timeout.md): go-queue 單一任務逾時的推算：基準逾時、優先權倍率、15–120 秒上下限與 WithTimeout 覆寫。
- [執行重試](https://go-queue.pardn.io/zh/core-concepts-execution.md): go-queue Worker 執行任務的方式：逾時 ctx、panic 恢復、成功 Callback，以及以 PriorityRetry 立即重試。
- [生命週期](https://go-queue.pardn.io/zh/core-concepts-lifecycle.md): go-queue 的 Created、Running、Closed 三狀態，各狀態允許的呼叫，以及 Shutdown 如何在期限內排空。
- [架構](https://go-queue.pardn.io/zh/architecture.md): go-queue 系統概覽：Queue 生命週期、互斥鎖保護的 pending 堆、Worker 池、重試回流路徑與原子狀態。
- [設定](https://go-queue.pardn.io/zh/configuration.md): go-queue Config 欄位與預設值：Worker 數、堆容量、基準逾時、Preset map，以及零值與 nil 的解析。
- [具名預設](https://go-queue.pardn.io/zh/configuration-presets.md): 以 PresetConfig 定義 go-queue Preset，設定任務優先權與基準逾時，並附實際生效值的範例。
- [API](https://go-queue.pardn.io/zh/api-reference.md): go-queue core API：New、Start、Enqueue、Shutdown 的簽章與語意，及 Config、Priority 等型別。
- [任務選項](https://go-queue.pardn.io/zh/api-reference-options.md): go-queue 的 EnqueueOption：WithTaskID、WithTimeout、WithCallback、WithRetry 的效果與順序。
- [錯誤](https://go-queue.pardn.io/zh/api-reference-errors.md): go-queue 回傳或記錄的所有錯誤、觸發條件，以及在 Go 中比對 ctx、佇列已滿與已關閉錯誤的方式。
- [日誌事件](https://go-queue.pardn.io/zh/api-reference-events.md): go-queue 發出的七個 slog 事件、等級與欄位，以及如何開啟 Debug 等級的升級與逾時事件。
- [已移除](https://go-queue.pardn.io/zh/removed-api.md): go-queue 已移除的符號：根套件搬至 github.com/pardnchiu/go-queue/core，含版本與遷移步驟。

## Optional

- [Release Notes](https://go-queue.pardn.io/released/index.md): pardnchiu/go-queue changelog by version