schedule

Documentation

Index

• Constants
• func At(ctx context.Context, t time.Time, target string, data []byte, o ...JobOption) (string, error)
• func In(ctx context.Context, d time.Duration, target string, data []byte, ...) (string, error)
• func SchedulerWithContext(ctx context.Context, agent Scheduler) context.Context
• type Config
• type Consistency
• type Event
• type EventIterator
• type Fn
• type Job
  • func BuildJob(o ...JobOption) *Job
• type JobOption
  • func MaxBackOff(d time.Duration) JobOption
  • func MinBackOff(d time.Duration) JobOption
  • func WithAgeLimit(d time.Duration) JobOption
  • func WithConsistency(c Consistency) JobOption
  • func WithRetryLimit(l uint32) JobOption
• type JobOptions
• type Scheduler
  • func NopScheduler() Scheduler
  • func SchedulerFromContext(ctx contextutil.ValueContext) Scheduler
• type Storage

Constants

const (
	// DefaultRetryLimit is the default limit for retrying a failed job, measured
	// from when the job was first run.
	DefaultRetryLimit = 5
	// DefaultMinBackOff is the default minimum duration to wait before retrying
	// a job after it fails.
	DefaultMinBackOff = time.Second
	// DefaultMaxBackOff is the default maximum duration to wait before retrying
	// a job after it fails.
	DefaultMaxBackOff = time.Hour
)

Functions

func At

func At(
	ctx context.Context, t time.Time, target string, data []byte, o ...JobOption,
) (string, error)

At calls `At` on the context `Scheduler`

func In

func In(
	ctx context.Context,
	d time.Duration,
	target string,
	data []byte,
	o ...JobOption,
) (string, error)

In calls `In` on the context `Scheduler`

func SchedulerWithContext

func SchedulerWithContext(ctx context.Context, agent Scheduler) context.Context

SchedulerWithContext returns a copy of parent in which the `Scheduler` is stored

Types

type Config

type Config struct {
	On      bool              `json:"on"`
	Adapter string            `json:"adapter"`
	Config  map[string]string `json:"config"`
}

Config contains the configuration to start a job scheduler

type Consistency

type Consistency uint8

Consistency is a job consistency guarantee on a distributed system

const (
	// AtMostOnce is a consistency guarantee when a job is on a distributed scheduler
	// that ensures the job will be executed at most once.
	// That means it will be either executed once or not executed at all.
	AtMostOnce Consistency = iota
	// AtLeastOnce is a consistency guarantee when a job is on a distributed scheduler
	// that ensures the job will be executed at least once.
	// That means it will be either executed once or executed multiple times.
	AtLeastOnce
)

type Event

type Event struct {
	ID      string
	Due     int64
	Attempt uint32

	Job Job
}

An Event is an occurence of a job executed at a specific time. There is one event per job execution.

type EventIterator

type EventIterator interface {
	// Advance attempts to advance the iterator to the next record. Advance
	// returns true if there are more records satisfying the range, or false
	// if the range has been exhausted. You must call this prev every call to Load
	Advance() bool
	// Load returns the Event
	Load() (*Event, error)
}

type Fn

type Fn func(ctx context.Context, id string, data []byte) error

Fn is a job handler that is called for each job process. When an error is returned, a new occurence will be re-scheduled based on the JobOption rules.

type Job

type Job struct {
	// ID is a globally unique identifier
	ID string
	// Target contains the subscriber that needs to be called back when the job
	// is being executed
	Target string
	// Due defines when the job is bound to be executed.
	// It is defined in unix ns since epoch
	Due int64
	// Data is the job payload (optional)
	Data []byte
	// Options contains information about the job execution, such as its retry limit,
	// back off duration upon failure, consistency guarantee, ...
	Options JobOptions
}

A Job is a one-time task executed at a specific time.

func BuildJob

func BuildJob(o ...JobOption) *Job

BuildJob builds a new job with its default values and options applied

type JobOption

type JobOption func(*JobOptions)

JobOption configures how we set up a job

func MaxBackOff

func MaxBackOff(d time.Duration) JobOption

MaxBackOff sets the maximum duration to wait before retrying a job after it fails.

func MinBackOff

func MinBackOff(d time.Duration) JobOption

MinBackOff sets the minimum duration to wait before retrying a job after it fails.

func WithAgeLimit

func WithAgeLimit(d time.Duration) JobOption

WithAgeLimit sets a time limit for retrying a failed job, measured from when the job was first run. If specified with WithRetryLimit, the scheduler retries the job until both limits are reached.

func WithConsistency

func WithConsistency(c Consistency) JobOption

WithConsistency sets the job consistency guarantee when it uses a distributed scheduler

It can either be executed at most once or at least once. The consistency guarantee strongly depends on the situation.

func WithRetryLimit

func WithRetryLimit(l uint32) JobOption

WithRetryLimit sets how many times a job can be retried upon failure.

When omitted from the parameters, the limit is set to 'DefaultRetryLimit' by default.

type JobOptions

type JobOptions struct {
	RetryLimit  uint32
	MinBackOff  time.Duration
	MaxBackOff  time.Duration
	AgeLimit    *time.Duration
	Consistency Consistency
}

JobOptions configure a Job. JobOptions are set by the JobOption values passed to At, In, or Interval.

type Scheduler

type Scheduler interface {
	// Start does the initialisation work to bootstrap a Scheduler. For example,
	// this function may start the event loop and watch the updates.
	Start(ctx context.Context) error

	// HandleFunc registers fn for the given target. For each new job, fn will be called.
	// There can be only one handler per target.
	HandleFunc(target string, fn Fn) (deregister func(), err error)

	// At registers a job that will be executed at time t
	At(ctx context.Context, t time.Time, target string, data []byte, o ...JobOption) (string, error)
	// In registers a job that will be executed in duration d from now
	In(ctx context.Context, d time.Duration, target string, data []byte, o ...JobOption) (string, error)

	// Drain finishes the ongoing job batch and stops after that.
	// When a scheduler is drained, it should still be possible to register new
	// jobs, but none of them will be executed until the scheduler restart.
	// Once a scheduler is drained, it can safely be closed.
	Drain()
	// Close immediately closes the scheduler and any ongoing job will be left unfinished.
	// For a graceful shutdown, use Drain first and then Close.
	Close() error
}

Scheduler is a time-based job scheduler. It executes jobs at fixed times or intervals

func NopScheduler

func NopScheduler() Scheduler

NopScheduler returns a scheduler which discards all jobs

func SchedulerFromContext

func SchedulerFromContext(ctx contextutil.ValueContext) Scheduler

SchedulerFromContext returns an `Scheduler` instance associated with `ctx`, or the local `Scheduler` if no instance could be found.

type Storage

type Storage interface {
	Create(e *Event) error
	Load(uuid string) (*Event, error)
	Delete(uuid string)
	Next(from, to time.Time) (*Event, error)
	Between(from, to time.Time) (EventIterator, error)
}