gocron

package module
v0.0.0-...-a85959f Latest Latest
Warning

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

 Go to latest Published: Apr 7, 2022 License: MIT Imports: 14 Imported by: 0

README

gocron: A Golang Job Scheduling Package.

CI State Go Report Card Go Doc

gocron is a job scheduling package which lets you run Go functions at pre-determined intervals using a simple, human-friendly syntax.

gocron is a Golang scheduler implementation similar to the Ruby module clockwork and the Python job scheduling package schedule.

See also these two great articles that were used for design input:

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(){ ... })

s.Every(1).Month(1, 2, 3).Do(func(){ ... })

// set time
s.Every(1).Day().At("10:30").Do(func(){ ... })

// set multiple times
s.Every(1).Day().At("10:30;08:00").Do(func(){ ... })

s.Every(1).Day().At("10:30").At("08:00").Do(func(){ ... })

// Schedule each last day of the month
s.Every(1).MonthLastDay().Do(func(){ ... })

// Or each last day of every other month
s.Every(2).MonthLastDay().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

Constants

View Source 
const (
	// RescheduleMode - the 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

	// WaitMode - 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
)

Variables

View Source 
var (
	ErrNotAFunction                  = errors.New("only functions can be scheduled 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")
	ErrInvalidDayOfMonthEntry           = errors.New("only days 1 through 28 are allowed for monthly schedules")
	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")
	ErrInvalidDaysOfMonthDuplicateValue = errors.New("duplicate days of month is not allowed in Month() and Months() methods")
)

Error declarations for gocron related errors

Functions

This section is empty.

Types

type Job 

type Job struct {
	// 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.

func (*Job) IsRunning 

func (j *Job) IsRunning() bool

IsRunning reports whether any instances of the job function are currently running

func (*Job) LastRun 

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

LastRun returns the time the job was run last

func (*Job) LimitRunsTo 

func (j *Job) LimitRunsTo(n int)

LimitRunsTo limits the number of executions of this job to n. Upon reaching the limit, the job is removed from 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()

func (*Job) NextRun 

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

NextRun returns the time the job will run next

func (*Job) RunCount 

func (j *Job) RunCount() int

RunCount returns the number of time the job ran so far

func (*Job) ScheduledAtTime 

func (j *Job) ScheduledAtTime() string

ScheduledAtTime returns the specific time of day the Job will run at. If multiple times are set, the earliest time will be returned.

func (*Job) ScheduledAtTimes 

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

ScheduledAtTimes returns the specific times of day the Job will run at

func (*Job) ScheduledTime 

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

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

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.

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

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

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

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

type Scheduler 

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

Scheduler struct stores a list of Jobs and the location of time used by the Scheduler, and 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).

func (*Scheduler) ChangeLocation 

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

ChangeLocation changes the default time location

func (*Scheduler) Clear 

func (s *Scheduler) Clear()

Clear clears all Jobs from this scheduler

func (*Scheduler) Cron 

func (s *Scheduler) Cron(cronExpression string) *Scheduler

func (*Scheduler) CronWithSeconds 

func (s *Scheduler) CronWithSeconds(cronExpression string) *Scheduler

func (*Scheduler) Day 

func (s *Scheduler) Day() *Scheduler

Day sets the unit with days

func (*Scheduler) Days 

func (s *Scheduler) Days() *Scheduler

Days set the unit with days

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

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".

func (*Scheduler) FindJobsByTag 

func (s *Scheduler) FindJobsByTag(tags ...string) ([]*Job, error)

FindJobsByTag will return a slice of Jobs that match all given tags

func (*Scheduler) Friday 

func (s *Scheduler) Friday() *Scheduler

Friday sets the start day as Friday

func (*Scheduler) Hour 

func (s *Scheduler) Hour() *Scheduler

Hour sets the unit with hours

func (*Scheduler) Hours 

func (s *Scheduler) Hours() *Scheduler

Hours sets the unit with hours

func (*Scheduler) IsRunning 

func (s *Scheduler) IsRunning() bool

IsRunning returns true if the scheduler is running

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()

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

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

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.

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.

func (*Scheduler) Location 

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

Location provides the current location set on the scheduler

func (*Scheduler) Midday 

func (s *Scheduler) Midday() *Scheduler

func (*Scheduler) Millisecond 

func (s *Scheduler) Millisecond() *Scheduler

Millisecond sets the unit with seconds

func (*Scheduler) Milliseconds 

func (s *Scheduler) Milliseconds() *Scheduler

Milliseconds sets the unit with seconds

func (*Scheduler) Minute 

func (s *Scheduler) Minute() *Scheduler

Minute sets the unit with minutes

func (*Scheduler) Minutes 

func (s *Scheduler) Minutes() *Scheduler

Minutes sets the unit with minutes

func (*Scheduler) Monday 

func (s *Scheduler) Monday() *Scheduler

Monday sets the start day as Monday

func (*Scheduler) Month 

func (s *Scheduler) Month(daysOfMonth ...int) *Scheduler

Month sets the unit with months

func (*Scheduler) MonthFirstWeekday 

func (s *Scheduler) MonthFirstWeekday(weekday time.Weekday) *Scheduler

MonthFirstWeekday sets the job to run the first specified weekday of the month

func (*Scheduler) MonthLastDay 

func (s *Scheduler) MonthLastDay() *Scheduler

MonthLastDay sets the unit with months at every last day of the month

func (*Scheduler) Months 

func (s *Scheduler) Months(daysOfTheMonth ...int) *Scheduler

Months sets the unit with months Note: Only days 1 through 28 are allowed for monthly schedules Note: Multiple add same days of month cannot be allowed Note: -1 is a special value and can only occur as single argument

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(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().

func (*Scheduler) RemoveByReference 

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

RemoveByReference removes specific Job by reference

func (*Scheduler) RemoveByTag 

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

RemoveByTag will remove Jobs that match the given tag.

func (*Scheduler) RemoveByTags 

func (s *Scheduler) RemoveByTags(tags ...string) error

RemoveByTags will remove Jobs that match all given tags.

func (*Scheduler) RemoveByTagsAny 

func (s *Scheduler) RemoveByTagsAny(tags ...string) error

RemoveByTagsAny will remove Jobs that match any one of the given tags.

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 the provided delay in between each job

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

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

func (*Scheduler) Saturday 

func (s *Scheduler) Saturday() *Scheduler

Saturday sets the start day as Saturday

func (*Scheduler) Second 

func (s *Scheduler) Second() *Scheduler

Second sets the unit with seconds

func (*Scheduler) Seconds 

func (s *Scheduler) Seconds() *Scheduler

Seconds sets the unit with seconds

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.

func (*Scheduler) SingletonMode 

func (s *Scheduler) SingletonMode() *Scheduler

SingletonMode prevents a new job from starting if the prior job has not yet completed its run

func (*Scheduler) SingletonModeAll 

func (s *Scheduler) SingletonModeAll()

SingletonModeAll prevents new jobs from starting if the prior instance of the particular job has not yet completed its run

func (*Scheduler) StartAsync 

func (s *Scheduler) StartAsync()

StartAsync starts all jobs without blocking the current thread

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

func (*Scheduler) StartBlocking 

func (s *Scheduler) StartBlocking()

StartBlocking starts all jobs and blocks the current thread

func (*Scheduler) StartImmediately 

func (s *Scheduler) StartImmediately() *Scheduler

StartImmediately sets the job to run immediately upon starting the scheduler or adding the job to a running scheduler. This overrides the jobs start status of any previously called methods in the chain.

Note: This is the default behavior of the scheduler for most jobs, but is useful for overriding the default behavior of Cron scheduled jobs which default to WaitForSchedule.

func (*Scheduler) Stop 

func (s *Scheduler) Stop()

Stop stops the scheduler. This is a no-op if the scheduler is already stopped. It waits for all running jobs to finish before returning, so it is safe to assume that running jobs will finish when calling this.

func (*Scheduler) Sunday 

func (s *Scheduler) Sunday() *Scheduler

Sunday sets the start day as 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.

func (*Scheduler) Tag 

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

Tag will add a tag when creating a job.

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()

func (*Scheduler) TaskPresent 

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

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

func (*Scheduler) Thursday 

func (s *Scheduler) Thursday() *Scheduler

Thursday sets the start day as Thursday

func (*Scheduler) Tuesday 

func (s *Scheduler) Tuesday() *Scheduler

Tuesday sets the start day as 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.

func (*Scheduler) WaitForSchedule 

func (s *Scheduler) WaitForSchedule() *Scheduler

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

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.

func (*Scheduler) Wednesday 

func (s *Scheduler) Wednesday() *Scheduler

Wednesday sets the start day as Wednesday

func (*Scheduler) Week 

func (s *Scheduler) Week() *Scheduler

Week sets the unit with weeks

func (*Scheduler) Weekday 

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

Weekday sets the scheduledWeekdays with a specifics weekdays

func (*Scheduler) Weeks 

func (s *Scheduler) Weeks() *Scheduler

Weeks sets the unit with weeks

Source Files

View all Source files

Directories

Path Synopsis

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.