scheduler

Documentation

Index

• Variables
• func Forever()
• type Clock
  • func AtClock(hour, min, sec int) *Clock
  • func AtHour(hour int) *Clock
  • func AtMinute(min int) *Clock
  • func AtSecond(sec int) *Clock
  • func ClockFromString(str string) *Clock
  • func FullClock() *Clock
  • func (c *Clock) Hour(hour int) *Clock
  • func (c Clock) IsMatched(t time.Time) bool
  • func (c *Clock) Minute(min int) *Clock
  • func (c Clock) Next(t time.Time) (next time.Time)
  • func (c *Clock) Second(sec int) *Clock
  • func (c Clock) String() string
• type Event
• type Schedule
  • func ClockSchedule(start, end *Clock, d time.Duration) Schedule
  • func ConditionSchedule(schedules ...Schedule) Schedule
  • func Every(d ...time.Duration) Schedule
  • func HourSchedule(hour ...int) Schedule
  • func ISOWeekSchedule(year int, week int, weekday *time.Weekday, clock *Clock) Schedule
  • func MinuteSchedule(min ...int) Schedule
  • func MultiSchedule(schedules ...Schedule) Schedule
  • func NewSchedule(year int, month time.Month, day int, clock *Clock) Schedule
  • func ScheduleFromString(str ...string) Schedule
  • func SecondSchedule(sec ...int) Schedule
  • func TimeSchedule(t ...time.Time) Schedule
  • func Weekday(weekday ...time.Weekday) Schedule
• type Scheduler
  • func NewScheduler() *Scheduler
  • func (sched *Scheduler) At(schedules ...Schedule) *Scheduler
  • func (sched *Scheduler) AtCondition(schedules ...Schedule) *Scheduler
  • func (sched *Scheduler) Clear()
  • func (sched *Scheduler) Do(fn func(Event)) error
  • func (sched *Scheduler) Immediately() <-chan struct{}
  • func (sched *Scheduler) Once() <-chan error
  • func (sched *Scheduler) Run(fn ...func(Event)) *Scheduler
  • func (sched *Scheduler) SetIgnoreMissed(ignore bool) *Scheduler
  • func (sched *Scheduler) Start() error
  • func (sched *Scheduler) Stop()
  • func (sched *Scheduler) String() string
  • func (sched *Scheduler) WithDebug(logger *slog.Logger) *Scheduler

Variables

var (
	Weekdays = Weekday(time.Monday, time.Tuesday, time.Wednesday, time.Thursday, time.Friday)
	Weekends = Weekday(time.Saturday, time.Sunday)
)

Predefined weekday groups.

var (
	// ErrNoFunction indicates that no function has been registered to run.
	ErrNoFunction = errors.New("scheduler function is not set")
	// ErrNoSchedule indicates that no schedule has been configured.
	ErrNoSchedule = errors.New("no schedule has been added")
	// ErrAlreadyRunning indicates that the scheduler is already active.
	ErrAlreadyRunning = errors.New("scheduler is already running")
)

Functions

func Forever

func Forever()

Forever blocks indefinitely, keeping the current goroutine alive.

Types

type Clock

type Clock struct {
	clock.Clock
	// contains filtered or unexported fields
}

Clock represents a specific time of day (hour, minute, second) that can be used as a schedule condition. Each field (hour, min, sec) can be optional, allowing partial matching (e.g., “every minute at second 0” or “every day at 12:00:*”).

func AtClock

func AtClock(hour, min, sec int) *Clock

AtClock creates a new Clock schedule at the specified hour, minute, and second. Use -1 for a wildcard (any value). Panics on invalid input.

func AtHour

func AtHour(hour int) *Clock

AtHour returns a Clock that triggers at the specified hour (minute and second = 0).

func AtMinute

func AtMinute(min int) *Clock

AtMinute returns a Clock that triggers at the specified minute of any hour.

func AtSecond

func AtSecond(sec int) *Clock

AtSecond returns a Clock that triggers at the specified second of any minute.

func ClockFromString

func ClockFromString(str string) *Clock

ClockFromString parses a clock string (e.g. "12:30:00") into a Clock schedule. Panics if the string cannot be parsed.

func FullClock

func FullClock() *Clock

FullClock returns a Clock with all fields as wildcards (matches any time).

func (*Clock) Hour

func (c *Clock) Hour(hour int) *Clock

Hour sets the hour field of the Clock (or disables it if -1).

func (Clock) IsMatched

func (c Clock) IsMatched(t time.Time) bool

IsMatched reports whether the given time matches this Clock. Wildcard fields (hour/min/sec=false) are ignored during comparison.

func (*Clock) Minute

func (c *Clock) Minute(min int) *Clock

Minute sets the minute field of the Clock (or disables it if -1).

func (Clock) Next

func (c Clock) Next(t time.Time) (next time.Time)

Next returns the next time that matches this Clock configuration after the given reference time. Handles wildcards intelligently.

func (*Clock) Second

func (c *Clock) Second(sec int) *Clock

Second sets the second field of the Clock (or disables it if -1).

func (Clock) String

func (c Clock) String() string

String returns a human-readable representation such as "12:--:--" or "14:30:00".

type Event

type Event struct {
	Time   time.Time
	Goal   time.Time
	Missed bool
}

Event represents a time event emitted by the scheduler engine. It carries both the actual trigger time (Time) and the intended schedule time (Goal). If Missed is true, the event was triggered after its scheduled Goal.

type Schedule

type Schedule interface {
	// IsMatched reports whether the given time matches the schedule.
	IsMatched(time.Time) bool
	// Next returns the next time that satisfies the schedule after the given time.
	// If there is no valid next time, a zero time is returned.
	Next(time.Time) time.Time
	// String returns a human-readable description of the schedule.
	String() string
}

Schedule defines a time-based trigger that determines whether a given time matches a schedule and can compute the next trigger time.

func ClockSchedule

func ClockSchedule(start, end *Clock, d time.Duration) Schedule

ClockSchedule creates a new schedule that triggers every d duration between start and end (inclusive). The duration must be at least one second and an integer multiple of a second.

func ConditionSchedule

func ConditionSchedule(schedules ...Schedule) Schedule

ConditionSchedule creates a new schedule that triggers only when all of the provided schedules match simultaneously. Equivalent to a logical AND.

func Every

func Every(d ...time.Duration) Schedule

Every returns a schedule that triggers repeatedly at the given durations. The minimum granularity is one second, and durations must be multiples of one second.

func HourSchedule

func HourSchedule(hour ...int) Schedule

HourSchedule creates a multi-schedule that triggers on any of the specified hours.

func ISOWeekSchedule

func ISOWeekSchedule(year int, week int, weekday *time.Weekday, clock *Clock) Schedule

ISOWeekSchedule creates a schedule based on ISO week number and weekday.

func MinuteSchedule

func MinuteSchedule(min ...int) Schedule

MinuteSchedule creates a multi-schedule that triggers on any of the specified minutes.

func MultiSchedule

func MultiSchedule(schedules ...Schedule) Schedule

MultiSchedule creates a new schedule that triggers when any of the provided schedules match. Equivalent to a logical OR of all schedules.

func NewSchedule

func NewSchedule(year int, month time.Month, day int, clock *Clock) Schedule

NewSchedule creates a new date-based Schedule. Zero values for year/month/day represent wildcards that match any year, month, or day.

func ScheduleFromString

func ScheduleFromString(str ...string) Schedule

ScheduleFromString constructs a Schedule from one or more string expressions. It supports both clock expressions (parsed by clock.Parse) and absolute timestamps (e.g., "2006-01-02 15:04:05").

func SecondSchedule

func SecondSchedule(sec ...int) Schedule

SecondSchedule creates a multi-schedule that triggers on any of the specified seconds.

func TimeSchedule

func TimeSchedule(t ...time.Time) Schedule

TimeSchedule creates a schedule based on one or more absolute times.

func Weekday

func Weekday(weekday ...time.Weekday) Schedule

Weekday creates a schedule that matches the specified weekdays at any time of day.

type Scheduler

type Scheduler struct {
	// contains filtered or unexported fields
}

Scheduler defines a flexible time-based job runner. It supports multiple schedules, condition combinations, missed-event handling, and optional structured debug logging.

func NewScheduler

func NewScheduler() *Scheduler

NewScheduler creates a new, uninitialized Scheduler instance.

func (*Scheduler) At

func (sched *Scheduler) At(schedules ...Schedule) *Scheduler

At sets the scheduler to trigger when *any* of the provided schedules match. This is a logical OR of all schedules.

func (*Scheduler) AtCondition

func (sched *Scheduler) AtCondition(schedules ...Schedule) *Scheduler

AtCondition sets the scheduler to trigger only when *all* schedules match. This is a logical AND of all schedules.

func (*Scheduler) Clear

func (sched *Scheduler) Clear()

Clear removes all schedules and stops any running context.

func (*Scheduler) Do

func (sched *Scheduler) Do(fn func(Event)) error

Do runs the given function according to the current schedule configuration. If the scheduler is already running, the error is suppressed.

func (*Scheduler) Immediately

func (sched *Scheduler) Immediately() <-chan struct{}

Immediately triggers all registered functions right now (non-scheduled).

func (*Scheduler) Once

func (sched *Scheduler) Once() <-chan error

Once starts the scheduler for a single execution and returns an error channel that reports initialization status.

func (*Scheduler) Run

func (sched *Scheduler) Run(fn ...func(Event)) *Scheduler

Run registers one or more functions to be executed when the schedule triggers. Functions are executed in separate goroutines.

func (*Scheduler) SetIgnoreMissed

func (sched *Scheduler) SetIgnoreMissed(ignore bool) *Scheduler

SetIgnoreMissed sets whether missed schedule times should be ignored. If true, the scheduler will skip backlogged runs caused by delays.

func (*Scheduler) Start

func (sched *Scheduler) Start() error

Start begins running the scheduler continuously until Stop is called.

func (*Scheduler) Stop

func (sched *Scheduler) Stop()

Stop stops the scheduler and cancels its running context.

func (*Scheduler) String

func (sched *Scheduler) String() string

String returns a human-readable representation of the configured schedule.

func (*Scheduler) WithDebug

func (sched *Scheduler) WithDebug(logger *slog.Logger) *Scheduler

WithDebug attaches a slog.Logger for debug output.