Schedule a function

To have a function invoked according to a cron specification, simply call the AddFunc() function of this Service.

For example, to invoke a function in your own service every hour on the half hour you can implement:

 1func (p *Example) Start() error {
 2    id, err := p.cron.AddFunc( "0 30 * * * *", p.tick )
 3    if err != nil {
 4        return err
 5    }
 6    p.tickId = id
 7
 8    return nil
 9}
10
11func (p *Example) Stop() {
12    p.cron.Remove(p.tickId)
13}
14
15// tick is called every hour on the half hour
16func (p *Example) tick() {
17    // Do something
18}

Schedule a Job

As an alternative, you can add a type instead of a function as long as that type implements the Job interface.

1type Job interface {
2    Run()
3}

To do this use the AddJob() function instead of AddFunc.

 1type MyJob struct {
 2}
 3
 4// Run will be called every hour on the half hour
 5func (j *MyJob) Run() {
 6    // Do something
 7}
 8
 9func (p *Example) Start() error {
10    id, err := p.cron.AddJob( "0 30 * * * *", &MyJob{} )
11    if err != nil {
12        return err
13    }
14    p.tickId = id
15
16    return nil
17}
18
19func (p *Example) Stop() {
20    p.cron.Remove(p.tickId)
21}

The underlying library supports a Schedule interface which allows for custom schedules to be implemented:

1type Schedule interface {
2    // Next returns the next activation time, later than the given time.
3    // Next is invoked initially, and then each time the job is run.
4    Next(time.Time) time.Time
5}

You can then create a type which implements this interface and, every time Next() is called return the time.Time when that job will execute.

To schedule the Job you then use the Schedule() function in the Service:

 1type MySchedule {
 2}
 3
 4func (s *MySchedule) Next(t time.Time) time.Time {
 5    return t.Add(time.Second*5)
 6}
 7
 8type MyJob struct {
 9}
10
11// Run will be called every 5 seconds
12func (j *MyJob) Run() {
13    // Do something
14}
15
16func (p *Example) Start() error {
17    id, err := p.cron.AddJob( &MySchedule{}, &MyJob{} )
18    if err != nil {
19        return err
20    }
21    p.tickId = id
22
23    return nil
24}
25
26func (p *Example) Stop() {
27    p.cron.Remove(p.tickId)
28}

The underlying library provides several Schedule implementations including ConstantDelaySchedule and SpecSchedule.

The AddFunc, AddJob and Schedule functions return two values, an EntryID and an error. If error is nil then the EntryID can be stored and used to cancel the Schedule at a later time.

 1func (p *Example) Start() error {
 2    id, err := p.cron.AddFunc("0 30 * * * *", p.tick)
 3    if err != nil {
 4        return err
 5    }
 6
 7    // Pointless but cancels the timer
 8    p.cron.Remove(id)
 9    return nil
10}
11
12// tick is called every hour on the half hour
13func (p *Example) tick() {
14    // Do something
15}

The following describes a Cron specification. This is copied from the underlying libraries documentation.

A cron expression represents a set of times, using 6 space-separated fields.

Note: Month and Day-of-week field values are case-insensitive.

Special Characters

Predefined schedules

You may use one of several pre-defined schedules in place of a cron expression.

Intervals

You may also schedule a job to execute at fixed intervals. This is supported by formatting the cron spec like this:

1@every <duration>

where "duration" is a string accepted by time.ParseDuration.

For example, "@every 1h30m10s" would indicate a schedule that activates every 1 hour, 30 minutes, 10 seconds.

Time zones

By default, all interpretation and scheduling is done in the machine's local time zone. 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"