v1.1.3
Home GitHub

Getting Started

Last updated

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

中文