Configuration

This page describes the scheduler configuration and the runtime options passed to individual tasks.

Scheduler configuration

The core.Config type currently contains one field:

type Config struct {
    Location *time.Location
}

Location controls the timezone used when the scheduler calculates the next occurrence of a cron expression or descriptor. When it is nil, core.New uses time.Local.

loc, err := time.LoadLocation("Asia/Taipei")
if err != nil {
    return err
}

scheduler, err := core.New(core.Config{
    Location: loc,
})

A nil location is equivalent to:

scheduler, err := core.New(core.Config{Location: time.Local})

Task options

Task-level options are supplied as variadic arguments to Add:

func (c *cron) Add(spec string, action interface{}, arg ...interface{}) (int64, error)

Arguments can be combined in any order. A task using []core.Wait or the deprecated []int64 form must use an action with signature func() error.

scheduler.Add("@every 1m", func() error {
    return runReport()
}, "daily report", 30*time.Second, func() {
    log.Println("report timeout")
})

Timeout behavior

The duration argument is an execution timeout, not a delay before the task starts. When the action does not finish before the timeout:

1. the task is marked as failed;
2. the onDelay callback runs when one was supplied; and
3. a timeout warning is written to the configured logger.

The action runs in its own goroutine. The scheduler stops waiting after the deadline, but the action goroutine itself is not forcibly canceled because the action API does not receive a context.

scheduler.Add("@every 5m", func() error {
    return slowOperation()
}, 10*time.Second, func() {
    log.Println("slowOperation exceeded 10 seconds")
})

Returned errors and recovered panics also result in a failed task state. A func() action is wrapped as a no-error action and is treated as successful when it returns normally.

Dependency configuration

Use core.Wait to configure a prerequisite:

type Wait struct {
    ID    int64
    Delay time.Duration
    State WaitState
}

• ID identifies the prerequisite task.
• Delay is the maximum time spent waiting for dependencies. A zero value uses a one-minute worker default.
• State is core.Stop or core.Skip.

core.Stop fails the dependent task when that prerequisite fails. core.Skip ignores the failed prerequisite and allows dependency evaluation to continue.

prepareID, _ := scheduler.Add("@every 1m", func() error {
    return prepare()
})

scheduler.Add("@every 1m", func() error {
    return consume()
}, []core.Wait{
    {ID: prepareID, Delay: 20 * time.Second, State: core.Stop},
})

Schedule configuration

The scheduler accepts exactly five cron fields:

Each field supports *, a single value, ranges, comma-separated lists, and */n steps. It also accepts the built-in descriptors @yearly, @annually, @monthly, @weekly, @daily, @midnight, and @hourly. @every <duration> requires a minimum interval of 30 seconds.

Logging and worker runtime

core.New attempts to create a syslog writer using the goCron identifier. If that fails, it uses a text logger writing to stderr. The dependency subsystem starts with two workers and uses runtime.NumCPU() workers when the host reports more than two CPUs.

There are no environment variables or external configuration files required by the current core package. Runtime configuration is provided through core.Config and Add arguments.

See Core Concepts for behavior details and API Reference for complete signatures.