101 lines
3.3 KiB
Go
101 lines
3.3 KiB
Go
// Package scheduling decides when scheduled jobs run and with what
|
|
// concurrency. Storage and delivery are behind JobSource and Runner.
|
|
package scheduling
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"fmt"
|
|
"strings"
|
|
"time"
|
|
)
|
|
|
|
// Pool is how a job's runs are dispatched relative to other jobs.
|
|
type Pool string
|
|
|
|
const (
|
|
// PoolParallel runs the job concurrently with every other job, bounded
|
|
// only by the engine's MaxParallel cap.
|
|
PoolParallel Pool = "parallel"
|
|
// PoolSequential runs the job on a single shared worker, one at a time,
|
|
// in the order the source returned them. Use it for jobs that contend
|
|
// for a resource that tolerates no concurrency.
|
|
PoolSequential Pool = "sequential"
|
|
)
|
|
|
|
// Validate rejects an unknown pool. The empty pool is valid and means
|
|
// PoolSequential: an unlabelled job is assumed to want the safer of the two,
|
|
// because wrongly serialising a job costs latency while wrongly parallelising
|
|
// one costs correctness.
|
|
func (p Pool) Validate() error {
|
|
switch p {
|
|
case "", PoolParallel, PoolSequential:
|
|
return nil
|
|
default:
|
|
return fmt.Errorf("scheduling: unknown pool %q", string(p))
|
|
}
|
|
}
|
|
|
|
// resolve maps the empty pool onto its documented default.
|
|
func (p Pool) resolve() Pool {
|
|
if p == "" {
|
|
return PoolSequential
|
|
}
|
|
return p
|
|
}
|
|
|
|
// Job is one due unit of scheduled work as handed to the engine. It carries
|
|
// identity and dispatch policy only: the schedule itself (cron expression,
|
|
// next-run time, catch-up policy) belongs to the job store behind JobSource,
|
|
// which is why the engine never sees one.
|
|
type Job struct {
|
|
// ID identifies the job across ticks. It is the overlap key: while a
|
|
// run with this ID is queued or in flight, later ticks that report the
|
|
// same ID are skipped rather than stacked.
|
|
ID string
|
|
// Pool selects the dispatch pool. Empty means PoolSequential.
|
|
Pool Pool
|
|
// Detail is a human-readable label recorded on emitted events so a run
|
|
// stays attributable without the engine knowing what the job does.
|
|
Detail string
|
|
}
|
|
|
|
// Validate checks the fields the engine relies on.
|
|
func (j Job) Validate() error {
|
|
if strings.TrimSpace(j.ID) == "" {
|
|
return errors.New("scheduling: job id must be non-empty")
|
|
}
|
|
return j.Pool.Validate()
|
|
}
|
|
|
|
// JobSource returns the jobs due at an instant.
|
|
type JobSource interface {
|
|
Due(ctx context.Context, now time.Time) ([]Job, error)
|
|
}
|
|
|
|
// Runner executes one due job. Implementations must respect ctx: the engine
|
|
// bounds every run with JobTimeout and cancels on shutdown, but a Runner that
|
|
// ignores cancellation can still delay Stop up to Stop's own deadline.
|
|
type Runner interface {
|
|
Run(ctx context.Context, job Job) error
|
|
}
|
|
|
|
// Clock is injectable time: Now for timestamps and After for the tick sleep.
|
|
// Loop timing is tested against a fake clock, never wall-clock sleeps.
|
|
type Clock interface {
|
|
Now() time.Time
|
|
After(d time.Duration) <-chan time.Time
|
|
}
|
|
|
|
type systemClock struct{}
|
|
|
|
func (systemClock) Now() time.Time { return time.Now() }
|
|
func (systemClock) After(d time.Duration) <-chan time.Time { return time.After(d) }
|
|
|
|
// Sink is the narrow event contract the engine needs. It matches
|
|
// events.Bus's emitter shape without importing it — the domain declares what
|
|
// it needs and app wires the implementation in.
|
|
type Sink interface {
|
|
Emit(kind, detail string, data map[string]any)
|
|
}
|