cron

package
v2.0.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 1, 2019 License: MIT Imports: 15 Imported by: 7

README

cron

cron is a basic job scheduling, task handling library that wraps goroutines with a little metadata.

Getting Started

Here is a simple example of getting started with chronometer; running a background task with easy cancellation.

package main

import "github.com/blend/go-sdk/cron"

...
	mgr := cron.New()
	mgr.RunTask(cron.NewTask(func(ctx context.Context) error {
		for {
			select {
			case <- ctx.Done():
				return nil
			default:
			... //long winded process here
				return nil
		}
	}))

The above wraps a simple function signature with a task, and allows us to check if a cancellation signal has been sent. For a more detailed (running) example, look in _sample/main.go.

Schedules

Schedules are very basic right now, either the job runs on a fixed interval (every minute, every 2 hours etc) or on given days weekly (every day at a time, or once a week at a time).

You're free to implement your own schedules outside the basic ones; a schedule is just an interface for GetNextRunTime(after time.Time).

Tasks vs. Jobs

Jobs are tasks with schedules, thats about it. The interfaces are very similar otherwise.

Optional Interfaces

You can optionally implement interfaces to give you more control over your jobs:

Enabled() bool

or tasks:

SequentialExecution() bool

Allows you to enable or disable your job within the job itself; this allows all the code required to manage the job be in the same place.

Documentation

Overview

Package cron is an implementation of a job scheduler to run within a worker or a server. It allows developers to configure flexible schedules to run jobs, and trigger retries on failure.

Index

Constants

View Source 
const (
	DefaultMaxCount = 10
	DefaultMaxAge   = 6 * time.Hour
)

Retention defaults

View Source 
const (
	// DefaultEnabled is a default.
	DefaultEnabled = true
	// DefaultSerial is a default.
	DefaultSerial = false
	// DefaultShouldWriteOutput is a default.
	DefaultShouldWriteOutput = true
	// DefaultShouldTriggerListeners is a default.
	DefaultShouldTriggerListeners = true
)
View Source 
const (
	// FlagStarted is an event flag.
	FlagStarted logger.Flag = "cron.started"
	// FlagFailed is an event flag.
	FlagFailed logger.Flag = "cron.failed"
	// FlagCancelled is an event flag.
	FlagCancelled logger.Flag = "cron.cancelled"
	// FlagComplete is an event flag.
	FlagComplete logger.Flag = "cron.complete"
	// FlagBroken is an event flag.
	FlagBroken logger.Flag = "cron.broken"
	// FlagFixed is an event flag.
	FlagFixed logger.Flag = "cron.fixed"
	// FlagEnabled is an event flag.
	FlagEnabled logger.Flag = "cron.enabled"
	// FlagDisabled is an event flag.
	FlagDisabled logger.Flag = "cron.disabled"
)
View Source 
const (
	// ErrJobNotLoaded is a common error.
	ErrJobNotLoaded exception.Class = "job not loaded"

	// ErrJobAlreadyLoaded is a common error.
	ErrJobAlreadyLoaded exception.Class = "job already loaded"

	// ErrJobNotFound is a common error.
	ErrJobNotFound exception.Class = "job not found"

	// ErrJobCancelled is a common error.
	ErrJobCancelled exception.Class = "job cancelled"
)
View Source 
const (
	ErrStringScheduleInvalid         exception.Class = "cron: schedule string invalid"
	ErrStringScheduleComponents      exception.Class = "cron: must have at least (5) components space delimited; ex: '0 0 * * * * *'"
	ErrStringScheduleValueOutOfRange exception.Class = "cron: string schedule part out of range"
	ErrStringScheduleInvalidRange    exception.Class = "cron: range (from-to) invalid"
)

Error Constants

View Source 
const (
	StringScheduleShorthandAnnually = "@annually"
	StringScheduleShorthandYearly   = "@yearly"
	StringScheduleShorthandMonthly  = "@monthly"
	StringScheduleShorthandWeekly   = "@weekly"
	StringScheduleShorthandDaily    = "@daily"
	StringScheduleShorthandHourly   = "@hourly"
)

String schedule shorthands labels

View Source 
const (
	// AllDaysMask is a bitmask of all the days of the week.
	AllDaysMask = 1<<uint(time.Sunday) | 1<<uint(time.Monday) | 1<<uint(time.Tuesday) | 1<<uint(time.Wednesday) | 1<<uint(time.Thursday) | 1<<uint(time.Friday) | 1<<uint(time.Saturday)
	// WeekDaysMask is a bitmask of all the weekdays of the week.
	WeekDaysMask = 1<<uint(time.Monday) | 1<<uint(time.Tuesday) | 1<<uint(time.Wednesday) | 1<<uint(time.Thursday) | 1<<uint(time.Friday)
	//WeekendDaysMask is a bitmask of the weekend days of the week.
	WeekendDaysMask = 1<<uint(time.Sunday) | 1<<uint(time.Saturday)
)

NOTE: we have to use shifts here because in their infinite wisdom google didn't make these values powers of two for masking

View Source 
const (
	// DefaultHeartbeatInterval is the interval between schedule next run checks.
	DefaultHeartbeatInterval = 50 * time.Millisecond
)
View Source 
const (
	// EnvVarHeartbeatInterval is an environment variable name.
	EnvVarHeartbeatInterval = "CRON_HEARTBEAT_INTERVAL"
)

Variables

View Source 
var (
	// DaysOfWeek are all the time.Weekday in an array for utility purposes.
	DaysOfWeek = []time.Weekday{
		time.Sunday,
		time.Monday,
		time.Tuesday,
		time.Wednesday,
		time.Thursday,
		time.Friday,
		time.Saturday,
	}

	// WeekDays are the business time.Weekday in an array.
	WeekDays = []time.Weekday{
		time.Monday,
		time.Tuesday,
		time.Wednesday,
		time.Thursday,
		time.Friday,
	}

	// WeekWeekEndDaysDays are the weekend time.Weekday in an array.
	WeekendDays = []time.Weekday{
		time.Sunday,
		time.Saturday,
	}

	// Epoch is unix epoch saved for utility purposes.
	Epoch = time.Unix(0, 0)
	// Zero is basically epoch but if you want to be super duper sure.
	Zero = time.Time{}
)

NOTE: time.Zero()? what's that?

View Source 
var (
	StringScheduleShorthands = map[string]string{
		StringScheduleShorthandAnnually: "0 0 0 1 1 * *",
		StringScheduleShorthandYearly:   "0 0 0 1 1 * *",
		StringScheduleShorthandMonthly:  "0 0 0 1 * * *",
		StringScheduleShorthandDaily:    "0 0 0 * * * *",
		StringScheduleShorthandHourly:   "0 0 * * * * *",
	}
)

String schedule shorthand values

Functions

func FormatTime 

func FormatTime(t time.Time) string

FormatTime returns a string for a time.

func IsContextCancelled added in v0.3.2 

func IsContextCancelled(ctx context.Context) bool

IsContextCancelled check if a job is cancelled

func IsJobAlreadyLoaded 

func IsJobAlreadyLoaded(err error) bool

IsJobAlreadyLoaded returns if the error is a job already loaded error.

func IsJobCancelled 

func IsJobCancelled(err error) bool

IsJobCancelled returns if the error is a task not found error.

func IsJobNotFound added in v0.3.2 

func IsJobNotFound(err error) bool

IsJobNotFound returns if the error is a task not found error.

func IsJobNotLoaded 

func IsJobNotLoaded(err error) bool

IsJobNotLoaded returns if the error is a job not loaded error.

func IsWeekDay 

func IsWeekDay(day time.Weekday) bool

IsWeekDay returns if the day is a monday->friday.

func IsWeekendDay 

func IsWeekendDay(day time.Weekday) bool

IsWeekendDay returns if the day is a monday->friday.

func Max 

func Max(t1, t2 time.Time) time.Time

Max returns the maximum of two times.

func Min 

func Min(t1, t2 time.Time) time.Time

Min returns the minimum of two times.

func NewEventListener 

func NewEventListener(listener func(e *Event)) logger.Listener

NewEventListener returns a new event listener.

func NewJobInvocationID added in v0.3.2 

func NewJobInvocationID() string

NewJobInvocationID returns a new pseudo-unique job invocation identifier.

func Now 

func Now() time.Time

Now returns a new timestamp.

func SetDefault 

func SetDefault(jm *JobManager)

SetDefault sets the default job manager.

func Since 

func Since(t time.Time) time.Duration

Since returns the duration since another timestamp.

func WithJobInvocation added in v0.3.2 

func WithJobInvocation(ctx context.Context, ji *JobInvocation) context.Context

WithJobInvocation adds a job invocation to a context as a value.

Types

type Action added in v0.3.2 

type Action func(ctx context.Context) error

Action is an function that can be run as a task

type Config 

type Config struct {
	History HistoryConfig `json:"history" yaml:"history"`
}

Config is the config object.

func MustNewConfigFromEnv 

func MustNewConfigFromEnv() *Config

MustNewConfigFromEnv returns a new config set from environment variables, it will panic if there is an error.

func NewConfigFromEnv 

func NewConfigFromEnv() (*Config, error)

NewConfigFromEnv creates a new config from the environment.

type DailySchedule 

type DailySchedule struct {
	DayOfWeekMask uint
	TimeOfDayUTC  time.Time
}

DailySchedule is a schedule that fires every day that satisfies the DayOfWeekMask at the given TimeOfDayUTC.

func (DailySchedule) Next added in v1.20201204.1 

func (ds DailySchedule) Next(after time.Time) time.Time

Next implements Schedule.

func (DailySchedule) String added in v1.20201204.1 

func (ds DailySchedule) String() string

type DescriptionProvider 

type DescriptionProvider interface {
	Description() string
}

DescriptionProvider is a type that proivdes a description.

type EnabledProvider 

type EnabledProvider interface {
	Enabled() bool
}

EnabledProvider is an optional interface that will allow jobs to control if they're enabled.

type Event 

type Event struct {
	*logger.EventMeta
	// contains filtered or unexported fields
}

Event is an event.

func NewEvent 

func NewEvent(flag logger.Flag, jobName string) *Event

NewEvent creates a new event.

func (Event) Complete 

func (e Event) Complete() bool

Complete returns if the event completed.

func (Event) Elapsed 

func (e Event) Elapsed() time.Duration

Elapsed returns the elapsed time for the task.

func (Event) Err 

func (e Event) Err() error

Err returns the event err (if any).

func (Event) IsEnabled 

func (e Event) IsEnabled() bool

IsEnabled determines if the event triggers listeners.

func (Event) IsWritable 

func (e Event) IsWritable() bool

IsWritable determines if the event is written to the logger output.

func (Event) JobInvocation added in v1.20201204.1 

func (e Event) JobInvocation() string

JobInvocation returns the event job invocation.

func (Event) JobName added in v0.3.2 

func (e Event) JobName() string

JobName returns the event job name.

func (*Event) WithAnnotation 

func (e *Event) WithAnnotation(key, value string) *Event

WithAnnotation adds an annotation to the event.

func (*Event) WithElapsed 

func (e *Event) WithElapsed(d time.Duration) *Event

WithElapsed sets the elapsed time.

func (*Event) WithErr 

func (e *Event) WithErr(err error) *Event

WithErr sets the error on the event.

func (*Event) WithFlag 

func (e *Event) WithFlag(f logger.Flag) *Event

WithFlag sets the event flag.

func (*Event) WithHeadings 

func (e *Event) WithHeadings(headings ...string) *Event

WithHeadings sets the headings.

func (*Event) WithIsEnabled 

func (e *Event) WithIsEnabled(isEnabled bool) *Event

WithIsEnabled sets if the event is enabled

func (*Event) WithIsWritable 

func (e *Event) WithIsWritable(isWritable bool) *Event

WithIsWritable sets if the event is writable.

func (*Event) WithJobInvocation 

func (e *Event) WithJobInvocation(jobInvocation string) *Event

WithJobInvocation sets the job invocation.

func (*Event) WithJobName added in v0.3.2 

func (e *Event) WithJobName(jobName string) *Event

WithJobName sets the job name.

func (*Event) WithLabel 

func (e *Event) WithLabel(key, value string) *Event

WithLabel sets a label on the event for later filtering.

func (*Event) WithTimestamp 

func (e *Event) WithTimestamp(ts time.Time) *Event

WithTimestamp sets the message timestamp.

func (Event) WriteJSON 

func (e Event) WriteJSON() logger.JSONObj

WriteJSON implements logger.JSONWritable.

func (Event) WriteText 

func (e Event) WriteText(tf logger.TextFormatter, buf *bytes.Buffer)

WriteText implements logger.TextWritable.

type HistoryConfig 

type HistoryConfig struct {
	MaxCount int           `json:"maxCount" yaml:"maxCount" env:"CRON_MAX_COUNT"`
	MaxAge   time.Duration `json:"maxAge" yaml:"maxAge" env:"CRON_MAX_AGE"`
}

HistoryConfig governs job history retention in memory.

func (HistoryConfig) MaxAgeOrDefault 

func (hc HistoryConfig) MaxAgeOrDefault() time.Duration

MaxAgeOrDefault returns the max age or a default.

func (HistoryConfig) MaxCountOrDefault 

func (hc HistoryConfig) MaxCountOrDefault() int

MaxCountOrDefault returns the max count or a default.

type ImmediateSchedule 

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

ImmediateSchedule fires immediately with an optional continuation schedule.

func Immediately 

func Immediately() *ImmediateSchedule

Immediately Returns a schedule that casues a job to run immediately on start, with an optional subsequent schedule.

func (*ImmediateSchedule) Next added in v1.20201204.1 

func (i *ImmediateSchedule) Next(after time.Time) time.Time

Next implements Schedule.

func (ImmediateSchedule) String added in v1.20201204.1 

func (i ImmediateSchedule) String() string

String returns a string representation of the schedul.e

func (*ImmediateSchedule) Then 

func (i *ImmediateSchedule) Then(then Schedule) Schedule

Then allows you to specify a subsequent schedule after the first run.

type IntervalSchedule 

type IntervalSchedule struct {
	Every      time.Duration
	StartDelay time.Duration
}

IntervalSchedule is as chedule that fires every given interval with an optional start delay.

func (IntervalSchedule) Next added in v1.20201204.1 

func (i IntervalSchedule) Next(after time.Time) time.Time

Next implements Schedule.

func (IntervalSchedule) String added in v1.20201204.1 

func (i IntervalSchedule) String() string

String returns a string representation of the schedule.

type Job 

type Job interface {
	Name() string
	Execute(ctx context.Context) error
}

Job is an interface types can satisfy to be loaded into the JobManager.

type JobBuilder added in v0.3.2 

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

JobBuilder allows for job creation w/o a fully formed struct.

func NewJob 

func NewJob(name string, action Action) *JobBuilder

NewJob returns a new job factory.

func (*JobBuilder) Enabled added in v0.3.2 

func (jb *JobBuilder) Enabled() bool

Enabled returns if the job is enabled.

func (*JobBuilder) Execute added in v0.3.2 

func (jb *JobBuilder) Execute(ctx context.Context) error

Execute runs the job action if it's set.

func (*JobBuilder) Name added in v0.3.2 

func (jb *JobBuilder) Name() string

Name returns the job name.

func (*JobBuilder) OnBroken added in v0.3.2 

func (jb *JobBuilder) OnBroken(ctx context.Context)

OnBroken is a lifecycle hook.

func (*JobBuilder) OnCancellation added in v0.3.2 

func (jb *JobBuilder) OnCancellation(ctx context.Context)

OnCancellation is a lifecycle hook.

func (*JobBuilder) OnComplete added in v0.3.2 

func (jb *JobBuilder) OnComplete(ctx context.Context)

OnComplete is a lifecycle hook.

func (*JobBuilder) OnDisabled 

func (jb *JobBuilder) OnDisabled(ctx context.Context)

OnDisabled is a lifecycle hook.

func (*JobBuilder) OnEnabled 

func (jb *JobBuilder) OnEnabled(ctx context.Context)

OnEnabled is a lifecycle hook.

func (*JobBuilder) OnFailure added in v0.3.2 

func (jb *JobBuilder) OnFailure(ctx context.Context)

OnFailure is a lifecycle hook.

func (*JobBuilder) OnFixed added in v0.3.2 

func (jb *JobBuilder) OnFixed(ctx context.Context)

OnFixed is a lifecycle hook.

func (*JobBuilder) OnStart added in v0.3.2 

func (jb *JobBuilder) OnStart(ctx context.Context)

OnStart is a lifecycle hook.

func (*JobBuilder) Schedule added in v0.3.2 

func (jb *JobBuilder) Schedule() Schedule

Schedule returns the job schedule.

func (*JobBuilder) ShouldTriggerListeners added in v0.3.2 

func (jb *JobBuilder) ShouldTriggerListeners() bool

ShouldTriggerListeners implements the should trigger listeners provider.

func (*JobBuilder) ShouldWriteOutput added in v0.3.2 

func (jb *JobBuilder) ShouldWriteOutput() bool

ShouldWriteOutput implements the should write output provider.

func (*JobBuilder) Timeout added in v0.3.2 

func (jb *JobBuilder) Timeout() (timeout time.Duration)

Timeout returns the job timeout.

func (*JobBuilder) WithAction added in v0.3.2 

func (jb *JobBuilder) WithAction(action Action) *JobBuilder

WithAction sets the job action.

func (*JobBuilder) WithEnabledProvider added in v0.3.2 

func (jb *JobBuilder) WithEnabledProvider(enabledProvider func() bool) *JobBuilder

WithEnabledProvider sets the enabled provider for the job.

func (*JobBuilder) WithName added in v0.3.2 

func (jb *JobBuilder) WithName(name string) *JobBuilder

WithName sets the job name.

func (*JobBuilder) WithOnBroken added in v0.3.2 

func (jb *JobBuilder) WithOnBroken(receiver func(*JobInvocation)) *JobBuilder

WithOnBroken sets a lifecycle handler.

func (*JobBuilder) WithOnCancellation added in v0.3.2 

func (jb *JobBuilder) WithOnCancellation(receiver func(*JobInvocation)) *JobBuilder

WithOnCancellation sets a lifecycle handler.

func (*JobBuilder) WithOnComplete added in v0.3.2 

func (jb *JobBuilder) WithOnComplete(receiver func(*JobInvocation)) *JobBuilder

WithOnComplete sets a lifecycle handler.

func (*JobBuilder) WithOnDisabled 

func (jb *JobBuilder) WithOnDisabled(receiver func(context.Context)) *JobBuilder

WithOnDisabled sets a lifecycle handler.

func (*JobBuilder) WithOnEnabled 

func (jb *JobBuilder) WithOnEnabled(receiver func(context.Context)) *JobBuilder

WithOnEnabled sets a lifecycle handler.

func (*JobBuilder) WithOnFailure added in v0.3.2 

func (jb *JobBuilder) WithOnFailure(receiver func(*JobInvocation)) *JobBuilder

WithOnFailure sets a lifecycle handler.

func (*JobBuilder) WithOnFixed added in v0.3.2 

func (jb *JobBuilder) WithOnFixed(receiver func(*JobInvocation)) *JobBuilder

WithOnFixed sets a lifecycle handler.

func (*JobBuilder) WithOnStart added in v0.3.2 

func (jb *JobBuilder) WithOnStart(receiver func(*JobInvocation)) *JobBuilder

WithOnStart sets a lifecycle handler.

func (*JobBuilder) WithSchedule added in v0.3.2 

func (jb *JobBuilder) WithSchedule(schedule Schedule) *JobBuilder

WithSchedule sets the schedule for the job.

func (*JobBuilder) WithShouldTriggerListenersProvider added in v0.3.2 

func (jb *JobBuilder) WithShouldTriggerListenersProvider(provider func() bool) *JobBuilder

WithShouldTriggerListenersProvider sets the enabled provider for the job.

func (*JobBuilder) WithShouldWriteOutputProvider added in v0.3.2 

func (jb *JobBuilder) WithShouldWriteOutputProvider(provider func() bool) *JobBuilder

WithShouldWriteOutputProvider sets the enabled provider for the job.

func (*JobBuilder) WithTimeoutProvider added in v0.3.2 

func (jb *JobBuilder) WithTimeoutProvider(timeoutProvider func() time.Duration) *JobBuilder

WithTimeoutProvider sets the timeout provider.

type JobInvocation added in v0.3.2 

type JobInvocation struct {
	ID        string             `json:"id"`
	JobName   string             `json:"jobName"`
	Started   time.Time          `json:"started"`
	Finished  time.Time          `json:"finished,omitempty"`
	Cancelled time.Time          `json:"cancelled,omitempty"`
	Timeout   time.Time          `json:"timeout,omitempty"`
	Err       error              `json:"err,omitempty"`
	Elapsed   time.Duration      `json:"elapsed"`
	Status    JobStatus          `json:"status"`
	State     interface{}        `json:"state,omitempty"`
	Context   context.Context    `json:"-"`
	Cancel    context.CancelFunc `json:"-"`
}

JobInvocation is metadata for a job invocation (or instance of a job running).

func GetJobInvocation added in v0.3.2 

func GetJobInvocation(ctx context.Context) *JobInvocation

GetJobInvocation returns the job invocation ID from a context.

type JobManager 

type JobManager struct {
	sync.Mutex
	// contains filtered or unexported fields
}

JobManager is the main orchestration and job management object.

func Default 

func Default() *JobManager

Default returns a shared instance of a JobManager. If unset, it will initialize it with `New()`.

func MustNewFromEnv 

func MustNewFromEnv() *JobManager

MustNewFromEnv returns a new job manager from the environment.

func New 

func New() *JobManager

New returns a new job manager.

func NewFromConfig 

func NewFromConfig(cfg *Config) *JobManager

NewFromConfig returns a new job manager from a given config.

func NewFromEnv 

func NewFromEnv() (*JobManager, error)

NewFromEnv returns a new job manager from the environment.

func (*JobManager) CancelJob added in v0.3.2 

func (jm *JobManager) CancelJob(jobName string) (err error)

CancelJob cancels (sends the cancellation signal) to a running job.

func (*JobManager) Config 

func (jm *JobManager) Config() *Config

Config returns the job manager config.

func (*JobManager) DisableJob 

func (jm *JobManager) DisableJob(jobName string) error

DisableJob stops a job from running but does not unload it.

func (*JobManager) DisableJobs 

func (jm *JobManager) DisableJobs(jobNames ...string) error

DisableJobs disables a variadic list of job names.

func (*JobManager) EnableJob 

func (jm *JobManager) EnableJob(jobName string) error

EnableJob enables a job that has been disabled.

func (*JobManager) EnableJobs 

func (jm *JobManager) EnableJobs(jobNames ...string) error

EnableJobs enables a variadic list of job names.

func (*JobManager) HasJob 

func (jm *JobManager) HasJob(jobName string) (hasJob bool)

HasJob returns if a jobName is loaded or not.

func (*JobManager) IsJobDisabled added in v0.3.2 

func (jm *JobManager) IsJobDisabled(jobName string) (value bool)

IsJobDisabled returns if a job is disabled.

func (*JobManager) IsJobRunning added in v0.3.2 

func (jm *JobManager) IsJobRunning(jobName string) (isRunning bool)

IsJobRunning returns if a task is currently running.

func (*JobManager) IsRunning 

func (jm *JobManager) IsRunning() bool

IsRunning returns if the job manager is running. It serves as an authoritative healthcheck.

func (*JobManager) Job 

func (jm *JobManager) Job(jobName string) (job *JobScheduler, err error)

Job returns a job metadata by name.

func (*JobManager) Latch added in v0.3.2 

func (jm *JobManager) Latch() *async.Latch

Latch returns the internal latch.

func (*JobManager) LoadJob 

func (jm *JobManager) LoadJob(job Job) error

LoadJob loads a job.

func (*JobManager) LoadJobs 

func (jm *JobManager) LoadJobs(jobs ...Job) error

LoadJobs loads a variadic list of jobs.

func (*JobManager) Logger 

func (jm *JobManager) Logger() logger.FullReceiver

Logger returns the diagnostics agent.

func (*JobManager) NotifyStarted added in v0.3.1 

func (jm *JobManager) NotifyStarted() <-chan struct{}

NotifyStarted returns the started notification channel.

func (*JobManager) NotifyStopped added in v0.3.1 

func (jm *JobManager) NotifyStopped() <-chan struct{}

NotifyStopped returns the stopped notification channel.

func (*JobManager) RunAllJobs 

func (jm *JobManager) RunAllJobs()

RunAllJobs runs every job that has been loaded in the JobManager at once.

func (*JobManager) RunJob 

func (jm *JobManager) RunJob(jobName string) error

RunJob runs a job by jobName on demand.

func (*JobManager) RunJobs 

func (jm *JobManager) RunJobs(jobNames ...string) error

RunJobs runs a variadic list of job names.

func (*JobManager) Start 

func (jm *JobManager) Start() error

Start starts the job manager and blocks.

func (*JobManager) StartAsync added in v1.20201204.1 

func (jm *JobManager) StartAsync() error

StartAsync starts the job manager and the loaded jobs. It does not block.

func (*JobManager) Status 

func (jm *JobManager) Status() *Status

Status returns a status object.

func (*JobManager) Stop 

func (jm *JobManager) Stop() error

Stop stops the schedule runner for a JobManager.

func (*JobManager) Tracer 

func (jm *JobManager) Tracer() Tracer

Tracer returns the manager's tracer.

func (*JobManager) WithConfig 

func (jm *JobManager) WithConfig(cfg *Config) *JobManager

WithConfig sets the job manager config.

func (*JobManager) WithLogger 

func (jm *JobManager) WithLogger(log logger.FullReceiver) *JobManager

WithLogger sets the logger and returns a reference to the job manager.

func (*JobManager) WithTracer 

func (jm *JobManager) WithTracer(tracer Tracer) *JobManager

WithTracer sets the manager's tracer.

type JobScheduler added in v1.20201204.1 

type JobScheduler struct {
	sync.Mutex `json:"-"`
	Latch      *async.Latch `json:"-"`

	Name        string `json:"name"`
	Description string `json:"description"`
	Job         Job    `json:"-"`

	Tracer Tracer              `json:"-"`
	Log    logger.FullReceiver `json:"-"`
	Config *Config             `json:"-"`

	// Meta Fields
	Disabled    bool            `json:"disabled"`
	NextRuntime time.Time       `json:"nextRuntime"`
	Current     *JobInvocation  `json:"current"`
	Last        *JobInvocation  `json:"last"`
	History     []JobInvocation `json:"history"`

	Schedule                       Schedule             `json:"-"`
	EnabledProvider                func() bool          `json:"-"`
	SerialProvider                 func() bool          `json:"-"`
	TimeoutProvider                func() time.Duration `json:"-"`
	ShouldTriggerListenersProvider func() bool          `json:"-"`
	ShouldWriteOutputProvider      func() bool          `json:"-"`
}

JobScheduler is a job instance.

func NewJobScheduler added in v1.20201204.1 

func NewJobScheduler(cfg *Config, job Job) *JobScheduler

NewJobScheduler returns a job scheduler for a given job.

func (*JobScheduler) Cancel added in v1.20201204.1 

func (js *JobScheduler) Cancel()

Cancel stops an execution in process.

func (*JobScheduler) Disable added in v1.20201204.1 

func (js *JobScheduler) Disable()

Disable sets the job as disabled.

func (*JobScheduler) Enable added in v1.20201204.1 

func (js *JobScheduler) Enable()

Enable sets the job as enabled.

func (*JobScheduler) Invocation 

func (js *JobScheduler) Invocation(id string) *JobInvocation

Invocation returns an invocation by id.

func (*JobScheduler) NotifyStarted added in v1.20201204.1 

func (js *JobScheduler) NotifyStarted() <-chan struct{}

NotifyStarted notifies the job scheduler has started.

func (*JobScheduler) NotifyStopped added in v1.20201204.1 

func (js *JobScheduler) NotifyStopped() <-chan struct{}

NotifyStopped notifies the job scheduler has stopped.

func (*JobScheduler) Run added in v1.20201204.1 

func (js *JobScheduler) Run()

Run forces the job to run. It checks if the job should be allowed to execute. It blocks on the job execution to enforce or clear timeouts.

func (*JobScheduler) RunLoop added in v1.20201204.1 

func (js *JobScheduler) RunLoop()

RunLoop is the main scheduler loop. it alarms on the next runtime and forks a new routine to run the job. It can be aborted with the scheduler's async.Latch.

func (*JobScheduler) Start added in v1.20201204.1 

func (js *JobScheduler) Start() error

Start starts the scheduler. This call blocks.

func (*JobScheduler) StartAsync 

func (js *JobScheduler) StartAsync() error

StartAsync starts the job scheduler in the background.

func (*JobScheduler) Stop added in v1.20201204.1 

func (js *JobScheduler) Stop() error

Stop stops the scheduler.

func (*JobScheduler) WithLogger 

func (js *JobScheduler) WithLogger(log logger.FullReceiver) *JobScheduler

WithLogger sets the scheduler logger.

func (*JobScheduler) WithTracer 

func (js *JobScheduler) WithTracer(tracer Tracer) *JobScheduler

WithTracer sets the scheduler tracer.

type JobSchedulersByJobNameAsc added in v1.20201204.1 

type JobSchedulersByJobNameAsc []*JobScheduler

JobSchedulersByJobNameAsc is a wrapper that sorts job schedulers by the job name ascending.

func (JobSchedulersByJobNameAsc) Len added in v1.20201204.1 

func (s JobSchedulersByJobNameAsc) Len() int

Len implements sorter.

func (JobSchedulersByJobNameAsc) Less added in v1.20201204.1 

func (s JobSchedulersByJobNameAsc) Less(i, j int) bool

Less implements sorter.

func (JobSchedulersByJobNameAsc) Swap added in v1.20201204.1 

func (s JobSchedulersByJobNameAsc) Swap(i, j int)

Swap implements sorter.

type JobStatus 

type JobStatus string

JobStatus is a job status. 

const (
	JobStatusRunning   JobStatus = "running"
	JobStatusCancelled JobStatus = "cancelled"
	JobStatusFailed    JobStatus = "failed"
	JobStatusComplete  JobStatus = "complete"
)

Status values.

type OnBrokenReceiver added in v0.3.2 

type OnBrokenReceiver interface {
	OnBroken(context.Context)
}

OnBrokenReceiver is an interface that allows a job to be signaled when it is a failure that followed a previous success.

type OnCancellationReceiver 

type OnCancellationReceiver interface {
	OnCancellation(context.Context)
}

OnCancellationReceiver is an interface that allows a task to be signaled when it has been canceled.

type OnCompleteReceiver 

type OnCompleteReceiver interface {
	OnComplete(context.Context)
}

OnCompleteReceiver is an interface that allows a task to be signaled when it has been completed.

type OnDisabledReceiver 

type OnDisabledReceiver interface {
	OnDisabled(context.Context)
}

OnDisabledReceiver is a lifecycle hook for disabled events.

type OnEnabledReceiver 

type OnEnabledReceiver interface {
	OnEnabled(context.Context)
}

OnEnabledReceiver is a lifecycle hook for enabled events.

type OnFailureReceiver added in v0.3.2 

type OnFailureReceiver interface {
	OnFailure(context.Context)
}

OnFailureReceiver is an interface that allows a task to be signaled when it has been completed.

type OnFixedReceiver added in v0.3.2 

type OnFixedReceiver interface {
	OnFixed(context.Context)
}

OnFixedReceiver is an interface that allows a jbo to be signaled when is a success that followed a previous failure.

type OnStartReceiver 

type OnStartReceiver interface {
	OnStart(context.Context)
}

OnStartReceiver is an interface that allows a task to be signaled when it has started.

type OnTheHourAtUTCSchedule added in v1.20201204.1 

type OnTheHourAtUTCSchedule struct {
	Minute int
	Second int
}

OnTheHourAtUTCSchedule is a schedule that fires every hour on the given minute.

func (OnTheHourAtUTCSchedule) Next added in v1.20201204.1 

func (o OnTheHourAtUTCSchedule) Next(after time.Time) time.Time

Next implements the chronometer Schedule api.

func (OnTheHourAtUTCSchedule) String added in v1.20201204.1 

func (o OnTheHourAtUTCSchedule) String() string

String returns a string representation of the schedule.

type OnceAtUTCSchedule added in v0.3.2 

type OnceAtUTCSchedule struct {
	Time time.Time
}

OnceAtUTCSchedule is a schedule.

func (OnceAtUTCSchedule) Next added in v1.20201204.1 

func (oa OnceAtUTCSchedule) Next(after time.Time) time.Time

Next returns the next runtime.

func (OnceAtUTCSchedule) String added in v1.20201204.1 

func (oa OnceAtUTCSchedule) String() string

String returns a string representation of the schedule.

type Schedule 

type Schedule interface {
	// GetNextRuntime should return the next runtime after a given previous runtime. If `after` is time.Time{} it should be assumed
	// the job hasn't run yet. If time.Time{} is returned by the schedule it is inferred that the job should not run again.
	Next(time.Time) time.Time
}

Schedule is a type that provides a next runtime after a given previous runtime.

func DailyAtUTC added in v0.3.2 

func DailyAtUTC(hour, minute, second int) Schedule

DailyAtUTC returns a schedule that fires every day at the given hour, minute and second in UTC.

func Every 

func Every(interval time.Duration) Schedule

Every returns a schedule that fires every given interval.

func EveryHour 

func EveryHour() Schedule

EveryHour returns a schedule that fire every hour.

func EveryHourAtUTC added in v1.20201204.1 

func EveryHourAtUTC(minute, second int) Schedule

EveryHourAtUTC returns a schedule that fires every hour at a given minute.

func EveryHourOnTheHour 

func EveryHourOnTheHour() Schedule

EveryHourOnTheHour returns a schedule that fires every 60 minutes on the 00th minute.

func EveryMinute 

func EveryMinute() Schedule

EveryMinute returns a schedule that fires every minute.

func EverySecond 

func EverySecond() Schedule

EverySecond returns a schedule that fires every second.

func OnceAtUTC added in v0.3.2 

func OnceAtUTC(t time.Time) Schedule

OnceAtUTC returns a schedule that fires once at a given time. It will never fire again unless reloaded.

func ParseString added in v1.20201204.1 

func ParseString(cronString string) (Schedule, error)

ParseString parses a cron formatted string into a schedule. The string must be at least 5 components, whitespace separated. If the string has 5 components a 0 will be prepended for the seconds component, and a * appended for the year component. If the string has 6 components a * appended for the year component. (seconds) (minutes) (hours) (day of month) (month) (day of week) (year) 

Field name     Mandatory?   Allowed values    Allowed special characters
----------     ----------   --------------    --------------------------
Seconds        No           0-59              * / , -
Minutes        Yes          0-59              * / , -
Hours          Yes          0-23              * / , -
Day of month   Yes          1-31              * / , - L W
Month          Yes          1-12 or JAN-DEC   * / , -
Day of week    Yes          0-6 or SUN-SAT    * / , - L #
Year           No           1970–2099         * / , -

You can also use shorthands for the cron string: 

@yearly is equivalent to "0 0 0 1 1 * *"
@monthly is equivalent to "0 0 0 1 * * *"
@weekly is equivalent to "0 0 0 * * 0 *"
@daily is equivalent to "0 0 0 * * * *"
@hourly is equivalent to "0 0 * * * * *"
@every xyz will parse the `xyz` value as a duration and return an every schedule for that

func WeekdaysAtUTC added in v0.3.2 

func WeekdaysAtUTC(hour, minute, second int) Schedule

WeekdaysAtUTC returns a schedule that fires every week day at the given hour, minute and second in UTC>

func WeekendsAtUTC added in v0.3.2 

func WeekendsAtUTC(hour, minute, second int) Schedule

WeekendsAtUTC returns a schedule that fires every weekend day at the given hour, minut and second.

func WeeklyAtUTC added in v0.3.2 

func WeeklyAtUTC(hour, minute, second int, days ...time.Weekday) Schedule

WeeklyAtUTC returns a schedule that fires on every of the given days at the given time by hour, minute and second in UTC.

type ScheduleProvider added in v0.3.2 

type ScheduleProvider interface {
	Schedule() Schedule
}

ScheduleProvider returns a schedule for the job.

type SerialProvider 

type SerialProvider interface {
	Serial() bool
}

SerialProvider is an optional interface that prohibits a task from running if another instance of the task is currently running.

type ShouldTriggerListenersProvider added in v0.3.2 

type ShouldTriggerListenersProvider interface {
	ShouldTriggerListeners() bool
}

ShouldTriggerListenersProvider is a type that enables or disables logger listeners.

type ShouldWriteOutputProvider added in v0.3.2 

type ShouldWriteOutputProvider interface {
	ShouldWriteOutput() bool
}

ShouldWriteOutputProvider is a type that enables or disables logger output for events.

type State 

type State string

State is a job state. 

const (
	//StateRunning is the running state.
	StateRunning State = "running"
	// StateEnabled is the enabled state.
	StateEnabled State = "enabled"
	// StateDisabled is the disabled state.
	StateDisabled State = "disabled"
)

type Status 

type Status struct {
	Jobs    []*JobScheduler             `json:"jobs"`
	Running map[string][]*JobInvocation `json:"running,omitempty"`
}

Status is a status object

type StatusProvider 

type StatusProvider interface {
	Status() string
}

StatusProvider is an interface that allows a task to report its status.

type StringSchedule added in v1.20201204.1 

type StringSchedule struct {
	Original string

	Seconds     []int
	Minutes     []int
	Hours       []int
	DaysOfMonth []int
	Months      []int
	DaysOfWeek  []int
	Years       []int
}

StringSchedule is a schedule generated from a cron string.

func (*StringSchedule) FullString added in v1.20201204.1 

func (ss *StringSchedule) FullString() string

FullString returns a fully formed string representation of the schedule's components. It shows fields as expanded.

func (*StringSchedule) Next added in v1.20201204.1 

func (ss *StringSchedule) Next(after time.Time) time.Time

Next implements cron.Schedule.

func (*StringSchedule) String added in v1.20201204.1 

func (ss *StringSchedule) String() string

String returns the original string schedule.

type TimeoutProvider 

type TimeoutProvider interface {
	Timeout() time.Duration
}

TimeoutProvider is an interface that allows a task to be timed out.

type TraceFinisher 

type TraceFinisher interface {
	Finish(context.Context)
}

TraceFinisher is a finisher for traces.

type Tracer 

type Tracer interface {
	Start(context.Context) (context.Context, TraceFinisher)
}

Tracer is a trace handler.

Source Files

View all Source files

Directories

Path Synopsis
_examples
load_test command
timeouts command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.