gron

README

gron

Gron provides a clear syntax for writing and deploying cron jobs.

Goals

• Minimalist APIs for scheduling jobs.
• Thread safety.
• Customizable Job Type.
• Customizable Schedule.

Installation

$ go get github.com/roylee0704/gron

Usage

Create schedule.go

package main

import (
	"fmt"
	"time"
	"github.com/roylee0704/gron"
)

func main() {
	c := gron.New()
	c.AddFunc(gron.Every(1*time.Hour), func() {
		fmt.Println("runs every hour.")
	})
	c.Start()
}

Schedule Parameters

All scheduling is done in the machine's local time zone (as provided by the Go time package).

Setup basic periodic schedule with gron.Every().

gron.Every(1*time.Second)
gron.Every(1*time.Minute)
gron.Every(1*time.Hour)

Also support Day, Week by importing gron/xtime:

import "github.com/roylee0704/gron/xtime"

gron.Every(1 * xtime.Day)
gron.Every(1 * xtime.Week)

Schedule to run at specific time with .At(hh:mm)

gron.Every(30 * xtime.Day).At("00:00")
gron.Every(1 * xtime.Week).At("23:59")

Custom Job Type

You may define custom job types by implementing gron.Job interface: Run().

For example:

type Reminder struct {
	Msg string
}

func (r Reminder) Run() {
  fmt.Println(r.Msg)
}

After job has defined, instantiate it and schedule to run in Gron.

c := gron.New()
r := Reminder{ "Feed the baby!" }
c.Add(gron.Every(8*time.Hour), r)
c.Start()

Custom Job Func

You may register Funcs to be executed on a given schedule. Gron will run them in their own goroutines, asynchronously.

c := gron.New()
c.AddFunc(gron.Every(1*time.Second), func() {
	fmt.Println("runs every second")
})
c.Start()

Custom Schedule

Schedule is the interface that wraps the basic Next method: Next(p time.Duration) time.Time

In gron, the interface value Schedule has the following concrete types:

• periodicSchedule. adds time instant t to underlying period p.
• atSchedule. reoccurs every period p, at time components(hh:mm).

For more info, checkout schedule.go.

Full Example

package main

import (
	"fmt"
	"github.com/roylee0704/gron"
	"github.com/roylee0704/gron/xtime"
)

type PrintJob struct{ Msg string }

func (p PrintJob) Run() {
	fmt.Println(p.Msg)
}

func main() {

	var (
		// schedules
		daily     = gron.Every(1 * xtime.Day)
		weekly    = gron.Every(1 * xtime.Week)
		monthly   = gron.Every(30 * xtime.Day)
		yearly    = gron.Every(365 * xtime.Day)

		// contrived jobs
		purgeTask = func() { fmt.Println("purge aged records") }
		printFoo  = printJob{"Foo"}
		printBar  = printJob{"Bar"}
	)

	c := gron.New()

	c.Add(daily.At("12:30"), printFoo)
	c.AddFunc(weekly, func() { fmt.Println("Every week") })
	c.Start()

	// Jobs may also be added to a running Gron
	c.Add(monthly, printBar)
	c.AddFunc(yearly, purgeTask)

	// Stop Gron (running jobs are not halted).
	c.Stop()
}

Documentation

Index

• type AtSchedule
  • func Every(p time.Duration) AtSchedule
• type Cron
  • func New() *Cron
  • func (c *Cron) Add(s Schedule, j Job)
  • func (c *Cron) AddFunc(s Schedule, j func())
  • func (c Cron) Entries() []*Entry
  • func (c *Cron) Start()
  • func (c *Cron) Stop()
• type Entry
• type Job
• type JobFunc
  • func (j JobFunc) Run()
• type Schedule

Types

type AtSchedule

type AtSchedule interface {
	At(t string) Schedule
	Schedule
}

AtSchedule extends Schedule by enabling periodic-interval & time-specific setup

func Every

func Every(p time.Duration) AtSchedule

Every returns a Schedule reoccurs every period p, p must be at least time.Second.

type Cron

type Cron struct {
	// contains filtered or unexported fields
}

Cron provides a convenient interface for scheduling job such as to clean-up database entry every month.

Cron keeps track of any number of entries, invoking the associated func as specified by the schedule. It may also be started, stopped and the entries may be inspected.

func New

func New() *Cron

New instantiates new Cron instant c.

func (*Cron) Add

func (c *Cron) Add(s Schedule, j Job)

Add appends schedule, job to entries.

if cron instant is not running, adding to entries is trivial. otherwise, to prevent data-race, adds through channel.

func (*Cron) AddFunc

func (c *Cron) AddFunc(s Schedule, j func())

AddFunc registers the Job function for the given Schedule.

func (Cron) Entries

func (c Cron) Entries() []*Entry

Entries returns cron etn

func (*Cron) Start

func (c *Cron) Start()

Start signals cron instant c to get up and running.

func (*Cron) Stop

func (c *Cron) Stop()

Stop halts cron instant c from running.

type Entry

type Entry struct {
	Schedule Schedule
	Job      Job

	// the next time the job will run. This is zero time if Cron has not been
	// started or invalid schedule.
	Next time.Time

	// the last time the job was run. This is zero time if the job has not been
	// run.
	Prev time.Time
}

Entry consists of a schedule and the job to be executed on that schedule.

type Job

type Job interface {
	Run()
}

Job is the interface that wraps the basic Run method.

Run executes the underlying func.

type JobFunc

type JobFunc func()

JobFunc is an adapter to allow the use of ordinary functions as gron.Job If f is a function with the appropriate signature, JobFunc(f) is a handler that calls f.

todo: possibly func with params? maybe not needed.

func (JobFunc) Run

func (j JobFunc) Run()

Run calls j()

type Schedule

type Schedule interface {
	Next(t time.Time) time.Time
}

Schedule is the interface that wraps the basic Next method.

Next deduces next occurring time based on t and underlying states.