README
¶
go-cron
configurable cronjobs with persistence
See the godocs for documentation.
This library is heavily inspired/borrows from https://github.com/robfig/cron. The main reason for it's creation was the need to serialize and store jobs, thus closures could not be used.
Documentation
¶
Overview ¶
Package cron is a cron manager partially based on github.com/robfig/cron (same parser semantics and scheduling logic). It adds more fine-grained control on running jobs, such as cancellations, as well as persistent storage of entries.
Usage Callers may register routines to be invoked on a given schedule. Cron will run them in their own goroutines. Package cron provides a global scheduler, as well as constructors for cron.Executor objects.
routine := func(ctx context.Context, args map[string]interface{}) error {
fmt.Println("called", time.Now())
}
cron.Register("printroutine", routine)
// Start the global executor
cron.Start()
// Add an entry to our global crontab
cron.Add(cron.Entry{
ID: "myjob",
Expression: "@every 1s",
Job: "printroutine",
})
CRON Expression Format A cron expression represents a set of times, using 6 space-separated fields.
Field name | Mandatory? | Allowed values | Allowed special characters ---------- | ---------- | -------------- | -------------------------- Seconds | Yes | 0-59 | * / , - Minutes | Yes | 0-59 | * / , - Hours | Yes | 0-23 | * / , - Day of month | Yes | 1-31 | * / , - ? Month | Yes | 1-12 or JAN-DEC | * / , - Day of week | Yes | 0-6 or SUN-SAT | * / , - ?
Note: Month and Day-of-week field values are case insensitive. "SUN", "Sun", and "sun" are equally accepted. Special Characters Asterisk ( * ) The asterisk indicates that the cron expression will match for all values of the field; e.g., using an asterisk in the 5th field (month) would indicate every month. Slash ( / ) Slashes are used to describe increments of ranges. For example 3-59/15 in the 1st field (minutes) would indicate the 3rd minute of the hour and every 15 minutes thereafter. The form "*\/..." is equivalent to the form "first-last/...", that is, an increment over the largest possible range of the field. The form "N/..." is accepted as meaning "N-MAX/...", that is, starting at N, use the increment until the end of that specific range. It does not wrap around. Comma ( , ) Commas are used to separate items of a list. For example, using "MON,WED,FRI" in the 5th field (day of week) would mean Mondays, Wednesdays and Fridays. Hyphen ( - ) Hyphens are used to define ranges. For example, 9-17 would indicate every hour between 9am and 5pm inclusive. Question mark ( ? ) Question mark may be used instead of '*' for leaving either day-of-month or day-of-week blank. Predefined schedules You may use one of several pre-defined schedules in place of a cron expression.
Entry | Description | Equivalent To ----- | ----------- | ------------- @yearly (or @annually) | Run once a year, midnight, Jan. 1st | 0 0 0 1 1 * @monthly | Run once a month, midnight, first of month | 0 0 0 1 * * @weekly | Run once a week, midnight between Sat/Sun | 0 0 0 * * 0 @daily (or @midnight) | Run once a day, midnight | 0 0 0 * * * @hourly | Run once an hour, beginning of hour | 0 0 * * * *
Intervals You may also schedule a job to execute at fixed intervals, starting at the time it's added or cron is run. This is supported by formatting the cron spec like this:
@every <duration>
where "duration" is a string accepted by time.ParseDuration (http://golang.org/pkg/time/#ParseDuration). For example, "@every 1h30m10s" would indicate a schedule that activates after 1 hour, 30 minutes, 10 seconds, and then every interval after that. Note: The interval does not take the job runtime into account. For example, if a job takes 3 minutes to run, and it is scheduled to run every 5 minutes, it will have only 2 minutes of idle time between each run. Time zones All interpretation and scheduling is done in the machine's local time zone (as provided by the Go time package (http://www.golang.org/pkg/time) by default. Setting an entries location will override the default location. Be aware that jobs scheduled during daylight-savings leap-ahead transitions will not be run! Thread safety Since the Cron service runs concurrently with the calling code, some amount of care must be taken to ensure proper synchronization. All cron methods are designed to be correctly synchronized as long as the caller ensures that invocations have a clear happens-before ordering between them. Storage Entries may be persistently stored by writing an implementation for the Tab interface.
Index ¶
- Variables
- func Add(entry Entry) error
- func Cancel(ID string)
- func CancelAll()
- func CancelFromContext(ctx context.Context) context.CancelFunc
- func Configure(opts ...Option) error
- func ContextRunning(ctx context.Context) bool
- func ContextStart(ctx context.Context) context.Context
- func ContextWithCancel(ctx context.Context, cfunc context.CancelFunc) context.Context
- func ContextWithEntry(ctx context.Context, e Entry) context.Context
- func ContextWithReport(ctx context.Context, rep string) context.Context
- func Err() chan error
- func GetLog() chan Log
- func IsRunning() bool
- func Location() time.Location
- func NewContext(ctx context.Context, entry Entry) (context.Context, context.CancelFunc)
- func Register(ID string, routine Routine) error
- func Remove(ID string) error
- func ReportFromContext(ctx context.Context) string
- func Start() error
- func Stop()
- func StopAll()
- type ByTimeAsc
- type ConstantDelaySchedule
- type Entry
- type ErrCronFailure
- type ErrNotFound
- type ErrPermanentFailure
- type ErrRepeatNextCron
- type ErrRepeatable
- type Executor
- func (e *Executor) Add(entry Entry) error
- func (e *Executor) Cancel(ID string) error
- func (e *Executor) CancelAll()
- func (e *Executor) Err() chan error
- func (e *Executor) IsRunning() bool
- func (e *Executor) Location() time.Location
- func (e *Executor) Log() chan Log
- func (e *Executor) Refresh() <-chan Update
- func (e *Executor) Register(ID string, routine Routine) error
- func (e *Executor) Remove(ID string) error
- func (e *Executor) Start() error
- func (e *Executor) Stop()
- func (e *Executor) StopAll()
- type Log
- type MemoryTab
- type Option
- type ParseOption
- type Parser
- type Routine
- type RunPolicy
- type Schedule
- type SpecSchedule
- type Tab
- type Update
- type UpdateType
Constants ¶
This section is empty.
Variables ¶
var ( // ErrJobExists is returned by the executor instance if the provided job ID is present in the registry. ErrJobExists = errors.New("job already registered") // ErrJobNotExists is returned/used by the executor if a job is not registered but called/queried. ErrJobNotExists = errors.New("job not registered") // DefaultLocation is the default locale of the executor. DefaultLocation = time.UTC )
Functions ¶
func Cancel ¶
func Cancel(ID string)
Cancel a specific entry in the global executor while running. If it is not running, Cancel is a noop.
func CancelFromContext ¶
func CancelFromContext(ctx context.Context) context.CancelFunc
CancelFromContext returns the cancel func.
func ContextRunning ¶
ContextRunning returns the job running state.
func ContextStart ¶
ContextStart sets the state of the job ctx to running. If already started, Start is a noop.
func ContextWithCancel ¶
ContextWithCancel sets the cancel func in a context.
func ContextWithEntry ¶
ContextWithEntry sets the job Entry.
func ContextWithReport ¶
ContextWithReport sets the job report.
func NewContext ¶
NewContext creates a cron Context from existing contexts and the entry. The contexts defaults to a running status of False.
func Remove ¶
Remove an entry from the global executor tab. Does not cancel running job nor removes it from the current queue.
func ReportFromContext ¶
ReportFromContext returns the job report.
Types ¶
type ByTimeAsc ¶
type ByTimeAsc []*Entry
ByTimeAsc defines ordering for []*Entry
func (ByTimeAsc) RemoveCons ¶
RemoveCons removes the ith element in constant time, does not preserves order
type ConstantDelaySchedule ¶
ConstantDelaySchedule represents a simple recurring duty cycle, e.g. "Every 5 minutes". It does not support jobs more frequent than once a second.
func Every ¶
func Every(duration time.Duration) ConstantDelaySchedule
Every returns a crontab Schedule that activates once every duration. Delays of less than a second are not supported (will round up to 1 second). Any fields less than a Second are truncated.
type Entry ¶
type Entry struct {
// Globally unique ID
ID string
// cron expression
Expression string
// Routine-identifier to be executed
Routine string
// Arguments passed to the Job. Arguments should be JSON serializeable if a persistent store is used.
Args map[string]interface{}
// Location overrides the executors location if provided. Not required.
Location *time.Location
Policy RunPolicy
NextRun time.Time
PreviousRun time.Time
}
Entry specifies a single (crontab) entry, a function which is executed periodically.
func EntryFromContext ¶
EntryFromContext returns the job entry.
type ErrCronFailure ¶
type ErrCronFailure error
ErrCronFailure indicates the cron executor should cease running.
type ErrNotFound ¶
type ErrNotFound error
type ErrPermanentFailure ¶
type ErrPermanentFailure error
ErrPermanentFailure indicates the cron should be removed from the schedule.
type ErrRepeatNextCron ¶
type ErrRepeatNextCron error
ErrRepeatNextCron indicates the job may be retried when the schedule allows.
type ErrRepeatable ¶
type ErrRepeatable error
ErrRepeatable indicates the job should be retried immediately.
type Executor ¶
type Executor struct {
// contains filtered or unexported fields
}
Executor is the godlevel struct.
func (*Executor) Cancel ¶
Cancel a specific entry while running. If it is not running, Cancel returns ErrNotFound
func (*Executor) Refresh ¶
Refresh blocks on the refresh channel,which returns updates on the internal executor queue
func (*Executor) Remove ¶
Remove an entry from the tab. Does not cancel running job nor removes it from the current queue.
type MemoryTab ¶
type MemoryTab struct {
// contains filtered or unexported fields
}
MemoryTab is a simple storage backend.
func NewMemoryTab ¶
func NewMemoryTab() *MemoryTab
NewMemoryTab returns an in-memory Tab. This is a non-persistent storage.
type Option ¶
Option is a constructor function
type ParseOption ¶
type ParseOption int
Configuration options for creating a parser. Most options specify which fields should be included, while others enable features. If a field is not included the parser will assume a default value. These options do not change the order fields are parse in.
const ( Second ParseOption = 1 << iota // Seconds field, default 0 Minute // Minutes field, default 0 Hour // Hours field, default 0 Dom // Day of month field, default * Month // Month field, default * Dow // Day of week field, default * DowOptional // Optional day of week field, default * Descriptor // Allow descriptors such as @monthly, @weekly, etc. )
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
A custom Parser that can be configured.
func NewParser ¶
func NewParser(options ParseOption) Parser
Creates a custom Parser with custom options.
// Standard parser without descriptors
specParser := NewParser(Minute | Hour | Dom | Month | Dow)
sched, err := specParser.Parse("0 0 15 */3 *")
// Same as above, just excludes time fields
subsParser := NewParser(Dom | Month | Dow)
sched, err := specParser.Parse("15 */3 *")
// Same as above, just makes Dow optional
subsParser := NewParser(Dom | Month | DowOptional)
sched, err := specParser.Parse("15 */3")
type RunPolicy ¶
type RunPolicy int
RunPolicy defines running behaviour of an entry.
const ( // RunParallel runs an entry while ignoring other running instances. RunParallel RunPolicy = 0 // CancelRunning cancels previously running entries before starting. CancelRunning RunPolicy = 1 // SingleInstanceOnly cancels previously running entries, awaits cancellation confirmation before starting. SingleInstanceOnly RunPolicy = 2 // SkipIfRunning ignores the entry if another instance is currently running SkipIfRunning RunPolicy = 3 )
type Schedule ¶
type Schedule interface {
// Return the next activation time, later than the given time.
// Next is invoked initially, and then each time the job is run.
Next(time.Time) time.Time
}
The Schedule describes a job's duty cycle.
func Parse ¶
Parse returns a new crontab schedule representing the given spec. It returns a descriptive error if the spec is not valid.
It accepts
- Full crontab specs, e.g. "* * * * * ?"
- Descriptors, e.g. "@midnight", "@every 1h30m"
func ParseStandard ¶
ParseStandard returns a new crontab schedule representing the given standardSpec (https://en.wikipedia.org/wiki/Cron). It differs from Parse requiring to always pass 5 entries representing: minute, hour, day of month, month and day of week, in that order. It returns a descriptive error if the spec is not valid.
It accepts
- Standard crontab specs, e.g. "* * * * ?"
- Descriptors, e.g. "@midnight", "@every 1h30m"
type SpecSchedule ¶
type SpecSchedule struct {
Second, Minute, Hour, Dom, Month, Dow uint64
}
SpecSchedule specifies a duty cycle (to the second granularity), based on a traditional crontab specification. It is computed initially and stored as bit sets.
type Tab ¶
type Tab interface {
// Stores a new entry
Put(Entry) error
// Returns all entries
All() (map[string]*Entry, error)
// Removes a single entry
Remove(ID string) error
// Update a single entry.
//
// ID is the ID of the current entry. If the ID does not match the provided entry.ID, the ID will be updated as well.
Update(ID string, entry Entry) error
// Clears all entries
Clear() error
// Refresh provides any new or updated entries. The executor selects on Refresh to update it's own internal queue.
//
// Do not read of Tab.Refresh as package user; instead listen on the Refresh method of executor if you wish to obtain
// updated/new entries.
Refresh() <-chan Update
}
Tab (crontab is short for cron table) defines the storage backend for the scheduler.
type Update ¶
type Update struct {
UpdateType
Entry
}
Source Files