sched

README

sched

A job scheduler for Go with the ability to fast-forward time.

Example: https://play.golang.org/p/BQDi8MKraIe

Documentation

Overview

Package sched provides a job scheduler implementation that's able to fast-forward time. All methods of both the package and a Scheduler instance are thread-safe and can safely be used from within multiple goroutines.

Index

• Constants
• Variables
• func Cancel(id Job) bool
• func Len() int
• func Offset() time.Duration
• func Scan(after Job, fn func(job Job, jobFn func()) bool) (ok bool)
• type Duration
  • func AdvanceTime(by Duration) (newOffset Duration)
  • func AdvanceToNext() (newOffset, advancedBy Duration)
• type Job
  • func Schedule(in Duration, fn func()) (Job, error)
  • func (id Job) Due() Time
  • func (id Job) String() string
• type QueueReadWriter
• type QueueReader
• type QueueWriter
• type Scheduler
  • func New(timeOffset Duration) *Scheduler
  • func NewWith(timeOffset Duration, t TimeProvider, q QueueReadWriter) *Scheduler
  • func NewWithProvider(timeOffset Duration, p TimeProvider) *Scheduler
  • func (s *Scheduler) AdvanceTime(by Duration) (newOffset Duration)
  • func (s *Scheduler) AdvanceToNext() (newOffset, advancedBy Duration)
  • func (s *Scheduler) Cancel(id Job) bool
  • func (s *Scheduler) Len() int
  • func (s *Scheduler) Now() Time
  • func (s *Scheduler) Offset() time.Duration
  • func (s *Scheduler) Scan(after Job, fn func(job Job, jobFn func()) bool) (ok bool)
  • func (s *Scheduler) Schedule(in Duration, fn func()) (Job, error)
• type Time
  • func Now() Time
• type TimeProvider
• type Timer

Constants

const (
	Nanosecond  = time.Nanosecond
	Microsecond = time.Microsecond
	Millisecond = time.Millisecond
	Second      = time.Second
	Minute      = time.Minute
	Hour        = time.Hour
)

Variables

var DefaultScheduler = New(0)

DefaultScheduler is the default Scheduler used by Schedule, Cancel, Now, AdvanceTime, AdvanceToNext, Len, Offset and Scan.

Functions

func Cancel

func Cancel(id Job) bool

Cancel cancels a pending job and returns true. Returns false if no job was canceled.

func Len

func Len() int

Len returns the length of the queue (number of pending jobs).

func Offset

func Offset() time.Duration

Offset returns the scheduler's time offset.

func Scan

func Scan(after Job, fn func(job Job, jobFn func()) bool) (ok bool)

Scan scans all jobs after the given job executing fn for each until either the end of the queue is reached or fn returns false. Starts from the front of the queue if after is zero. Returns false if after doesn't exist, otherwise returns true.

Types

type Duration

type Duration = time.Duration

func AdvanceTime

func AdvanceTime(by Duration) (newOffset Duration)

AdvanceTime advances the current time by the given duration.

func AdvanceToNext

func AdvanceToNext() (newOffset, advancedBy Duration)

AdvanceToNext advances the current time to the next job executing it immediately. Does nothing if no jobs are pending.

type Job

type Job ksuid.KSUID

Job is a unique job identifier.

func Schedule

func Schedule(in Duration, fn func()) (Job, error)

Schedule schedules fn for execution at the scheduler's time. fn will be executed in its own goroutine. if in < 1 then fn will be executed immediately and the returned JobID will be zero.

func (Job) Due

func (id Job) Due() Time

Due returns the scheduled due time of the job.

func (Job) String

func (id Job) String() string

String returns the stringified identifier.

type QueueReadWriter

type QueueReadWriter interface {
	QueueReader
	QueueWriter
}

type QueueReader

type QueueReader interface {
	Has(ksuid.KSUID) bool
	Len() int
	Scan(
		after ksuid.KSUID,
		fn func(ksuid.KSUID, func()) bool,
	) (afterFound bool)
}

type QueueWriter

type QueueWriter interface {
	Set(ksuid.KSUID, func()) (setAtFront bool)
	Front() (ksuid.KSUID, func())
	Remove(ksuid.KSUID) (ok bool)
}

type Scheduler

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

Scheduler is a job scheduler.

func New

func New(timeOffset Duration) *Scheduler

New creates a new scheduler with the given time offset.

func NewWith

func NewWith(
	timeOffset Duration,
	t TimeProvider,
	q QueueReadWriter,
) *Scheduler

NewWith is similar to New but replaces the default time provider and queue implementation. If t == nil then standard time package is used by default. If q == nil then sched/internal/queue.Queue is used by default.

func NewWithProvider

func NewWithProvider(
	timeOffset Duration,
	p TimeProvider,
) *Scheduler

NewWithProvider is similar to New but replaces the default time provider.

func (*Scheduler) AdvanceTime

func (s *Scheduler) AdvanceTime(by Duration) (newOffset Duration)

AdvanceTime advances the current time by the given duration.

func (*Scheduler) AdvanceToNext

func (s *Scheduler) AdvanceToNext() (newOffset, advancedBy Duration)

AdvanceToNext advances the current time to the next job executing it immediately. Does nothing if no jobs are pending.

func (*Scheduler) Cancel

func (s *Scheduler) Cancel(id Job) bool

Cancel cancels a pending job and returns true. Returns false if no job was canceled.

func (*Scheduler) Len

func (s *Scheduler) Len() int

Len returns the length of the queue (number of pending jobs).

func (*Scheduler) Now

func (s *Scheduler) Now() Time

Now returns the current time of the scheduler considering the offset.

func (*Scheduler) Offset

func (s *Scheduler) Offset() time.Duration

Offset returns the scheduler's time offset.

func (*Scheduler) Scan

func (s *Scheduler) Scan(
	after Job,
	fn func(job Job, jobFn func()) bool,
) (ok bool)

Scan scans all jobs after the given job executing fn for each until either the end of the queue is reached or fn returns false. Starts from the front of the queue if after is zero. Returns false if after doesn't exist, otherwise returns true.

func (*Scheduler) Schedule

func (s *Scheduler) Schedule(in Duration, fn func()) (Job, error)

Schedule schedules fn for execution at the scheduler's time. fn will be executed in its own goroutine. if in < 1 then fn will be executed immediately and the returned JobID will be zero.

type Time

type Time = time.Time

func Now

func Now() Time

Now returns the current time of the scheduler considering the offset.

type TimeProvider

type TimeProvider interface {
	Now() Time
	AfterFunc(Duration, func()) Timer
}

type Timer

type Timer interface {
	Stop() bool
	Reset(Duration) bool
}