Generic worker pool for executing tasks asynchronously.

This module provides a pooling mechanism for executing async and stream tasks without spawning unlimited processes. Workers are supervised and reused across multiple requests.

Architecture

The worker pool consists of:

• A pool of worker processes (GenServers)
• A queue for pending tasks when all workers are busy
• A supervisor managing the worker processes
• Pool-level circuit breaker for fault tolerance

Configuration

Configure pool sizes in your config.exs:

config :phoenix_gen_api, :worker_pool,
  async_pool_size: 100,
  stream_pool_size: 50,
  max_queue_size: 1000,
  task_timeout: 30_000

Usage

# Execute a task asynchronously
WorkerPool.execute_async(:async_pool, fn ->
  # Your async work here
  result = process_data()
  send(caller_pid, {:result, result})
end)

# Execute a stream task
WorkerPool.execute_async(:stream_pool, fn ->
  # Your stream work here
  StreamCall.handle_stream(request, config)
end)

Worker States

Each worker can be in one of two states:

• :idle - Available to accept new work
• :busy - Currently executing a task

Queue Management

When all workers are busy, tasks are queued. If the queue exceeds the max size, new tasks will be rejected to prevent memory exhaustion.

Circuit Breaker

The pool tracks consecutive failures across all workers. If the failure rate exceeds the threshold, the pool enters a degraded state and rejects new tasks for a cooldown period.

Supervision

Workers are supervised and automatically restarted on failure. Failed tasks are not retried automatically - the caller should handle failures.