gocron

README

Note from current maintainers:

A currently maintained fork of this project has been migrated to https://github.com/go-co-op/gocron

Disclaimer: we (the maintainers) tried, with no luck, to get in contact with Jason (the repository owner) in order to add new maintainers or leave the project within an organization. Unfortunately, he hasn't replied for months now (March, 2020).

So, we decided to move the project to a new repository (as stated above), in order to keep the evolution of the project coming from as many people as possible. Feel free to reach over!

goCron: A Golang Job Scheduling Package.

This package is currently looking for new maintainers (cause @jasonlvhit is in ICU). Please message @jasonlvhit if you are interested.

goCron is a Golang job scheduling package which lets you run Go functions periodically at pre-determined interval using a simple, human-friendly syntax.

goCron is a Golang implementation of Ruby module clockwork and Python job scheduling package schedule, and personally, this package is my first Golang program, just for fun and practice.

See also this two great articles:

• Rethinking Cron
• Replace Cron with Clockwork

If you want to chat, you can find us at Slack!

Back to this package, you could just use this simple API as below, to run a cron scheduler.

package main

import (
	"fmt"
	"time"

	"github.com/jasonlvhit/gocron"
)

func task() {
	fmt.Println("I am running task.")
}

func taskWithParams(a int, b string) {
	fmt.Println(a, b)
}

func main() {
	// Do jobs without params
	gocron.Every(1).Second().Do(task)
	gocron.Every(2).Seconds().Do(task)
	gocron.Every(1).Minute().Do(task)
	gocron.Every(2).Minutes().Do(task)
	gocron.Every(1).Hour().Do(task)
	gocron.Every(2).Hours().Do(task)
	gocron.Every(1).Day().Do(task)
	gocron.Every(2).Days().Do(task)
	gocron.Every(1).Week().Do(task)
	gocron.Every(2).Weeks().Do(task)

	// Do jobs with params
	gocron.Every(1).Second().Do(taskWithParams, 1, "hello")

	// Do jobs on specific weekday
	gocron.Every(1).Monday().Do(task)
	gocron.Every(1).Thursday().Do(task)

	// Do a job at a specific time - 'hour:min:sec' - seconds optional
	gocron.Every(1).Day().At("10:30").Do(task)
	gocron.Every(1).Monday().At("18:30").Do(task)
	gocron.Every(1).Tuesday().At("18:30:59").Do(task)

	// Begin job immediately upon start
	gocron.Every(1).Hour().From(gocron.NextTick()).Do(task)

	// Begin job at a specific date/time
	t := time.Date(2019, time.November, 10, 15, 0, 0, 0, time.Local)
	gocron.Every(1).Hour().From(&t).Do(task)

	// NextRun gets the next running time
	_, time := gocron.NextRun()
	fmt.Println(time)

	// Remove a specific job
	gocron.Remove(task)

	// Clear all scheduled jobs
	gocron.Clear()

	// Start all the pending jobs
	<- gocron.Start()

	// also, you can create a new scheduler
	// to run two schedulers concurrently
	s := gocron.NewScheduler()
	s.Every(3).Seconds().Do(task)
	<- s.Start()
}

and full test cases and document will be coming soon (help is wanted! If you want to contribute, pull requests are welcome).

If you need to prevent a job from running at the same time from multiple cron instances (like running a cron app from multiple servers), you can provide a Locker implementation and lock the required jobs.

gocron.SetLocker(lockerImplementation)
gocron.Every(1).Hour().Lock().Do(task)

Once again, thanks to the great works of Ruby clockwork and Python schedule package. BSD license is used, see the file License for detail.

Looking to contribute? Try to follow these guidelines:

• Use issues for everything
• For a small change, just send a PR!
• For bigger changes, please open an issue for discussion before sending a PR.
• PRs should have: tests, documentation and examples (if it makes sense)
• You can also contribute by:
  • Reporting issues
  • Suggesting new features or enhancements
  • Improving/fixing documentation

Have fun!

Documentation

Overview

Package gocron : A Golang Job Scheduling Package.

An in-process Scheduler for periodic jobs that uses the builder pattern for configuration. Schedule lets you run Golang functions periodically at pre-determined intervals using a simple, human-friendly syntax.

Inspired by the Ruby module clockwork <https://github.com/tomykaira/clockwork> and Python package schedule <https://github.com/dbader/schedule>

See also http://adam.heroku.com/past/2010/4/13/rethinking_cron/ http://adam.heroku.com/past/2010/6/30/replace_cron_with_clockwork/

Copyright 2014 Jason Lyu. jasonlvhit@gmail.com . All rights reserved. Use of this source code is governed by a BSD-style . license that can be found in the LICENSE file.

Index

• Variables
• type Job
  • func NewJob(interval time.Duration) *Job
  • func (j *Job) Do(jobFun interface{}, params ...interface{}) error
  • func (j *Job) DoSafely(jobFun interface{}, params ...interface{}) error
  • func (j *Job) Err() error
  • func (j *Job) From(t time.Time) *Job
  • func (j *Job) FromMidNight() *Job
  • func (j *Job) Immediately() *Job
  • func (j *Job) NextScheduledTime() time.Time
  • func (j *Job) Once() *Job
  • func (j *Job) SetTags(tags ...string)
  • func (j *Job) Tags() []string
  • func (j *Job) Untag(t string)
• type Scheduler
  • func NewScheduler() *Scheduler
  • func (s *Scheduler) Clear()
  • func (s *Scheduler) Every(interval time.Duration) *Job
  • func (s *Scheduler) Jobs() []*Job
  • func (s *Scheduler) Len() int
  • func (s *Scheduler) Less(i, j int) bool
  • func (s *Scheduler) NextRun() (*Job, time.Time)
  • func (s *Scheduler) Remove(j interface{})
  • func (s *Scheduler) RemoveByRef(j *Job)
  • func (s *Scheduler) RemoveByTag(tag string)
  • func (s *Scheduler) RunAll()
  • func (s *Scheduler) RunAllwithDelay(d time.Duration)
  • func (s *Scheduler) Scheduled(j interface{}) bool
  • func (s *Scheduler) Start()
  • func (s *Scheduler) StartAsync() chan struct{}
  • func (s *Scheduler) Stop()
  • func (s *Scheduler) Swap(i, j int)

Variables

var (
	ErrTimeFormat           = errors.New("time format error")
	ErrParamsNotAdapted     = errors.New("the number of params is not adapted")
	ErrNotAFunction         = errors.New("only functions can be schedule into the job queue")
	ErrPeriodNotSpecified   = errors.New("unspecified job period")
	ErrParameterCannotBeNil = errors.New("nil paramaters cannot be used with reflection")
)

Types

type Job

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

Job struct keeping information about job

func NewJob

func NewJob(interval time.Duration) *Job

NewJob creates a new job with the time interval.

func (*Job) Do

func (j *Job) Do(jobFun interface{}, params ...interface{}) error

Do specifies the jobFunc that should be called every time the job runs

func (*Job) DoSafely

func (j *Job) DoSafely(jobFun interface{}, params ...interface{}) error

DoSafely does the same thing as Do, but logs unexpected panics, instead of unwinding them up the chain Deprecated: DoSafely exists due to historical compatibility and will be removed soon. Use Do instead

func (*Job) Err

func (j *Job) Err() error

Err should be checked to ensure an error didn't occur creating the job

func (*Job) From

func (j *Job) From(t time.Time) *Job

From schedules the next run of the job

func (*Job) FromMidNight

func (j *Job) FromMidNight() *Job

func (*Job) Immediately

func (j *Job) Immediately() *Job

Immediately job will run at next ticker

func (*Job) NextScheduledTime

func (j *Job) NextScheduledTime() time.Time

NextScheduledTime returns the time of when this job is to run next

func (*Job) Once

func (j *Job) Once() *Job

func (*Job) SetTags

func (j *Job) SetTags(tags ...string)

func (*Job) Tags

func (j *Job) Tags() []string

Tags returns the tags attached to the job

func (*Job) Untag

func (j *Job) Untag(t string)

Untag removes a tag from a job

type Scheduler

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

Scheduler struct, the only data member is the list of jobs. - implements the sort.Interface{} for sorting jobs, by the time nextRun

func NewScheduler

func NewScheduler() *Scheduler

NewScheduler creates a new Scheduler

func (*Scheduler) Clear

func (s *Scheduler) Clear()

Clear delete all scheduled jobs

func (*Scheduler) Every

func (s *Scheduler) Every(interval time.Duration) *Job

Every schedule a new periodic job with interval

func (*Scheduler) Jobs

func (s *Scheduler) Jobs() []*Job

Jobs returns the list of Jobs from the Scheduler

func (*Scheduler) Len

func (s *Scheduler) Len() int

func (*Scheduler) Less

func (s *Scheduler) Less(i, j int) bool

func (*Scheduler) NextRun

func (s *Scheduler) NextRun() (*Job, time.Time)

NextRun datetime when the next job should run.

func (*Scheduler) Remove

func (s *Scheduler) Remove(j interface{})

Remove specific job j by function

func (*Scheduler) RemoveByRef

func (s *Scheduler) RemoveByRef(j *Job)

RemoveByRef removes specific job j by reference

func (*Scheduler) RemoveByTag

func (s *Scheduler) RemoveByTag(tag string)

func (*Scheduler) RunAll

func (s *Scheduler) RunAll()

RunAll run all jobs regardless if they are scheduled to run or not

func (*Scheduler) RunAllwithDelay

func (s *Scheduler) RunAllwithDelay(d time.Duration)

RunAllwithDelay runs all jobs with delay seconds

func (*Scheduler) Scheduled

func (s *Scheduler) Scheduled(j interface{}) bool

Scheduled checks if specific job j was already added

func (*Scheduler) Start

func (s *Scheduler) Start()

func (*Scheduler) StartAsync

func (s *Scheduler) StartAsync() chan struct{}

func (*Scheduler) Stop

func (s *Scheduler) Stop()

func (*Scheduler) Swap

func (s *Scheduler) Swap(i, j int)