runutil

Documentation

Index

• Variables
• func ProvideWorker(c *dig.Container, fn any) error
• func RunAllJobs(ctx context.Context, jobs ...Job) error
• func RunAllWorkers(ctx context.Context, workers ...Worker) error
• func RunProvidedWorkers(ctx context.Context, c *dig.Container) error
• func Wait(ctx context.Context, d time.Duration)
• type Backoff
• type DeclarativeWorker
  • func (w DeclarativeWorker) Run(ctx context.Context) error
• type ExponentialBackoff
  • func (b ExponentialBackoff) Duration(attempt int) time.Duration
• type Job
• type JobFunc
  • func (fn JobFunc) RunOnce(ctx context.Context) error
• type RepeatOption
  • func WithStartImmediately() RepeatOption
• type StaticBackoff
  • func (b StaticBackoff) Duration(attempt int) time.Duration
• type Worker
  • func NamedWorker(worker Worker, name string) Worker
  • func NamedWorkerFromType(worker Worker, t any) Worker
  • func Repeat(wait time.Duration, job Job, opts ...RepeatOption) Worker
  • func Retry(worker Worker, bo Backoff) Worker
• type WorkerConfiger
• type WorkerFunc
  • func (fn WorkerFunc) Run(ctx context.Context) error
• type WorkerGroup

Variables

var ErrWorkerExitedPrematurely = errors.New("worker exited prematurely")

WorkerExitedPrematurely indicates that a worker exited in RunAllWorkers while the context was not cancelled yet.

Functions

func ProvideWorker

func ProvideWorker(c *dig.Container, fn any) error

ProvideWorker injects a WorkerConfiger, which can later be started with RunProvidedWorkers.

func RunAllJobs

func RunAllJobs(ctx context.Context, jobs ...Job) error

RunAllJobs runs all jobs in parallel and return their errors.

func RunAllWorkers

func RunAllWorkers(ctx context.Context, workers ...Worker) error

RunAllWorkers starts all workers in goroutines and waits until all are exited.

Behaviour:

• The execution for all workers get cancelled when the first worker exists, regardless of the exit code.
• Err is nil, if the context gets cancelled and the workers return a nil error too.
• Err contains [WorkerExitedPrematurely], if the workers return a nil error while the context was not cancelled.
• Err contains all errors, returned by the workers.

func RunProvidedWorkers

func RunProvidedWorkers(ctx context.Context, c *dig.Container) error

RunProvidedWorkers starts all workers there were injected using RunAllWorkers.

func Wait

func Wait(ctx context.Context, d time.Duration)

Wait is similar to time.Sleep, but stops blocking when the context gets cancelled.

Types

type Backoff

type Backoff interface {
	Duration(int) time.Duration
}

Backoff is an interface to calculate the wait times between attemts of doing a task. The first attempt must always return 0s. The Duration function can be used together with the Wait function for a cancelable backoff sleep.

type DeclarativeWorker

type DeclarativeWorker struct {
	Name   string
	Worker Worker
	Retry  Backoff
}

DeclarativeWorker is an alternative to building the worker behaviour with chained functions.If automatically chains worker functions based on defined field in the most sensful order.

It satisfies the Worker interface for easier use.

func (DeclarativeWorker) Run

func (w DeclarativeWorker) Run(ctx context.Context) error

type ExponentialBackoff

type ExponentialBackoff struct {
	Initial          time.Duration
	Max              time.Duration
	JitterProportion float64
}

ExponentialBackoff is a typical exponentail backoff with Jitter, based on this blog post: https://aws.amazon.com/ru/blogs/architecture/exponential-backoff-and-jitter/

func (ExponentialBackoff) Duration

func (b ExponentialBackoff) Duration(attempt int) time.Duration

type Job

type Job interface {
	RunOnce(ctx context.Context) error
}

Job is a function that runs once and exits afterwards.

type JobFunc

type JobFunc func(ctx context.Context) error

JobFunc is a helper to cast a function directly to a Job.

func (JobFunc) RunOnce

func (fn JobFunc) RunOnce(ctx context.Context) error

type RepeatOption

type RepeatOption func(*jobWorker)

func WithStartImmediately

func WithStartImmediately() RepeatOption

type StaticBackoff

type StaticBackoff struct {
	Sleep time.Duration
}

StaticBackoff always returns the same sleep duration to any but the 0th attempt.

func (StaticBackoff) Duration

func (b StaticBackoff) Duration(attempt int) time.Duration

type Worker

type Worker interface {
	Run(ctx context.Context) error
}

Worker is a service that is supposed to run continuously until the context gets cancelled.

func NamedWorker

func NamedWorker(worker Worker, name string) Worker

NamedWorker assigns a new logutil subsystem on startup. See logutil.Start.

func NamedWorkerFromType

func NamedWorkerFromType(worker Worker, t any) Worker

NamedWorkerFromType assigns a new logutil subsystem on startup based on the provided type name. See logutil.Start.

func Repeat

func Repeat(wait time.Duration, job Job, opts ...RepeatOption) Worker

Repeat reruns a job indefinitely until the context gets cancelled. The job will run at most once in the given time interval. This means the wait duration is not the sleep between executions, but the time between the start of runs (based on time.Ticker).

func Retry

func Retry(worker Worker, bo Backoff) Worker

Retry restarts a Worker forever when it exists. This happens regardless of whether the worker returns an error or nil. The worker only stops with restarting, when the context gets cancelled.

type WorkerConfiger

type WorkerConfiger interface {
	Workers() []Worker
}

WorkerConfiger is for Workers that configure themselfes. This means they can define repeats, backoff and jitter themselves.

func (w *CommitFetcher) Workers() []runutil.Worker {
	return []runutil.Worker{
		runutil.DeclarativeWorker{
			Name:   "Commits",
			Worker: runutil.Repeat(5*time.Second, runutil.JobFunc(w.fetchCommits)),
			Retry: runutil.ExponentialBackoff{
				Initial:          time.Second,
				Max:              time.Minute,
				JitterProportion: 0.5,
			},
		},
		runutil.DeclarativeWorker{
			Name:   "PRs",
			Worker: runutil.Repeat(5*time.Second, runutil.JobFunc(w.fetchPRs)),
			Retry: runutil.ExponentialBackoff{
				Initial:          time.Second,
				Max:              time.Minute,
				JitterProportion: 0.5,
			},
		},
	}
}

type WorkerFunc

type WorkerFunc func(ctx context.Context) error

WorkerFunc is a helper to cast a function directly to a Worker.

func (WorkerFunc) Run

func (fn WorkerFunc) Run(ctx context.Context) error

type WorkerGroup

type WorkerGroup struct {
	dig.In
	All []WorkerConfiger `group:"worker"`
}

WorkerGroup is a input parameter struct for Dig to retrieve all instances that implement the WorkerConfigerer.