cron

Documentation

Overview

Package cron provides periodic-job services for shost — the analog of a timed BackgroundService. Runs never overlap: the next tick fires only after the previous run completes (ticks arriving mid-run are dropped by time.Ticker).

Index

• type Job
• type Option
  • func RunImmediately() Option
  • func StopOnError() Option
  • func WithErrorHandler(fn func(error)) Option
  • func WithJitter(d time.Duration) Option
  • func WithRunTimeout(d time.Duration) Option
• type Schedule
  • func Expr(spec string) (Schedule, error)
  • func MustExpr(spec string) Schedule
• type ScheduleFunc
  • func (f ScheduleFunc) Next(after time.Time) time.Time
• type Service
  • func At(name string, schedule Schedule, job Job, opts ...Option) *Service
  • func Every(name string, interval time.Duration, job Job, opts ...Option) *Service
  • func (s *Service) Name() string
  • func (s *Service) Start(ctx context.Context) error
  • func (s *Service) Stop(ctx context.Context) error

Types

type Job

type Job func(ctx context.Context) error

Job is a single run of a periodic task. The passed ctx is canceled when the host shuts down; long jobs should respect it.

type Option

type Option func(*Service)

Option customizes a Service.

func RunImmediately

func RunImmediately() Option

RunImmediately runs the job once at startup, before the first tick.

func StopOnError

func StopOnError() Option

StopOnError makes a failed run stop the service (and therefore the host, unless the service is registered with shost.WithRestart). By default a failed run is passed to the error handler and the schedule continues.

func WithErrorHandler

func WithErrorHandler(fn func(error)) Option

WithErrorHandler receives errors (including recovered panics) of failed runs. Without it failed runs are silently skipped, so wiring a handler that logs is strongly recommended.

func WithJitter

func WithJitter(d time.Duration) Option

WithJitter delays each run by a random duration in [0, d). Spreads load when many instances share the same schedule (thundering herd).

func WithRunTimeout

func WithRunTimeout(d time.Duration) Option

WithRunTimeout bounds a single run: the job's ctx is canceled after d. A run exceeding the timeout counts as a failed run (context.DeadlineExceeded).

type Schedule

type Schedule interface {
	Next(after time.Time) time.Time
}

Schedule computes run times for At services. Next returns the first run time strictly after the given moment, or the zero time when the schedule will never fire again.

func Expr

func Expr(spec string) (Schedule, error)

Expr parses a standard 5-field cron expression:

┌──────────── minute       (0-59)
│ ┌────────── hour         (0-23)
│ │ ┌──────── day of month (1-31)
│ │ │ ┌────── month        (1-12 or jan-dec)
│ │ │ │ ┌──── day of week  (0-6 or sun-sat; 7 = sunday)
│ │ │ │ │
* * * * *

Each field accepts wildcards (*), lists (1,15), ranges (9-17) and steps (*/5, 9-17/2). The aliases @hourly, @daily (@midnight), @weekly, @monthly and @yearly (@annually) are supported. As in classic cron, when both day-of-month and day-of-week are restricted the job runs when either matches. Times are evaluated in the location of the time passed to Next (the host's local time when used with At).

func MustExpr

func MustExpr(spec string) Schedule

MustExpr is Expr panicking on a malformed expression. Intended for literal expressions in main().

type ScheduleFunc

type ScheduleFunc func(after time.Time) time.Time

ScheduleFunc adapts a function to the Schedule interface.

func (ScheduleFunc) Next

func (f ScheduleFunc) Next(after time.Time) time.Time

type Service

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

Service runs a Job on a fixed interval (Every) or a Schedule (At) as a shost.Service.

func At

func At(name string, schedule Schedule, job Job, opts ...Option) *Service

At creates a service running job per the given Schedule — typically a cron expression (see Expr / MustExpr):

cron.At("backup", cron.MustExpr("0 3 * * *"), backupJob)

As with Every, runs never overlap: the next run time is computed after the previous run completes; runs whose time passed mid-run are skipped. It panics on invalid arguments — configuration is a programmer error.

func Every

func Every(name string, interval time.Duration, job Job, opts ...Option) *Service

Every creates a periodic service running job on the given interval. It panics on invalid arguments — configuration is a programmer error.

func (*Service) Name

func (s *Service) Name() string

func (*Service) Start

func (s *Service) Start(ctx context.Context) error

func (*Service) Stop

func (s *Service) Stop(ctx context.Context) error