133 lines
4.9 KiB
Go
133 lines
4.9 KiB
Go
/*
|
|
Package cron implements a cron spec parser and job runner.
|
|
|
|
Usage
|
|
|
|
Callers may register Funcs to be invoked on a given schedule. Cron will run
|
|
them in their own goroutines.
|
|
|
|
c := cron.New()
|
|
c.AddFunc("0 30 * * * *", func() { fmt.Println("Every hour on the half hour") })
|
|
c.AddFunc("TZ=Asia/Tokyo 30 04 * * * *", func() { fmt.Println("Runs at 04:30 Tokyo time every day") })
|
|
c.AddFunc("@hourly", func() { fmt.Println("Every hour") })
|
|
c.AddFunc("@every 1h30m", func() { fmt.Println("Every hour thirty") })
|
|
c.Start()
|
|
..
|
|
// Funcs are invoked in their own goroutine, asynchronously.
|
|
...
|
|
// Funcs may also be added to a running Cron
|
|
c.AddFunc("@daily", func() { fmt.Println("Every day") })
|
|
..
|
|
// Inspect the cron job entries' next and previous run times.
|
|
inspect(c.Entries())
|
|
..
|
|
c.Stop() // Stop the scheduler (does not stop any jobs already running).
|
|
|
|
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 | No | 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 on Sunday | 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. 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 every
|
|
1 hour, 30 minutes, 10 seconds.
|
|
|
|
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
|
|
|
|
By default, 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).
|
|
The time zone may be overridden by providing an additional space-separated field
|
|
at the beginning of the cron spec, of the form "TZ=Asia/Tokyo"
|
|
|
|
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.
|
|
|
|
Implementation
|
|
|
|
Cron entries are stored in an array, sorted by their next activation time. Cron
|
|
sleeps until the next job is due to be run.
|
|
|
|
Upon waking:
|
|
- it runs each entry that is active on that second
|
|
- it calculates the next run times for the jobs that were run
|
|
- it re-sorts the array of entries by next activation time.
|
|
- it goes to sleep until the soonest job.
|
|
*/
|
|
package cron
|