task

Gousing Task

介绍

开箱即用的 Gousing Task, 基于分片定时任务队列调度器进行管理，提供全局默认任务管理器, 支持状态监控和管理，支持多种任务类型，包含定时模式/延迟模式/周期模式, 支持运行册数限制和超时控制。

无依赖，不使用Cron表达式语法，提供直接语义化接口，如：

定时模式

• OnceAt 创建一次性定时任务（基于一个明确时间）

定时模式

• OnceAfter 创建一次性延迟任务（基于一个延迟时间）
• OnceBuffer 创建一次性延迟任务(缓冲模式), 常用于延迟更新任务, 如缓存更新等场景

周期模式

• EveryInterval 创建周期性任务,基于一个明确的间隔时间 interval
• EverySecond 创建周期性任务（每几秒钟运行一次）
• EveryMinute 创建周期性任务（每几分钟运行一次）
• EveryHour 创建周期性任务（每几小时运行一次）
• EveryDay 创建周期性任务（每几天运行一次）
• EveryWeekDay 创建周期性任务（每周几运行一次）
• EveryMonthDay 创建周期性任务（每月的某一日运行一次）
• EveryMonthFirstDay 创建周期性任务（每月第1天运行一次）
• EveryMonthLastDay 创建周期性任务（每月最后一天运行一次）

添加任务时，支持更细定时控制和超时控制

• WithStartAt 设置任务开始的时间(默认为Now)
• WithHour 设置任务时刻：时 (默认为当前小时)
• WithMinute 设置任务时刻：分 (默认为当前分钟)
• WithSecond 设置任务时刻：秒 (默认为当前秒)
• WithMillisecond 设置任务时刻：毫秒 (默认为当前毫秒)
• WithTimeout 设置任务执行超时时间(默认为0, 即不限制)
• WithRunMax 设置任务执行最大次数(周期任务有效, 默认为0, 即不限制)

安装

go get -u gitee.com/gousing/task

使用

开箱即用, 全局默认任务管理器

import "gitee.com/gousing/task"
// Global 获取全局默认任务管理器
// task.GetGlobal() *TaskManager
// task.SetGlobal(*TaskManager)
// OnceAt 创建一次性定时任务（基于一个明确时间）
//   - executeAt 调度器内部会统一转换为本地时区后处理，如已过期则调整为当前时间(立即执行)
//   - ops 可通过 TaskOption 指定任务运行的超时时间: WithTimeout
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
task.OnceAt(key string, executeAt time.Time, handler TaskHandler, ops ...TaskOption) error
// 一小时后运行，超时设置为 1s
task.OnceAt("key", time.Now().Add(time.Hour), func() error {
		return nil
}, WithTimeout(time.Second))
// EveryInterval 创建周期性任务,基于一个明确的间隔时间 interval
//   - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
task.EveryInterval(key string, interval time.Duration, handler TaskHandler, ops ...TaskOption) error
// 每秒钟运行一次, 一直重复直到任务被删除
task.EveryInterval("key", time.Second, func() error {
		return nil
})
// 每秒钟运行一次, 运行100次
task.EveryInterval("key", time.Second, func() error {
		return nil
}, WithRunMax(100))
// 更多接口见 TaskManagerIO

自定义任务管理器

import "gitee.com/gousing/task"
// NewTaskManager 创建一个新任务管理器
//   - name string   管理器名称
//   - options *Options  配置选项
//   - type Options struct {
//   - 	ShardCount  int           // 任务队列存储分片数量,  默认 32, 最小 1, 最大 512
//   - 	WorkerCount int           // 任务处理协程数量, 默认 2048, 最小 1, 最大 262144
//   - 	CheckPeriod time.Duration // 任务队列检查最小时间，决定了定时任务定时/间隔精度， 默认 10 毫秒, 最小 1毫秒, 最大 1000毫秒(1秒)
//   - }
func NewTaskManager(name string, options *Options) *TaskManager

myTask := task.NewTaskManager("MyTask",&options{ShardCount:32,WorkerCount：2048,CheckPeriod：10*time.Millisecond})
// OnceAt 创建一次性定时任务（基于一个明确时间）
//   - executeAt 调度器内部会统一转换为本地时区后处理，如已过期则调整为当前时间(立即执行)
//   - ops 可通过 TaskOption 指定任务运行的超时时间: WithTimeout
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
myTask.OnceAt(key string, executeAt time.Time, handler TaskHandler, ops ...TaskOption) error
// 更多接口见 TaskManagerIO

TaskManagerIO

注意：如未设置超时时间, 默认任务执行超时时间为30秒

// OnceAt 创建一次性定时任务（基于一个明确时间）
//   - executeAt 调度器内部会统一转换为本地时区后处理，如已过期则调整为当前时间(立即执行)
//   - ops 可通过 TaskOption 指定任务运行的超时时间: WithTimeout
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
OnceAt(key string, executeAt time.Time, handler TaskHandler, ops ...TaskOption) error

// OnceAfter 创建一次性延迟任务（基于一个延迟时间）
//   - ops 可通过 TaskOption 指定任务运行的开始时间: WithStartAt  超时时间: WithTimeout 等
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
OnceAfter(key string, delay time.Duration, handler TaskHandler, ops ...TaskOption) error
// OnceBuffer 创建一次性延迟任务(缓冲模式), 常用于延迟更新任务, 如缓存更新等场景
//   - ops 可通过 TaskOption 指定任务运行的开始时间: WithStartAt  超时时间: WithTimeout 等
//   - 注意：任务添加后/执行前相同Key任务的添加操作将会忽略
OnceBuffer(key string, delay time.Duration, handler TaskHandler, ops ...TaskOption) error 
// EveryInterval 创建周期性任务,基于一个明确的间隔时间 interval
//   - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
EveryInterval(key string, interval time.Duration, handler TaskHandler, ops ...TaskOption) 
// EverySecond 创建周期性任务（每几秒钟运行一次）
//   - ops 可通过 TaskOption 指定具体的具体运行时刻: WithMillisecond
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
EverySecond(key string, seconds int, handler TaskHandler, ops ...TaskOption) error 

// EveryMinute 创建周期性任务（每几分钟运行一次）
//   - ops 可通过 TaskOption 指定具体的具体运行时刻：WithSecond WithMillisecond
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
EveryMinute(key string, minutes int, handler TaskHandler, ops ...TaskOption) error

// EveryHour 创建周期性任务（每几小时运行一次）
//   - ops 可通过 TaskOption 指定具体的具体运行时刻：WithMinute WithSecond WithMillisecond
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
EveryHour(key string, hours int, handler TaskHandler, ops ...TaskOption) error

// EveryDay 创建周期性任务（每几天运行一次）
//   - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
EveryDay(key string, days int, handler TaskHandler, ops ...TaskOption) error 

// EveryWeekDay 创建周期性任务（每周X运行一次）
//   - weekDay 0-7, 0/7 => 星期日
//   - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
EveryWeekDay(key string, weekDay int, handler TaskHandler, ops ...TaskOption) error
// EveryMonthDay 创建周期性任务（每月的某一日运行一次）
//   - day: 1-31, 如指定31号，但当月只有30天，则30日执行
//   - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
EveryMonthDay(key string, day int, handler TaskHandler, ops ...TaskOption) error
// EveryMonthFirstDay 创建周期性任务（每月第1天运行一次）
//   - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
EveryMonthFirstDay(key string, handler TaskHandler, ops ...TaskOption) error
// EveryMonthLastDay 创建周期性任务（每月最后一天运行一次）
//   - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond
//   - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务
EveryMonthLastDay(key string, handler TaskHandler, ops ...TaskOption) error
// Remove 删除指定key的任务
RemoveTask(keys ...string) error
// RemoveAllTasks 删除所有任务
RemoveAllTasks() error
// GetTask 获取指定key的定时任务
GetTask(key string) (TaskInfo, error)
// GetAllTasks 获取所有定时任务信息
GetAllTasks() ([]TaskInfo, error)
// Size 获取定时任务数量(包含未运行、已运行的全部任务)
//   - 包含全部定时任务的映射(可主动通过RemoveTask删除指定任务信息)
Size() int
// IsRuning 获取定时任务管理器运行状态
IsRuning() bool
// Monitor 获取定时任务运行监控信息
Monitor() TaskMonitorData
// Stop 关闭定时任务管理器
//   - 注意：仅停止定时任务管理器的运行，不会删除任务数据
Stop() error
// Restart 重启定时任务管理器
//   - 注意：重启后，所有到期任务会立即运行
Restart()

Test Benchmark

Test 全包测试需要设置下超时，以完成任务执行测试

go.exe test -timeout 60s -run ^Test* gitee.com/gousing/task -v

Benchmark

go.exe test -benchmem -run=^$ -bench ^Benchmark* gitee.com/gousing/task -v
goos: windows
goarch: amd64
pkg: gitee.com/gousing/task
cpu: 12th Gen Intel(R) Core(TM) i5-12400F

Gousing 通用选项

自定义 Logger

// 默认使用Golang标准库slog.Default()全局日志记录日志
// task.SetLogger(*slog.Logger)
myLogger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
task.SetLogger(myLogger)