hardloop

README

hardloop

Hardloop is a cron time-based function runner.

Set start and end times as cron specs, and give function to run between them.

go get github.com/worldline-go/hardloop

Usage

Check the https://crontab.guru/ to explain about cron specs.

Hardloop different works than crontab.guru in weekdays and day of month selection. We use and operation but that site use or operation when used both of them.

You can give as much as you want start, stop times.

If stop time is not given, it will run forever.

If just stop time given, it will restart in the stop times.

Use Timezone to set the timezone: CRON_TZ=Europe/Istanbul 0 7 * * 1,2,3,4,5

Default timezone is system timezone.

Some times doens't exist in some timezones. For example, CRON_TZ=Europe/Amsterdam 30 2 26 3 * doesn't exist due to in that time 02:00 -> 03:00 DST 1 hour adding. It will be make some problems so don't use non-exist times.

// Set start cron specs.
startSpecs := []string{
    // start at 7:00 in Monday, Tuesday, Wednesday, Thursday, Friday
    "0 7 * * 1,2,3,4,5",
    // start at 9:00 in Saturday
    "0 9 * * 6",
}
// Set stop cron specs.
stopSpecs := []string{
    // stop at 17:00 in Monday, Tuesday, Wednesday, Thursday, Friday
    "0 17 * * 1,2,3,4,5",
    // stop at 13:00 in Saturday
    "0 13 * * 6",
}

// Create a new schedule.
myFunctionLoop, err := hardloop.NewLoop(startSpecs, stopSpecs, MyFunction)
if err != nil {
    // wrong cron specs
    log.Fatal(err)
}

// run forever in goroutine (or until the function returns ErrLoopExited)
myFunctionLoop.RunWait(context.Background(), wg)

Set Logger

Implement Logger interface and set to the loop.

myFunctionLoop.SetLogger(myLog{})

Development

Test code

make test
# make coverage html-wsl

Documentation

Overview

Example (Parser)

schedule := "0 7 * * *"

p := hardloop.Parser{ParseFn: cron.ParseStandard}

s, err := p.Parse2(schedule)
if err != nil {
	log.Fatal(err)
}

now := time.Date(2023, 1, 1, 0, 0, 0, 0, time.UTC)

fmt.Println("Next 5 times:")
tmpNow := now
for i := 0; i < 5; i++ {
	tmpNow = s.Next(tmpNow)
	fmt.Println(tmpNow)
}

tmpNow = now
fmt.Println("Prev 5 times:")
for i := 0; i < 5; i++ {
	tmpNow = s.Prev(tmpNow)
	fmt.Println(tmpNow)
}

Output:

Next 5 times:
2023-01-01 07:00:00 +0000 UTC
2023-01-02 07:00:00 +0000 UTC
2023-01-03 07:00:00 +0000 UTC
2023-01-04 07:00:00 +0000 UTC
2023-01-05 07:00:00 +0000 UTC
Prev 5 times:
2022-12-31 07:00:00 +0000 UTC
2022-12-30 07:00:00 +0000 UTC
2022-12-29 07:00:00 +0000 UTC
2022-12-28 07:00:00 +0000 UTC
2022-12-27 07:00:00 +0000 UTC

Index

• Variables
• func FindNext(schedules []Schedule, now time.Time) time.Time
• func FindPrev(schedules []Schedule, now time.Time) time.Time
• type Logger
• type Loop
  • func NewLoop(startSpec, endSpec []string, ...) (*Loop, error)
  • func (l *Loop) ChangeStartSchedules(startSpecs []string) error
  • func (l *Loop) ChangeStopSchedules(stopSpecs []string) error
  • func (l *Loop) IsFunctionRunning() bool
  • func (l *Loop) IsLoopRunning() bool
  • func (l *Loop) Run(ctx context.Context, wg *sync.WaitGroup)
  • func (l *Loop) RunWait(ctx context.Context)
  • func (l *Loop) SetFunction(fn func(ctx context.Context, wg *sync.WaitGroup) error, ...)
  • func (l *Loop) SetLogger(log Logger)
• type Parser
  • func (p Parser) Parse(spec string) (cron.Schedule, error)
  • func (p Parser) Parse2(spec string) (Schedule, error)
• type Schedule
• type SpecSchedule
  • func ParseStandard(spec string) (*SpecSchedule, error)
  • func (s *SpecSchedule) Next(t time.Time) time.Time
  • func (s *SpecSchedule) Prev(t time.Time) time.Time

Examples

• Package (Parser)

Variables

var (
	// GapDurationStart to start the function should be at least 1 second bigger than gap duration.
	GapDurationStart time.Duration = 1 * time.Second //nolint:revive // more readable
	// GapDurationStop to stop the function.
	GapDurationStop time.Duration = 0 //nolint:revive // more readable

	// ErrCloseLoop is returned when the loop should be closed.
	ErrCloseLoop = errors.New("close loop")
)

var YearLimit = 5

YearLimit is the maximum number of years to search for a matching time.

Functions

func FindNext

func FindNext(schedules []Schedule, now time.Time) time.Time

func FindPrev

func FindPrev(schedules []Schedule, now time.Time) time.Time

Types

type Logger

type Logger interface {
	Error(msg string, keysAndValues ...interface{})
	Info(msg string, keysAndValues ...interface{})
	Debug(msg string, keysAndValues ...interface{})
	Warn(msg string, keysAndValues ...interface{})
}

type Loop

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

func NewLoop

func NewLoop(startSpec, endSpec []string, fn func(ctx context.Context, wg *sync.WaitGroup) error) (*Loop, error)

NewLoop returns a new Loop with the given start and end cron specs and function.

• Standard crontab specs, e.g. "* * * * ?"
• Descriptors, e.g. "@midnight", "@every 1h30m"

func (*Loop) ChangeStartSchedules

func (l *Loop) ChangeStartSchedules(startSpecs []string) error

ChangeStartSchedules sets the start cron specs. Not effects immediately!

func (*Loop) ChangeStopSchedules

func (l *Loop) ChangeStopSchedules(stopSpecs []string) error

ChangeStopSchedule sets the end cron specs. Not effects immediately!

func (*Loop) IsFunctionRunning

func (l *Loop) IsFunctionRunning() bool

IsFunctionRunning returns true if the function is running.

func (*Loop) IsLoopRunning

func (l *Loop) IsLoopRunning() bool

IsLoopRunning returns true if the loop is running.

func (*Loop) Run

func (l *Loop) Run(ctx context.Context, wg *sync.WaitGroup)

Run starts the loop.

func (*Loop) RunWait

func (l *Loop) RunWait(ctx context.Context)

RunWait starts the loop and wait to exit with ErrLoopExited.

func (*Loop) SetFunction

func (l *Loop) SetFunction(fn func(ctx context.Context, wg *sync.WaitGroup) error, stopPreviousFunction bool)

SetFunction sets the function to be called when the loop is started. Function should be blocking.

func (*Loop) SetLogger

func (l *Loop) SetLogger(log Logger)

type Parser

type Parser struct {
	ParseFn func(standardSpec string) (cron.Schedule, error)
}

Parser is default parser for cron to replacing the functions.

func (Parser) Parse

func (p Parser) Parse(spec string) (cron.Schedule, error)

Parse returns a new cron schedule for the given spec. It use hardloop.Schedule interface instead of cron.Schedule.

func (Parser) Parse2

func (p Parser) Parse2(spec string) (Schedule, error)

Parse2 is a helper function for parsing the spec and returning the SpecSchedule.

type Schedule

type Schedule interface {
	// Next returns the next time this schedule is activated, greater than the given time.
	Next(time.Time) time.Time
	// Prev returns the previous time this schedule is activated, less than the given time.
	Prev(time.Time) time.Time
}

type SpecSchedule

type SpecSchedule struct {
	*cron.SpecSchedule
}

func ParseStandard

func ParseStandard(spec string) (*SpecSchedule, error)

Parse returns a new cron schedule for the given spec.

It accepts

• Standard crontab specs, e.g. "* * * * ?"
• Descriptors, e.g. "@midnight", "@every 1h30m"

func (*SpecSchedule) Next

func (s *SpecSchedule) Next(t time.Time) time.Time

Next returns the next time this schedule is activated, greater than the given time. If no time can be found to satisfy the schedule, return the zero time.

func (*SpecSchedule) Prev

func (s *SpecSchedule) Prev(t time.Time) time.Time

Prev returns the prev time this schedule is activated, less than the given time. If no time can be found to satisfy the schedule, return the zero time.