{"id":29803520,"url":"https://github.com/uptutu/goman","last_synced_at":"2025-07-28T11:08:59.683Z","repository":{"id":305847958,"uuid":"1024129613","full_name":"uptutu/goman","owner":"uptutu","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-22T08:27:08.000Z","size":151,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-22T10:35:14.726Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uptutu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-22T08:22:59.000Z","updated_at":"2025-07-22T08:27:13.000Z","dependencies_parsed_at":"2025-07-22T10:45:22.340Z","dependency_job_id":null,"html_url":"https://github.com/uptutu/goman","commit_stats":null,"previous_names":["uptutu/goman"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/uptutu/goman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uptutu%2Fgoman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uptutu%2Fgoman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uptutu%2Fgoman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uptutu%2Fgoman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uptutu","download_url":"https://codeload.github.com/uptutu/goman/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uptutu%2Fgoman/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267505099,"owners_count":24098346,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-28T11:08:59.128Z","updated_at":"2025-07-28T11:08:59.667Z","avatar_url":"https://github.com/uptutu.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Goroutine Pool SDK\n\n[![Go Version](https://img.shields.io/badge/go-%3E%3D1.19-blue.svg)](https://golang.org/)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()\n[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)]()\n\nA high-performance, feature-rich goroutine pool management library for Go applications. Built for production use with comprehensive monitoring, extensibility, and graceful shutdown capabilities.\n\n## ✨ Features\n\n- **🚀 High Performance**: Lock-free queues, work-stealing, and optimized scheduling\n- **🔧 Flexible Configuration**: Builder pattern with validation and environment support\n- **📊 Built-in Monitoring**: Real-time statistics, metrics collection, and health checks\n- **🔌 Extensible Architecture**: Middleware, plugins, and event system\n- **⚡ Priority Scheduling**: Multi-level task prioritization\n- **🛡️ Robust Error Handling**: Panic recovery, timeout handling, and circuit breaker\n- **🔄 Graceful Shutdown**: Context-aware cancellation and resource cleanup\n- **📈 Production Ready**: Battle-tested patterns and best practices\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\ngo get github.com/uptutu/goman\n```\n\n### Basic Usage\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n    \"time\"\n\n    \"github.com/uptutu/goman/pkg/pool\"\n)\n\n// Implement the Task interface\ntype MyTask struct {\n    ID   int\n    Data string\n}\n\nfunc (t *MyTask) Execute(ctx context.Context) (any, error) {\n    // Your business logic here\n    time.Sleep(100 * time.Millisecond)\n    return fmt.Sprintf(\"Task %d processed: %s\", t.ID, t.Data), nil\n}\n\nfunc (t *MyTask) Priority() int {\n    return pool.PriorityNormal\n}\n\nfunc main() {\n    // Create pool with default configuration\n    p, err := pool.NewPool(nil)\n    if err != nil {\n        log.Fatalf(\"Failed to create pool: %v\", err)\n    }\n    defer p.Shutdown(context.Background())\n\n    // Submit synchronous task\n    task := \u0026MyTask{ID: 1, Data: \"example\"}\n    err = p.Submit(task)\n    if err != nil {\n        log.Printf(\"Failed to submit task: %v\", err)\n    }\n\n    // Submit asynchronous task\n    future := p.SubmitAsync(task)\n    result, err := future.Get()\n    if err != nil {\n        log.Printf(\"Task failed: %v\", err)\n    } else {\n        fmt.Printf(\"Result: %v\\n\", result)\n    }\n}\n```\n\n### Advanced Configuration\n\n```go\nconfig, err := pool.NewConfigBuilder().\n    WithWorkerCount(runtime.NumCPU() * 2).\n    WithQueueSize(10000).\n    WithTaskTimeout(30 * time.Second).\n    WithShutdownTimeout(60 * time.Second).\n    WithMetrics(true).\n    WithPreAlloc(true).\n    Build()\n\nif err != nil {\n    log.Fatalf(\"Invalid config: %v\", err)\n}\n\np, err := pool.NewPool(config)\nif err != nil {\n    log.Fatalf(\"Failed to create pool: %v\", err)\n}\n```\n\n## 📖 Documentation\n\n- **[API Documentation](docs/api.md)** - Complete API reference\n- **[Usage Examples](docs/examples.md)** - Comprehensive examples and patterns\n- **[Best Practices](docs/best-practices.md)** - Production deployment guide\n- **[Performance Tuning](docs/performance-tuning.md)** - Optimization strategies\n\n## 🏗️ Architecture\n\n### Core Components\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   Task Queue    │    │   Load Balancer  │    │   Worker Pool   │\n│                 │────│                  │────│                 │\n│ Priority-based  │    │ Round Robin/     │    │ Goroutines with │\n│ Lock-free Queue │    │ Weighted/Custom  │    │ Local Queues    │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n         │                        │                        │\n         └────────────────────────┼────────────────────────┘\n                                  │\n         ┌────────────────────────┼────────────────────────┐\n         │                       │                        │\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   Extensions    │    │     Monitor      │    │ Error Handler   │\n│                 │    │                  │    │                 │\n│ • Middleware    │    │ • Statistics     │    │ • Panic Recovery│\n│ • Plugins       │    │ • Health Checks  │    │ • Timeout       │\n│ • Event System  │    │ • Metrics        │    │ • Circuit Break │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n```\n\n### Key Interfaces\n\n```go\n// Core pool interface\ntype Pool interface {\n    Submit(task Task) error\n    SubmitWithTimeout(task Task, timeout time.Duration) error\n    SubmitAsync(task Task) Future\n    Shutdown(ctx context.Context) error\n    Stats() PoolStats\n    // Extension methods...\n}\n\n// Task interface - implement this for your work\ntype Task interface {\n    Execute(ctx context.Context) (any, error)\n    Priority() int\n}\n\n// Future interface for async operations\ntype Future interface {\n    Get() (any, error)\n    GetWithTimeout(timeout time.Duration) (any, error)\n    IsDone() bool\n    Cancel() bool\n}\n```\n\n## 🔧 Configuration Options\n\n| Option | Description | Default | Range |\n|--------|-------------|---------|-------|\n| `WorkerCount` | Number of worker goroutines | `10` | `1-10000` |\n| `QueueSize` | Task queue buffer size | `1000` | `1-1000000` |\n| `TaskTimeout` | Maximum task execution time | `30s` | `1s-24h` |\n| `ShutdownTimeout` | Graceful shutdown timeout | `30s` | `1s-1h` |\n| `ObjectPoolSize` | Object pool size for optimization | `100` | `0-∞` |\n| `EnableMetrics` | Enable built-in monitoring | `true` | `true/false` |\n| `MetricsInterval` | Metrics collection interval | `10s` | `1s-1h` |\n\n## 📊 Monitoring \u0026 Observability\n\n### Built-in Statistics\n\n```go\nstats := pool.Stats()\nfmt.Printf(\"Active Workers: %d\\n\", stats.ActiveWorkers)\nfmt.Printf(\"Queued Tasks: %d\\n\", stats.QueuedTasks)\nfmt.Printf(\"Completed: %d\\n\", stats.CompletedTasks)\nfmt.Printf(\"Failed: %d\\n\", stats.FailedTasks)\nfmt.Printf(\"Throughput: %.2f TPS\\n\", stats.ThroughputTPS)\nfmt.Printf(\"Avg Duration: %v\\n\", stats.AvgTaskDuration)\n```\n\n### Health Check Endpoint\n\n```go\nfunc healthHandler(w http.ResponseWriter, r *http.Request) {\n    if !pool.IsRunning() {\n        http.Error(w, \"Pool not running\", http.StatusServiceUnavailable)\n        return\n    }\n    \n    stats := pool.Stats()\n    json.NewEncoder(w).Encode(map[string]interface{}{\n        \"status\": \"healthy\",\n        \"stats\":  stats,\n    })\n}\n```\n\n## 🔌 Extensions\n\n### Middleware System\n\n```go\n// Custom middleware for logging\ntype LoggingMiddleware struct{}\n\nfunc (lm *LoggingMiddleware) Before(ctx context.Context, task Task) context.Context {\n    log.Printf(\"Task started: priority=%d\", task.Priority())\n    return context.WithValue(ctx, \"start_time\", time.Now())\n}\n\nfunc (lm *LoggingMiddleware) After(ctx context.Context, task Task, result any, err error) {\n    startTime := ctx.Value(\"start_time\").(time.Time)\n    duration := time.Since(startTime)\n    log.Printf(\"Task completed in %v\", duration)\n}\n\n// Add to pool\npool.AddMiddleware(\u0026LoggingMiddleware{})\n```\n\n### Plugin System\n\n```go\n// Custom monitoring plugin\ntype MonitoringPlugin struct {\n    name string\n    // ... implementation\n}\n\nfunc (mp *MonitoringPlugin) Name() string { return mp.name }\nfunc (mp *MonitoringPlugin) Init(pool Pool) error { /* ... */ }\nfunc (mp *MonitoringPlugin) Start() error { /* ... */ }\nfunc (mp *MonitoringPlugin) Stop() error { /* ... */ }\n\n// Register plugin\npool.RegisterPlugin(\u0026MonitoringPlugin{name: \"monitor\"})\n```\n\n## 🎯 Use Cases\n\n### Web Server Integration\n\n```go\nfunc taskHandler(w http.ResponseWriter, r *http.Request) {\n    task := \u0026BusinessTask{\n        UserID: getUserID(r),\n        Action: r.URL.Path,\n        Data:   getRequestData(r),\n    }\n    \n    future := pool.SubmitAsync(task)\n    result, err := future.GetWithTimeout(25 * time.Second)\n    \n    if err != nil {\n        http.Error(w, \"Task failed\", http.StatusInternalServerError)\n        return\n    }\n    \n    json.NewEncoder(w).Encode(result)\n}\n```\n\n### Message Queue Processing\n\n```go\ntype MessageTask struct {\n    Topic   string\n    Payload []byte\n}\n\nfunc (t *MessageTask) Execute(ctx context.Context) (any, error) {\n    switch t.Topic {\n    case \"user.created\":\n        return processUserCreated(t.Payload)\n    case \"order.placed\":\n        return processOrderPlaced(t.Payload)\n    default:\n        return nil, fmt.Errorf(\"unknown topic: %s\", t.Topic)\n    }\n}\n\nfunc (t *MessageTask) Priority() int {\n    if t.Topic == \"payment.completed\" {\n        return pool.PriorityCritical\n    }\n    return pool.PriorityNormal\n}\n```\n\n### Batch Processing\n\n```go\ntype BatchProcessor struct {\n    pool      pool.Pool\n    batchSize int\n    buffer    []Task\n}\n\nfunc (bp *BatchProcessor) Process(items []DataItem) error {\n    // Split into batches\n    for i := 0; i \u003c len(items); i += bp.batchSize {\n        end := min(i+bp.batchSize, len(items))\n        batch := items[i:end]\n        \n        task := \u0026BatchTask{Items: batch}\n        if err := bp.pool.Submit(task); err != nil {\n            return err\n        }\n    }\n    return nil\n}\n```\n\n## ⚡ Performance\n\n### Benchmarks\n\n```\nBenchmarkPoolSubmit-8           5000000    250 ns/op    48 B/op    1 allocs/op\nBenchmarkPoolSubmitAsync-8      3000000    420 ns/op    96 B/op    2 allocs/op\nBenchmarkHighConcurrency-8      1000000   1200 ns/op   128 B/op    3 allocs/op\n```\n\n### Optimization Tips\n\n1. **Worker Count**: \n   - CPU-intensive: `runtime.NumCPU()`\n   - I/O-intensive: `runtime.NumCPU() * 2-4`\n\n2. **Queue Size**: \n   - Set to `WorkerCount * 10-100` based on task duration\n\n3. **Object Pools**: \n   - Enable `PreAlloc` for high-throughput scenarios\n\n4. **Batch Processing**: \n   - Group small tasks to reduce overhead\n\n## 🛡️ Error Handling\n\n### Panic Recovery\n\n```go\ntype SafeTask struct {\n    riskyOperation func() (any, error)\n}\n\nfunc (t *SafeTask) Execute(ctx context.Context) (any, error) {\n    defer func() {\n        if r := recover(); r != nil {\n            log.Printf(\"Task panic recovered: %v\", r)\n        }\n    }()\n    \n    return t.riskyOperation()\n}\n```\n\n### Timeout Handling\n\n```go\nfunc (t *TimeoutTask) Execute(ctx context.Context) (any, error) {\n    // Check for cancellation\n    select {\n    case \u003c-ctx.Done():\n        return nil, ctx.Err()\n    default:\n    }\n    \n    // Your work here with periodic cancellation checks\n    return result, nil\n}\n```\n\n## 🔄 Graceful Shutdown\n\n```go\nfunc gracefulShutdown(pool pool.Pool) {\n    // Listen for interrupt signals\n    sigChan := make(chan os.Signal, 1)\n    signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)\n    \n    go func() {\n        \u003c-sigChan\n        log.Println(\"Shutdown signal received...\")\n        \n        // Create shutdown context with timeout\n        ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)\n        defer cancel()\n        \n        if err := pool.Shutdown(ctx); err != nil {\n            log.Printf(\"Forced shutdown: %v\", err)\n        } else {\n            log.Println(\"Graceful shutdown completed\")\n        }\n    }()\n}\n```\n\n## 🧪 Testing\n\n```go\nfunc TestPoolBasicOperations(t *testing.T) {\n    pool, err := pool.NewPool(nil)\n    require.NoError(t, err)\n    defer pool.Shutdown(context.Background())\n    \n    task := \u0026TestTask{data: \"test\"}\n    err = pool.Submit(task)\n    require.NoError(t, err)\n    \n    // Wait for completion\n    time.Sleep(100 * time.Millisecond)\n    \n    stats := pool.Stats()\n    assert.Equal(t, int64(1), stats.CompletedTasks)\n}\n```\n\n## 📈 Production Deployment\n\n### Docker Integration\n\n```dockerfile\nFROM golang:1.21-alpine AS builder\nWORKDIR /app\nCOPY . .\nRUN go build -o app ./cmd/server\n\nFROM alpine:latest\nRUN apk --no-cache add ca-certificates\nWORKDIR /root/\nCOPY --from=builder /app/app .\nEXPOSE 8080\nCMD [\"./app\"]\n```\n\n### Environment Configuration\n\n```bash\n# Pool configuration\nPOOL_WORKER_COUNT=20\nPOOL_QUEUE_SIZE=10000\nPOOL_TASK_TIMEOUT=30s\nPOOL_SHUTDOWN_TIMEOUT=60s\nPOOL_ENABLE_METRICS=true\n\n# Application configuration\nSERVER_ADDR=:8080\nLOG_LEVEL=info\n```\n\n### Kubernetes Deployment\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: goroutine-pool-app\nspec:\n  replicas: 3\n  selector:\n    matchLabels:\n      app: goroutine-pool-app\n  template:\n    metadata:\n      labels:\n        app: goroutine-pool-app\n    spec:\n      containers:\n      - name: app\n        image: your-registry/goroutine-pool-app:latest\n        ports:\n        - containerPort: 8080\n        env:\n        - name: POOL_WORKER_COUNT\n          value: \"20\"\n        - name: POOL_QUEUE_SIZE\n          value: \"10000\"\n        livenessProbe:\n          httpGet:\n            path: /health\n            port: 8080\n          initialDelaySeconds: 30\n          periodSeconds: 10\n        readinessProbe:\n          httpGet:\n            path: /ready\n            port: 8080\n          initialDelaySeconds: 5\n          periodSeconds: 5\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/uptutu/goman.git\ncd goman\n\n# Install dependencies\ngo mod download\n\n# Run tests\ngo test ./...\n\n# Run benchmarks\ngo test -bench=. ./pkg/pool\n\n# Run with race detection\ngo test -race ./...\n```\n\n### Code Quality\n\n- **Test Coverage**: Maintain \u003e90% test coverage\n- **Benchmarks**: Include benchmarks for performance-critical code\n- **Documentation**: Update docs for API changes\n- **Linting**: Use `golangci-lint` for code quality\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Inspired by Java's ThreadPoolExecutor and .NET's Task Parallel Library\n- Built with Go's excellent concurrency primitives\n- Community feedback and contributions\n\n## 📞 Support\n\n- **Issues**: [GitHub Issues](https://github.com/uptutu/goman/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/uptutu/goman/discussions)\n- **Documentation**: [docs/](docs/)\n\n---\n\n**Made with ❤️ for the Go community**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuptutu%2Fgoman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuptutu%2Fgoman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuptutu%2Fgoman/lists"}