Documentation
Home GitHub

API Reference

This page documents the public configuration types and the exported lifecycle, task, dependency, and scheduling methods provided by the core package.

Package

import "github.com/pardnchiu/go-scheduler/core"

The constructor returns a scheduler value whose concrete type is internal to the package. Its exported methods remain available to callers through the returned value.

Config

type Config struct {
    Location *time.Location
}
Field Type Description
Location *time.Location Timezone used to calculate scheduled occurrences. When nil, time.Local is used.

New

func New(c Config) (*cron, error)

Creates a scheduler and initializes its task heap, parser, dependency manager, channels, and logger. The logger uses syslog when available and falls back to an informational stderr logger when syslog cannot be opened.

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

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

Start and Stop

func (c *cron) Start()
func (c *cron) Stop() context.Context

scheduler.Start()
// ... serve the application ...
shutdown := scheduler.Stop()
<-shutdown.Done()

Add

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

Parses spec, registers a task, and returns its monotonically increasing int64 ID. The schedule may be added before or after Start.

Parameter Type Description
spec string A five-field cron expression, a supported descriptor, or @every <duration>.
action func() or func() error Task body. Use func() error for dependencies or explicit failure reporting.
arg variadic Optional description, timeout, timeout callback, or dependency list.

Supported optional arguments:

Argument type Meaning
string Stored task description used in logging.
time.Duration Maximum execution time for the action.
func() Called when the configured execution timeout expires (onDelay).
[]core.Wait Prerequisite tasks and their failure policies.
[]int64 Deprecated prerequisite ID list; converted to Wait values with the default Stop policy.

A task with dependencies must use func() error; otherwise Add returns an error. Add also returns an error when the schedule expression is invalid or an unsupported action type is supplied.

id, err := scheduler.Add("*/5 * * * *", func() error {
    return poll()
}, "poll", 10*time.Second, func() {
    log.Println("poll timed out")
})

Remove, RemoveAll, and List

func (c *cron) Remove(id int64)
func (c *cron) RemoveAll()
func (c *cron) List() []*task
Method Description
Remove Disables and removes the enabled task with the specified ID.
RemoveAll Removes all scheduled entries from the heap.
List Returns pointers to currently enabled tasks held by the scheduler heap. Each task exposes its exported ID field.

When the scheduler is running, add and remove operations are delivered to the event loop through channels. Before Start, they update the heap directly.

Wait and WaitState

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

type WaitState int

const (
    Stop WaitState = iota
    Skip
)
Field Description
ID ID of the prerequisite task.
Delay Maximum time to wait for dependency completion. A zero value uses the dependency worker's one-minute default.
State Failure policy: Stop fails the dependent task, while Skip ignores that failed prerequisite. 
parentID, _ := scheduler.Add("@every 1m", func() error {
    return prepare()
})

_, err := scheduler.Add("@every 1m", func() error {
    return process()
}, []core.Wait{{
    ID: parentID,
    Delay: 10 * time.Second,
    State: core.Stop,
}})

Task states

const (
    TaskPending int = iota
    TaskRunning
    TaskCompleted
    TaskFailed
)

These constants describe the internal task lifecycle. A recurring task is scheduled again after an occurrence is dispatched; an action error, panic, or timeout marks that execution as failed.

Schedule syntax

Format Example Description
Five-field cron */5 9-17 * * 1-5 minute, hour, day of month, month, day of week
Descriptor @hourly, @daily, @weekly, @monthly, @yearly Built-in schedule shortcuts; @annually and @midnight are also accepted.
Fixed interval @every 30s Repeats after a parsed duration; the minimum interval is 30 seconds.
Field syntax *, n, n-m, a,b,c, */n wildcard, single value, range, list, and step

Cron fields use these ranges: minute 0-59, hour 0-23, day of month 1-31, month 1-12, and day of week 0-6 where Sunday is 0.

中文