A supervisor that starts multiple partitions of the same child.

Certain processes may become bottlenecks in large systems. If those processes can have their state trivially partitioned, in a way there is no dependency between them, then they can use the PartitionSupervisor to create multiple isolated and independent partitions.

Once the PartitionSupervisor starts, you can dispatch to its children using {:via, PartitionSupervisor, {name, key}}, where name is the name of the PartitionSupervisor and key is used for routing.

This module was introduced in Elixir v1.14.0.

Simple Example

Let's start with an example which is not useful per se, but shows how the partitions are started and how messages are routed to them.

Here's a toy GenServer that simply collects the messages it's given. It prints them for easy illustration.

defmodule Collector do
  use GenServer

  def start_link(args) do
    GenServer.start_link(__MODULE__, args)
  end

  def init(args) do
    IO.inspect([__MODULE__, " got args ", args, " in ", self()])
    {:ok, _initial_state = []}
  end

  def collect(server, msg) do
    GenServer.call(server, {:collect, msg})
  end

  def handle_call({:collect, msg}, _from, state) do
    new_state = [msg | state]
    IO.inspect(["current messages:", new_state, " in process", self()])
    {:reply, :ok, new_state}
  end
end

To run multiple of these, we can start them under a PartitionSupervisor by placing this in our supervision tree:

{PartitionSupervisor,
  child_spec: Collector.child_spec([some: :arg]),
  name: MyApp.PartitionSupervisor
}

We can send messages to them using a "via tuple":

# The key is used to route our message to a particular instance.
key = 1
Collector.collect({:via, PartitionSupervisor, {MyApp.PartitionSupervisor, key}}, :hi)
# ["current messages:", [:hi], " in process", #PID<0.602.0>]
:ok
Collector.collect({:via, PartitionSupervisor, {MyApp.PartitionSupervisor, key}}, :ho)
# ["current messages:", [:ho, :hi], " in process", #PID<0.602.0>]
:ok

# With a different key, the message will be routed to a different instance.
key = 2
Collector.collect({:via, PartitionSupervisor, {MyApp.PartitionSupervisor, key}}, :a)
# ["current messages:", [:a], " in process", #PID<0.603.0>]
:ok
Collector.collect({:via, PartitionSupervisor, {MyApp.PartitionSupervisor, key}}, :b)
# ["current messages:", [:b, :a], " in process", #PID<0.603.0>]
:ok

Now let's move on to a useful example.

DynamicSupervisor Example

The DynamicSupervisor is a single process responsible for starting other processes. In some applications, the DynamicSupervisor may become a bottleneck. To address this, you can start multiple instances of the DynamicSupervisor through a PartitionSupervisor, and then pick a "random" instance to start the child on.

Instead of starting a single DynamicSupervisor:

children = [
  {DynamicSupervisor, name: MyApp.DynamicSupervisor}
]

Supervisor.start_link(children, strategy: :one_for_one)

and starting children on that dynamic supervisor directly:

DynamicSupervisor.start_child(MyApp.DynamicSupervisor, {Agent, fn -> %{} end})

You can start the dynamic supervisors under a PartitionSupervisor:

children = [
  {PartitionSupervisor,
   child_spec: DynamicSupervisor,
   name: MyApp.DynamicSupervisors}
]

Supervisor.start_link(children, strategy: :one_for_one)

and then:

DynamicSupervisor.start_child(
  {:via, PartitionSupervisor, {MyApp.DynamicSupervisors, self()}},
  {Agent, fn -> %{} end}
)

In the code above, we start a partition supervisor that will by default start a dynamic supervisor for each core in your machine. Then, instead of calling the DynamicSupervisor by name, you call it through the partition supervisor using the {:via, PartitionSupervisor, {name, key}} format. We picked self() as the routing key, which means each process will be assigned one of the existing dynamic supervisors. See start_link/1 to see all options supported by the PartitionSupervisor.

Implementation notes

The PartitionSupervisor uses either an ETS table or a Registry to manage all of the partitions. Under the hood, the PartitionSupervisor generates a child spec for each partition and then acts as a regular supervisor. The ID of each child spec is the partition number.

For routing, two strategies are used. If key is an integer, it is routed using rem(abs(key), partitions) where partitions is the number of partitions. Otherwise it uses :erlang.phash2(key, partitions). The particular routing may change in the future, and therefore must not be relied on. If you want to retrieve a particular PID for a certain key, you can use GenServer.whereis({:via, PartitionSupervisor, {name, key}}).