tasks

type Option interface {
	// contains filtered or unexported methods
}

type Publisher interface {
	// Publish is called with the task whose status changed.
	Publish(task Task)
}

type Schedule struct {
	// Format is the original string given to ParseSchedule, if any.
	Format string
	// Interval is the number of Unit between runs.
	Interval uint64
	// Unit is the time unit of Interval.
	Unit TimeUnit
	// StartDay is the weekday for Weeks schedules (ignored otherwise).
	StartDay time.Weekday
	// LastRunAt is when the task last started; nil until first run or
	// until an "hh:mm" anchor is applied.
	LastRunAt *time.Time
	// NextRunAt is when the task is next due.
	NextRunAt time.Time
	// RunCount is the number of runs; updated atomically by Run.
	RunCount uint32
	// contains filtered or unexported fields
}

type Scheduler interface {
	// SetPublisher sets the publisher on the scheduler and on every task
	// already added; tasks added later inherit it in Add.
	SetPublisher(Publisher) Scheduler
	// Add appends a task to the pool. It may be called while the scheduler
	// is running; the task is picked up on the next tick.
	Add(Task) Scheduler
	// Get returns the task with the given ID, or nil if not found.
	Get(id string) Task
	// List returns a snapshot of the registered task slice. Changes to the
	// returned slice do not change scheduler membership.
	List() []Task
	// Clear removes all tasks from the pool. Tasks already started keep running.
	Clear()
	// Count returns the number of registered tasks.
	Count() int
	// IsRunning reports whether Start has been called and Stop has not yet
	// taken effect.
	IsRunning() bool
	// Start publishes every task and spawns the ticker goroutine.
	// It returns an error if the scheduler is already running.
	Start() error
	// Stop signals the ticker goroutine to exit. It does not wait for the
	// goroutine or for in-flight tasks. A task created by this package
	// (New, NewTask*) is not dispatched after Stop returned, and every run
	// dispatched before is already counted by RunCount and reported by
	// Task.IsRunning until it finishes, although its callback may begin
	// executing after Stop returned. The
	// scheduler cannot mark a custom Task implementation running: it calls
	// its Run on a new goroutine, so a run dispatched before Stop may begin,
	// and become visible, after Stop returned. Repeated calls succeed.
	Stop() error
	// Publish calls Publish on every registered task.
	Publish()
}

type Task interface {
	// ID returns the task ID: the WithID option value or a generated UUIDv7.
	ID() string
	// Name returns "<taskName>@<callback function name>" as set by Do;
	// empty before Do is called.
	Name() string
	// RunCount returns how many runs have started; a run is counted when it
	// is marked running, right before its callback is invoked.
	RunCount() uint32
	// Schedule returns a snapshot of the current schedule and run state.
	Schedule() *Schedule
	// UpdateSchedule replaces the schedule with one parsed from format
	// (see ParseSchedule); the next run is recomputed on the next Run.
	UpdateSchedule(format string) error
	// ShouldRun reports whether the task is not running and NextRunAt has passed.
	ShouldRun() bool
	// Run executes the callback if the run lock can be acquired within the
	// run timeout, then recomputes NextRunAt and returns true. It returns
	// false without running if the task is already running. Callback panics
	// are recovered and logged.
	Run() bool
	// SetNextRun forces the next run to TimeNow()+after.
	SetNextRun(time.Duration) Task
	// Do binds the callback and its arguments and computes the first NextRunAt.
	// It panics if task is not a function or the number of params does not
	// match its arity; argument types are only checked when the callback is
	// invoked (a mismatch is then recovered and logged as an error).
	Do(taskName string, task any, params ...any) Task
	// IsRunning reports whether the callback is currently executing.
	IsRunning() bool
	// SetPublisher sets the Publisher notified before and after each run.
	SetPublisher(Publisher) Task
	// Publish sends the task to its Publisher, if any.
	Publish()
}

type TimeUnit uint