Task Definition and Configuration

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion
10. Appendix

Introduction

This document focuses on the design and implementation of the task system, with the following objectives:

• Clarify the design and implementation requirements of the Task interface, including the responsibilities and specifications of methods such as ID(), Type(), Schedule(), Handler(), OnComplete(), OnCancel(), IsRecurring(), GetInterval(), and GetTimeout().
• Explain the three scheduling types of the TaskSchedule structure: immediate execution, timed execution, and periodic execution configuration methods and usage scenarios.
• Compare the differences and application scenarios between TaskScheduleType enumeration and ExecutionMode enumeration.
• Summarize best practices and common usage patterns for task configuration.

Project Structure

The task system is located in the pkg/tasks directory, organized around a layered design of "Task Interface + Builder + Scheduler + Wrapper", combined with task entity models in pkg/entity, forming clear responsibility boundaries and extensibility.

• Task Interface: Unified abstraction of task behavior, defining task identification, type, scheduling time, handler, completion/cancellation callbacks, periodic properties, and timeout.
• TaskSchedule: Encapsulates scheduling type and time/interval information, providing convenient constructors for ImmediateExecution, ScheduleAt, and ScheduleRecurring.
• TaskScheduleType: Scheduling type enumeration, distinguishing between immediate, timed, and periodic.
• ExecutionMode: Execution mode enumeration, distinguishing between concurrent and sequential, used by hybrid scheduler to select execution path by task type.
• TaskBuilder: Chain configuration of tasks, responsible for validation and assembly of Task instances.
• SchedulerWrapper: Unified external entry point, encapsulating scheduler capabilities, providing RunTask*, RunTypedTask*, CancelTask, GetTaskStatus, ListTasks, etc.
• Scheduler Implementations: ConcurrentScheduler (concurrent), SequentialScheduler (sequential), HybridScheduler (select by type).

Tasks are generated from the "builder" as "task objects", submitted to the "scheduler" through the "scheduler wrapper". The scheduler selects the execution mode based on task type and scheduling configuration, and handles timeout, retry, completion callbacks, and cancellation callbacks during execution.

Task Interface Design and Implementation Specifications

• Method Responsibilities

  • ID(): Returns unique task identifier, used for scheduler indexing and cancellation.
  • Type(): Returns task type, used by hybrid scheduler to select execution mode by type.
  • Schedule(): Returns task scheduled execution time; immediate tasks are usually current time or zero value.
  • Handler(): Returns task processing function, receives context.Context, returns error.
  • OnComplete(): Returns callback after task completion, receives context.Context and error.
  • OnCancel(): Returns callback after task cancellation, receives context.Context.
  • IsRecurring(): Determines if it is a periodic task.
  • GetInterval(): Returns periodic task interval.
  • GetTimeout(): Returns task timeout duration, used for execution context timeout control.

• Implementation Points

  • builtTask implements both Task and TaskInfoProvider, facilitating scheduler reading of TaskInfo.
  • Schedule() calculation is determined at Build() time, immediate tasks are current time, timed tasks are specified time, periodic tasks are current time plus interval.
  • IsRecurring()/GetInterval() are determined by TaskSchedule, periodic tasks in sequential scheduler will recalculate next execution time and write back.

• Structure Fields

  • Type: TaskScheduleType (Immediate/Timed/Periodic)
  • At: Time point for timed execution
  • Interval: Interval for periodic execution

• Convenient Constructors

  • ImmediateExecution(): Immediate execution
  • ScheduleAt(at): Execute at specified time
  • ScheduleRecurring(interval): Periodic execution

• Usage Scenarios

  • Immediate execution: Quick response lightweight tasks
  • Timed execution: Delayed tasks, timed batch processing
  • Periodic execution: Heartbeat, polling, periodic cleanup

• TaskScheduleType

  • Describes "when to execute": Immediate, Timed, Periodic
  • Determined by TaskSchedule, affects how scheduler enqueues and reorders

• ExecutionMode

  • Describes "how to execute": Concurrent, Sequential
  • Determined by hybrid scheduler's task type mapping, affects scheduler selection of concurrent or sequential executor

• Application Suggestions

  • Timed/periodic tasks default to sequential execution, ensuring timing and consistency
  • High throughput, no strong timing dependency tasks use concurrent execution
  • Granular control of task types through SchedulerWrapper's WithSequential/WithConcurrent

• Chain Configuration

  • WithID/WithType/WithHandler/WithOnComplete/WithOnCancel
  • WithSchedule/WithRecurring/WithTimeout/WithRetry/WithPriority

• Build and Validation

  • Required: Handler cannot be empty
  • Timed tasks: Execution time must be later than current time
  • Retry and timeout: Neither can be negative
  • Calculate execution time: Immediate is current time, timed is At, periodic is current time+Interval

• Output: builtTask implementing Task and TaskInfoProvider

• Functions

  • RunTask*/RunTypedTask*: Submit tasks (immediate/timed/periodic)
  • CancelTask: Cancel tasks
  • GetTaskStatus/ListTasks: Query status and list
  • SetTaskTypeMode: Set execution mode by task type
  • SetMaxConcurrentTasks: Set maximum concurrency for concurrent scheduler

• Default Behaviors

  • Default retry count: 3 times (adjustable via WithRetryCount)
  • Default scheduler: Hybrid scheduler (selects concurrent/sequential by type)

• Best Practices

  • Clarify task types, use RunTypedTask* and combine WithSequential/WithConcurrent for precise control
  • Set reasonable concurrency limits for high throughput tasks
  • Use sequential execution for tasks requiring strict timing (such as timed/periodic)
  • Set timeout for critical tasks to avoid blocking

• ConcurrentScheduler

  • Concurrent execution, limited by maxConcurrent
  • Supports timeout, retry, TTL cleanup, dead letter state
  • Immediate tasks execute immediately, timed/periodic tasks triggered in monitor

• SequentialScheduler

  • Sequential execution, maintains pending execution queue and completion notification channel
  • Timed tasks added to queue when time is reached, periodic tasks recalculate next execution time after completion
  • Exponential backoff retry (sequential scheduler)

• HybridScheduler

  • Selects concurrent or sequential by task type mapping
  • Timed/periodic tasks default to sequential
  • Supports dynamic setting of task type execution mode

• Task Entity (Domain Layer)

  • Fields: ID, Type, Status, Payload, Result, Error, Priority, Retries, MaxRetry, StartedAt, EndedAt
  • Methods: Start/Complete/Fail/Cancel/CanRetry/GetExecutionTime/IsExpired

• State Machine (Scheduler Side)

  • unknown/waiting/running/completed/cancelled/failed/retrying/dead_letter
  • Retry strategy: Linear backoff for concurrent scheduler, exponential backoff for sequential scheduler
  • Dead letter: Enters dead_letter when exceeding maximum retry count or not retryable

• Concurrent vs Sequential Selection

  • Concurrent: Improves throughput, suitable for tasks without strong dependencies or timing requirements
  • Sequential: Ensures timing and consistency, suitable for timed/periodic tasks

• Concurrency Limit

  • Controls concurrency through SetMaxConcurrentTasks to avoid resource contention

• Retry Strategy

  • Concurrent scheduler uses linear backoff, sequential scheduler uses exponential backoff to avoid avalanche

• Memory Management

  • TTL and maximum task count limits, regularly cleans up completed/cancelled/failed tasks to prevent memory bloat

• Timeout Control

  • Sets context timeout for task execution through Task.GetTimeout() to avoid long-term blocking

• Common Errors and Localization

  • "Task handler cannot be empty": Check if TaskBuilder.WithHandler is set
  • "Timed task execution time must be greater than current time": Confirm ScheduleAt time parameter
  • "Task ID cannot be empty": Concurrent scheduler has constraints on task ID
  • "Task does not exist": Confirm task ID is correct or has been cleaned up

• State Anomalies

  • failed/retrying/dead_letter: View LastError and NextRetryAt, adjust retry strategy
  • cancelled: Confirm if actively cancelled or timeout cancelled

• Debugging Suggestions

  • Use ListTasks to get full task snapshot
  • Use GetTaskStatus to query specific task status
  • Set timeout for critical tasks to avoid long-term blocking
  • For sequential tasks, focus on queue length and execution duration to avoid backlog

This task system provides complete task lifecycle management from "immediate/timed/periodic" to "concurrent/sequential" through clear interface abstraction, flexible builder, and multiple scheduler implementations. Combined with SchedulerWrapper's unified entry point and default retry strategy, it can meet the needs of most business scenarios. It is recommended to clarify task types and execution modes in production environments, reasonably set concurrency limits and retry strategies, and ensure system stability through TTL and state monitoring.

Appendix

Task Configuration Best Practices Checklist

• Clarify task types: Use RunTypedTask* and combine WithSequential/WithConcurrent
• Reasonably set timeout: Set GetTimeout for time-consuming tasks to avoid blocking
• Control concurrency: Limit concurrency through SetMaxConcurrentTasks
• Retry strategy: Set WithRetryCount according to business tolerance, note backoff strategy differences
• Timed/periodic: Prefer sequential execution to ensure timing and consistency
• Monitoring and cleanup: Regularly check ListTasks, focus on dead_letter and retrying states

Common Usage Patterns

• Immediate tasks: RunTask/RunTaskWithID
• Delayed tasks: RunTaskAfter/RunTaskAfterWithID
• Timed tasks: RunTaskAt/RunTaskWithIDAt
• Periodic tasks: RunTaskRecurring/RunTaskWithIDRecurring
• Typed tasks: RunTypedTask/RunTypedTaskWithID