adhocore/gronx

gronx is Golang cron expression parser ported from adhocore/cron-expr with task runner and daemon that supports crontab like task list file. Use it programatically in Golang or as standalone binary instead of crond. If that's not enough, you can use gronx to find the next (NextTick()) or previous (PrevTick()) run time of an expression from any arbitrary point of time.

• Zero dependency.
• Very fast because it bails early in case a segment doesn't match.
• Built in crontab like daemon.
• Supports time granularity of Seconds.

Find gronx in pkg.go.dev.

Installation

As a Go library

go get -u github.com/adhocore/gronx

Using Bash install script

For installing the tasker command-line tool, you can use the bash installation script:

curl -sS https://raw.githubusercontent.com/adhocore/gronx/refs/heads/main/install.sh | sh

For non-interactive installation (useful in CI/CD environments):

curl -sS https://raw.githubusercontent.com/adhocore/gronx/refs/heads/main/install.sh | sh -s -- --yes

The script supports several options including custom installation directory, version selection, and platform/architecture overrides. Use --help to see all available options:

curl -sS https://raw.githubusercontent.com/adhocore/gronx/refs/heads/main/install.sh | sh -s -- --help

Usage

import (
	"time"

	"github.com/adhocore/gronx"
)

gron := gronx.New()
expr := "* * * * *"

// check if expr is even valid, returns bool
gron.IsValid(expr) // true

// check if expr is due for current time, returns bool and error
gron.IsDue(expr) // true|false, nil

// check if expr is due for given time
gron.IsDue(expr, time.Date(2021, time.April, 1, 1, 1, 0, 0, time.UTC)) // true|false, nil

Validity can be checked without instantiation:

import "github.com/adhocore/gronx"

gronx.IsValid("* * * * *") // true

Batch Due Check

If you have multiple cron expressions to check due on same reference time use BatchDue():

gron := gronx.New()
exprs := []string{"* * * * *", "0 */5 * * * *"}

// gives []gronx.Expr{} array, each item has Due flag and Err enountered.
dues := gron.BatchDue(exprs)

for _, expr := range dues {
    if expr.Err != nil {
        // Handle err
    } else if expr.Due {
        // Handle due
    }
}

// Or with given time
ref := time.Now()
gron.BatchDue(exprs, ref)

Next Tick

To find out when is the cron due next (in near future):

allowCurrent = true // includes current time as well
nextTime, err := gronx.NextTick(expr, allowCurrent) // gives time.Time, error

// OR, next tick after certain reference time
refTime = time.Date(2022, time.November, 1, 1, 1, 0, 0, time.UTC)
allowCurrent = false // excludes the ref time
nextTime, err := gronx.NextTickAfter(expr, refTime, allowCurrent) // gives time.Time, error

Prev Tick

To find out when was the cron due previously (in near past):

allowCurrent = true // includes current time as well
prevTime, err := gronx.PrevTick(expr, allowCurrent) // gives time.Time, error

// OR, prev tick before certain reference time
refTime = time.Date(2022, time.November, 1, 1, 1, 0, 0, time.UTC)
allowCurrent = false // excludes the ref time
nextTime, err := gronx.PrevTickBefore(expr, refTime, allowCurrent) // gives time.Time, error

The working of PrevTick*() and NextTick*() are mostly the same except the direction. They differ in lookback or lookahead.

Standalone Daemon

In a more practical level, you would use this tool to manage and invoke jobs in app itself and not mess around with crontab for each and every new tasks/jobs.

In crontab just put one entry with * * * * * which points to your Go entry point that uses this tool. Then in that entry point you would invoke different tasks if the corresponding Cron expr is due. Simple map structure would work for this.

Check the section below for more sophisticated way of managing tasks automatically using gronx daemon called tasker.

Go Tasker

Tasker is a task manager that can be programatically used in Golang applications. It runs as a daemon and invokes tasks scheduled with cron expression:

package main

import (
	"context"
	"time"

	"github.com/adhocore/gronx/pkg/tasker"
)

func main() {
	taskr := tasker.New(tasker.Option{
		Verbose: true,
		// optional: defaults to local
		Tz:      "Asia/Bangkok",
		// optional: defaults to stderr log stream
		Out:     "/full/path/to/output-file",
	})

	// add task to run every minute
	taskr.Task("* * * * *", func(ctx context.Context) (int, error) {
		// do something ...

		// then return exit code and error, for eg: if everything okay
		return 0, nil
	}).Task("*/5 * * * *", func(ctx context.Context) (int, error) { // every 5 minutes
		// you can also log the output to Out file as configured in Option above:
		taskr.Log.Printf("done something in %d s", 2)

		return 0, nil
	})

	// run task without overlap, set concurrent flag to false:
	concurrent := false
	taskr.Task("* * * * * *", , tasker.Taskify("sleep 2", tasker.Option{}), concurrent)

	// every 10 minute with arbitrary command
	taskr.Task("@10minutes", taskr.Taskify("command --option val -- args", tasker.Option{Shell: "/bin/sh -c"}))

	// ... add more tasks

	// optionally if you want tasker to stop after 2 hour, pass the duration with Until():
	taskr.Until(2 * time.Hour)

	// finally run the tasker, it ticks sharply on every minute and runs all the tasks due on that time!
	// it exits gracefully when ctrl+c is received making sure pending tasks are completed.
	taskr.Run()
}

Concurrency

By default the tasks can run concurrently i.e if previous run is still not finished but it is now due again, it will run again. If you want to run only one instance of a task at a time, set concurrent flag to false:

taskr := tasker.New(tasker.Option{})

concurrent := false
expr, task := "* * * * * *", tasker.Taskify("php -r 'sleep(2);'")
taskr.Task(expr, task, concurrent)

Task Daemon

It can also be used as standalone task daemon instead of programmatic usage for Golang application.

First, just install tasker command:

go install github.com/adhocore/gronx/cmd/tasker@latest

Or, you can install using mise:

mise use github:adhocore/gronx@latest

Or you can also download latest prebuilt binary from release for platform of your choice.

Then prepare a taskfile (example) in crontab format (or can even point to existing crontab).

user is not supported: it is just cron expr followed by the command.

Finally run the task daemon like so

tasker -file path/to/taskfile

You can pass more options to control the behavior of task daemon, see below.

Tasker command options:

-file string <required>
    The task file in crontab format
-out string
    The fullpath to file where output from tasks are sent to (defaults to stderr)
-shell string
    The shell to use for running tasks (default "/usr/bin/bash")
-tz string
    The timezone to use for tasks (default "Local")
-until int
    The timeout for task daemon in minutes
-verbose
    The verbose mode outputs as much as possible

Examples:

tasker -verbose -file path/to/taskfile -until 120 # run until next 120min (i.e 2hour) with all feedbacks echoed back
tasker -verbose -file path/to/taskfile -out path/to/output # with all feedbacks echoed to the output file
tasker -tz America/New_York -file path/to/taskfile -shell zsh # run all tasks using zsh shell based on NY timezone

File extension of taskfile for