cycle

README

Documentation

Overview

Package cycle provides utilities for performing cyclical, recurrent tasks.

Index

• Variables
• type Group
  • func NewGroup(opts ...GroupOption) (*Group, error)
  • func (g *Group) Add(opts ...TaskOption) error
  • func (g *Group) Start(ctx context.Context) error
  • func (g *Group) Stop(ctx context.Context) error
• type GroupOption
  • func WithTasks(tasks ...*Task) GroupOption
• type GroupOptions
  • func NewGroupOptions() GroupOptions
  • func (o GroupOptions) With(opts ...GroupOption) GroupOptions
• type Task
  • func NewTask(opts ...TaskOption) (*Task, error)
  • func Run(d time.Duration, f TaskFunc) (*Task, error)
  • func (t *Task) Cycles() uint64
  • func (t *Task) Err() error
  • func (t *Task) IsRunning() bool
  • func (t *Task) Start(ctx context.Context) error
  • func (t *Task) Stop(ctx context.Context) error
• type TaskFunc
  • func ErrFuncToTask(fn func() error) TaskFunc
  • func FuncToTask(fn func()) TaskFunc
• type TaskHook
• type TaskOption
  • func WithClock(clk clock.Clock) TaskOption
  • func WithFreeSpin() TaskOption
  • func WithFunc(fn TaskFunc) TaskOption
  • func WithHooks(hooks ...TaskHook) TaskOption
  • func WithJitter(d time.Duration) TaskOption
  • func WithJitterRange(min time.Duration, max time.Duration) TaskOption
  • func WithName(name string) TaskOption
  • func WithRate(rate time.Duration) TaskOption
• type TaskOptions
  • func DefaultTaskOptions() TaskOptions
  • func (o TaskOptions) Validate() (err error)
  • func (o TaskOptions) With(opts ...TaskOption) TaskOptions

Variables

var (
	// ErrGroupAlreadyStarted is returned by Group.Start if called once a Group
	// has already been started.
	ErrGroupAlreadyStarted = errors.New("group already started")
	// ErrGroupNotRunning is returned by Group.Stop if called when a Group is
	// not running.
	ErrGroupNotRunning = errors.New("group not running")
)

var (
	// ErrTaskAlreadyStarted is returned by Task.Start if called after the Task
	// has started.
	ErrTaskAlreadyStarted = errors.New("task already started")
	// ErrTaskNotRunning is returned by Task.Stop if called when the Task is
	// not running.
	ErrTaskNotRunning = errors.New("task not running")
	// ErrStartHook is returned by Task.Start if a given TaskHook.OnStart
	// returned an error.
	ErrStartHook = errors.New("start hook error")
	// ErrStopHook is returned by Task.Stop if any TaskHook.OnStop returned an
	// error.
	ErrStopHook = errors.New("stop hook error")
)

var (
	// ErrNoClock indicates that no valid clock was provided.
	ErrNoClock = errors.New("no clock provided")
	// ErrInvalidJitter indicates that a given jitter value is invalid.
	ErrInvalidJitter = errors.New("invalid jitter")
	// ErrNoTaskFunc indicates that no valid TaskFunc was provided.
	ErrNoTaskFunc = errors.New("no task function provided")
	// ErrNoTaskRate indicates that a given task rate is invalid.
	ErrNoTaskRate = errors.New("no task rate provided")
)

Types

type Group

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

A Group controls multiple Tasks simultaneously.

func NewGroup

func NewGroup(opts ...GroupOption) (*Group, error)

NewGroup creates a new Group with the given options.

func (*Group) Add

func (g *Group) Add(opts ...TaskOption) error

Add creates a new Task with the given options and adds it to the Group. If the group is already running, the resulting task is started immediately; otherwise, it will be started when Group.Start is called.

func (*Group) Start

func (g *Group) Start(ctx context.Context) error

Start starts all tasks in the Group. Once called, additional tasks added via Add will be started immediately.

func (*Group) Stop

func (g *Group) Stop(ctx context.Context) error

Stop stops all tasks in the Group.

type GroupOption

type GroupOption interface {
	// contains filtered or unexported methods
}

A GroupOption configures a Group.

func WithTasks

func WithTasks(tasks ...*Task) GroupOption

WithTasks configures a GroupOption to use the given tasks.

type GroupOptions

type GroupOptions struct {
	Tasks []*Task
}

GroupOptions configure a Group.

func NewGroupOptions

func NewGroupOptions() GroupOptions

NewGroupOptions creates a new GroupOptions.

func (GroupOptions) With

func (o GroupOptions) With(opts ...GroupOption) GroupOptions

With merges the given options into a copy of the current GroupOptions and returns the result.

type Task

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

A Task is a periodic task executed on a predefined interval. Unlike simple sleep loops, a Task will adjust its sleep duration dynamically based on the latency of its TaskFunc such that all calls are evenly spaced. If a cycle latencie exceeds the Task's configured rate, the subsequent cycle will be executed immediately. Once a Task has been stopped, it may not be started again: tasks are intended to be long-running operations.

Tasks are designed to provide consistent cycle lengths, controlling for noise in each cycle, however they may also be configured to use jitter. See TaskOptions for more information.

func NewTask

func NewTask(opts ...TaskOption) (*Task, error)

NewTask creates a new Task based on the given options.

func Run

func Run(d time.Duration, f TaskFunc) (*Task, error)

Run creates a new Task with the given rate and TaskFunc, and starts it immediately.

func (*Task) Cycles

func (t *Task) Cycles() uint64

Cycles returns the number of cycles that this Task has executed.

func (*Task) Err

func (t *Task) Err() error

Err returns the last error that the Task encountered while running.

func (*Task) IsRunning

func (t *Task) IsRunning() bool

IsRunning returns whether or not the task is currently running.

func (*Task) Start

func (t *Task) Start(ctx context.Context) error

Start starts the task. Start will return an error if any configured OnStart hook returns an error, or if Start has previously been called.

If the Task's TaskFunc returns an error, the Task will stop.

func (*Task) Stop

func (t *Task) Stop(ctx context.Context) error

Stop stops the task. Stop will return an error if any configured OnStop hook returns an error, or if Stop has previously been called. Note that the Task will still be stopped even if the OnStop hooks error.

type TaskFunc

type TaskFunc = func(context.Context) error

A TaskFunc is a function that can be executed by a Task. If a TaskFunc returns an error, the Task will stop.

func ErrFuncToTask

func ErrFuncToTask(fn func() error) TaskFunc

ErrFuncToTask converts fn to a TaskFunc.

func FuncToTask

func FuncToTask(fn func()) TaskFunc

FuncToTask converts fn to a TaskFunc.

type TaskHook

type TaskHook struct {
	// OnStart is executed as part of Task.Start.
	OnStart func(context.Context) error
	// OnStop is executed as part of Task.Stop.
	OnStop func(context.Context) error
}

A TaskHook provides hooks to be executed as part of Task.Start and Task.Stop. Hooks are cumulative: for example, hooks may be added through by more than one TaskOption.

OnStart hooks are executed in the order in which they were provided. OnStop hooks are executed in reverse order.

type TaskOption

type TaskOption interface {
	// contains filtered or unexported methods
}

A TaskOption configures a Task.

func WithClock

func WithClock(clk clock.Clock) TaskOption

WithClock configures a Task to use the given clock.

func WithFreeSpin

func WithFreeSpin() TaskOption

WithFreeSpin configures a Task to be free-spinning: it will not wait between cycles.

func WithFunc

func WithFunc(fn TaskFunc) TaskOption

WithFunc configures a Task to use the given function as its TaskFunc.

func WithHooks

func WithHooks(hooks ...TaskHook) TaskOption

WithHooks configures a Task to use the given hooks.

func WithJitter

func WithJitter(d time.Duration) TaskOption

WithJitter configures a Task to use [0,d) as its jitter range. bound.

func WithJitterRange

func WithJitterRange(min time.Duration, max time.Duration) TaskOption

WithJitterRange configures a Task to use [min,max) as its jitter range.

func WithName

func WithName(name string) TaskOption

WithName configures a Task to use the given name.

func WithRate

func WithRate(rate time.Duration) TaskOption

WithRate configures a Task to use the given rate.

type TaskOptions

type TaskOptions struct {
	// Clock is used within a Task for measuring time. This field is required.
	Clock clock.Clock
	// Func is the function executed by a Task. This field is required.
	Func TaskFunc
	// Hooks configure Task.Start and Task.Stop behavior.
	Hooks []TaskHook
	// Rate is the target cycle rate for a Task. This field is required.
	Rate time.Duration
	// JitterMax is the maximum jitter permitted for a Task. This value will
	// be dynamically clamped based on runtime cycle latency.
	JitterMax time.Duration
	// JitterMin is the minimum jitter permitted for a Task.
	JitterMin time.Duration
	// Name is the name of a Task. Task names do not need to be unique.
	Name string
}

TaskOptions configure a Task.

func DefaultTaskOptions

func DefaultTaskOptions() TaskOptions

DefaultTaskOptions creates a new TaskOptions with some sane defaults. The resulting TaskOptions is not valid verbatim; see TaskOptions for information on required fields.

func (TaskOptions) Validate

func (o TaskOptions) Validate() (err error)

Validate returns an error if the current TaskOptions is invalid.

func (TaskOptions) With

func (o TaskOptions) With(opts ...TaskOption) TaskOptions

With copies the current TaskOptions and applies the given options to it, returning the result.