gocron: A Golang Job Scheduling Package
gocron is a job scheduling package which lets you run Go functions at pre-determined intervals.
If you want to chat, you can find us on Slack at
Quick Start
go get github.com/go-co-op/gocron/v2
package main
import (
"fmt"
"time"
"github.com/go-co-op/gocron/v2"
)
func main() {
// create a scheduler
s, err := gocron.NewScheduler()
if err != nil {
// handle error
}
// add a job to the scheduler
j, err := s.NewJob(
gocron.DurationJob(
10*time.Second,
),
gocron.NewTask(
func(a string, b int) {
// do things
},
"hello",
1,
),
)
if err != nil {
// handle error
}
// each job has a unique id
fmt.Println(j.ID())
// start the scheduler
s.Start()
// block until you are ready to shut down
select {
case <-time.After(time.Minute):
}
// when you're done, shut it down
err = s.Shutdown()
if err != nil {
// handle error
}
}
Examples
Concepts
- Job: The job encapsulates a "task", which is made up of a go function and any function parameters. The Job then
provides the scheduler with the time the job should next be scheduled to run.
- Scheduler: The scheduler keeps track of all the jobs and sends each job to the executor when
it is ready to be run.
- Executor: The executor calls the job's task and manages the complexities of different job
execution timing requirements (e.g. singletons that shouldn't overrun each other, limiting the max number of jobs running)
Features
Job types
Jobs can be run at various intervals.
- Duration:
Jobs can be run at a fixed
time.Duration
.
- Random duration:
Jobs can be run at a random
time.Duration
between a min and max.
- Cron:
Jobs can be run using a crontab.
- Daily:
Jobs can be run every x days at specific times.
- Weekly:
Jobs can be run every x weeks on specific days of the week and at specific times.
- Monthly:
Jobs can be run every x months on specific days of the month and at specific times.
- One time:
Jobs can be run at specific time(s) (either once or many times).
Concurrency Limits
Jobs can be limited individually or across the entire scheduler.
- Per job limiting with singleton mode:
Jobs can be limited to a single concurrent execution that either reschedules (skips overlapping executions)
or queues (waits for the previous execution to finish).
- Per scheduler limiting with limit mode:
Jobs can be limited to a certain number of concurrent executions across the entire scheduler
using either reschedule (skip when the limit is met) or queue (jobs are added to a queue to
wait for the limit to be available).
- Note: A scheduler limit and a job limit can both be enabled.
Distributed instances of gocron
Multiple instances of gocron can be run.
- Elector:
An elector can be used to elect a single instance of gocron to run as the primary with the
other instances checking to see if a new leader needs to be elected.
- Implementations: go-co-op electors
(don't see what you need? request on slack to get a repo created to contribute it!)
- Locker:
A locker can be used to lock each run of a job to a single instance of gocron.
Locker can be at job or scheduler, if it is defined both at job and scheduler then locker of job will take precedence.
- Implementations: go-co-op lockers
(don't see what you need? request on slack to get a repo created to contribute it!)
Events
Job events can trigger actions.
Options
Many job and scheduler options are available.
- Job options:
Job options can be set when creating a job using
NewJob
.
- Global job options:
Global job options can be set when creating a scheduler using
NewScheduler
and the WithGlobalJobOptions
option.
- Scheduler options:
Scheduler options can be set when creating a scheduler using
NewScheduler
.
Logging
Logs can be enabled.
- Logger:
The Logger interface can be implemented with your desired logging library.
The provided NewLogger uses the standard library's log package.
Metrics
Metrics may be collected from the execution of each job.
- Monitor:
A monitor can be used to collect metrics for each job from a scheduler.
- Implementations: go-co-op monitors
(don't see what you need? request on slack to get a repo created to contribute it!)
Testing
The gocron library is set up to enable testing.
Supporters
We appreciate the support for free and open source software!
This project is supported by:
Star History