workerpool

type Config struct {
	// WorkerCount is the number of workers in the pool.
	WorkerCount int

	// QueueSize is the maximum number of tasks that can be queued.
	// If 0, uses a reasonable default based on worker count.
	QueueSize int

	// TaskTimeout is the default timeout for individual task execution.
	// Zero means no timeout.
	TaskTimeout time.Duration
}

type Pool interface {
	// Submit adds a task to the pool for execution.
	// The task will be executed with context.Background().
	// Use SubmitWithContext to provide a custom context.
	Submit(task Task) error

	// SubmitWithContext adds a task to the pool for execution with the given context.
	// The context is passed to the task's Execute method, enabling timeout and
	// cancellation propagation. If the pool has a TaskTimeout configured, the
	// effective timeout will be the minimum of the context deadline and TaskTimeout.
	SubmitWithContext(ctx context.Context, task Task) error

	// Results returns a channel of task results.
	Results() <-chan Result

	// Shutdown initiates a graceful shutdown of the pool.
	Shutdown() <-chan struct{}

	// Size returns the number of workers in the pool.
	Size() int

	// QueueSize returns the current number of queued tasks.
	QueueSize() int
}

type Result struct {
	// Task is the original task that was executed
	Task Task

	// Error is any error that occurred during task execution
	Error error

	// Duration is how long the task took to execute
	Duration time.Duration

	// WorkerID identifies which worker executed the task
	WorkerID int
}

type Task interface {
	// Execute runs the task with the given context.
	// It should respect context cancellation and return any error encountered.
	Execute(ctx context.Context) error
}

type TaskFunc func(ctx context.Context) error