Documentation
¶
Overview ¶
Package scheduler provides a cron-style task scheduler with support for named intervals (@daily, @every 5m), 5-field cron expressions, typed schedule categories, and freeform tags.
Index ¶
- func ValidateExpr(s string) error
- type Config
- type Entry
- type JobFunc
- type ScheduleType
- type Scheduler
- func (s *Scheduler) AgentEntries() []Entry
- func (s *Scheduler) Context() context.Context
- func (s *Scheduler) Entries() []Entry
- func (s *Scheduler) EntriesByTag(tag string) []Entry
- func (s *Scheduler) GetEntry(name string) (Entry, bool)
- func (s *Scheduler) Register(cfg Config, job JobFunc) error
- func (s *Scheduler) RegisterAndStart(cfg Config, job JobFunc) error
- func (s *Scheduler) Start()
- func (s *Scheduler) Stop()
- func (s *Scheduler) SystemEntries() []Entry
- func (s *Scheduler) Unregister(name string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ValidateExpr ¶
ValidateExpr checks whether a schedule expression is syntactically valid. It is used by callers to validate configuration before registering schedules.
Types ¶
type Config ¶
type Config struct {
// Name is a unique identifier for this schedule.
Name string
// Type classifies the schedule as "system" or "agent".
Type string
// Schedule is the timing expression. Supported formats:
// @hourly, @daily, @midnight, @weekly, @monthly, @yearly, @annually
// @every <duration> (e.g. @every 5m, @every 1h30m)
// 5-field cron: "0 8 * * 1-5"
Schedule string
// Skill is the name of the skill to invoke when this schedule fires.
Skill string
// SessionTier is the permission tier for the session spawned on each run.
SessionTier string
// Channel is the adapter channel to deliver results to (e.g. "telegram:123456").
Channel string
// SessionMode controls which conversation context is used on each run.
// "shared": reuses the channel's existing conversation history (default).
// "isolated": creates a fresh conversation for each run.
SessionMode string
// Tags are freeform labels for organizing and filtering schedules.
Tags []string
// Enabled controls whether this schedule runs. Disabled schedules are
// registered but their goroutines are never started.
Enabled bool
}
Config holds the configuration for a single schedule entry. It is populated from the application's main config and passed to Register.
type Entry ¶
type Entry struct {
Name string
Type ScheduleType
Expr string // original schedule expression string
Skill string
SessionTier string
SessionMode string
Channel string
Tags []string
Enabled bool
LastRun time.Time // zero if never fired
NextRun time.Time // zero if disabled or indeterminate
}
Entry is an immutable snapshot of a schedule entry and its runtime state. It is passed to JobFunc and returned by the Entries methods.
type JobFunc ¶
type JobFunc func(entry Entry)
JobFunc is the function called each time a schedule fires. It receives a read-only snapshot of the triggering entry.
type ScheduleType ¶
type ScheduleType string
ScheduleType classifies the priority and security context of a schedule.
const ( // ScheduleTypeSystem is for core system tasks: agent heartbeats, memory // cleanup, cost resets, etc. System schedules run with elevated priority // and should not be modifiable by the agent without explicit permission. ScheduleTypeSystem ScheduleType = "system" // ScheduleTypeAgent is for user-configured scheduled agent skill runs. // These are created and managed through normal configuration. ScheduleTypeAgent ScheduleType = "agent" )
type Scheduler ¶
type Scheduler struct {
// contains filtered or unexported fields
}
Scheduler runs registered schedules concurrently. System and agent schedules are tracked separately to allow priority enforcement and selective querying.
func New ¶
New creates a Scheduler. Cron expressions are evaluated in the given time.Location. If loc is nil it defaults to UTC.
func (*Scheduler) AgentEntries ¶
AgentEntries returns a snapshot of entries with Type == ScheduleTypeAgent.
func (*Scheduler) Context ¶ added in v0.16.9
Context returns the scheduler's lifecycle context. It is cancelled when Stop() is called. Callers can derive job contexts from this to ensure work stops on shutdown.
func (*Scheduler) Entries ¶
Entries returns a snapshot of all registered entries (enabled and disabled).
func (*Scheduler) EntriesByTag ¶
EntriesByTag returns entries that carry the given tag.
func (*Scheduler) GetEntry ¶ added in v0.1.0
GetEntry returns a snapshot of the named entry and true, or a zero value and false if not found.
func (*Scheduler) Register ¶
Register adds a schedule entry with its associated job function.
The schedule expression is validated immediately; an error is returned for invalid expressions or duplicate names. Disabled entries are stored but their goroutines are not started.
Register may be called before or after Start. Entries added after Start are not automatically activated — Stop and re-Start, or register before the first Start.
func (*Scheduler) RegisterAndStart ¶
RegisterAndStart registers a new schedule entry and immediately starts its goroutine if the entry is enabled. Unlike Register, this is safe to call after Start has been invoked — the goroutine is spawned inline rather than waiting for the next Start call.
func (*Scheduler) Start ¶
func (s *Scheduler) Start()
Start launches goroutines for all enabled entries. Calling Start on an already-running Scheduler is safe but will spawn duplicate goroutines for already-active entries.
func (*Scheduler) Stop ¶
func (s *Scheduler) Stop()
Stop signals all schedule goroutines to exit and blocks until they finish.
func (*Scheduler) SystemEntries ¶
SystemEntries returns a snapshot of entries with Type == ScheduleTypeSystem.
func (*Scheduler) Unregister ¶ added in v0.1.0
Unregister stops and removes a named schedule entry. If the entry is running, its goroutine is cancelled asynchronously. Returns an error if the name is not found.
Source Files