scheduler

README

* Go Task Scheduler
[[https://travis-ci.org/rakanalh/scheduler][https://img.shields.io/travis/rakanalh/scheduler/master.svg?style=flat-square]] [[http://codecov.io/github/rakanalh/scheduler?branch=master][http://codecov.io/github/rakanalh/scheduler/coverage.svg?branch=master]] [[https://godoc.org/github.com/rakanalh/scheduler][https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square]] [[https://github.com/rakanalh/scheduler/blob/master/LICENSE.txt][https://img.shields.io/badge/License-MIT-orange.svg?style=flat-square]]



Go Task scheduler is a small library that you can use within your application that enables you to execute callbacks (goroutines) after a pre-defined
amount of time. GTS also provides task storage which is used to invoke callbacks for tasks which couldn't be executed
during down-time as well as maintaining a history of the callbacks that got executed.

** Features
- Execute tasks based after a specific duration or at a specific point in time
- Job stores for history & recovery, provided stores out of the box:
 - Sqlite3
 - Redis (Coming soon)

* Installation
#+BEGIN_SRC shell
go get github.com/rakanalh/scheduler
#+END_SRC

* How To Use

Instantiate a scheduler as follows:

#+BEGIN_SRC go
s := scheduler.New(storage)
#+END_SRC

GTS currently supports 2 kinds of storages:
1. NoOpStorage: Does nothing
#+BEGIN_SRC go
noOpStorage := storage.NewNoOpStorage()
#+END_SRC
2. MemoryStorage: Does nothing
#+BEGIN_SRC go
memStorage := storage.NewMemoryStorage()
#+END_SRC
2. SqliteStorage: Persists tasks into a SQLite3 database.
#+BEGIN_SRC go
sqliteStorage := storage.NewSqlite3Storage()
#+END_SRC

Example:
#+BEGIN_SRC go
storage := storage.NewSqlite3Storage(
	storage.Sqlite3Config{
		DbName: "db.store",
	},
)
if err := storage.Connect(); err != nil {
	log.Fatal("Could not connect to db", err)
}

if err := storage.Initialize(); err != nil {
	log.Fatal("Could not intialize database", err)
}
#+END_SRC

and then pass it to the scheduler.

Scheduling tasks can be done in 3 ways:

** Execute a task after 5 seconds.
#+BEGIN_SRC go
func MyFunc(arg1 string, arg2 string)
taskID := s.RunAfter(5*time.Second, MyFunc, "Hello", "World")
#+END_SRC

** Execute a task at a specific time.
#+BEGIN_SRC go
func MyFunc(arg1 string, arg2 string)
taskID := s.RunAt(time.Now().Add(24 * time.Hour), MyFunc, "Hello", "World")
#+END_SRC

** Execute a task every 1 minute.
#+BEGIN_SRC go
func MyFunc(arg1 string, arg2 string)
taskID := s.RunEvery(1 * time.Minute, MyFunc, "Hello", "World")
#+END_SRC

* Examples

The [[https://github.com/rakanalh/scheduler/tree/master/_example/][Examples]] folder contains a bunch of code samples you can look into.

* Custom Storage

GTS supports the ability to provide a custom storage, the newly created storage has to implement the TaskStore interface

#+BEGIN_SRC go
type TaskStore interface {
	Store(task *TaskAttributes) error
        Remove(task *TaskAttributes) error
	Fetch() ([]TaskAttributes, error)
}
#+END_SRC

TaskAttributes looks as follows:
#+BEGIN_SRC go
type TaskAttributes struct {
	Hash        string
	Name        string
	LastRun     string
	NextRun     string
	Duration    string
	IsRecurring string
	Params      string
}
#+END_SRC

* TODOs
- [ ] Design a cron-like task schedule for RunEvery method

* Credit
This package is heavily inspired by [[https://github.com/agronholm/apscheduler/][APScheduler]] for Python & [[https://github.com/jasonlvhit/gocron][GoCron]]

* License

MIT

Documentation

Overview

Package scheduler is a small library that you can use within your application that enables you to execute callbacks (goroutines) after a pre-defined amount of time. GTS also provides task storage which is used to invoke callbacks for tasks which couldn’t be executed during down-time as well as maintaining a history of the callbacks that got executed.

Index

• type Scheduler
  • func New(store storage.TaskStore) Scheduler
  • func (scheduler *Scheduler) Cancel(taskID task.ID) error
  • func (scheduler *Scheduler) Clear()
  • func (scheduler *Scheduler) RunAfter(duration time.Duration, function task.Function, params ...task.Param) (task.ID, error)
  • func (scheduler *Scheduler) RunAt(time time.Time, function task.Function, params ...task.Param) (task.ID, error)
  • func (scheduler *Scheduler) RunEvery(duration time.Duration, function task.Function, params ...task.Param) (task.ID, error)
  • func (scheduler *Scheduler) Start() error
  • func (scheduler *Scheduler) Stop()
  • func (scheduler *Scheduler) Wait()

Types

type Scheduler

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

Scheduler is used to schedule tasks. It holds information about those tasks including metadata such as argument types and schedule times

func New

func New(store storage.TaskStore) Scheduler

New will return a new instance of the Scheduler struct.

func (*Scheduler) Cancel

func (scheduler *Scheduler) Cancel(taskID task.ID) error

Cancel is used to cancel the planned execution of a specific task using it's ID. The ID is returned when the task was scheduled using RunAt, RunAfter or RunEvery

func (*Scheduler) Clear

func (scheduler *Scheduler) Clear()

Clear will cancel the execution and clear all registered tasks.

func (*Scheduler) RunAfter

func (scheduler *Scheduler) RunAfter(duration time.Duration, function task.Function, params ...task.Param) (task.ID, error)

RunAfter executes function once after a specific duration has elapsed.

func (*Scheduler) RunAt

func (scheduler *Scheduler) RunAt(time time.Time, function task.Function, params ...task.Param) (task.ID, error)

RunAt will schedule function to be executed once at the given time.

func (*Scheduler) RunEvery

func (scheduler *Scheduler) RunEvery(duration time.Duration, function task.Function, params ...task.Param) (task.ID, error)

RunEvery will schedule function to be executed every time the duration has elapsed.

func (*Scheduler) Start

func (scheduler *Scheduler) Start() error

Start will run the scheduler's timer and will trigger the execution of tasks depending on their schedule.

func (*Scheduler) Stop

func (scheduler *Scheduler) Stop()

Stop will put the scheduler to halt

func (*Scheduler) Wait

func (scheduler *Scheduler) Wait()

Wait is a convenience function for blocking until the scheduler is stopped.