Documentation
¶
Index ¶
- Variables
- type CronJobDefinition
- type DurationJobDefinition
- type DurationRandomJobDefinition
- type Job
- type JobDefinition
- type JobDescriptorOption
- func WithConcurrent() JobDescriptorOption
- func WithContext(ctx context.Context) JobDescriptorOption
- func WithLimitedRuns(limitedRuns uint) JobDescriptorOption
- func WithName(name string) JobDescriptorOption
- func WithStartAt(startAt time.Time) JobDescriptorOption
- func WithStartImmediately() JobDescriptorOption
- func WithStopAt(stopAt time.Time) JobDescriptorOption
- func WithTags(tags ...string) JobDescriptorOption
- func WithTask(handler any, params ...any) JobDescriptorOption
- type OneTimeJobDefinition
- type Scheduler
Constants ¶
This section is empty.
Variables ¶
var ( // ErrJobNameRequired indicates job name is required. ErrJobNameRequired = errors.New("job name is required") // ErrJobTaskHandlerRequired indicates job task handler is required. ErrJobTaskHandlerRequired = errors.New("job task handler is required") // ErrJobTaskHandlerMustFunc indicates job task handler must be a function. ErrJobTaskHandlerMustFunc = errors.New("job task handler must be a function") )
Functions ¶
This section is empty.
Types ¶
type CronJobDefinition ¶
type CronJobDefinition struct {
// contains filtered or unexported fields
}
CronJobDefinition defines a job using standard cron expression syntax. It supports both standard 5-field and extended 6-field (with seconds) cron expressions.
func NewCronJob ¶
func NewCronJob(expression string, withSeconds bool, options ...JobDescriptorOption) *CronJobDefinition
NewCronJob creates a new cron-based job definition using cron expression syntax. Set withSeconds to true if the expression includes seconds (6 fields), false for standard 5-field format.
type DurationJobDefinition ¶
type DurationJobDefinition struct {
// contains filtered or unexported fields
}
DurationJobDefinition defines a job that runs repeatedly at fixed intervals. The interval is specified as a time.Duration.
func NewDurationJob ¶
func NewDurationJob(interval time.Duration, options ...JobDescriptorOption) *DurationJobDefinition
NewDurationJob creates a new duration-based job definition that runs at fixed intervals. The job will execute repeatedly with the specified interval between runs.
type DurationRandomJobDefinition ¶
type DurationRandomJobDefinition struct {
// contains filtered or unexported fields
}
DurationRandomJobDefinition defines a job that runs at random intervals. The interval is randomly chosen between MinInterval and MaxInterval for each execution.
func NewDurationRandomJob ¶
func NewDurationRandomJob(minInterval, maxInterval time.Duration, options ...JobDescriptorOption) *DurationRandomJobDefinition
NewDurationRandomJob creates a new random duration job definition. The job will execute with a random interval between minInterval and maxInterval for each run.
type Job ¶
type Job interface {
// Id returns the job's unique identifier as a string.
Id() string
// LastRun returns the time when the job was last executed.
LastRun() (time.Time, error)
// Name returns the human-readable name assigned to the job.
Name() string
// NextRun returns the time when the job is next scheduled to run.
NextRun() (time.Time, error)
// NextRuns returns the specified number of future scheduled run times.
NextRuns(count int) ([]time.Time, error)
// RunNow executes the job immediately without affecting its regular schedule.
// This respects all job and scheduler limits and may affect future scheduling
// if the job has run limits configured.
RunNow() error
// Tags returns the list of tags associated with the job for grouping and filtering.
Tags() []string
}
Job represents a scheduled task in the cron system. It provides methods to inspect and control individual job instances.
type JobDefinition ¶
type JobDefinition interface {
// contains filtered or unexported methods
}
JobDefinition defines how a job should be scheduled and executed. Implementations specify different scheduling strategies (cron, duration, one-time, etc.).
type JobDescriptorOption ¶
type JobDescriptorOption func(*jobDescriptor)
JobDescriptorOption is a function type for configuring job descriptors using the options pattern. This allows for flexible and extensible job configuration.
func WithConcurrent ¶
func WithConcurrent() JobDescriptorOption
WithConcurrent allows the job to run concurrently with other instances of itself. By default, jobs run in singleton mode (no concurrent execution).
func WithContext ¶
func WithContext(ctx context.Context) JobDescriptorOption
If the context is canceled, the job will be canceled as well.
func WithLimitedRuns ¶
func WithLimitedRuns(limitedRuns uint) JobDescriptorOption
WithLimitedRuns limits the job to run only the specified number of times.
func WithName ¶
func WithName(name string) JobDescriptorOption
func WithStartAt ¶
func WithStartAt(startAt time.Time) JobDescriptorOption
WithStartAt specifies when the job should start its schedule.
func WithStartImmediately ¶
func WithStartImmediately() JobDescriptorOption
WithStartImmediately makes the job start immediately when the scheduler starts.
func WithStopAt ¶
func WithStopAt(stopAt time.Time) JobDescriptorOption
WithStopAt specifies when the job should stop running.
func WithTags ¶
func WithTags(tags ...string) JobDescriptorOption
WithTags assigns tags to the job for grouping and bulk operations.
func WithTask ¶
func WithTask(handler any, params ...any) JobDescriptorOption
The handler must be a function, and params are the arguments to pass to it.
type OneTimeJobDefinition ¶
type OneTimeJobDefinition struct {
// contains filtered or unexported fields
}
OneTimeJobDefinition defines a job that runs once at specified times. It supports running immediately, at a single time, or at multiple specific times.
func NewOneTimeJob ¶
func NewOneTimeJob(times []time.Time, options ...JobDescriptorOption) *OneTimeJobDefinition
NewOneTimeJob creates a new one-time job definition with the specified execution times. If times is empty, the job will run immediately. If it contains one time, the job runs once at that time. If it contains multiple times, the job will run at each specified time.
type Scheduler ¶
type Scheduler interface {
// Jobs returns all jobs currently registered with the scheduler.
Jobs() []Job
// NewJob creates and registers a new job with the scheduler.
// The job will be scheduled according to its definition when the scheduler is running.
// If the task function accepts a context.Context as its first parameter,
// the scheduler will provide cancellation support for graceful shutdown.
NewJob(definition JobDefinition) (Job, error)
// RemoveByTags removes all jobs that have any of the specified tags.
RemoveByTags(tags ...string)
// RemoveJob removes the job with the specified unique identifier.
RemoveJob(id string) error
// Start begins scheduling and executing jobs according to their definitions.
// Jobs added to a running scheduler are scheduled immediately. This method is non-blocking.
Start()
// StopJobs stops the execution of all jobs without removing them from the scheduler.
// Jobs can be restarted by calling Start() again.
StopJobs() error
// Update replaces an existing job's definition while preserving its unique identifier.
// This allows for dynamic job reconfiguration without losing job history.
Update(id string, definition JobDefinition) (Job, error)
// JobsWaitingInQueue returns the number of jobs waiting in the execution queue.
// This is only relevant when using LimitModeWait; otherwise it returns zero.
JobsWaitingInQueue() int
}
Scheduler manages the lifecycle and execution of cron jobs. It provides a high-level interface for job scheduling, management, and control.
func NewScheduler ¶
NewScheduler creates a new Scheduler implementation wrapping the provided gocron.Scheduler. This is the main entry point for creating scheduler instances in the application.
Source Files