Getting Started

Last updated 2026-10-30

This page covers installing go-queue, starting a worker pool, enqueueing a first task, and shutting the queue down within a deadline.

Prerequisites

Item	Requirement
Go	1.23 or higher (`go.mod` declares `go 1.23`)
External dependencies	None; standard library only

Installation

go get github.com/pardnchiu/go-queue

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

The public API lives in the core sub-package. This path ships in the first release after v1.1.3; until that tag exists, use go get github.com/pardnchiu/go-queue@develop.

Your First Queue

package main
import (
	"context"
	"fmt"
	"log"
	"time"
	"github.com/pardnchiu/go-queue/core"
)
func main() {
	q := core.New(&core.Config{Workers: 4})
	ctx := context.Background()
	if err := q.Start(ctx); err != nil {
		log.Fatal(err)
	}
	for i := range 3 {
		id, err := q.Enqueue(ctx, "", func(ctx context.Context) error {
			fmt.Println("task", i, "running")
			return nil
		})
		if err != nil {
			log.Printf("enqueue: %v", err)
			continue
		}
		fmt.Println("enqueued", id)
	}
	// Drain the queue, waiting at most 10 seconds
	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()
	if err := q.Shutdown(shutdownCtx); err != nil {
		log.Printf("shutdown: %v", err)
	}
}

Each task emits one task.completed slog record with the task ID, preset name, and elapsed time.

Three Lifecycle Calls

Step	Call	Key Point
Create	`core.New(cfg)`	`cfg` may be `nil`; zero-value fields take defaults
Start	`q.Start(ctx)`	Launches `Workers` goroutines; cancelling `ctx` cancels every running task's ctx
Shut down	`q.Shutdown(ctx)`	Rejects new tasks, then waits for workers to drain the heap; returns an error when `ctx` expires

Enqueue also works before Start: tasks wait in the heap and run by priority once Start is called.

Next Steps

Priority levels and promotion → Priority Levels, Anti-Starvation Promotion
How long a task may run → Timeout Derivation
Tuning Config and presets → Configuration, Presets
Retries, callbacks, and custom IDs → Enqueue Options
Full signatures and error messages → API Reference, Errors