GoTask

<div align="center"> <img src="logo.png" alt="GoTask Logo" width="200" height="200"> </div>

中文文档 | English

An asynchronous task management framework based on Go language, providing precise control capabilities similar to an operating system task manager

Table of Contents

• Project Purpose
  • Core Philosophy
  • Core Problems Solved
  • Nine Core Features
  • Use Cases
• Quick Start
  • Installation
  • Build Options
  • Basic Usage
  • RootManager Usage Guide
  • Dashboard
• AI IDE Rules
• Project Structure
• Features
  • Nine Core Features
• Usage Guide
  • Conditional Compilation Parameters
  • Task Startup
  • EventLoop Mechanism
  • Task Stopping
• Task Management API
  • Task Public Methods
  • Job Public Methods
  • Global Functions
  • Race Condition Handling
• Dashboard
  • Backend Service (dashboard/server)
  • Frontend Interface (dashboard/web)
  • Quick Start
  • One-click Startup
• Tutorial Lessons
  • Course Structure
  • How to Use the Lessons
  • Course Features
  • Learning Recommendations
• Contribution
  • Contribution Methods
• License
• Acknowledgements
• Related Links
• Support

Project Purpose

GoTask is an asynchronous task management framework based on Go language, designed to solve task management challenges in complex projects. We believe that everything is a task, whether it's network connections, data processing, scheduled tasks, or business processes, all can be abstracted as tasks for unified management.

Core Philosophy

Everything is a Task - Breaking down complex business logic into manageable task units, each with a clear lifecycle, execution path, and resource management. This design philosophy makes the system architecture clearer, code more maintainable, and issues easier to locate.

OS-like Task Manager - GoTask functions like an operating system task manager, capable of precisely controlling shutdown and restart of different granularity logic in your project:

• Process-level Control - Starting, stopping, and restarting entire applications or services
• Service-level Control - Microservices, database connection pools, cache services, etc.
• Component-level Control - Network connections, scheduled tasks, data processing pipelines, etc.
• Function-level Control - Individual business functions, API endpoints, data stream processing, etc.

Core Problems Solved

1. Observability in Complex Projects - In microservice architectures and distributed systems, traditional logging and monitoring methods often fail to provide complete execution path tracking. GoTask provides comprehensive observability through task tree structures, execution history records, and performance monitoring.

2. Concurrency Safety in Asynchronous Systems - Traditional goroutine management methods can easily lead to race conditions and resource contention. GoTask ensures tasks execute sequentially in the parent task's goroutine through a single-goroutine event loop mechanism, completely avoiding concurrency issues.

3. Resource Disposal Challenges in Complex Projects - In complex projects, the most difficult aspect is resource disposal for asynchronous tasks, including disposal order, race conditions, and cascading disposal. GoTask thoroughly solves these challenges through:

   • Optimized Disposal - Automatically manages resource disposal order, avoiding dependency conflicts
   • Automatic Cascading Disposal - Automatically triggers disposal of all child tasks when a parent task is disposed, ensuring complete resource release
   • Associated Disposal - Supports associated disposal between tasks, automatically stopping related tasks when a key task stops
   • Race-condition Safety - Ensures thread safety during disposal through the single-goroutine mechanism

4. System Stability Assurance - Ensures system stability under various exceptional conditions through graceful shutdown, exception handling, retry mechanisms, and other features.

Nine Core Features

GoTask provides a complete task management solution for complex projects through the following nine core features:

1. Called in Parent Task's Goroutine - Avoids concurrency issues, ensures predictability of task execution
2. Graceful Shutdown - Supports proper resource release and system stability, implementing optimized disposal, automatic cascading disposal, and associated disposal
3. Unique ID - Enables complete task lifecycle tracking
4. Measurable Call Duration - Provides precise performance monitoring and analysis
5. Extensible - Supports flexible customization for various business scenarios
6. Traceable - Provides complete execution path and call stack tracing
7. Fallback Mechanism - Comprehensive exception handling and error recovery
8. Optional Retry Mechanism - Intelligent failure recovery strategies
9. Storable History Records - Supports querying and analyzing task execution history

Use Cases

• Microservice Architecture - Task coordination and lifecycle management between services
• Streaming Media Processing - Audio/video stream receiving, processing, and forwarding tasks
• Data Pipelines - Management of complex data processing workflows
• Scheduled Task Systems - Reliable scheduling and execution of timed tasks
• Network Services - Lifecycle management of HTTP, WebSocket, RTMP, and other network services
• Monitoring Systems - System health check and performance monitoring tasks
• Hot Update Systems - Like an OS task manager, supporting hot updates and restarts of components at different granularities
• Fault Recovery - Automatic detection and recovery of faulty components, implementing system self-healing capabilities

GoTask is not just a task management framework, but an architectural philosophy that helps developers build more stable, observable, and maintainable complex systems.

Quick Start

Installation

go get github.com/langhuihui/gotask

Build Options

GoTask supports conditional compilation to control panic behavior:

# Default mode - recommended for production
go build

# Panic mode - for development and debugging
go build -tags taskpanic

Basic Usage

package main

import (
    "github.com/langhuihui/gotask"
    "time"
)

// Define a simple task
type MyTask struct {
    task.Task
    Name string
}

func (t *MyTask) Start() error {
    t.Info("Task started", "name", t.Name)
    return nil
}

func (t *MyTask) Run() error {
    // Execute task logic
    time.Sleep(5 * time.Second)
    return nil
}

func (t *MyTask) Dispose() {
    t.Info("Task cleanup", "name", t.Name)
}

// Using the root task manager from gotask project
type TaskManager = task.RootManager[uint32, *MyTask]

func main() {
    // Create root task manager
    root := &TaskManager{}
    root.Init()
    
    // Create and start task
    myTask := &MyTask{Name: "Example Task"}
    root.AddTask(myTask)
    
    // Wait for task completion
    myTask.WaitStopped()
}

RootManager Usage Guide

Important: When using the task system, you must use RootManager as the root task manager. RootManager provides the following features:

1. Automatic Signal Handling: Automatically handles operating system signals (SIGHUP, SIGINT, SIGTERM, SIGQUIT)
2. Graceful Shutdown: Provides a Shutdown() method for graceful shutdown
3. Task Management: Acts as the root node for all tasks, managing the lifecycle of the entire task tree

Usage Steps:

1. Create RootManager instance:

type TaskManager = task.RootManager[uint32, *MyTask]
root := &TaskManager{}
root.Init()

2. Add tasks:

myTask := &MyTask{Name: "Example Task"}
root.AddTask(myTask)

4. Graceful shutdown:

// Call when program exits
root.Shutdown()

Dashboard

Start the built-in dashboard to visually monitor tasks:

# Start backend service
cd dashboard/server
go run main.go

# Start frontend interface
cd dashboard/web
pnpm install
pnpm run dev

Visit http://localhost:5173 to view the task management interface.

---

This project includes an independent task library (github.com/langhuihui/gotask), a React-based management interface, and an example backend program.

AI IDE Rules

The project includes AI IDE rule files to help AI assistants understand the project structure and development guidelines:

| File | Description | Purpose | |------|-------------|---------| | ai_rules/Claude.md | Claude AI Rules for GoTask Project | Comprehensive guidelines for AI assistan