Documentation
¶
Index ¶
- func GetTaskName(ctx context.Context) string
- type CronSchedule
- type CtxtKey
- type Option
- func WithAllowOverlapping(allow bool) Option
- func WithContextInjector(injector func(ctx context.Context, taskName string) context.Context) Option
- func WithContextValue(key string, value any) Option
- func WithLocation(loc *time.Location) Option
- func WithLogger(logger *log.Logger) Option
- func WithMaxConcurrent(max int) Option
- type Schedule
- type ScheduleBuilder
- func (s *ScheduleBuilder) At(hour, minute int) *ScheduleBuilder
- func (s *ScheduleBuilder) Day() *ScheduleBuilder
- func (s *ScheduleBuilder) Days(interval int) *ScheduleBuilder
- func (s *ScheduleBuilder) Hour() *ScheduleBuilder
- func (s *ScheduleBuilder) Hours(interval int) *ScheduleBuilder
- func (s *ScheduleBuilder) Minute() *ScheduleBuilder
- func (s *ScheduleBuilder) Minutes(interval int) *ScheduleBuilder
- func (s *ScheduleBuilder) OnDay(day int) *ScheduleBuilder
- func (s *ScheduleBuilder) OnWeekday(weekday time.Weekday) *ScheduleBuilder
- func (s *ScheduleBuilder) Second() *ScheduleBuilder
- func (s *ScheduleBuilder) Seconds(interval int) *ScheduleBuilder
- func (s *ScheduleBuilder) String() string
- type Task
- type TaskInfo
- type TaskManager
- func (tm *TaskManager) AddTask(name string, schedule Schedule, task Task) error
- func (tm *TaskManager) DisableTask(name string) error
- func (tm *TaskManager) EnableTask(name string) error
- func (tm *TaskManager) GetContextValue(key string) any
- func (tm *TaskManager) GetStats() map[string]interface{}
- func (tm *TaskManager) GetTask(name string) (*TaskInfo, error)
- func (tm *TaskManager) IsRunning() bool
- func (tm *TaskManager) ListTasks() []*TaskInfo
- func (tm *TaskManager) RemoveTask(name string) error
- func (tm *TaskManager) RunTaskNow(name string) error
- func (tm *TaskManager) SetContextValue(key string, value any)
- func (tm *TaskManager) Start()
- func (tm *TaskManager) Stop()
- func (tm *TaskManager) WebHandler(baseURL string) *http.ServeMux
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetTaskName ¶
GetTaskName extracts the task name from a task context. Returns empty string if the context doesn't contain a task name.
Types ¶
type CronSchedule ¶
type CronSchedule struct {
// contains filtered or unexported fields
}
CronSchedule wraps a standard cron expression string.
func Cron ¶
func Cron(expr string) *CronSchedule
Cron creates a Schedule from a cron expression string. The expression should be in the format: "second minute hour day month weekday"
func (*CronSchedule) String ¶
func (c *CronSchedule) String() string
String returns the cron expression.
type Option ¶
type Option func(*TaskManager)
Option is a functional option for configuring TaskManager.
func WithAllowOverlapping ¶
WithAllowOverlapping controls whether the same task can run multiple instances concurrently. By default, overlapping is not allowed (false).
func WithContextInjector ¶
func WithContextInjector(injector func(ctx context.Context, taskName string) context.Context) Option
WithContextInjector sets a custom function to dynamically inject values into task contexts. The injector is called for each task execution and receives the base context and task name.
func WithContextValue ¶
WithContextValue adds a static key-value pair that will be injected into all task contexts.
func WithLocation ¶
WithLocation sets the timezone for cron schedule interpretation.
func WithLogger ¶
WithLogger sets a custom logger for the task manager. If not provided, log.Default() will be used.
func WithMaxConcurrent ¶
WithMaxConcurrent sets the maximum number of tasks that can run concurrently. A value of 0 means unlimited concurrency. Negative values are treated as 0.
type Schedule ¶
type Schedule interface {
String() string
}
Schedule represents a task scheduling expression.
type ScheduleBuilder ¶
type ScheduleBuilder struct {
// contains filtered or unexported fields
}
ScheduleBuilder provides a fluent API for building cron schedules.
func Every ¶
func Every() *ScheduleBuilder
Every creates a new ScheduleBuilder with default values (runs every minute).
func (*ScheduleBuilder) At ¶
func (s *ScheduleBuilder) At(hour, minute int) *ScheduleBuilder
At specifies a specific time of day for the schedule. For example, At(14, 30) runs at 2:30 PM. Hour must be 0-23 and minute must be 0-59, otherwise the method panics.
func (*ScheduleBuilder) Day ¶
func (s *ScheduleBuilder) Day() *ScheduleBuilder
Day configures the schedule to run every day (at midnight).
func (*ScheduleBuilder) Days ¶
func (s *ScheduleBuilder) Days(interval int) *ScheduleBuilder
Days configures the schedule to run at the specified day interval. For example, Days(2) runs every 2 days at midnight. Interval must be positive, otherwise the method panics.
func (*ScheduleBuilder) Hour ¶
func (s *ScheduleBuilder) Hour() *ScheduleBuilder
Hour configures the schedule to run every hour (at 0 minutes, 0 seconds).
func (*ScheduleBuilder) Hours ¶
func (s *ScheduleBuilder) Hours(interval int) *ScheduleBuilder
Hours configures the schedule to run at the specified hour interval. For example, Hours(6) runs every 6 hours. Interval must be positive, otherwise the method panics.
func (*ScheduleBuilder) Minute ¶
func (s *ScheduleBuilder) Minute() *ScheduleBuilder
Minute configures the schedule to run every minute (at 0 seconds).
func (*ScheduleBuilder) Minutes ¶
func (s *ScheduleBuilder) Minutes(interval int) *ScheduleBuilder
Minutes configures the schedule to run at the specified minute interval. For example, Minutes(15) runs every 15 minutes. Interval must be positive, otherwise the method panics.
func (*ScheduleBuilder) OnDay ¶
func (s *ScheduleBuilder) OnDay(day int) *ScheduleBuilder
OnDay restricts the schedule to a specific day of the month. For example, OnDay(15) runs on the 15th of each month. Day must be between 1 and 31, otherwise the method panics.
func (*ScheduleBuilder) OnWeekday ¶
func (s *ScheduleBuilder) OnWeekday(weekday time.Weekday) *ScheduleBuilder
OnWeekday restricts the schedule to a specific day of the week. For example, OnWeekday(time.Monday) runs only on Mondays.
func (*ScheduleBuilder) Second ¶
func (s *ScheduleBuilder) Second() *ScheduleBuilder
Second configures the schedule to run every second.
func (*ScheduleBuilder) Seconds ¶
func (s *ScheduleBuilder) Seconds(interval int) *ScheduleBuilder
Seconds configures the schedule to run at the specified second interval. For example, Seconds(30) runs every 30 seconds. Interval must be positive, otherwise the method panics.
func (*ScheduleBuilder) String ¶
func (s *ScheduleBuilder) String() string
String converts the builder to a cron expression string.
type Task ¶
Task represents a function that performs work within a given context. It should return an error if the task execution fails.
type TaskInfo ¶
type TaskInfo struct {
Name string // Unique identifier for the task
Schedule string // Cron expression for the task schedule
Task Task // The actual task function to execute
EntryID cron.EntryID // Cron entry ID for this task
AddedAt time.Time // When the task was added to the manager
LastRun time.Time // Last execution time
NextRun time.Time // Next scheduled execution time
RunCount int64 // Total number of executions
ErrorCount int64 // Total number of failed executions
LastError string // Most recent error message (empty if last run succeeded)
Enabled bool // Whether the task is enabled for execution
Running bool // Whether the task is currently executing
}
TaskInfo holds metadata and statistics about a scheduled task.
type TaskManager ¶
type TaskManager struct {
// contains filtered or unexported fields
}
TaskManager orchestrates scheduled task execution with concurrent control, error tracking, and flexible configuration options.
func New ¶
func New(opts ...Option) *TaskManager
New creates a new TaskManager with the given options. The manager must be started with Start() before tasks will execute.
func (*TaskManager) AddTask ¶
func (tm *TaskManager) AddTask(name string, schedule Schedule, task Task) error
AddTask registers a new task with the given name and schedule. Returns an error if a task with the same name already exists or if the schedule is invalid.
func (*TaskManager) DisableTask ¶
func (tm *TaskManager) DisableTask(name string) error
DisableTask disables a task without removing it. The task will not execute but can be re-enabled later.
func (*TaskManager) EnableTask ¶
func (tm *TaskManager) EnableTask(name string) error
EnableTask enables a previously disabled task. The task will resume executing on its schedule.
func (*TaskManager) GetContextValue ¶
func (tm *TaskManager) GetContextValue(key string) any
GetContextValue retrieves a static context value. Returns nil if the key does not exist.
func (*TaskManager) GetStats ¶
func (tm *TaskManager) GetStats() map[string]interface{}
GetStats returns aggregated statistics about the task manager and all tasks.
func (*TaskManager) GetTask ¶
func (tm *TaskManager) GetTask(name string) (*TaskInfo, error)
GetTask returns a copy of the task information for the given task name. Returns an error if the task does not exist.
func (*TaskManager) IsRunning ¶
func (tm *TaskManager) IsRunning() bool
IsRunning checks whether the task manager is currently running.
func (*TaskManager) ListTasks ¶
func (tm *TaskManager) ListTasks() []*TaskInfo
ListTasks returns a copy of all task information. The returned slice can be safely modified without affecting the manager.
func (*TaskManager) RemoveTask ¶
func (tm *TaskManager) RemoveTask(name string) error
RemoveTask removes a task from the manager. Returns an error if the task does not exist.
func (*TaskManager) RunTaskNow ¶
func (tm *TaskManager) RunTaskNow(name string) error
RunTaskNow immediately executes a task outside of its regular schedule. The execution is asynchronous and subject to the same concurrency limits and overlap rules as scheduled executions.
func (*TaskManager) SetContextValue ¶
func (tm *TaskManager) SetContextValue(key string, value any)
SetContextValue adds or updates a static context value that will be injected into all task contexts.
func (*TaskManager) Start ¶
func (tm *TaskManager) Start()
Start begins the task scheduler. Tasks will start executing according to their schedules.
func (*TaskManager) Stop ¶
func (tm *TaskManager) Stop()
Stop gracefully shuts down the task manager. It stops accepting new task executions and waits for running tasks to complete or times out after 30 seconds.
func (*TaskManager) WebHandler ¶
func (tm *TaskManager) WebHandler(baseURL string) *http.ServeMux
WebHandler creates an HTTP handler for the task manager web interface. The baseURL parameter should be the URL prefix where the handler is mounted (e.g., "/tasks"). Returns a ServeMux that can be integrated into your HTTP server.