A process that manages a pool of persistent gRPC channels.

When ConnGRPC.Pool is started, it will start a pool of pre-connected channels. You can then fetch an individual channel from it by calling ConnGRPC.Pool.get_channel/1, which uses round-robin to determine the channel returned.

ConnGRPC.Pool doesn't implement any checkout mechanism and acts as a routing pool, or a simple load balancer. The reason checkout is not implemented is because gRPC allows making multiple requests in parallel in a single channel, so we don't need to lock the channel to a specific process while it's being used.

module-based-pool

Module-based pool

To implement a module-based gRPC pool, define a module that uses ConnGRPC.Pool.

defmodule DemoPool do
  use ConnGRPC.Pool,
    pool_size: 5,
    channel: [address: "localhost:50051", opts: []]
end

You can also use the :otp_app option to load configuration from your application's config:

defmodule DemoPool do
  use ConnGRPC.Pool, otp_app: :my_app
end

This will load configuration from Application.get_env(:my_app, DemoPool, []) and merge it with the options passed to child_spec/1.

Then configure it in your config/runtime.exs:

import Config

config :my_app, DemoPool,
  pool_size: String.to_integer(System.get_env("GRPC_POOL_SIZE", "5")),
  channel: [
    address: System.fetch_env!("GRPC_ADDRESS"),
    opts: []
  ]

The format of address and opts is the same used by GRPC.Stub.connect/2

Then, you can add the module to your application supervision tree.

defmodule Demo.Application do
  use Application

  @impl true
  def start(_type, _args) do
    children = [
      DemoPool
    ]

    Supervisor.start_link(children, strategy: :one_for_one, name: Demo.Supervisor)
  end
end

To get a connection from the pool in your application, call:

DemoPool.get_channel()

It'll return either {:ok, channel} or {:error, :not_connected}.

pool-without-module

Pool without module

If you don't want to define a module for your pool, you can add ConnGRPC.Pool directly to your supervision tree and pass the options on the child spec.

defmodule Demo.Application do
  use Application

  @impl true
  def start(_type, _args) do
    children = [
      Supervisor.child_spec(
        {ConnGRPC.Pool, name: :demo_pool, pool_size: 5, channel: [address: "localhost:50051", opts: []]},
        id: :demo_pool
      )
    ]

    Supervisor.start_link(children, strategy: :one_for_one, name: Demo.Supervisor)
  end
end

The format of address and opts is the same used by GRPC.Stub.connect/2

To get a connection from the pool in your application, call:

ConnGRPC.Pool.get_channel(:demo_pool)

options-available

Options available

For all options available, see start_link/1.

telemetry

Telemetry

ConnGRPC sends telemetry events. See telemetry.md.