README
¶
goCron: A Golang Job Scheduling Package.
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.
See also these two great articles:
If you want to chat, you can find us at Slack!
Examples:
package main
import (
"fmt"
"time"
"github.com/XTao-Technology/gocron"
)
func task() {
fmt.Println("I am running task.")
}
func taskWithParams(a int, b string) {
fmt.Println(a, b)
}
func main() {
// defines a new scheduler that schedules and runs jobs
s1 := gocron.NewScheduler(time.UTC)
s1.Every(3).Seconds().Do(task)
// scheduler starts running jobs and current thread continues to execute
s1.StartAsync()
// Do jobs without params
s2 := gocron.NewScheduler(time.UTC)
s2.Every(1).Second().Do(task)
s2.Every(2).Seconds().Do(task)
s2.Every(1).Minute().Do(task)
s2.Every(2).Minutes().Do(task)
s2.Every(1).Hour().Do(task)
s2.Every(2).Hours().Do(task)
s2.Every(1).Day().Do(task)
s2.Every(2).Days().Do(task)
s2.Every(1).Week().Do(task)
s2.Every(2).Weeks().Do(task)
s2.Every(1).Month(time.Now().Day()).Do(task)
s2.Every(2).Months(15).Do(task)
// Do jobs with params
s2.Every(1).Second().Do(taskWithParams, 1, "hello")
// Do Jobs with tags
// initialize tag
tag1 := []string{"tag1"}
tag2 := []string{"tag2"}
s2.Every(1).Week().SetTag(tag1).Do(task)
s2.Every(1).Week().SetTag(tag2).Do(task)
// Removing Job Based on Tag
s2.RemoveJobByTag("tag1")
// Do jobs on specific weekday
s2.Every(1).Monday().Do(task)
s2.Every(1).Thursday().Do(task)
// Do a job at a specific time - 'hour:min:sec' - seconds optional
s2.Every(1).Day().At("10:30").Do(task)
s2.Every(1).Monday().At("18:30").Do(task)
s2.Every(1).Tuesday().At("18:30:59").Do(task)
// Begin job at a specific date/time.
// Attention: scheduler timezone has precedence over job's timezone!
t := time.Date(2019, time.November, 10, 15, 0, 0, 0, time.UTC)
s2.Every(1).Hour().StartAt(t).Do(task)
// use .StartImmediately() to run job upon scheduler start
s2.Every(1).Hour().StartImmediately().Do(task)
// NextRun gets the next running time
_, time := s2.NextRun()
fmt.Println(time)
// Remove a specific job
s2.Remove(task)
// Clear all scheduled jobs
s2.Clear()
// stop our first scheduler (it still exists but doesn't run anymore)
s1.Stop()
// executes the scheduler and blocks current thread
s2.StartBlocking()
// this line is never reached
}
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)
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
Jetbrains supports this project with GoLand licenses. We appreciate their support for free and open source software!
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.
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
- func SetLocker(l Locker)
- type Job
- type Locker
- type Scheduler
- func (s *Scheduler) At(t string) *Scheduler
- func (s *Scheduler) ChangeLocation(newLocation *time.Location)
- func (s *Scheduler) Clear()
- func (s *Scheduler) Day() *Scheduler
- func (s *Scheduler) Days() *Scheduler
- func (s *Scheduler) Do(jobFun interface{}, params ...interface{}) (*Job, error)
- func (s *Scheduler) Every(interval uint64) *Scheduler
- func (s *Scheduler) Friday() *Scheduler
- func (s *Scheduler) Hour() *Scheduler
- func (s *Scheduler) Hours() *Scheduler
- func (s *Scheduler) Jobs() []*Job
- func (s *Scheduler) Len() int
- func (s *Scheduler) Less(i, j int) bool
- func (s *Scheduler) Lock() *Scheduler
- func (s *Scheduler) Minute() *Scheduler
- func (s *Scheduler) Minutes() *Scheduler
- func (s *Scheduler) Monday() *Scheduler
- func (s *Scheduler) Month(dayOfTheMonth int) *Scheduler
- func (s *Scheduler) Months(dayOfTheMonth int) *Scheduler
- func (s *Scheduler) NextRun() (*Job, time.Time)
- func (s *Scheduler) Remove(j interface{})
- func (s *Scheduler) RemoveByReference(j *Job)
- func (s *Scheduler) RemoveJobByTag(tag string) error
- func (s *Scheduler) RunAll()
- func (s *Scheduler) RunAllWithDelay(d int)
- func (s *Scheduler) RunPending()
- func (s *Scheduler) Saturday() *Scheduler
- func (s *Scheduler) Scheduled(j interface{}) bool
- func (s *Scheduler) Second() *Scheduler
- func (s *Scheduler) Seconds() *Scheduler
- func (s *Scheduler) SetTag(t []string) *Scheduler
- func (s *Scheduler) StartAsync() chan struct{}
- func (s *Scheduler) StartAt(t time.Time) *Scheduler
- func (s *Scheduler) StartBlocking()
- func (s *Scheduler) StartImmediately() *Scheduler
- func (s *Scheduler) Stop()
- func (s *Scheduler) Sunday() *Scheduler
- func (s *Scheduler) Swap(i, j int)
- func (s *Scheduler) Thursday() *Scheduler
- func (s *Scheduler) Tuesday() *Scheduler
- func (s *Scheduler) Wednesday() *Scheduler
- func (s *Scheduler) Week() *Scheduler
- func (s *Scheduler) Weekday(startDay time.Weekday) *Scheduler
- func (s *Scheduler) Weeks() *Scheduler
Examples ¶
Constants ¶
This section is empty.
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") ErrNotScheduledWeekday = errors.New("job not scheduled weekly on a weekday") ErrJobNotFoundWithTag = errors.New("no jobs found with given tag") ErrUnsupportedTimeFormat = errors.New("the given time format is not supported") )
Error declarations for gocron related errors
Functions ¶
Types ¶
type Job ¶
type Job struct {
// contains filtered or unexported fields
}
Job struct stores the information necessary to run a Job
func (*Job) ScheduledAtTime ¶
ScheduledAtTime returns the specific time of day the Job will run at
func (*Job) ScheduledTime ¶
ScheduledTime returns the time of the Job's next scheduled run
Example ¶
package main
import (
"fmt"
"time"
"github.com/XTao-Technology/gocron"
)
var task = func() {
fmt.Println("I am a task")
}
func main() {
s := gocron.NewScheduler(time.UTC)
job, _ := s.Every(1).Day().At("10:30").Do(task)
fmt.Println(job.ScheduledAtTime())
}
Output: 10:30
type Locker ¶
Locker provides an interface for implementing job locking to prevent jobs from running at the same time on multiple instances of gocron
type Scheduler ¶
type Scheduler struct {
// contains filtered or unexported fields
}
Scheduler struct stores a list of Jobs and the location of time Scheduler Scheduler implements the sort.Interface{} for sorting Jobs, by the time of nextRun
func NewScheduler ¶
NewScheduler creates a new Scheduler
func (*Scheduler) At ¶
At schedules the Job at a specific time of day in the form "HH:MM:SS" or "HH:MM"
Example ¶
package main
import (
"fmt"
"time"
"github.com/XTao-Technology/gocron"
)
var task = func() {
fmt.Println("I am a task")
}
func main() {
s := gocron.NewScheduler(time.UTC)
s.Every(1).Day().At("10:30").Do(task)
s.Every(1).Monday().At("10:30:01").Do(task)
}
Output:
func (*Scheduler) ChangeLocation ¶
ChangeLocation changes the default time location
func (*Scheduler) Remove ¶
func (s *Scheduler) Remove(j interface{})
Remove specific Job j by function
func (*Scheduler) RemoveByReference ¶
RemoveByReference removes specific Job j by reference
func (*Scheduler) RemoveJobByTag ¶
RemoveJobByTag will Remove Jobs by Tag
func (*Scheduler) RunAll ¶
func (s *Scheduler) RunAll()
RunAll run all Jobs regardless if they are scheduled to run or not
func (*Scheduler) RunAllWithDelay ¶
RunAllWithDelay runs all Jobs with delay seconds
func (*Scheduler) RunPending ¶
func (s *Scheduler) RunPending()
RunPending runs all the Jobs that are scheduled to run.
func (*Scheduler) StartAsync ¶
func (s *Scheduler) StartAsync() chan struct{}
StartAsync starts a goroutine that runs all the pending using a second-long ticker
func (*Scheduler) StartBlocking ¶
func (s *Scheduler) StartBlocking()
StartBlocking starts all the pending jobs using a second-long ticker and blocks the current thread
Example ¶
package main
import (
"fmt"
"time"
"github.com/XTao-Technology/gocron"
)
var task = func() {
fmt.Println("I am a task")
}
func main() {
s := gocron.NewScheduler(time.UTC)
s.Every(3).Seconds().Do(task)
s.StartBlocking()
}
Output:
func (*Scheduler) StartImmediately ¶
StartImmediately sets the Jobs next run as soon as the scheduler starts
func (*Scheduler) Stop ¶
func (s *Scheduler) Stop()
Stop stops the scheduler. This is a no-op if the scheduler is already stopped .
Source Files
Directories