scheduler

README

Go Cron Job Scheduler

Golang Cron Job Scheduler

Get

go get github.com/MichaelS11/go-scheduler

Simple Example

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/MichaelS11/go-scheduler"
)

func main() {
	myFunction := func(dataInterface interface{}) {
		data := dataInterface.(string)
		fmt.Println(data)
	}

	// Create new scheduler
	s := scheduler.NewScheduler()

	// Make a new job that runs myFunction passing it "myData"
	// A cron of * * * * * * * will run every second.
	err := s.Make("jobName", "* * * * * * *", myFunction, "myData")
	if err != nil {
		log.Fatalln("Make error:", err)
	}

	// Starts the job schedule. Job will run at it's next run time.
	s.Start("jobName")

	// Wait a second to make sure job was run
	time.Sleep(time.Second)

	// Stop all the jobs and waits for then to all stop. In the below case it waits for at least a second.
	// Note this does not kill any running jobs, only stops them from running again.
	s.StopAllWait(time.Second)

	// Output:
	// myData
}

Important note about Cron format

The Cron format is in the form of:

Seconds, Minutes, Hours, Day of month, Month, Day of week, Year

Field name     Mandatory?   Allowed values    Allowed special characters
----------     ----------   --------------    --------------------------
Seconds        No           0-59              * / , -
Minutes        Yes          0-59              * / , -
Hours          Yes          0-23              * / , -
Day of month   Yes          1-31              * / , - L W
Month          Yes          1-12 or JAN-DEC   * / , -
Day of week    Yes          0-6 or SUN-SAT    * / , - L #
Year           No           1970�2099         * / , -

The Cron parser used is:

https://github.com/gorhill/cronexpr

Documentation

Overview

Example (Basic)

// This is for testing, to know when myFunction has been called by the scheduler job.
chanStart := make(chan struct{}, 1)

// Create a function for the job to call
myFunction := func(dataInterface interface{}) {
	chanStart <- struct{}{}
	data := dataInterface.(string)
	fmt.Println(data)
}

// Create new scheduler
s := scheduler.NewScheduler()

// cron is in the form: Seconds, Minutes, Hours, Day of month, Month, Day of week, Year
// A cron of * * * * * * * will run every second.
// Parsing cron using:
// https://github.com/gorhill/cronexpr

// Make a new job that runs myFunction passing it "myData"
err := s.Make("jobName", "* * * * * * *", myFunction, "myData")
if err != nil {
	log.Fatalln("Make error:", err)
}

// The follow is normally not needed unless you want the job to run right away.
// Updating next run time so don't have to wait till the next on the second for the job to run.
err = s.UpdateNextRun("jobName", time.Now())
if err != nil {
	log.Fatalln("UpdateNextRun error:", err)
}

// Starts the job schedule. Job will run at it's next run time.
s.Start("jobName")

// For testing, wait until the job has run before stopping all the jobs
<-chanStart

// Stop all the jobs and waits for then to all stop. In the below case it waits for at least a second.
// Note this does not kill any running jobs, only stops them from running again.
s.StopAllWait(time.Second)

Output:

myData

Index

• Variables
• type Scheduler
  • func NewScheduler() *Scheduler
  • func (s *Scheduler) Delete(name string) error
  • func (s *Scheduler) GetData(name string) (interface{}, error)
  • func (s *Scheduler) GetState(name string) (State, error)
  • func (s *Scheduler) Jobs() []string
  • func (s *Scheduler) Make(name string, cron string, function func(interface{}), data interface{}) error
  • func (s *Scheduler) Start(name string) error
  • func (s *Scheduler) Stop(name string) error
  • func (s *Scheduler) StopAll()
  • func (s *Scheduler) StopAllWait(timeout time.Duration)
  • func (s *Scheduler) UpdateCron(name string, cron string) error
  • func (s *Scheduler) UpdateFunction(name string, function func(interface{}), data interface{}) error
  • func (s *Scheduler) UpdateNextRun(name string, nextRun time.Time) error
• type State

Examples

• Package (Basic)

Variables

var (
	// ErrJobNotFound is returned when job has not been found. Make sure to make a job first.
	ErrJobNotFound = errors.New("job not found")
	// ErrJobAlreadyExists is returned when a job name already exists. Make sure to delete the job with the same name first.
	ErrJobAlreadyExists = errors.New("job already exists")
	// ErrJobMustBeStopped is returned when a job is not stopped first.
	ErrJobMustBeStopped = errors.New("job must be stopped")
	// ErrJobIsRunning is returned when a job is running
	ErrJobIsRunning = errors.New("job is running")
)

Types

type Scheduler

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

Scheduler is used to create and run jobs. Must use NewScheduler to create a new one.

func NewScheduler

func NewScheduler() *Scheduler

NewScheduler creates a new Scheduler

func (*Scheduler) Delete

func (s *Scheduler) Delete(name string) error

Delete stops the job and deletes the job. If the job is not running, the job is deleted. If the job is running, the job will finish running then be deleted.

func (*Scheduler) GetData

func (s *Scheduler) GetData(name string) (interface{}, error)

GetData returns job data

func (*Scheduler) GetState

func (s *Scheduler) GetState(name string) (State, error)

GetState returns job state

func (*Scheduler) Jobs

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

Jobs returns all job names

func (*Scheduler) Make

func (s *Scheduler) Make(name string, cron string, function func(interface{}), data interface{}) error

Make creates a new job. Will error if job with same name is already created.

func (*Scheduler) Start

func (s *Scheduler) Start(name string) error

Start starts the job run schedule. Job will run at next run time. Job must be created and stopped to start the job run schedule.

func (*Scheduler) Stop

func (s *Scheduler) Stop(name string) error

Stop stops the job run schedule. If the job is not running, it will not run again until job is started. If the job is running, the job will finish running then will not run again until the job is started. Will not error if job is stopped more than once.

func (*Scheduler) StopAll

func (s *Scheduler) StopAll()

StopAll stops all job from running again. Does not kill any running jobs.

func (*Scheduler) StopAllWait

func (s *Scheduler) StopAllWait(timeout time.Duration)

StopAllWait stops all job from running again and waits till they have all stopped or the timeout duration has passed. Does not kill any running jobs.

func (*Scheduler) UpdateCron

func (s *Scheduler) UpdateCron(name string, cron string) error

UpdateCron updates the job's cron shedule

func (*Scheduler) UpdateFunction

func (s *Scheduler) UpdateFunction(name string, function func(interface{}), data interface{}) error

UpdateFunction updates the job's function and data

func (*Scheduler) UpdateNextRun

func (s *Scheduler) UpdateNextRun(name string, nextRun time.Time) error

UpdateNextRun updates the job's next run time. This is best used when the job is stopped, then it just updates the next run time. If the job is running or the next run cannot be stopped, this will return error ErrJobIsRunning so the job does not possibility run twice

type State

type State int

State what state the job is in

const (
	// StateScheduled when job pending schedule to run
	StateScheduled State = 1 << iota
	// StateRunning when job is running
	StateRunning
	// StateStopping when job is scheduled to stop after run
	StateStopping
	// StateStopped when job is stopped
	StateStopped
	// StateDeleting when job is scheduled to be deleted after run
	StateDeleting
)