doc.go

// Package chronos is an in-process, cron-like scheduler. It exists to

// run recurring work inside a single Go program without an external

// scheduler or a separate process: jobs share one supervisor, one

// concurrency budget, and the program's own context for shutdown.

//

// A job pairs a schedule with a [JobFunc]. Build one of two ways:

//

//   - [NewCron] parses a cron spec (5- or 6-field, an @-macro, or

//     "@every <dur>").

//   - [NewEvery] fires on a fixed interval expressed as one or more

//     [Span] values, which are calendar-aware: months and years respect

//     month lengths, leap years, and daylight saving.

//

// Refine a job with chained builders before registering it: [Job.Delta]

// (per-fire jitter), [Job.Timeout] (cancel a slow run), [Job.SlotWait]

// (how long to wait for a concurrency slot), [Job.Name], and

// [Job.OnOverlap] ([OverlapSkip] or [OverlapAllow]).

//

// A [Supervisor] owns the jobs and their lifecycle. Build it with [New]

// and [Option]s, register jobs with [Supervisor.Add], then call

// [Supervisor.Start] with a context and [Supervisor.Stop] to drain. The

// supervisor bounds total concurrency across all jobs with

// [WithMaxInflight]: when the budget is full, [WithSlotWait] (or the

// per-job [Job.SlotWait]) decides whether a fire sheds, waits, or waits

// then sheds.

//

// Inside a run, the [JobFunc] receives a [ChronosContext]. It embeds the

// run's [context.Context] (cancelled on timeout or shutdown) and lets the

// job register sibling jobs with [ChronosContext.Add] or retire itself

// with [ChronosContext.Deactivate] without cancelling the current run.

package chronos