queue

type Config struct {
	// MaxConcurrency 单个task的最大并发处理数量，默认为3
	// 最大worker数 = 可运行的task数 * MaxConcurrency + 1
	MaxConcurrency uint8
	// TablePrefix 当使用MySQL驱动时数据表的前缀，默认为空
	TablePrefix string
	// AutoScale 是否开启自动扩缩容，默认不开启
	AutoScale bool
	// AutoScaleInterval 开启自动扩缩容时，自动监测是否需扩容数间隔时间间隔
	// 默认 5 * time.Minute
	AutoScaleInterval time.Duration
	// AutoScaleJobThreshold 开启自动扩缩容时
	// 当个task累计堆积job数大于等于该值时触发扩容，默认值：1000
	// 自动扩缩容主要在于扩容worker，指标是job堆积数量（等待执行的job数据）
	// 而自动缩容则是当堆积job小于等于可运行的task数时自动降低worker数至
	// 扩容worker最大值为：最大worker数，参照 MaxConcurrency 的说明
	AutoScaleJobThreshold int64
}

type DefaultTaskSetting struct{}

type DefaultTaskSettingWithoutTimeout struct{}

type FailedJobHandler func(payload *Payload, err error) error

type JobIFace interface {
	Release(delay int64) (err error) // 释放任务：将任务重新放入队列
	Delete() (err error)             // 删除任务：任务不再执行
	IsDeleted() (deleted bool)       // 检查任务是否已删除
	IsReleased() (released bool)     // 检查任务是否已释放
	Attempts() (attempt int64)       // 获取任务已尝试执行过的次数
	PopTime() (time time.Time)       // 获取任务首次被pop取出的时刻
	Timeout() (time time.Duration)   // 任务超时时长
	TimeoutAt() (time time.Time)     // 任务执行超时的时刻
	HasFailed() (hasFail bool)       // 检测当前job任务执行是否出现了错误
	MarkAsFailed()                   // 设置当前job任务执行出现了错误
	Failed(err error)                // 设置任务执行失败
	Queue() (queue QueueIFace)       // 获取job任务所属队列queue句柄
	GetName() (queueName string)     // 获取job所属队列名称
	Payload() (payload *Payload)     // 获取任务执行参数payload
}

type JobMemory struct {
	// contains filtered or unexported fields
}

type JobMySQL struct {
	// contains filtered or unexported fields
}

type JobRedis struct {
	// contains filtered or unexported fields
}

type JobStatistics struct {
	TotalJobs      int64            `json:"total_jobs"`      // 待消费的job总数
	JobsStatistics map[string]int64 `json:"jobs_statistics"` // job和待消费数map
}

type Logger interface {
	// Debug debug级别输出的日志
	//   - msg 日志消息文本描述
	//   - keyValue 按顺序一个key一个value，len(keyValue)一定是偶数<注意0也是偶数>
	Debug(msg string, keyValue ...any)
	// Info info级别输出的日志
	//   - msg 日志消息文本描述
	//   - keyValue 按顺序一个key一个value，len(keyValue)一定是偶数<注意0也是偶数>
	Info(msg string, keyValue ...any)
	// Warn warn级别输出的日志
	//   - msg 日志消息文本描述
	//   - keyValue 按顺序一个key一个value，len(keyValue)一定是偶数<注意0也是偶数>
	Warn(msg string, keyValue ...any)
	// Error error级别输出的日志
	//   - msg 日志消息文本描述
	//   - keyValue 按顺序一个key一个value，len(keyValue)一定是偶数<注意0也是偶数>
	Error(msg string, keyValue ...any)
}

type MemoryStatistics struct {
	SysMemoryTotal       uint64  `json:"sys_memory_total"`        // 系统内存总数（单位：字节）
	SysMemoryUsed        uint64  `json:"sys_memory_used"`         // 系统内存已使用数（单位：字节）
	SysMemoryAvailable   uint64  `json:"sys_memory_available"`    // 系统内存可供申请使用的内存数（单位：字节）
	SysMemoryUsedPercent float64 `json:"sys_memory_used_percent"` // 系统内存已使用比例（0~1之间的小数）
	GoMemoryTotal        uint64  `json:"go_memory_total"`         // go程序从系统申请的内存总数（单位：字节）
	GoMemoryAlloc        uint64  `json:"go_memory_alloc"`         // go程序当前正在使用的内存数（单位：字节）
	GoMemoryUsedPercent  float64 `json:"go_memory_used_percent"`  // go程序申请的内存与系统总内存的比例（0~1之间的小数）
}

type Payload struct {
	Name          string `json:"Name"`          // 队列名称
	ID            string `json:"ID"`            // 任务ID
	MaxTries      int64  `json:"MaxTries"`      // 任务最大尝试次数，默认1
	RetryInterval int64  `json:"RetryInterval"` // 当任务最大允许尝试次数大于0时，下次尝试之前的间隔时长，单位：秒
	Attempts      int64  `json:"Attempts"`      // 任务已被尝试执行的的次数
	Payload       []byte `json:"Payload"`       // 任务参数比特字面量，可decode成具体job被execute时的类型
	PopTime       int64  `json:"PopTime"`       // 任务首次被取出执行的时间戳，取出的时候才去设置
	Timeout       int64  `json:"Timeout"`       // 任务最大执行超时时长，单位：秒
	TimeoutAt     int64  `json:"TimeoutAt"`     // 任务超时时刻时间戳，被执行时刻才会去设置
}

type Queue struct {
	// contains filtered or unexported fields
}

type QueueIFace interface {
	// Size 获取当前队列长度方法
	// @param queue 队列的名称
	Size(queue string) (size int64)
	// Push 投递一条任务到队列方法
	// @param queue 队列的名称
	// @param payload 投递进队列的参数负载
	Push(queue string, payload interface{}) (err error)
	// Later 投递一条指定延长时长的延迟任务到队列的方法
	// @param queue 延迟队列的名称
	// @param durationTo 相对于投递任务时刻延迟的时长
	// @param payload 投递进队列的多个参数负载
	Later(queue string, durationTo time.Duration, payload interface{}) (err error)
	// LaterAt 投递一条指定执行时间的延迟任务到队列的方法
	// @param queue 延迟队列的名称
	// @param timeAt 延迟执行的时刻
	// @param payload 投递进队列的多个参数负载
	LaterAt(queue string, timeAt time.Time, payload interface{}) (err error)
	// Pop 从队尾取出一条任务的方法
	// @param queue 队列的名称
	Pop(queue string) (job JobIFace, exist bool)
	// SetConnection 设置队列底层连接器
	// @param connection 底层连接器实例
	SetConnection(connection interface{}) (err error)
	// GetConnection 获取队列底层连接器
	GetConnection() (connection interface{}, err error)
}

type RawBody struct {
	ID string // 队列内部唯一标识符ID
	// contains filtered or unexported fields
}

type Statistics struct {
	StatisticsTime   int64            `json:"statistics_time"`   // 统计时间戳
	MemoryStatistics MemoryStatistics `json:"memory_statistics"` // 内存情况统计
	WorkerStatistics WorkerStatistics `json:"worker_statistics"` // worker情况统计
	JobStatistics    JobStatistics    `json:"job_statistics"`    // job情况统计
}

type TaskIFace interface {
	MaxTries() int64                                 // 定义队列任务最大尝试次数：任务执行的最大尝试次数
	RetryInterval() int64                            // 定义队列任务最大尝试间隔：当任务执行失败后再次尝试执行的间隔时长，单位：秒
	Timeout() time.Duration                          // 定义队列超时方法：返回超时时长
	Name() string                                    // 定义队列名称方法：返回队列名称
	Execute(ctx context.Context, job *RawBody) error // 定义队列任务执行时的方法：执行成功返回nil，执行失败返回error
	Remark() string                                  // 队列任务說明
}

type WorkerStatistics struct {
	ActiveWorkers int64          `json:"active_workers"` // 正在处理任务的worker数量
	TotalWorkers  int64          `json:"total_workers"`  // 实际存在的worker总数
	WorkerState   map[int64]bool `json:"worker_state"`   // 每个worker的状态映射
}