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.