Cron | Ergo Framework documentation (original) (raw)

  1. Basics

Cron

schedule tasks on a repetitive basis, such as daily, weekly, or monthly

Introduced in Ergo Framework 3.1.0

Cron functionality is provided to enable periodic job execution in a node. Its implementation replicates the functionality of the Cron service in Unix systems and supports the Crontab specification format.

To set up jobs at the node startup, use the gen.NodeOptions.Cron parameters. Each job is described using the gen.CronJob:

type CronJob struct {
    // Name job name
    Name gen.Atom
    // Spec time spec in "crontab" format
    Spec string
    // Location defines timezone
    Location *time.Location
    // Action
    Action gen.CronAction
    // Fallback
    Fallback gen.ProcessFallback
}

Parameters:

The Action field has the interface type gen.CronAction. You can use the following ready-to-use implementations:

When using CreateCronActionSpawn or CreateCronActionRemoteSpawn, the following environment variables will be added to the spawned processes:

In the example below, every day at 21:07 (Shanghai time), a gen.MessageCron message will be sent to the local process registered as myweb1. If the message cannot be delivered, a gen.MessageCronFallback message will be sent to the local process named myweb2:

You can also manage jobs using the gen.Cron interface. It provides the following methods for this:

Access to the gen.Cron interface can be obtained using the Cron method of the gen.Node interface.

You can also create your own Action. To do this, simply implement the gen.CronAction interface:

It is worth noting that the action_time argument is passed in the time zone of the job, i.e., the one specified in the gen.CronJob.Location field when the job was created.

The Info method of the interface is used when calling gen.Cron.Info() to retrieve summary information about Cron and its jobs.

You can also use the following macro definitions:

1 19 * * 1#1,7L run at 19:01 every month on the first Monday and last Sunday

15 15 10-15/3 * * run at 15:15 every month on the 10th and 13th

To view the schedule of your job, use the JobSchedule method of the gen.Cron interface. To view the schedule of all jobs, use the Schedule method of this interface.

DST (daylight saving time) and Time-adjustment support

This implementation takes time changes into account – if a time adjustment occurs at the time of the job's scheduled execution and the new time does not match the job's schedule, the job will not be executed.

For example, if a job has the specification 0 2 * * * (to run every day at 2:00), it will be skipped on March 30, 2025, because at 2:00 that day, the time will be moved forward by one hour (due to DST). After the end of DST on October 26, 2025, at 3:00, the time will be shifted back by one hour, but the job in the example will be executed only once.

Last updated 3 months ago

func main() {
    var options gen.NodeOptions
    // ...
    locationAsiaShanghai, _ := time.LoadLocation("Asia/Shanghai")
    options.Cron.Jobs = []gen.CronJob{
        gen.CronJob{Name: "job1",
            Spec:     "7 21 * * *",
            Action:   gen.CreateCronActionMessage(gen.Atom("myweb1"), 
                            gen.MessagePriorityNormal),
            Location: locationAsiaShanghai,
            Fallback: gen.ProcessFallback{Enable: true, Name: "myweb2"},
        },
    }
    node, err := ergo.StartNode("cron@localhost", options)
    if err != nil {
        panic(err)
    }
    // ...
}
type Cron interface {
    // AddJob adds a new job
    AddJob(job gen.CronJob) error
    // RemoveJob removes new job
    RemoveJob(name gen.Atom) error
    // EnableJob allows you to enable previously disabled job
    EnableJob(name gen.Atom) error
    // DisableJob disables job
    DisableJob(name gen.Atom) error

    // Info returns information about the jobs, spool of jobs for the next run
    Info() gen.CronInfo
    // JobInfo returns information for the given job
    JobInfo(name gen.Atom) (gen.CronJobInfo, error)

    // Schedule returns a list of jobs planned to be run for the given period
    Schedule(since time.Time, duration time.Duration) []gen.CronSchedule
    // JobSchedule returns a list of scheduled run times for the given job and period.
    JobSchedule(job Atom, since time.Time, duration time.Duration) ([]time.Time, error)
}

type CronAction interface {
    Do(job gen.Atom, node gen.Node, action_time time.Time) error
    Info() string
}
* * * * *
| | | | |                                                 allowed format
| | | | day-of-week (1–7) (Monday to Sunday)      *   d   d,d   d-d    dL    d#d
| | | month (1–12)                                *   d   d,d   d-d   */d
| | day-of-month (1–31)                           *   d   d,d   d-d   */d   d-d/d   L
| hour (0–23)                                     *   d   d,d   d-d   */d   d-d/d
minute (0–59)                                     *   d   d,d   d-d   */d   d-d/d