cron

README

Cron

A Go package that implements a crontab-like service to execute and schedule repetitive tasks/jobs.

Features

• Supports cron expressions for flexible scheduling
• Allows registering and managing multiple jobs
• Provides macros for common schedule patterns
• Supports custom timezones
• Allows setting custom tick intervals
• Supports starting and stopping the cron service

Installation

go get github.com/hvuhsg/gatego/pkg/cron

Usage

package main

import (
	"fmt"
	"time"

	"github.com/hvuhsg/gatego/pkg/cron"
)

func main() {
	c := cron.New()

	// Register a job
	c.MustAdd("job1", "*/5 * * * *", func() {
		fmt.Println("Running job1...")
	})

	// Set a custom timezone
	loc, _ := time.LoadLocation("Asia/Tokyo")
	c.SetTimezone(loc)

	// Set a custom tick interval
	c.SetInterval(5 * time.Second)

	// Start the cron service
	c.Start()

	// Stop the cron service after 30 seconds
	time.Sleep(30 * time.Second)
	c.Stop()
}

Cron Expression Format

The package supports the following cron expression format:

* * * * *
│ │ │ │ │
│ │ │ │ └── Day of Week (0-6)
│ │ │ └──── Month (1-12)
│ │ └────── Day of Month (1-31)
│ └──────── Hour (0-23)
└────────── Minute (0-59)

It also supports the following macros:

• @yearly or @annually: Run once a year at midnight on the first day of the year
• @monthly: Run once a month at midnight on the first day of the month
• @weekly: Run once a week at midnight on Sunday
• @daily or @midnight: Run once a day at midnight
• @hourly: Run once an hour at the beginning of the hour
• @minutely: Run once a minute at the beginning of the minute

Documentation

Overview

Package cron implements a crontab-like service to execute and schedule repeative tasks/jobs.

Example:

c := cron.New()
c.MustAdd("dailyReport", "0 0 * * *", func() { ... })
c.Start()

Index

• Constants
• type Cron
  • func New() *Cron
  • func (c *Cron) Add(jobId string, cronExpr string, run func()) error
  • func (c *Cron) HasStarted() bool
  • func (c *Cron) MustAdd(jobId string, cronExpr string, run func())
  • func (c *Cron) Remove(jobId string)
  • func (c *Cron) RemoveAll()
  • func (c *Cron) SetInterval(d time.Duration)
  • func (c *Cron) SetTimezone(l *time.Location)
  • func (c *Cron) Start()
  • func (c *Cron) Stop()
  • func (c *Cron) Total() int
• type Moment
  • func NewMoment(t time.Time) *Moment
• type Schedule
  • func NewSchedule(cronExpr string) (*Schedule, error)
  • func (s *Schedule) IsDue(m *Moment) bool

Constants

const (
	Yearly   = "@yearly"
	Annually = "@annually"
	Monthly  = "@monthly"
	Weekly   = "@weekly"
	Daily    = "@daily"
	Midnight = "@midnight"
	Hourly   = "@hourly"
	Minutely = "@minutely"
)

Types

type Cron

type Cron struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Cron is a crontab-like struct for tasks/jobs scheduling.

func New

func New() *Cron

New create a new Cron struct with default tick interval of 1 minute and timezone in UTC.

You can change the default tick interval with Cron.SetInterval(). You can change the default timezone with Cron.SetTimezone().

func (*Cron) Add

func (c *Cron) Add(jobId string, cronExpr string, run func()) error

Add registers a single cron job.

If there is already a job with the provided id, then the old job will be replaced with the new one.

cronExpr is a regular cron expression, eg. "0 */3 * * *" (aka. at minute 0 past every 3rd hour). Check cron.NewSchedule() for the supported tokens.

func (*Cron) HasStarted

func (c *Cron) HasStarted() bool

HasStarted checks whether the current Cron ticker has been started.

func (*Cron) MustAdd

func (c *Cron) MustAdd(jobId string, cronExpr string, run func())

MustAdd is similar to Add() but panic on failure.

func (*Cron) Remove

func (c *Cron) Remove(jobId string)

Remove removes a single cron job by its id.

func (*Cron) RemoveAll

func (c *Cron) RemoveAll()

RemoveAll removes all registered cron jobs.

func (*Cron) SetInterval

func (c *Cron) SetInterval(d time.Duration)

SetInterval changes the current cron tick interval (it usually should be >= 1 minute).

func (*Cron) SetTimezone

func (c *Cron) SetTimezone(l *time.Location)

SetTimezone changes the current cron tick timezone.

func (*Cron) Start

func (c *Cron) Start()

Start starts the cron ticker.

Calling Start() on already started cron will restart the ticker.

func (*Cron) Stop

func (c *Cron) Stop()

Stop stops the current cron ticker (if not already).

You can resume the ticker by calling Start().

func (*Cron) Total

func (c *Cron) Total() int

Total returns the current total number of registered cron jobs.

type Moment

type Moment struct {
	Minute    int `json:"minute"`
	Hour      int `json:"hour"`
	Day       int `json:"day"`
	Month     int `json:"month"`
	DayOfWeek int `json:"dayOfWeek"`
}

Moment represents a parsed single time moment.

func NewMoment

func NewMoment(t time.Time) *Moment

NewMoment creates a new Moment from the specified time.

type Schedule

type Schedule struct {
	Minutes    map[int]struct{} `json:"minutes"`
	Hours      map[int]struct{} `json:"hours"`
	Days       map[int]struct{} `json:"days"`
	Months     map[int]struct{} `json:"months"`
	DaysOfWeek map[int]struct{} `json:"daysOfWeek"`
}

Schedule stores parsed information for each time component when a cron job should run.

func NewSchedule

func NewSchedule(cronExpr string) (*Schedule, error)

NewSchedule creates a new Schedule from a cron expression.

A cron expression could be a macro OR 5 segments separated by space, representing: minute, hour, day of the month, month and day of the week.

The following segment formats are supported:

• wildcard: *
• range: 1-30
• step: */n or 1-30/n
• list: 1,2,3,10-20/n

The following macros are supported:

• @yearly (or @annually)
• @monthly
• @weekly
• @daily (or @midnight)
• @hourly
• @minutely

func (*Schedule) IsDue

func (s *Schedule) IsDue(m *Moment) bool

IsDue checks whether the provided Moment satisfies the current Schedule.