gocron

package module
v1.6.1-0...-a8b1ada Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 2, 2021 License: MIT Imports: 13 Imported by: 0

README

gocron: A Golang Job Scheduling Package.

CI State Go Report Card Go Doc

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 the Ruby module clockwork and the Python job scheduling package schedule.

See also these two great articles:

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

Concepts

  • Scheduler: The scheduler tracks all the jobs assigned to it and makes sure they are passed to the executor when ready to be run. The scheduler is able to manage overall aspects of job behavior like limiting how many jobs are running at one time.
  • Job: The job is simply aware of the task (go function) it's provided and is therefore only able to perform actions related to that task like preventing itself from overruning a previous task that is taking a long time.
  • Executor: The executor, as it's name suggests, is simply responsible for calling the task (go function) that the job hands to it when sent by the scheduler.

Examples

s := gocron.NewScheduler(time.UTC)

s.Every(5).Seconds().Do(func(){ ... })

// strings parse to duration
s.Every("5m").Do(func(){ ... })

s.Every(5).Days().Do(func(){ ... })

// cron expressions supported
s.Cron("*/1 * * * *").Do(task) // every minute

// you can start running the scheduler in two different ways:
// starts the scheduler asynchronously
s.StartAsync()
// starts the scheduler and blocks current execution path 
s.StartBlocking()

For more examples, take a look in our go docs

Options

Interval Supported schedule options
sub-second StartAt()
milliseconds StartAt()
seconds StartAt()
minutes StartAt()
hours StartAt()
days StartAt(), At()
weeks StartAt(), At(), Weekday() (and all week day named functions)
months StartAt(), At()

There are several options available to restrict how jobs run:

Mode Function Behavior
Default jobs are rescheduled at every interval
Job singleton SingletonMode() a long running job will not be rescheduled until the current run is completed
Scheduler limit SetMaxConcurrentJobs() set a collective maximum number of concurrent jobs running across the scheduler

Tags

Jobs may have arbitrary tags added which can be useful when tracking many jobs. The scheduler supports both enforcing tags to be unique and when not unique, running all jobs with a given tag.

s := gocron.NewScheduler(time.UTC)
s.TagsUnique()

_, _ = s.Every(1).Week().Tag("foo").Do(task)
_, err := s.Every(1).Week().Tag("foo").Do(task)
// error!!!

s := gocron.NewScheduler(time.UTC)

s.Every(2).Day().Tag("tag").At("10:00").Do(task)
s.Every(1).Minute().Tag("tag").Do(task)
s.RunByTag("tag")
// both jobs will run

FAQ

  • Q: I'm running multiple pods on a distributed environment. How can I make a job not run once per pod causing duplication?

  • A: We recommend using your own lock solution within the jobs themselves (you could use Redis, for example)

  • Q: I've removed my job from the scheduler, but how can I stop a long-running job that has already been triggered?

  • A: We recommend using a means of canceling your job, e.g. a context.WithCancel().

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

Design

design-diagram

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. gocron lets you run Golang functions periodically at pre-determined intervals using a simple, human-friendly syntax.

Index

Examples

Constants

View Source 
const (
	// default is that if a limit on maximum concurrent jobs is set
	// and the limit is reached, a job will skip it's run and try
	// again on the next occurrence in the schedule
	RescheduleMode limitMode = iota

	// in wait mode if a limit on maximum concurrent jobs is set
	// and the limit is reached, a job will wait to try and run
	// until a spot in the limit is freed up.
	//
	// Note: this mode can produce unpredictable results as
	// job execution order isn't guaranteed. For example, a job that
	// executes frequently may pile up in the wait queue and be executed
	// many times back to back when the queue opens.
	WaitMode
)
View Source 
const (
	// default unit is seconds
	Milliseconds schedulingUnit = iota
	Seconds
	Minutes
	Hours
	Days
	Weeks
	Months
	Duration
	Crontab
)

Variables

View Source 
var (
	ErrNotAFunction                  = errors.New("only functions can be schedule into the job queue")
	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")
	ErrInvalidInterval               = errors.New(".Every() interval must be greater than 0")
	ErrInvalidIntervalType           = errors.New(".Every() interval must be int, time.Duration, or string")
	ErrInvalidIntervalUnitsSelection = errors.New(".Every(time.Duration) and .Cron() cannot be used with units (e.g. .Seconds())")

	ErrAtTimeNotSupported     = errors.New("the At() method is not supported for this time unit")
	ErrWeekdayNotSupported    = errors.New("weekday is not supported for time unit")
	ErrTagsUnique             = func(tag string) error { return fmt.Errorf("a non-unique tag was set on the job: %s", tag) }
	ErrWrongParams            = errors.New("wrong list of params")
	ErrUpdateCalledWithoutJob = errors.New("a call to Scheduler.Update() requires a call to Scheduler.Job() first")
	ErrCronParseFailure       = errors.New("cron expression failed to be parsed")
)

Error declarations for gocron related errors

Functions

This section is empty.

Types

type Job 

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

Job struct stores the information necessary to run a Job

func (*Job) Error 

func (j *Job) Error() error

Error returns an error if one occurred while creating the Job. If multiple errors occurred, they will be wrapped and can be checked using the standard unwrap options.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

func main() {
	s := gocron.NewScheduler(time.UTC)
	s.Every(1).Day().At("bad time")
	j := s.Jobs()[0]
	fmt.Println(j.Error())
}

Output:

the given time format is not supported

func (*Job) LastRun 

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

LastRun returns the time the job was run last

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	job, _ := s.Every(1).Second().Do(task)
	s.StartAsync()

	fmt.Println("Last run:", job.LastRun())
}

Output:

func (*Job) LimitRunsTo 

func (j *Job) LimitRunsTo(n int)
	return j.scheduledWeekday
}

LimitRunsTo limits the number of executions of this job to n. The job will remain in the scheduler. Note: If a job is added to a running scheduler and this method is then used you may see the job run more than the set limit as job is scheduled immediately by default upon being added to the scheduler. It is recommended to use the LimitRunsTo() func on the scheduler chain when scheduling the job. For example: scheduler.LimitRunsTo(1).Do()

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	job, _ := s.Every(1).Second().Do(task)
	job.LimitRunsTo(2)
	s.StartAsync()
}

Output:

func (*Job) NextRun 

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

NextRun returns the time the job will run next

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	job, _ := s.Every(1).Second().Do(task)
	go func() {
		for {
			fmt.Println("Next run", job.NextRun())
			time.Sleep(time.Second)
		}
	}()
	s.StartAsync()
}

Output:

func (*Job) RunCount 

func (j *Job) RunCount() int

RunCount returns the number of time the job ran so far

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	job, _ := s.Every(1).Second().Do(task)
	go func() {
		for {
			fmt.Println("Run count", job.RunCount())
			time.Sleep(time.Second)
		}
	}()
	s.StartAsync()
}

Output:

func (*Job) ScheduledAtTime 

func (j *Job) ScheduledAtTime() string

ScheduledAtTime returns the specific time of day the Job will run at

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	job, _ := s.Every(1).Day().At("10:30").Do(task)
	s.StartAsync()
	fmt.Println(job.ScheduledAtTime())
}

Output:

10:30

func (*Job) ScheduledTime 

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

ScheduledTime returns the time of the Job's next scheduled run

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	job, _ := s.Every(1).Day().At("10:30").Do(task)
	s.StartAsync()
	fmt.Println(job.ScheduledTime())
}

Output:

func (*Job) SingletonMode 

func (j *Job) SingletonMode()

SingletonMode prevents a new job from starting if the prior job has not yet completed it's run Note: If a job is added to a running scheduler and this method is then used you may see the job run overrun itself as job is scheduled immediately by default upon being added to the scheduler. It is recommended to use the SingletonMode() func on the scheduler chain when scheduling the job.

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	job, _ := s.Every(1).Second().Do(task)
	job.SingletonMode()
}

Output:

func (*Job) Tag 

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

Tag allows you to add arbitrary labels to a Job that do not impact the functionality of the Job

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	job, _ := s.Every("1s").Do(task)

	job.Tag("tag1", "tag2", "tag3")
	s.StartAsync()
	fmt.Println(job.Tags())
}

Output:

[tag1 tag2 tag3]

func (*Job) Tags 

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

Tags returns the tags attached to the Job

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	job, _ := s.Every("1s").Do(task)

	job.Tag("tag1", "tag2", "tag3")
	s.StartAsync()
	fmt.Println(job.Tags())
}

Output:

[tag1 tag2 tag3]

func (*Job) Untag 

func (j *Job) Untag(t string)

Untag removes a tag from a Job

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	job, _ := s.Every("1s").Do(task)

	job.Tag("tag1", "tag2", "tag3")
	s.StartAsync()
	fmt.Println(job.Tags())
	job.Untag("tag2")
	fmt.Println(job.Tags())
}

Output:

[tag1 tag2 tag3]
[tag1 tag3]

func (*Job) Weekday 

func (j *Job) Weekday() (time.Weekday, error)

Weekday returns which day of the week the Job will run on and will return an error if the Job is not scheduled weekly

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	weeklyJob, _ := s.Every(1).Week().Monday().Do(task)
	weekday, _ := weeklyJob.Weekday()
	fmt.Println(weekday)

	dailyJob, _ := s.Every(1).Day().Do(task)
	_, err := dailyJob.Weekday()
	fmt.Println(err)
}

Output:

Monday
job not scheduled weekly on a weekday

func (*Job) Weekdays 

func (j *Job) Weekdays() []time.Weekday

Weekdays returns a slice of time.Weekday that the Job will run in a week and will return an error if the Job is not scheduled weekly

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	j, _ := s.Every(1).Week().Monday().Wednesday().Friday().Do(task)
	fmt.Println(j.Weekdays())
}

Output:

[Monday Wednesday Friday]

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 

func NewScheduler(loc *time.Location) *Scheduler

NewScheduler creates a new Scheduler

func (*Scheduler) At 

func (s *Scheduler) At(i interface{}) *Scheduler

At schedules the Job at a specific time of day in the form "HH:MM:SS" or "HH:MM" or time.Time (note that only the hours, minutes, seconds and nanos are used).

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

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 

func (s *Scheduler) ChangeLocation(newLocation *time.Location)

ChangeLocation changes the default time location

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

func main() {
	s := gocron.NewScheduler(time.UTC)
	fmt.Println(s.Location())

	location, err := time.LoadLocation("America/Los_Angeles")
	if err != nil {
		panic(err)
	}
	s.ChangeLocation(location)
	fmt.Println(s.Location())
}

Output:

UTC
America/Los_Angeles

func (*Scheduler) Clear 

func (s *Scheduler) Clear()

Clear clear all Jobs from this scheduler

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	_, _ = s.Every(1).Second().Do(task)
	_, _ = s.Every(1).Minute().Do(task)
	_, _ = s.Every(1).Month(1).Do(task)
	fmt.Println(len(s.Jobs())) // Print the number of jobs before clearing
	s.Clear()                  // Clear all the jobs
	fmt.Println(len(s.Jobs())) // Print the number of jobs after clearing
	s.StartAsync()
}

Output:

3
0

func (*Scheduler) Cron 

func (s *Scheduler) Cron(cronExpression string) *Scheduler
Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	// parsing handled by https://pkg.go.dev/github.com/robfig/cron/v3
	// which follows https://en.wikipedia.org/wiki/Cron
	_, _ = s.Cron("*/1 * * * *").Do(task) // every minute
	_, _ = s.Cron("0 1 * * *").Do(task)   // every day at 1 am
	_, _ = s.Cron("0 0 * * 6,0").Do(task) // weekends only
}

Output:

func (*Scheduler) CronWithSeconds 

func (s *Scheduler) CronWithSeconds(cronExpression string) *Scheduler
Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	// parsing handled by https://pkg.go.dev/github.com/robfig/cron/v3
	// which follows https://en.wikipedia.org/wiki/Cron
	_, _ = s.CronWithSeconds("*/1 * * * * *").Do(task)  // every second
	_, _ = s.CronWithSeconds("0-30 * * * * *").Do(task) // every second 0-30
}

Output:

func (*Scheduler) Day 

func (s *Scheduler) Day() *Scheduler

Day sets the unit with days

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every("24h").Do(task)
	_, _ = s.Every(1).Day().Do(task)
	_, _ = s.Every(1).Days().Do(task)
}

Output:

func (*Scheduler) Days 

func (s *Scheduler) Days() *Scheduler

Days set the unit with days

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every("24h").Do(task)
	_, _ = s.Every(1).Day().Do(task)
	_, _ = s.Every(1).Days().Do(task)
}

Output:

func (*Scheduler) Do 

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

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

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	j, err := s.Every(1).Second().Do(task)
	s.StartAsync()
	fmt.Printf("Job: %v, Error: %v", j, err)
}

Output:

func (*Scheduler) Every 

func (s *Scheduler) Every(interval interface{}) *Scheduler

Every schedules a new periodic Job with an interval. Interval can be an int, time.Duration or a string that parses with time.ParseDuration(). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	_, _ = s.Every(1).Second().Do(task)
	_, _ = s.Every(1 * time.Second).Do(task)
	_, _ = s.Every("1s").Do(task)
	s.StartAsync()
}

Output:

func (*Scheduler) Friday 

func (s *Scheduler) Friday() *Scheduler

Friday sets the start day as Friday

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	j, _ := s.Every(1).Day().Friday().Do(task)
	s.StartAsync()
	wd, _ := j.Weekday()
	fmt.Println(wd)
}

Output:

Friday

func (*Scheduler) Hour 

func (s *Scheduler) Hour() *Scheduler

Hour sets the unit with hours

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every("1h").Do(task)
	_, _ = s.Every(1).Hour().Do(task)
	_, _ = s.Every(1).Hours().Do(task)
}

Output:

func (*Scheduler) Hours 

func (s *Scheduler) Hours() *Scheduler

Hours sets the unit with hours

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every("1h").Do(task)
	_, _ = s.Every(1).Hour().Do(task)
	_, _ = s.Every(1).Hours().Do(task)
}

Output:

func (*Scheduler) IsRunning 

func (s *Scheduler) IsRunning() bool

IsRunning returns true if the scheduler is running

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every("1s").Do(task)
	fmt.Println(s.IsRunning())
	s.StartAsync()
	fmt.Println(s.IsRunning())
}

Output:

false
true

func (*Scheduler) Job 

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

Job puts the provided job in focus for the purpose of making changes to the job with the scheduler chain and finalized by calling Update()

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

func main() {
	s := gocron.NewScheduler(time.UTC)
	j, _ := s.Every("1s").Do(func() {})
	s.StartAsync()

	time.Sleep(10 * time.Second)
	_, _ = s.Job(j).Every("10m").Update()

	time.Sleep(30 * time.Minute)
	_, _ = s.Job(j).Every(1).Day().At("02:00").Update()
}

Output:

func (*Scheduler) Jobs 

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

Jobs returns the list of Jobs from the Scheduler

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every("1s").Do(task)
	_, _ = s.Every("1s").Do(task)
	_, _ = s.Every("1s").Do(task)
	fmt.Println(len(s.Jobs()))
}

Output:

3

func (*Scheduler) Len 

func (s *Scheduler) Len() int

Len returns the number of Jobs in the Scheduler - implemented for sort

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every("1s").Do(task)
	_, _ = s.Every("1s").Do(task)
	_, _ = s.Every("1s").Do(task)
	fmt.Println(s.Len())
}

Output:

3

func (*Scheduler) Less 

func (s *Scheduler) Less(first, second int) bool

Less compares the next run of jobs based on their index. Returns true if the second job is after the first.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every("1s").Do(task)
	_, _ = s.Every("2s").Do(task)
	s.StartAsync()
	fmt.Println(s.Less(0, 1))
}

Output:

true

func (*Scheduler) LimitRunsTo 

func (s *Scheduler) LimitRunsTo(i int) *Scheduler

LimitRunsTo limits the number of executions of this job to n. Upon reaching the limit, the job is removed from the scheduler.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	j, _ := s.Every(1).Second().LimitRunsTo(1).Do(task)
	s.StartAsync()

	fmt.Println(j.RunCount())
}

Output:

1

func (*Scheduler) Location 

func (s *Scheduler) Location() *time.Location

Location provides the current location set on the scheduler

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

func main() {
	s := gocron.NewScheduler(time.UTC)
	fmt.Println(s.Location())
}

Output:

UTC

func (*Scheduler) Millisecond 

func (s *Scheduler) Millisecond() *Scheduler

Millisecond sets the unit with seconds

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every(1).Millisecond().Do(task)
	_, _ = s.Every(1).Milliseconds().Do(task)
	_, _ = s.Every("1ms").Seconds().Do(task)
	_, _ = s.Every(time.Millisecond).Seconds().Do(task)
}

Output:

func (*Scheduler) Milliseconds 

func (s *Scheduler) Milliseconds() *Scheduler

Milliseconds sets the unit with seconds

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every(1).Millisecond().Do(task)
	_, _ = s.Every(1).Milliseconds().Do(task)
	_, _ = s.Every("1ms").Seconds().Do(task)
	_, _ = s.Every(time.Millisecond).Seconds().Do(task)
}

Output:

func (*Scheduler) Minute 

func (s *Scheduler) Minute() *Scheduler

Minute sets the unit with minutes

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every("1m").Do(task)
	_, _ = s.Every(1).Minute().Do(task)
	_, _ = s.Every(1).Minutes().Do(task)
}

Output:

func (*Scheduler) Minutes 

func (s *Scheduler) Minutes() *Scheduler

Minutes sets the unit with minutes

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every("1m").Do(task)
	_, _ = s.Every(1).Minute().Do(task)
	_, _ = s.Every(1).Minutes().Do(task)
}

Output:

func (*Scheduler) Monday 

func (s *Scheduler) Monday() *Scheduler

Monday sets the start day as Monday

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	j, _ := s.Every(1).Day().Monday().Do(task)
	s.StartAsync()
	wd, _ := j.Weekday()
	fmt.Println(wd)
}

Output:

Monday

func (*Scheduler) Month 

func (s *Scheduler) Month(dayOfTheMonth int) *Scheduler

Month sets the unit with months

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every(1).Month(1).Do(task)
	_, _ = s.Every(1).Months(1).Do(task)
}

Output:

func (*Scheduler) Months 

func (s *Scheduler) Months(dayOfTheMonth int) *Scheduler

Months sets the unit with months

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every(1).Month(1).Do(task)
	_, _ = s.Every(1).Months(1).Do(task)
}

Output:

func (*Scheduler) NextRun 

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

NextRun datetime when the next Job should run.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	_, _ = s.Every(1).Day().At("10:30").Do(task)
	s.StartAsync()
	_, t := s.NextRun()
	// print only the hour and minute (hh:mm)
	fmt.Println(t.Format("15:04"))
}

Output:

10:30

func (*Scheduler) Remove 

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

Remove specific Job by function

Removing a job stops that job's timer. However, if a job has already been started by by the job's timer before being removed, there is no way to stop it through gocron as https://pkg.go.dev/time#Timer.Stop explains. The job function would need to have implemented a means of stopping, e.g. using a context.WithCancel().

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	_, _ = s.Every(1).Week().Do(task)
	s.StartAsync()
	s.Remove(task)
	fmt.Println(s.Len())
}

Output:

0

func (*Scheduler) RemoveByReference 

func (s *Scheduler) RemoveByReference(job *Job)

RemoveByReference removes specific Job by reference

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	j, _ := s.Every(1).Week().Do(task)
	_, _ = s.Every(1).Week().Do(task)
	s.StartAsync()
	s.RemoveByReference(j)
	fmt.Println(s.Len())
}

Output:

1

func (*Scheduler) RemoveByTag 

func (s *Scheduler) RemoveByTag(tag string) error

RemoveByTag will remove a job by a given tag.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	_, _ = s.Every(1).Week().Tag("tag1").Do(task)
	_, _ = s.Every(1).Week().Tag("tag2").Do(task)
	s.StartAsync()
	_ = s.RemoveByTag("tag1")
	fmt.Println(s.Len())
}

Output:

1

func (*Scheduler) RunAll 

func (s *Scheduler) RunAll()

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

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	_, _ = s.Every(1).Day().At("10:00").Do(task)
	_, _ = s.Every(2).Day().At("10:00").Do(task)
	_, _ = s.Every(3).Day().At("10:00").Do(task)
	s.StartAsync()
	s.RunAll()
}

Output:

func (*Scheduler) RunAllWithDelay 

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

RunAllWithDelay runs all jobs with the provided delay in between each job

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	_, _ = s.Every(1).Day().At("10:00").Do(task)
	_, _ = s.Every(2).Day().At("10:00").Do(task)
	_, _ = s.Every(3).Day().At("10:00").Do(task)
	s.StartAsync()
	s.RunAllWithDelay(10 * time.Second)
}

Output:

func (*Scheduler) RunByTag 

func (s *Scheduler) RunByTag(tag string) error

RunByTag runs all the jobs containing a specific tag regardless of whether they are scheduled to run or not

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	_, _ = s.Every(1).Day().At("10:00").Do(task)
	_, _ = s.Every(2).Day().Tag("tag").At("10:00").Do(task)
	s.StartAsync()
	_ = s.RunByTag("tag")
}

Output:

func (*Scheduler) RunByTagWithDelay 

func (s *Scheduler) RunByTagWithDelay(tag string, d time.Duration) error

RunByTagWithDelay is same as RunByTag but introduces a delay between each job execution

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	_, _ = s.Every(1).Day().Tag("tag").At("10:00").Do(task)
	_, _ = s.Every(2).Day().Tag("tag").At("10:00").Do(task)
	s.StartAsync()
	_ = s.RunByTagWithDelay("tag", 2*time.Second)
}

Output:

func (*Scheduler) Saturday 

func (s *Scheduler) Saturday() *Scheduler

Saturday sets the start day as Saturday

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	j, _ := s.Every(1).Day().Saturday().Do(task)
	s.StartAsync()
	wd, _ := j.Weekday()
	fmt.Println(wd)
}

Output:

Saturday

func (*Scheduler) Second 

func (s *Scheduler) Second() *Scheduler

Second sets the unit with seconds

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	// the default unit is seconds
	// these are all the same
	_, _ = s.Every(1).Do(task)
	_, _ = s.Every(1).Second().Do(task)
	_, _ = s.Every(1).Seconds().Do(task)
	_, _ = s.Every("1s").Seconds().Do(task)
	_, _ = s.Every(time.Second).Seconds().Do(task)
}

Output:

func (*Scheduler) Seconds 

func (s *Scheduler) Seconds() *Scheduler

Seconds sets the unit with seconds

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	// the default unit is seconds
	// these are all the same
	_, _ = s.Every(1).Do(task)
	_, _ = s.Every(1).Second().Do(task)
	_, _ = s.Every(1).Seconds().Do(task)
	_, _ = s.Every("1s").Seconds().Do(task)
	_, _ = s.Every(time.Second).Seconds().Do(task)

}

Output:

func (*Scheduler) SetMaxConcurrentJobs 

func (s *Scheduler) SetMaxConcurrentJobs(n int, mode limitMode)

SetMaxConcurrentJobs limits how many jobs can be running at the same time. This is useful when running resource intensive jobs and a precise start time is not critical.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

func main() {
	s := gocron.NewScheduler(time.UTC)
	s.SetMaxConcurrentJobs(1, gocron.RescheduleMode)
	_, _ = s.Every(1).Seconds().Do(func() {
		fmt.Println("This will run once every 5 seconds even though it is scheduled every second because maximum concurrent job limit is set.")
		time.Sleep(5 * time.Second)
	})
}

Output:

func (*Scheduler) SetUnit 

func (s *Scheduler) SetUnit(unit schedulingUnit)

setUnit sets the unit type

func (*Scheduler) SingletonMode 

func (s *Scheduler) SingletonMode() *Scheduler

SingletonMode prevents a new job from starting if the prior job has not yet completed it's run

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	_, _ = s.Every(1).Second().SingletonMode().Do(task)
}

Output:

func (*Scheduler) StartAsync 

func (s *Scheduler) StartAsync()

StartAsync starts all jobs without blocking the current thread

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	_, _ = s.Every(3).Seconds().Do(task)
	s.StartAsync()
}

Output:

func (*Scheduler) StartAt 

func (s *Scheduler) StartAt(t time.Time) *Scheduler

StartAt schedules the next run of the Job. If this time is in the past, the configured interval will be used to calculate the next future time

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	specificTime := time.Date(2019, time.November, 10, 15, 0, 0, 0, time.UTC)
	_, _ = s.Every(1).Hour().StartAt(specificTime).Do(task)
	s.StartBlocking()
}

Output:

func (*Scheduler) StartBlocking 

func (s *Scheduler) StartBlocking()

StartBlocking starts all jobs and blocks the current thread

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	_, _ = s.Every(3).Seconds().Do(task)
	s.StartBlocking()
}

Output:

func (*Scheduler) Stop 

func (s *Scheduler) Stop()

Stop stops the scheduler. This is a no-op if the scheduler is already stopped .

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	_, _ = s.Every(1).Second().Do(task)
	s.StartAsync()
	s.Stop()
	fmt.Println(s.IsRunning())
}

Output:

false

func (*Scheduler) Sunday 

func (s *Scheduler) Sunday() *Scheduler

Sunday sets the start day as Sunday

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	j, _ := s.Every(1).Day().Sunday().Do(task)
	s.StartAsync()
	wd, _ := j.Weekday()
	fmt.Println(wd)
}

Output:

Sunday

func (*Scheduler) Swap 

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

Swap places each job into the other job's position given the provided job indexes.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every(1).Tag("tag1").Do(task)
	_, _ = s.Every(1).Tag("tag2").Day().Monday().Do(task)
	fmt.Println(s.Jobs()[0].Tags()[0], s.Jobs()[1].Tags()[0])
	s.Swap(0, 1)
	fmt.Println(s.Jobs()[0].Tags()[0], s.Jobs()[1].Tags()[0])
}

Output:

tag1 tag2
tag2 tag1

func (*Scheduler) Tag 

func (s *Scheduler) Tag(t ...string) *Scheduler

Tag will add a tag when creating a job.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	j, _ := s.Every(1).Week().Tag("tag").Do(task)
	fmt.Println(j.Tags())
}

Output:

[tag]

func (*Scheduler) TagsUnique 

func (s *Scheduler) TagsUnique()

TagsUnique forces job tags to be unique across the scheduler when adding tags with (s *Scheduler) Tag(). This does not enforce uniqueness on tags added via (j *Job) Tag()

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	s.TagsUnique()

	_, _ = s.Every(1).Week().Tag("foo").Do(task)
	_, err := s.Every(1).Week().Tag("foo").Do(task)

	fmt.Println(err)
}

Output:

a non-unique tag was set on the job: foo

func (*Scheduler) TaskPresent 

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

TaskPresent checks if specific job's function was added to the scheduler.

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every(1).Do(task)
	fmt.Println(s.TaskPresent(task))
}

Output:

true

func (*Scheduler) Thursday 

func (s *Scheduler) Thursday() *Scheduler

Thursday sets the start day as Thursday

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	j, _ := s.Every(1).Day().Thursday().Do(task)
	s.StartAsync()
	wd, _ := j.Weekday()
	fmt.Println(wd)
}

Output:

Thursday

func (*Scheduler) Tuesday 

func (s *Scheduler) Tuesday() *Scheduler

Tuesday sets the start day as Tuesday

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	j, _ := s.Every(1).Day().Tuesday().Do(task)
	s.StartAsync()
	wd, _ := j.Weekday()
	fmt.Println(wd)
}

Output:

Tuesday

func (*Scheduler) Update 

func (s *Scheduler) Update() (*Job, error)

Update stops the job (if running) and starts it with any updates that were made to the job in the scheduler chain. Job() must be called first to put the given job in focus.

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	j, _ := s.Every("1s").Do(task)
	s.StartAsync()

	time.Sleep(10 * time.Second)
	_, _ = s.Job(j).Every("10m").Update()

	time.Sleep(30 * time.Minute)
	_, _ = s.Job(j).Every(1).Day().At("02:00").Update()
}

Output:

func (*Scheduler) WaitForSchedule 

func (s *Scheduler) WaitForSchedule() *Scheduler

WaitForSchedule sets the job to not start immediately but rather wait until the first scheduled interval.

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	// job will run 5 minutes from the scheduler starting
	_, _ = s.Every("5m").WaitForSchedule().Do(task)

	// job will run immediately and 5 minutes from the scheduler starting
	_, _ = s.Every("5m").Do(task)
	s.StartAsync()
}

Output:

func (*Scheduler) WaitForScheduleAll 

func (s *Scheduler) WaitForScheduleAll()

WaitForScheduleAll defaults the scheduler to create all new jobs with the WaitForSchedule option as true. The jobs will not start immediately but rather will wait until their first scheduled interval.

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	s.WaitForScheduleAll()

	// all jobs will run 5 minutes from the scheduler starting
	_, _ = s.Every("5m").Do(task)
	_, _ = s.Every("5m").Do(task)
	s.StartAsync()
}

Output:

func (*Scheduler) Wednesday 

func (s *Scheduler) Wednesday() *Scheduler

Wednesday sets the start day as Wednesday

Example 
package main

import (
	"fmt"
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)
	j, _ := s.Every(1).Day().Wednesday().Do(task)
	s.StartAsync()
	wd, _ := j.Weekday()
	fmt.Println(wd)
}

Output:

Wednesday

func (*Scheduler) Week 

func (s *Scheduler) Week() *Scheduler

Week sets the unit with weeks

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every(1).Week().Do(task)
	_, _ = s.Every(1).Weeks().Do(task)

	_, _ = s.Every(1).Week().Monday().Wednesday().Friday().Do(task)
}

Output:

func (*Scheduler) Weekday 

func (s *Scheduler) Weekday(weekDay time.Weekday) *Scheduler

Weekday sets the scheduledWeekday with a specifics weekdays

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every(1).Week().Weekday(time.Monday).Do(task)
	_, _ = s.Every(1).Weeks().Weekday(time.Tuesday).Weekday(time.Friday).Do(task)
}

Output:

func (*Scheduler) Weeks 

func (s *Scheduler) Weeks() *Scheduler

Weeks sets the unit with weeks

Example 
package main

import (
	"time"

	"github.com/hidevopsio/gocron"
)

var task = func() {}

func main() {
	s := gocron.NewScheduler(time.UTC)

	_, _ = s.Every(1).Week().Do(task)
	_, _ = s.Every(1).Weeks().Do(task)

	_, _ = s.Every(2).Weeks().Monday().Wednesday().Friday().Do(task)
}

Output:

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.