background

Documentation

Overview

Package background provides a way to run background tasks that run outside of a request/response cycle. This allows tracking of tasks that are running and the ability to cancel them.

Index

• func Set(t *Tasks)
• type RunOption
• type Task
• type Tasks
  • func Default() *Tasks
  • func New(ctx context.Context) *Tasks
  • func (t *Tasks) Close(ctx context.Context) error
  • func (t *Tasks) Meter() metric.Meter
  • func (t *Tasks) Once(ctx context.Context, name string, task Task, options ...RunOption) error
  • func (t *Tasks) Run(ctx context.Context, name string, task Task, boff *exponential.Backoff, ...) error

Functions

func Set

func Set(t *Tasks)

Set sets the default tasks to t. This is normally not called by user code. Instead, use options in init.Service().

Types

type RunOption

type RunOption func(runOpts) (runOpts, error)

RunOption is an optional argument for Run().

type Task

type Task func(context.Context) error

Task is a function that runs in the background.

type Tasks

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

Tasks tracks background tasks that are not in the path of a request/response cycle. Task errors are logged, but do not appear in OTEL traces. However this does provide metrics on the tasks.

func Default

func Default() *Tasks

Default returns the default Tasks object. It is safe to call this from multiple goroutines.

func New

func New(ctx context.Context) *Tasks

New creates a new Tasks object. An application should only create one Tasks object. This is usually retrieved via context.Tasks().

func (*Tasks) Close

func (t *Tasks) Close(ctx context.Context) error

Close stops the running of all tasks and waits for them to finish. This will only stop new tasks from starting or restarting. It will not stop a task that is currently running. If you want to stop a task that is currently running, you will need to use a context passed to the invoked function with support in that function. The context passed to Close() is only used to wait for the tasks to finish. If that context has a deadline, this will wait for everything to finish or for that deadline. If not, it will set a deadline of 30 seconds. If this doesn't finish by then, it will return an error.

func (*Tasks) Meter

func (t *Tasks) Meter() metric.Meter

Meter returns the OpenTelemetry meter for the Tasks.

func (*Tasks) Once

func (t *Tasks) Once(ctx context.Context, name string, task Task, options ...RunOption) error

Once is like Run, but it only runs the function once. If the function ends, it will not be restarted. name can be reused if you want to keep stats on a collection of one shot tasks.

func (*Tasks) Run

func (t *Tasks) Run(ctx context.Context, name string, task Task, boff *exponential.Backoff, options ...RunOption) error

Run submits a task to run in the background. The name is used to identify the task and to gather metrics on it. This name is appended to the name of the package + function Run() is called from, meaning the name has to be unique within that function. The Task is the function to run. If task() ends, it will use the Backoff provided to restart the Task. If Context is canceled, this will stop launching the task, however, the task itself has to honor the context passed to it in order for it to be stopped. An error is only returned if an option fails. Do not try to use this for a cron like task. If you need to run background cron like tasks, use the .Once() method wrapped with some timer.