Documentation
Home GitHub

Getting Started

Install go-queue, start a worker pool, enqueue tasks with optional presets, and shut down cleanly.

Prerequisites

Installation

go get github.com/pardnchiu/go-queue

Import path for the public API:

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

Basic usage

package main

import (
    "context"
    "fmt"
    "log"
    "time"

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

func main() {
    q := goQueue.New(&goQueue.Config{
        Workers: 4,
    })

    ctx := context.Background()
    if err := q.Start(ctx); err != nil {
        log.Fatal(err)
    }
    defer func() {
        if err := q.Shutdown(context.Background()); err != nil {
            log.Printf("shutdown: %v", err)
        }
    }()

    id, err := q.Enqueue(ctx, "", func(ctx context.Context) error {
        fmt.Println("task running")
        return nil
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("enqueued:", id)
    time.Sleep(100 * time.Millisecond)
}

Priority presets

Named presets map enqueue names to priority and optional timeout overrides.

q := goQueue.New(&goQueue.Config{
    Workers: 2,
    Timeout: 30 * time.Second,
    Preset: map[string]goQueue.PresetConfig{
        "urgent": {Priority: goQueue.PriorityImmediate},
        "batch":  {Priority: goQueue.PriorityLow, Timeout: 60 * time.Second},
    },
})

_ = q.Start(ctx)

_, _ = q.Enqueue(ctx, "urgent", func(ctx context.Context) error {
    // high priority work
    return nil
})

_, _ = q.Enqueue(ctx, "batch", func(ctx context.Context) error {
    // low priority work
    return nil
})

Enqueue options

id, err := q.Enqueue(ctx, "urgent", func(ctx context.Context) error {
    // business logic
    return nil
},
    goQueue.WithTaskID("order-123"),
    goQueue.WithTimeout(10*time.Second),
    goQueue.WithRetry(2),
    goQueue.WithCallback(func(id string) {
        fmt.Println("done:", id)
    }),
)
if err != nil {
    log.Fatal(err)
}
Option Purpose
WithTaskID Custom task ID; auto UUID if omitted
WithTimeout Override per-task timeout
WithRetry Enable retries; default max 3 when arg omitted
WithCallback Async callback after success

Graceful shutdown

shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

if err := q.Shutdown(shutdownCtx); err != nil {
    // timed out: tasks still remaining
    log.Printf("shutdown: %v", err)
}

Shutdown is idempotent. On context timeout it returns the remaining pending task count.

From source

git clone https://github.com/pardnchiu/go-queue.git
cd go-queue
go test ./...

Next steps

中文