Documentation
¶
Overview ¶
Package schedule provides explicit recurring job definitions and scheduler lifecycle.
Index ¶
- Constants
- Variables
- func MustRegister(registry *Registry, definition Definition)
- func Register(registry *Registry, definition Definition) error
- type Config
- type Definition
- func (definition Definition) Expression() string
- func (definition Definition) Fingerprint() string
- func (definition Definition) JobName() string
- func (definition Definition) JobPolicy() job.Policy
- func (definition Definition) MisfireGrace() time.Duration
- func (definition Definition) Name() string
- func (definition Definition) Next(after time.Time) time.Time
- func (definition Definition) Queue() string
- func (definition Definition) TimeZone() string
- type Event
- type Factory
- type MaterializeFunc
- type Observer
- type ObserverFunc
- type Occurrence
- type Option
- type Outcome
- type Registry
- type Result
- type Scheduler
- type Status
- type Store
Constants ¶
Variables ¶
var ErrDefinitionConflict = errors.New("schedule: durable definition conflicts with code")
Functions ¶
func MustRegister ¶
func MustRegister(registry *Registry, definition Definition)
func Register ¶
func Register(registry *Registry, definition Definition) error
Register adds a definition without runtime discovery.
Types ¶
type Config ¶
Config bounds scheduler polling, framework I/O, and callbacks that cooperate with context cancellation. OperationTimeout cannot preempt arbitrary Go code.
type Definition ¶
type Definition struct {
// contains filtered or unexported fields
}
Definition is an immutable recurring typed-job contract.
func Define ¶
func Define[P any](name, expression string, target job.Definition[P], factory Factory[P], options ...Option) (Definition, error)
Define validates and binds a recurring typed-job definition.
func MustDefine ¶
func MustDefine[P any](name, expression string, target job.Definition[P], factory Factory[P], options ...Option) Definition
MustDefine panics when a package-level definition is invalid.
func (Definition) Expression ¶
func (definition Definition) Expression() string
func (Definition) Fingerprint ¶
func (definition Definition) Fingerprint() string
func (Definition) JobName ¶
func (definition Definition) JobName() string
func (Definition) JobPolicy ¶
func (definition Definition) JobPolicy() job.Policy
JobPolicy returns a defensive copy of the effective target-job policy.
func (Definition) MisfireGrace ¶
func (definition Definition) MisfireGrace() time.Duration
func (Definition) Name ¶
func (definition Definition) Name() string
func (Definition) Next ¶
func (definition Definition) Next(after time.Time) time.Time
Next returns the next matching UTC occurrence strictly after after.
func (Definition) Queue ¶
func (definition Definition) Queue() string
func (Definition) TimeZone ¶
func (definition Definition) TimeZone() string
type Factory ¶
type Factory[P any] struct { // contains filtered or unexported fields }
Factory is an opaque typed schedule payload strategy.
func Dynamic ¶
func Dynamic[P any](factory func(Occurrence) (P, error)) Factory[P]
Dynamic binds an occurrence-aware typed payload factory. Its implementation is governed by the schedule's versioned name rather than function identity.
func DynamicContext ¶ added in v0.14.2
DynamicContext binds a cancellation-aware occurrence payload factory. Its implementation shares Dynamic's versioned strategy marker, so adopting it does not change an existing schedule definition's fingerprint.
type MaterializeFunc ¶
type MaterializeFunc func(context.Context, job.Executor, Occurrence) (job.DispatchResult, error)
MaterializeFunc dispatches the selected occurrence through the executor for the store's current transaction.
type Observer ¶
Observer receives immutable schedule events after durable materialization returns successfully.
func SlogObserver ¶
SlogObserver emits payload-free schedule decisions through structured logs.
type ObserverFunc ¶
ObserverFunc adapts a function to Observer.
type Occurrence ¶
type Occurrence struct {
Schedule string
ScheduledAt time.Time
TimeZone string
// contains filtered or unexported fields
}
Occurrence identifies one cron minute. ScheduledAt is always UTC.
func (Occurrence) LocalTime ¶
func (occurrence Occurrence) LocalTime() time.Time
LocalTime returns the occurrence in its declared location.
type Option ¶
type Option func(*definitionSettings) error
Option changes one schedule definition.
func MisfireGrace ¶
MisfireGrace sets the inclusive coalescing window.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry contains explicit code-owned schedule definitions.
func NewRegistry ¶
func NewRegistry() *Registry
func (*Registry) Definitions ¶
func (registry *Registry) Definitions() []Definition
Definitions returns deterministic immutable definition values.
type Result ¶
Result describes one scheduler decision. A zero ScheduledAt means that no concrete occurrence was selected.
type Scheduler ¶
type Scheduler struct {
// contains filtered or unexported fields
}
Scheduler materializes due definitions into the durable job queue.
func NewScheduler ¶
func (*Scheduler) DroppedObserverEvents ¶
DroppedObserverEvents reports events discarded because the configured observer did not keep up with the bounded serialized delivery queue.
type Status ¶
type Status struct {
Name string
Expression string
TimeZone string
JobName string
Queue string
MisfireGrace time.Duration
Fingerprint string
NextRunAt time.Time
LastEvaluatedAt *time.Time
LastCursorAt *time.Time
LastOccurrenceAt *time.Time
LastJobID job.ID
LastOutcome Outcome
CreatedAt *time.Time
UpdatedAt *time.Time
}
Status combines the current code-owned definition with its durable state. Nil timestamps mean that the scheduler has not recorded that transition.
type Store ¶
type Store interface {
Materialize(context.Context, Definition, MaterializeFunc) (Result, error)
List(context.Context, []Definition) ([]Status, error)
}
Store is the replaceable durable coordination boundary. Materialize must invoke dispatch and advance its cursor in one atomic transaction.