queue

Documentation

Overview

Package queue provides explicit background jobs with typed handler registration, an inline sync driver for development, and a Redis (asynq) driver for production with retries, delays, and graceful drain.

Index

• func Dispatch[T any](ctx context.Context, q *Queue, name string, payload T, opts ...Option) error
• func Register[T any](q *Queue, name string, handler func(context.Context, T) error)
• type HandlerFunc
• type Option
  • func Delay(d time.Duration) Option
  • func MaxRetry(n int) Option
  • func OnQueue(name string) Option
• type Options
• type Queue
  • func New(options Options) (*Queue, error)
  • func (q *Queue) Close() error
  • func (q *Queue) Handle(name string, handler HandlerFunc)
  • func (q *Queue) Start(ctx context.Context) error
  • func (q *Queue) Stats(ctx context.Context) (Stats, error)
• type QueueStats
• type Stats

Functions

func Dispatch

func Dispatch[T any](ctx context.Context, q *Queue, name string, payload T, opts ...Option) error

Dispatch JSON-encodes payload and enqueues the named job. The sync driver executes the handler inline and returns its error directly.

func Register

func Register[T any](q *Queue, name string, handler func(context.Context, T) error)

Register binds a typed handler; payloads are JSON-decoded into T before the handler runs, and undecodable payloads fail the job.

Types

type HandlerFunc

type HandlerFunc func(ctx context.Context, payload []byte) error

HandlerFunc processes one job payload.

type Option

type Option func(*jobOptions)

Option customizes a single dispatch.

func Delay

func Delay(d time.Duration) Option

Delay schedules the job to run after d. Ignored by the sync driver.

func MaxRetry

func MaxRetry(n int) Option

MaxRetry caps redis-driver retries for the job. Ignored by the sync driver.

func OnQueue

func OnQueue(name string) Option

OnQueue routes the job to a named queue listed in Options.Queues.

type Options

type Options struct {
	// Driver selects the backend: "sync" (default, executes jobs inline) or
	// "redis" (asynq worker with retries and graceful drain).
	Driver string
	// RedisURL configures the redis driver, e.g. redis://localhost:6379/0.
	RedisURL string
	// Concurrency is the redis worker goroutine count, defaulting to 10.
	Concurrency int
	// Queues maps queue names to priorities; defaults to {"default": 1}.
	Queues map[string]int
	// ShutdownTimeout bounds the in-flight drain on stop, defaulting to 8s.
	ShutdownTimeout time.Duration
	Logger          *slog.Logger
}

type Queue

type Queue struct {
	// contains filtered or unexported fields
}

Queue dispatches and processes background jobs.

func New

func New(options Options) (*Queue, error)

func (*Queue) Close

func (q *Queue) Close() error

Close releases driver resources. It is safe to call more than once.

func (*Queue) Handle

func (q *Queue) Handle(name string, handler HandlerFunc)

Handle registers a raw payload handler for the named job. Register every handler before Start; later registrations are not picked up by a running worker.

func (*Queue) Start

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

Start runs the worker until ctx is canceled, then drains in-flight jobs. It is safe to use as an application runner (app.Go) or from a dedicated worker binary. The sync driver simply blocks until cancellation.

func (*Queue) Stats

func (q *Queue) Stats(ctx context.Context) (Stats, error)

Stats reports the queue backend and its per-queue task counts. The redis driver inspects the broker; the sync driver reports only its name.

type QueueStats

type QueueStats struct {
	Name      string `json:"name"`
	Pending   int    `json:"pending"`
	Active    int    `json:"active"`
	Scheduled int    `json:"scheduled"`
	Retry     int    `json:"retry"`
	Archived  int    `json:"archived"`
	Completed int    `json:"completed"`
}

QueueStats reports the task counts of one named queue.

type Stats

type Stats struct {
	Driver string       `json:"driver"`
	Queues []QueueStats `json:"queues,omitempty"`
}

Stats reports the driver backing the queue and per-queue task counts. The sync driver executes jobs inline, so it reports no queues.