asynctask

type CronTask struct {
	Name        string // Use Identifier method to access
	Description string
	Func        TaskFunc
	Total       uint64
	ErrCount    uint64
}

type CronTaskDispatcher interface {
	scene.Named
	// Add will add task with a generated name common uuid
	Add(spec string, cmd TaskFunc) (*CronTask, error)
	// AddWithName will add task with specific name. name should be unique
	AddWithName(spec string, name string, cmd TaskFunc) (*CronTask, error)
	// AddTask is the underlying implementation for Add and AddWithName
	AddTask(spec string, task *CronTask) error
	// Cancel will cancel task have specific identifier
	Cancel(id string) error
	// GetTask will return the underlying task, not copy of the task info.
	// which means user can modify TaskFunc if they need
	GetTask(id string) (*CronTask, error)
}

type QueueTask struct {
	ID string `json:"id"`
	// Queue is the logical queue name.
	// It defines the consumption domain and queue-level runtime config.
	Queue string `json:"queue"`
	// Type is the task type inside a queue.
	// Consumers use it to route the task to a specific handler.
	Type string `json:"type"`
	// Key is an optional business grouping key.
	// It can be used by backends or future schedulers for partitioning,
	// deduplication, or serializing tasks for the same business object.
	Key string `json:"key,omitempty"`
	// Payload is the serialized task body, usually JSON.
	Payload []byte `json:"payload,omitempty"`
	// Headers stores optional metadata for tracing or backend-specific routing.
	Headers map[string]string `json:"headers,omitempty"`
	// Delay requests delayed execution.
	// The exact behavior depends on the backend implementation.
	Delay time.Duration `json:"delay,omitempty"`
	// Timeout is the handler execution timeout for this task.
	Timeout time.Duration `json:"timeout,omitempty"`
	// MaxRetry overrides the queue-level retry limit when greater than zero.
	MaxRetry int `json:"max_retry,omitempty"`
	// Attempt is the current retry attempt count.
	Attempt     int             `json:"attempt,omitempty"`
	Status      QueueTaskStatus `json:"status,omitempty"`
	LastError   string          `json:"last_error,omitempty"`
	CreatedAt   time.Time       `json:"created_at"`
	AvailableAt time.Time       `json:"available_at"`
}

type QueueTaskStatus string

type Task struct {
	Name string
	Func TaskFunc
	Err  error
	// contains filtered or unexported fields
}

type TaskDispatcher interface {
	scene.Named
	// Run run task once, the task should be ended in expected time
	Run(task TaskFunc) *Task
	// RunTask run task once, the task should be ended in expected time
	RunTask(task *Task)
}

type TaskFunc func() error

type TaskQueueConfig struct {
	// Concurrency is the number of workers consuming the logical queue.
	Concurrency int
	// MaxRetry is the default retry limit for tasks in the queue.
	MaxRetry int
	// RetryDelay is the default delay before retrying a failed task.
	RetryDelay time.Duration
	// BufferSize is the in-memory queue buffer size.
	// It is only meaningful for in-process backends such as memoryqueue.
	BufferSize int
}

type TaskQueueConsumer interface {
	scene.Named
	// RegisterQueue defines the config of a logical queue.
	// Re-registering the same queue requires an identical config.
	RegisterQueue(queue string, config TaskQueueConfig) error
	// RegisterHandler binds a task type to a logical queue.
	// The queue must be registered before handlers are attached.
	RegisterHandler(queue string, taskType string, handler TaskQueueHandler) error
}

type TaskQueueHandler interface {
	HandleTask(ctx context.Context, task *QueueTask) error
}

type TaskQueueHandlerFunc func(ctx context.Context, task *QueueTask) error

type TaskQueuePublisher interface {
	scene.Named
	// Publish enqueues a task to the backend and returns the stored task model.
	// The implementation may populate fields such as ID, CreatedAt and Status.
	Publish(ctx context.Context, task *QueueTask) (*QueueTask, error)
}

type TaskStatus int32