Skip to main content

Task Wrapper

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​

The task wrapper is the core abstraction layer of the Sparrow task management system, providing a unified interface for task submission, execution, monitoring, and management. This design adopts the decorator pattern and interceptor pattern, achieving modular processing of cross-cutting concerns through wrapper chains.

The main design goals of the task wrapper include:

  • Unified Interface: Providing consistent APIs for different types of schedulers
  • Decorator Pattern: Supporting cross-cutting concern processing during task execution
  • Interceptor Pattern: Inserting custom logic before and after task execution
  • Extensibility: Supporting custom wrapper composition and configuration
  • Monitoring Capability: Built-in task status monitoring, logging, and performance statistics

Project Structure​

Task wrapper related code is mainly located in the pkg/tasks directory, adopting a layered architecture design:

Task Wrapper (SchedulerWrapper)​

The task wrapper is the core controller of the entire task system, responsible for:

  • Task Submission: Providing multiple task submission methods (immediate execution, timed execution, periodic execution)
  • Configuration Management: Supporting configuration of retry count, concurrency, execution mode, etc.
  • Scheduler Proxy: Delegating tasks to underlying schedulers for execution
  • Status Monitoring: Providing task status query and listing functions

The task builder adopts the builder pattern, providing flexible task configuration capabilities:

  • Chain Configuration: Supporting continuous configuration calls
  • Parameter Validation: Validating task parameter validity at build time
  • Default Value Setting: Setting reasonable default values for missing parameters
  • Type Safety: Ensuring type safety of task configuration

The scheduler interface defines the core behavior of the task system:

  • Task Lifecycle Management: Scheduling, cancellation, status query
  • Concurrency Control: Supporting configuration of maximum concurrent task count
  • Graceful Shutdown: Providing shutdown mechanism with timeout control
  • Extensibility: Supporting scheduler implementations with different execution modes

The task wrapper adopts a layered architecture design, achieving modular processing of cross-cutting concerns through the decorator pattern:

Task Wrapper Execution Flow​

The execution flow of the task wrapper reflects the core idea of the decorator pattern:

The hybrid scheduler selects appropriate execution mode based on task type and scheduling characteristics:

The task wrapper has built-in intelligent retry mechanism, supporting exponential backoff and linear backoff strategies:

The concurrent scheduler implements fine-grained concurrency control to ensure rational utilization of system resources:

The sequential scheduler ensures strict sequential execution of tasks through queues and state machines:

The dependency relationships of the task wrapper reflect a clear layered architecture:

Memory Management Optimization​

The task wrapper implements intelligent memory management strategies:

  • Task Count Limit: Default maximum of 500 tasks saved
  • TTL Mechanism: Completed tasks automatically cleaned up after 5 minutes
  • LRU Cleanup: Deletes oldest completed tasks to free up space

Concurrency Performance Tuning​

  • Concurrency Slot Control: Precise control of concurrent task count through condition variables
  • Waiting Strategy: Uses combination of polling and condition variables to avoid blocking
  • Timeout Control: Supports task-level timeout control

Execution Efficiency Optimization​

  • Task Type Cache: Hybrid scheduler caches task type to execution mode mapping
  • Fast State Query: Direct access to task status without complex queries
  • Batch Operation Support: Supports batch task status query and management

Troubleshooting Guide​

Common Problem Diagnosis​

  1. Task Cannot Execute

    • Check if task handler is empty
    • Verify if task scheduled time is valid
    • Confirm if scheduler has started

  2. Concurrency Control Failure

    • Check maximum concurrency configuration
    • Verify if concurrency slots are properly released
    • Confirm if wait channel is working properly

  3. Retry Mechanism Abnormal

    • Check retry count configuration
    • Verify retry delay calculation
    • Confirm task state transition logic

Debugging Techniques​

  • Use ListTasks() method to view all task statuses
  • Get specific task details through GetTaskStatus()
  • Monitor active task count and maximum concurrency
  • Check task logs and error information

The task wrapper achieves the following goals through carefully designed architecture:

  1. Unified Abstraction: Providing consistent API interfaces for different types of schedulers
  2. Cross-Cutting Concerns: Achieving modularization of monitoring, logging, retry and other functions through decorator pattern
  3. Extensibility: Supporting combination of custom schedulers and wrappers
  4. Performance Optimization: Implementing efficient concurrency control and memory management
  5. Reliability Guarantee: Built-in retry mechanism and error handling

This design provides a powerful foundation for the Sparrow task system, supporting various needs from simple tasks to complex business scenarios.

Appendix​

Configuration Options Details​

OptionTypeDefaultDescription
WithRetryCountint3Default retry count
WithSchedulerTaskSchedulerNewHybridScheduler()Custom scheduler instance
WithMaxConcurrentintUnlimitedMaximum concurrent tasks
WithConcurrentstring...NoneSpecify task types for concurrent execution
WithSequentialstring...NoneSpecify task types for sequential execution

Usage Examples​

// Basic Usage
wrapper := NewSchedulerWrapper()

// Configure Retry and Concurrency
wrapper = NewSchedulerWrapper(
    WithRetryCount(3),
    WithMaxConcurrent(10),
)

// Specify Task Type Execution Mode
wrapper = NewSchedulerWrapper(
    WithSequential("critical-task"),
    WithConcurrent("batch-task"),
)

Extension Development Guide​

  1. Custom Scheduler: Implement TaskScheduler interface
  2. Custom Wrapper: Inherit SchedulerWrapper functionality
  3. Task Interceptor: Insert custom logic before and after task execution
  4. Monitoring Component: Implement task status monitoring and statistics