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

Concepts

• Job: The encapsulates a "task", which is made up of a go func and any function parameters, and then provides the scheduler with the time the job should be scheduled to run.
• Executor: The executor, calls the "task" function and manages the complexities of different job execution timing (e.g. singletons that shouldn't overrun each other, limiting the max number of jobs running)
• Scheduler: The scheduler keeps track of all the jobs and sends each job to the executor when it is ready to be run.

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

	// when you're done, shut it down
	err = s.Shutdown()
	if err != nil {
		// handle error
	}
}

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.
• Limited Concurrency: 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).
• 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
  • Locker: A locker can be used to lock each run of a job to a single instance of gocron.
    • Implementations: go-co-op lockers
• Events: Job events can trigger actions.
  • Listeners: Event listeners can be added to a job or all jobs in the scheduler to listen for job events and 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.
  • 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.
• Mocking: The gocron library is set up to enable testing.
  • Mocks are provided in the mock package using gomock.
  • Time can be mocked by passing in a FakeClock to WithClock - see the example on WithClock in the go-docs.

Supporters

Jetbrains supports this project with Intellij licenses. We appreciate their support for free and open source software!

Star History