README
¶
scheduler
Package cron provides mechanism for executing scheduled tasks with cron-like expression.
Documentation & Examples
Documentation & Examples can be found on the packages documentation.
Documentation
¶
Overview ¶
Package cron provides a pure-go mechanism for executing scheduled tasks with cron patterns.
Cron patterns are a simple and flexible way to configure a schedule for which an automated task should run.
- * * * * | | | | \ | | | \ The day of the week (0=Sunday - 6=Saturday or MON-FRI) | | \ Month (1=January - 12=December or JAN-DEC) | \ The day of the month (1-31) \ Hour (0-23) Minute (0-59)
Each component of the pattern can be: a single numerical value, a range, a comma-separated list of numerical values, an pattern, or a wildcard. Typically all values must match the current time for the job to run, however, when a day of month or day of week is specified (not a wildcard) those two values are OR-d. This can be confusing to understand, so know that the only real gotcha with this quirk is that there is no way to have a job run on a schedule such as 'every Friday the 13th'. It would instead run on every Friday and the 13th of each month.
If the component is a numerical value, then the same component (minute, hour, month, etc...) of the current time must match the exact value for the component. If the component is a range, the current time value must fall between that range. If the component is a comma-separated list of numerical values, the current time must match any one of the values.
Month and Day of Week values can also be the first three letters of the english name of that unit. For example, JAN for January or THU for Thursday.
Components can also be an pattern for a mod operation, such as */5 or */2. Where if the remainder from the current times component and the pattern is zero, it matches.
Lastly, components can be a wildcard *, which will match any value.
Some example patterns are:
"* * * * *" Run every minute "0 * * * *" Run at the start of every hour "0 0 * * *" Run every day at midnight "*/5 * * * *" Run every 5 minutes "* */2 * * *" Run every 2 hours "0 9-17 * * *" Run every day at the start every hour between 9AM to 5PM "0 3,5,7 * * *" Run every day at 3AM, 5AM, and 7AM
This package conforms to the POSIX crontab standard, which can be found here: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html
Cron wakes up each minute to check for any jobs to run, then sleeps for the remainder of the minute. Under normal circumstances cron is accurate up-to 1 second. Each job's method is called in a unique goroutine and will recover from any panics.
By default, Cron operates using the local timezone as determined by Golang, but this can be changed with the TZ field of a Tab object.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Job ¶
type Job struct {
// Cron pattern describing the schedule of this job
Pattern string
// The name of this job, only used for logging
Name string
// The method to invoke when the job runs
Exec func()
// contains filtered or unexported fields
}
Job describes a single job that will run based on the pattern
func (Job) Validate ¶ added in v1.1.0
Validate will ensure that the job pattern is valid and return an error with any validation error
func (Job) WouldRunNow ¶
WouldRunNow returns true if this job would run right now in the current timezone
type Tab ¶
type Tab struct {
// The jobs to run
Jobs []Job
// Optional time when the schedule should expire. Set to nil for no expiry date.
ExpireAfter *time.Time
// The frequency to check if the jobs should run. By default this is 60 seconds and should not be changed.
Interval time.Duration
// The timezone to use when checking if jobs should run. Defaults to the local timezone as determined by Go.
TZ *time.Location
}
Tab describes a group of jobs, known as a "Tab"
func New ¶
New create a new cron instance (known as a "tab") for the given slice of jobs but do not start it. Error is only populated if there is a validation error on any of the job patterns.
Example ¶
package main
import (
"github.com/ecnepsnai/cron"
)
func main() {
schedule, _ := cron.New([]cron.Job{
{
Pattern: "* * * * *",
Name: "RunsEveryMinute",
Exec: func() {
// This would run every minute
},
},
{
Pattern: "0 * * * *",
Name: "OnTheHour",
Exec: func() {
// This would run at the start of every hour
},
},
{
Pattern: "*/5 * * * *",
Name: "Every5Minutes",
Exec: func() {
// This would run every 5 minutes
},
},
})
// This will start the cron at (or as close to as possible) 0 seconds of the next minute
go schedule.Start()
}
Output:
func (*Tab) ForceStart ¶
func (s *Tab) ForceStart()
ForceStart will start the schedule immediately without waiting. This can have the undesired effect of jobs running at most 60 seconds later than they would if you used `Start`.
This method blocks.
Source Files