gotask: Instructions file for Kiro

Kiro AI Rules for GoTask Project

Project Context

GoTask is an asynchronous task management framework for Go that implements an "Everything is a Task" philosophy. It provides OS-like task manager capabilities with precise control over different granularity levels of system components.

Core Architectural Principles

1. Single Goroutine Event Loop (CRITICAL)

• NEVER create goroutines directly in task implementations
• All child tasks execute sequentially in the parent task's goroutine
• This eliminates race conditions and ensures predictable execution
• Use parent.AddTask(child) instead of go func()

2. Task Hierarchy and Lifecycle

• Tasks form a tree structure with parent-child relationships
• Each task has a unique ID for tracking and management
• Use RootManager as the root task manager for signal handling
• Implement proper Start(), Run(), and Dispose() methods

3. Resource Management Philosophy

• Framework handles cascading disposal automatically
• Use OnStop() and OnDispose() hooks for cleanup
• Implement graceful shutdown patterns
• Never call Start() directly - it must be called by the parent task

Task Type System

task.Task (Base Task)

• Use for simple, single-purpose tasks
• Basic task implementation with lifecycle methods

task.Job (Container Task)

• Can contain child tasks
• Ends when all child tasks complete
• Use for task coordinators and containers

task.Work (Persistent Task)

• Similar to Job but continues after children complete
• Use for background workers and long-running services

task.TickTask (Periodic Task)

• Executes at regular intervals
• Implement GetTickInterval() time.Duration
• Use for timers, heartbeats, cleanup tasks

task.ChannelTask (Event-Driven Task)

• Custom signal-based tasks
• Override GetSignal() method
• Use for event-driven and reactive tasks

Implementation Patterns

Standard Task Template

type MyTask struct {
    task.Task  // Choose appropriate type
    // Task-specific fields
    Name        string
    Config      map[string]interface{}
    Resources   []Resource
}

func (t *MyTask) Start() error {
    // Resource initialization
    t.Info("Task starting", "name", t.Name, "taskId", t.GetID())
    
    // Add resource dependencies
    t.Using(t.Resources...)
    
    // OnStop: 用于关闭阻塞性资源（如端口监听、网络连接）
    t.OnStop(func() {
        // 关闭阻塞性资源，如 server.Close(), conn.Close()
        server.Close()
    })
    
    // OnDispose: 用于清理非阻塞性资源
    t.OnDispose(func() {
        // 清理其他资源，如缓存、文件句柄等
        cache.Flush()
    })
    
    return nil
}

func (t *MyTask) Run() error {
    // Main task logic (blocking)
    for !t.IsStopped() {
        // Do work
        if err := t.doWork(); err != nil {
            return err
        }
    }
    return t.StopReason()
}

func (t *MyTask) Dispose() {
    // Resource cleanup
    t.Info("Task disposing", "name", t.Name)
    for _, resource := range t.Resources {
        resource.Close()
    }
}