README.md

scheduling

Tier: Platform · Status: Full · Java original: Spring @Scheduled · .NET project: Quartz.NET / IHostedService

Overview

scheduling is the framework's task scheduler — a Scheduler runner that owns Cron, FixedRate, and FixedDelay triggers, runs each task in its own goroutine with panic recovery, and respects context.Context for cancellation.

s := scheduling.New()
_ = s.Cron("nightly-rollup", "0 2 * * *", rollup)
s.FixedRate("metrics-emit", 30*time.Second, emitMetrics)
s.FixedDelay("cleanup", 5*time.Minute, cleanup)

ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT)
defer cancel()
_ = s.Start(ctx)

Cron syntax

5-field, no macros (yet). minute hour day-of-month month day-of-week. Each field accepts:

• A literal: 0, 15, 30
• A list: 0,15,30,45
• A range: 9-17
• A wildcard: *
• A step: */15, 9-17/2

Day-of-month + day-of-week semantics: when both are restricted, the rule fires when either matches (Vixie cron behaviour).

Triggers

Trigger	Behaviour
CronTrigger	Fires when the wall clock matches the parsed expression
FixedRateTrigger	Fires every Period from a fixed Start anchor (slips on slow runs)
FixedDelayTrigger	Fires Delay after the previous run finished

Public surface

type Trigger interface { Next(now time.Time) time.Time }

type CronExpr struct{ Minute, Hour, DayOfMonth, Month, DayOfWeek []int }
func ParseCron(expr string) (*CronExpr, error)
func (*CronExpr) Next(from time.Time) time.Time

type CronTrigger      struct{ Expr *CronExpr }
type FixedRateTrigger struct{ Start time.Time; Period time.Duration }
type FixedDelayTrigger struct{ Delay time.Duration; /* unexported lastRun */ }

type Task struct {
    Name    string
    Trigger Trigger
    Run     func(ctx) error
}

type Scheduler struct{ ... }
func New() *Scheduler
func (*Scheduler) WithLogger(*slog.Logger) *Scheduler
func (*Scheduler) Register(*Task)
func (*Scheduler) Cron(name, expr, run) error
func (*Scheduler) FixedRate(name, period, run)
func (*Scheduler) FixedDelay(name, delay, run)
func (*Scheduler) Start(ctx) error  // blocks until ctx cancelled
func (*Scheduler) Stop()

startercore.Core exposes a pre-wired Scheduler with the core's logger.

Quick start

import (
    "context"
    "log/slog"
    "time"
    "github.com/fireflyframework/fireflyframework-go/scheduling"
)

s := scheduling.New().WithLogger(slog.Default())
_ = s.Cron("eod-report", "0 23 * * *", eodReport)
s.FixedRate("heartbeat", time.Minute, heartbeat)

ctx, cancel := context.WithCancel(context.Background())
defer cancel()
go func() { _ = s.Start(ctx) }()

Testing

cd scheduling
go test ./...

Covers cron parsing (literal, list, range, step, invalid), FixedRate timing, FixedDelay timing (delay-after-finish), and panic recovery (a panicking task does not stop the scheduler).