Documentation
¶
Overview ¶
Package schedule runs recurring tasks: functions, app commands and queue jobs, on cron expressions or helpers such as DailyAt.
s.Command("reports:send").DailyAt("08:00").WithoutOverlapping()
s.Job(jobs.PruneSessions{}).Hourly()
s.Func("ping", func(ctx context.Context) error { ... }).EveryFiveMinutes()
Run it in process with Work (vukem schedule:work) or from one cron entry calling RunDue every minute (vukem schedule:run). Schedule holds the Task list, Cron parses five-field expressions, and WithoutOverlapping takes a lock in the Options.Locks cache.
See https://github.com/AlexGalhardo/vukem/blob/main/docs/subsystems.md#scheduler.
Example ¶
package main
import (
"context"
"fmt"
"time"
"github.com/AlexGalhardo/vukem/schedule"
)
func main() {
s := schedule.New(schedule.Options{})
s.Func("ping", func(context.Context) error { return nil }).EveryFiveMinutes()
s.Command("reports:send").DailyAt("08:00").WithoutOverlapping()
for _, t := range s.Tasks() {
fmt.Println(t.Name(), t.Expression())
}
now := time.Date(2026, 1, 5, 8, 0, 0, 0, time.UTC)
for _, t := range s.Due(now) {
fmt.Println("due at 08:00:", t.Name())
}
}
Output: ping */5 * * * * reports:send 0 8 * * * due at 08:00: ping due at 08:00: reports:send
Index ¶
- Variables
- type Cron
- type Options
- type Schedule
- func (s *Schedule) Command(name string, args ...string) *Task
- func (s *Schedule) Due(now time.Time) []*Task
- func (s *Schedule) Func(name string, fn func(ctx context.Context) error) *Task
- func (s *Schedule) Job(j queue.Job, opts ...queue.Option) *Task
- func (s *Schedule) Next(t *Task, now time.Time) time.Time
- func (s *Schedule) RunDue(ctx context.Context, now time.Time) error
- func (s *Schedule) Tasks() []*Task
- func (s *Schedule) Work(ctx context.Context, now func() time.Time) error
- type Task
- func (t *Task) Cron(expr string) *Task
- func (t *Task) Daily() *Task
- func (t *Task) DailyAt(hhmm string) *Task
- func (t *Task) Every(d time.Duration) *Task
- func (t *Task) EveryFiveMinutes() *Task
- func (t *Task) EveryMinute() *Task
- func (t *Task) Expression() string
- func (t *Task) Hourly() *Task
- func (t *Task) HourlyAt(minute int) *Task
- func (t *Task) In(loc *time.Location) *Task
- func (t *Task) MonthlyOn(day int, hhmm string) *Task
- func (t *Task) Name() string
- func (t *Task) Weekdays() *Task
- func (t *Task) WeeklyOn(weekday time.Weekday, hhmm string) *Task
- func (t *Task) WithoutOverlapping(ttl ...time.Duration) *Task
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrCron = errors.New("schedule: invalid cron expression")
ErrCron reports an invalid expression.
Functions ¶
This section is empty.
Types ¶
type Cron ¶
type Cron struct {
// contains filtered or unexported fields
}
Cron is a parsed five-field cron expression (minute hour day-of-month month day-of-week) with the usual syntax: "*", "5", "1-5", "*/15", "10-50/10", lists ("1,15"), month and weekday names ("JAN", "MON"), and the macros @yearly, @monthly, @weekly, @daily, @hourly. As in Vixie cron, when both day fields are restricted a day matches either.
func MustParseCron ¶
MustParseCron is ParseCron that panics (for literals).
func ParseCron ¶
ParseCron parses expr.
Example ¶
package main
import (
"fmt"
"time"
"github.com/AlexGalhardo/vukem/schedule"
)
func main() {
c, err := schedule.ParseCron("30 9 * * 1-5")
if err != nil {
fmt.Println(err)
return
}
from := time.Date(2026, 1, 3, 12, 0, 0, 0, time.UTC) // a Saturday
fmt.Println(c.Next(from).Format(time.RFC1123))
}
Output: Mon, 05 Jan 2026 09:30:00 UTC
type Options ¶
type Options struct {
// Location is the default time zone of expressions (default UTC).
Location *time.Location
// Log receives task outcomes (default slog.Default()).
Log *slog.Logger
// Locks backs WithoutOverlapping (default an in-memory store, which
// only protects one process; use the database or Redis cache store
// when several servers run the schedule).
Locks *cache.Cache
// Commands runs app commands for Command tasks.
Commands func(ctx context.Context, name string, args []string) error
// Queue dispatches Job tasks.
Queue func() (*queue.Queue, error)
// StopTimeout is how long Work waits for running tasks once its
// context is cancelled before cancelling theirs (default 30s). Tasks
// must honor ctx; one that ignores it still holds Work.
StopTimeout time.Duration
}
Options configure a Schedule.
type Schedule ¶
type Schedule struct {
// contains filtered or unexported fields
}
Schedule holds the tasks.
func (*Schedule) RunDue ¶
RunDue runs the tasks due at now concurrently and waits for them. Task errors are logged and joined into the result.
type Task ¶
type Task struct {
// contains filtered or unexported fields
}
Task is a scheduled unit of work; configure it with the chained methods.
func (*Task) Cron ¶
Cron sets a cron expression; it panics on a bad expression, so mistakes surface at boot.
func (*Task) Every ¶
Every runs the task every d, aligned to the clock (d must be a whole number of minutes dividing an hour or a day, e.g. 5m, 15m, 2h).
func (*Task) EveryFiveMinutes ¶
EveryFiveMinutes runs the task every five minutes.
func (*Task) EveryMinute ¶
EveryMinute runs the task every minute.
func (*Task) Expression ¶
Expression returns the cron expression.
Source Files