API Reference

Exported types and functions in github.com/pardnchiu/go-queue/core.

Package

import goQueue "github.com/pardnchiu/go-queue/core"

Requires Go 1.23+.

Types

Queue

type Queue struct {
    // unexported fields
}

Public API and lifecycle entry point. Owns config, pending queue, and worker coordination.

Config

type Config struct {
    Workers int
    Size    int
    Timeout time.Duration
    Preset  map[string]PresetConfig
}

Field	Type	Default	Description
`Workers`	`int`	`runtime.NumCPU() * 2`	Worker count
`Size`	`int`	`Workers * 64`	Pending queue capacity
`Timeout`	`time.Duration`	`30 * time.Second`	Base timeout
`Preset`	`map[string]PresetConfig`	empty	Named priority/timeout presets

PresetConfig

type PresetConfig struct {
    Priority Priority
    Timeout  time.Duration
}

Field	Description
`Priority`	Priority level; zero value is `PriorityImmediate` (iota 0)
`Timeout`	When `0`, derived from base `Timeout` by priority

Priority

type Priority int

const (
    PriorityImmediate Priority = iota // 0
    PriorityHigh                      // 1
    PriorityRetry                     // 2
    PriorityNormal                    // 3
    PriorityLow                       // 4
)

Constant	Value	Description
`PriorityImmediate`	0	Highest, run first
`PriorityHigh`	1	High priority
`PriorityRetry`	2	Retry tasks
`PriorityNormal`	3	Default
`PriorityLow`	4	Lowest; may be promoted after wait

EnqueueOption

type EnqueueOption func(*enqueueConfig)

Functional option applied inside Enqueue.

Constructors

New

func New(config *Config) *Queue

Creates a queue. Pass nil for defaults. Initializes state to Created and builds the pending heap with promotion rules from config.Timeout.

Methods

Start

func (q *Queue) Start(ctx context.Context) error

Starts the worker pool. Transitions only from Created to Running via CAS.

Condition	Result
First call from Created	`nil`, spawns `Workers` goroutines
Already Running	`error: queue already started`
Already Closed	`error: queue already closed`

The provided ctx becomes the parent of all task execution contexts.

Enqueue

func (q *Queue) Enqueue(
    ctx context.Context,
    presetName string,
    action func(ctx context.Context) error,
    options ...EnqueueOption,
) (string, error)

Enqueues a task and returns its ID.

Condition	Result
Success	`(taskID, nil)`
`ctx` already canceled	`("", ctx.Err())`
Queue closed	`("", error wrapping "staging queue is closed")`
Queue full	`("", error wrapping "staging queue is full")`

presetName selects Config.Preset[name] for priority and timeout base. An empty or unknown name yields the zero-value preset (PriorityImmediate, timeout from base config).

Shutdown

func (q *Queue) Shutdown(ctx context.Context) error

Closes the queue, drains pending work, and waits for workers.

Condition	Result
Drain completes before `ctx` deadline	`nil`
Already Closed	`nil` (idempotent)
`ctx` times out	`error: shutdown timeout: N tasks remaining`

Options

Option	Signature	Description
`WithTaskID`	`func WithTaskID(id string) EnqueueOption`	Custom task ID; auto UUID if omitted
`WithTimeout`	`func WithTimeout(d time.Duration) EnqueueOption`	Override per-task timeout
`WithCallback`	`func WithCallback(fn func(id string)) EnqueueOption`	Async callback after success
`WithRetry`	`func WithRetry(retryMax ...int) EnqueueOption`	Enable retries; default max 3 when arg omitted

WithTaskID

func WithTaskID(id string) EnqueueOption

Sets a custom task identifier. If omitted or empty after options, Enqueue generates a UUID v4-style string.

WithTimeout

func WithTimeout(d time.Duration) EnqueueOption

Replaces the derived timeout for this task. Not clamped by the 15s–120s derivation bounds.

WithCallback

func WithCallback(fn func(id string)) EnqueueOption

Registers a success-only callback. Invoked as go fn(task.ID) after a nil error from action. Not called on failure, timeout, panic, or exhausted retries.

WithRetry

func WithRetry(retryMax ...int) EnqueueOption

Enables retry on failure/timeout/panic.

No arguments: retryMax = 3
One argument: uses that integer as max retry count
Each retry re-enqueues with PriorityRetry and resets startAt

Timeout Derivation

Base is Config.Timeout (or preset override), then adjusted by priority and clamped to 15s–120s:

Priority	Formula
Immediate	`timeout / 4`
High / Retry	`timeout / 2`
Normal	`timeout`
Low	`timeout * 2`

Priority Promotion

From	Wait	To
Low	`clamp(Timeout, 30s, 120s)`	Normal
Normal	`clamp(Timeout*2, 30s, 120s)`	High