Core / Worker Pool

[char2cs]

Feature Description

Implement a generic worker pool system to manage concurrent task execution with configurable worker count, task queuing, and lifecycle management.

Problem Statement

The system lacks a unified way to handle concurrent operations. Without a worker pool, operations run sequentially or use ad-hoc goroutines, leading to resource contention, unbounded concurrency, and difficulty managing task lifecycles. This limits scalability and control over concurrent operations like arrow installations, quiver management, and batch processing.

Proposed Solution

Implement a generic worker pool system that:

• Manages a configurable number of worker goroutines
• Queues tasks for execution with priority support
• Provides lifecycle management (start, stop, graceful shutdown)
• Handles task errors and retries
• Supports context cancellation and timeouts

Key elements:

• Generic worker pool interface and implementation
• Task interface for pluggable work items
• Queue management (FIFO with optional priority)
• Worker lifecycle and graceful shutdown
• Integration hooks for existing operations

Alternative Solutions

• Ad-hoc goroutines: No control over concurrency limits, harder to manage
• Fixed goroutine pools per operation: Duplicates logic, less flexible
• External job queue (Redis, RabbitMQ): Adds infrastructure complexity; start with in-memory pool

Use Cases

1. Concurrent arrow installations: Process multiple arrow installs in parallel with controlled concurrency
2. Batch quiver operations: Start/stop multiple quivers concurrently with worker limits
3. Background processing: Queue long-running tasks (updates, validations) for background execution
4. Resource management: Limit concurrent operations to prevent system overload
5. Task prioritization: Process high-priority tasks (user-initiated) before background tasks

Acceptance Criteria

• Generic worker pool interface with Start(), Stop(), Submit(task), SubmitWithPriority(task, priority) methods
• Configurable worker count and queue size
• Task interface for pluggable work execution
• Graceful shutdown: finish in-flight tasks, drain queue
• Context support for cancellation and timeouts
• Error handling and optional retry mechanism
• Metrics hooks for queue depth, active workers, completed/failed tasks
• Unit tests for worker pool lifecycle, task execution, and shutdown
• Concurrency tests for worker limits and queue behavior
• Integration example with existing operations (arrow install, quiver start)

Additional Context

• Worker pool should be generic and reusable across different operation types
• Consider thread-safety for concurrent task submission
• Configuration should allow tuning worker count per use case
• Integration with existing context propagation patterns
• Optional: task result channels for async result retrieval

Implementation Notes

• Worker pool structure:

  • Interface: WorkerPool with Start(), Stop(), Submit(task), Stats()
  • Implementation: Configurable worker count, buffered task queue
  • Task interface: Task with Execute(ctx) error method

• Queue management:

  • Buffered channel for task queue
  • Optional priority queue for task ordering
  • Queue size limits to prevent unbounded memory growth

• Lifecycle:

  • Start(): Spawn worker goroutines
  • Stop(): Signal shutdown, wait for in-flight tasks, drain queue
  • Graceful shutdown with configurable timeout

• Integration:

  • Create worker pool instances in composition root (internal/internal.go)
  • Use for concurrent arrow operations, quiver management, batch processing
  • Pass context through task execution for cancellation

• Testing:

  • Unit tests for worker pool start/stop, task submission
  • Concurrency tests verifying worker limits
  • Graceful shutdown tests
  • Error handling and retry tests

• Future enhancements:

  • Task result channels
  • Dynamic worker scaling
  • Task scheduling (delayed execution)