mirror of https://github.com/ouqiang/gocron
142 lines
4.8 KiB
Markdown
142 lines
4.8 KiB
Markdown
cron
|
|
====
|
|
|
|
A cron library for Go. See the
|
|
[godoc](http://go.pkgdoc.org/github.com/robfig/cron).
|
|
|
|
## Usage
|
|
|
|
Callers may register Funcs to be invoked on a given schedule. Cron will run
|
|
them in their own goroutines. A name must be provided.
|
|
|
|
```go
|
|
c := cron.New()
|
|
c.AddFunc("0 5 * * * *", func() { fmt.Println("Every 5 minutes") }, "Often")
|
|
c.AddFunc("@hourly", func() { fmt.Println("Every hour") }, "Frequent")
|
|
c.AddFunc("@every 1h30m", func() { fmt.Println("Every hour thirty") }, "Less Frequent")
|
|
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") }, "My Job")
|
|
..
|
|
// Inspect the cron job entries' next and previous run times.
|
|
inspect(c.Entries())
|
|
..
|
|
// Remove an entry from the cron by name.
|
|
c.RemoveJob("My Job")
|
|
..
|
|
c.Stop() // Stop the scheduler (does not stop any jobs already running).
|
|
```
|
|
|
|
## CRON Expression
|
|
|
|
This section describes the specific format accepted by this cron. Some snippets
|
|
are taken from [the wikipedia article](http://en.wikipedia.org/wiki/Cron).
|
|
|
|
### 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 | <code>0 0 0 1 1 *</code>
|
|
@monthly | Run once a month, midnight, first of month | <code>0 0 0 1 * *</code>
|
|
@weekly | Run once a week, midnight on Sunday | <code>0 0 0 * * 0</code>
|
|
@daily (or @midnight) | Run once a day, midnight | <code>0 0 0 * * *</code>
|
|
@hourly | Run once an hour, beginning of hour | <code>0 0 * * * *</code>
|
|
|
|
## 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
|
|
|
|
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)).
|
|
|
|
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](http://go.pkgdoc.org/github.com/robfig/cron#Cron) 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.
|