Task API

Last updated 2026-10-21

This page lists the core methods for registering, removing, and listing tasks, plus the task state constants.

Add

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

Parameter	Type	Description
`spec`	`string`	5-field cron, descriptor, or `@every <duration>`
`action`	`func()` or `func() error`	Task body
`arg`	`string`, `time.Duration`, `func()`, `[]Wait`, `[]int64`	Description, execution limit, timeout callback, prerequisites

Return	Condition
`id > 0, nil`	Registered
`0, failed to parse: ...`	Invalid field count, range, step, or duration in `spec`, or `@every` below 30 seconds
`0, action need to be func() or func()`	Unsupported `action` type
`0, need return value to get dependence support`	`func()` combined with `[]Wait` or `[]int64`

An empty spec is not rejected with an error: the parser reads spec[0] first, so Add("", ...) panics with index out of range.

Remove and RemoveAll

Remove

func (c *cron) Remove(id int64)

Disables the task with the given ID and removes it from the heap; no-op when the ID does not exist.

RemoveAll

func (c *cron) RemoveAll()

Clears the heap while running; disables every task before Start.

List

func (c *cron) List() []*task

Returns pointers to enabled tasks in the heap; the exported field is ID int64. List holds the scheduler mutex, but after Start the event loop goroutine modifies the heap without that mutex, so calling List while the scheduler is running is reported as a data race by go test -race.

for _, t := range c.List() {
	log.Println(t.ID)
}

Task State Constants

const (
	TaskPending int = iota
	TaskRunning
	TaskCompleted
	TaskFailed
)

See Task Model for state transition rules.