# `Portals.Pool`
[🔗](https://github.com/Ziinc/portals/blob/v0.1.0/lib/portals/pool.ex#L1)

A supervised, load-balanced set of workers running the same command
(FR-3). Maintains `size` base workers plus up to `max_overflow`
temporary overflow workers, created on demand and retired as soon as
they go idle.

Workers are not checked out exclusively: each worker can serve many
concurrent in-flight calls (bounded by its own SDK-advertised
`max_concurrency`), so "checkout" here means *selecting* a worker with
spare capacity via least-in-flight scheduling (round-robin among ties),
not reserving it. When every worker (base and overflow) is already at
capacity and `max_overflow` is exhausted, new calls block for up to
`checkout_timeout` before failing with `%Portals.Error{kind:
:checkout_timeout}`. Execution timeout (the `:timeout` given to
`call/5`/`async/5`) only starts once a worker is actually selected and
the call is dispatched to it — it is completely independent of how
long checkout itself took.

# `start_opts`

```elixir
@type start_opts() :: [
  command: binary(),
  args: [binary()],
  size: pos_integer(),
  max_overflow: non_neg_integer(),
  checkout_timeout: timeout(),
  name: GenServer.name()
]
```

# `async`

```elixir
@spec async(GenServer.server(), binary(), binary(), list(), keyword()) ::
  {:ok, Portals.Request.t()} | {:error, Portals.Error.t()}
```

# `await`

```elixir
@spec await(Portals.Request.t(), timeout()) ::
  {:ok, term()} | {:error, Portals.Error.t()}
```

# `call`

```elixir
@spec call(GenServer.server(), binary(), binary(), list(), keyword()) ::
  {:ok, term()} | {:error, Portals.Error.t()}
```

# `call!`

```elixir
@spec call!(GenServer.server(), binary(), binary(), list(), keyword()) :: term()
```

# `cancel`

```elixir
@spec cancel(Portals.Request.t()) :: :ok
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `health`

```elixir
@spec health(GenServer.server()) :: map()
```

# `start_link`

```elixir
@spec start_link(start_opts()) :: GenServer.on_start()
```

# `stop`

```elixir
@spec stop(GenServer.server(), timeout()) :: :ok
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*