partition_supervisor (ex_stdlib v0.3.0)
View SourcePartitionSupervisor implementation inspired by Elixir's PartitionSupervisor.
A PartitionSupervisor is a supervisor that manages multiple partitions of the same child specification. It's designed for high-concurrency scenarios where you want to distribute work across multiple instances of the same process type.
Each partition runs as a separate DynamicSupervisor, and work is distributed across partitions using a hash function on a partition key.
Examples:
% Start a partition supervisor with 4 partitions
{ok, Pid} = partition_supervisor:start_link([
{partitions, 4},
{child_spec, #{id => worker, start => {worker, start_link, []}}}
]),
% Start a child in a specific partition
{ok, ChildPid} = partition_supervisor:start_child(Pid, user_123, [arg1, arg2]).Summary
Functions
Returns a count of children in all partitions.
Returns a count of children in a specific partition.
Returns the partition index for the given partition key.
Returns the number of partitions in the supervisor.
Starts a child in the partition determined by the partition key.
Starts a child in the partition determined by the partition key with options.
Starts a PartitionSupervisor with the given options.
Starts a named PartitionSupervisor with the given options.
Synchronously stops the partition supervisor with reason normal.
Synchronously stops the partition supervisor with the given reason.
Synchronously stops the partition supervisor with the given reason and timeout. All partitions and their children are shut down first.
Terminates a child in the partition determined by the partition key.
Terminates a child in a specific partition.
Returns the PID of a child process by partition key.
Returns information about all children in all partitions.
Returns information about children in a specific partition.
Types
-type partition_index() :: non_neg_integer().
-type partition_key() :: term().
-type partition_options() :: #{partitions := pos_integer(), child_spec := supervisor:child_spec(), hash_function => fun((partition_key()) -> non_neg_integer()), name => atom()}.
Functions
-spec count_children(pid() | atom()) -> [{specs | active | supervisors | workers, non_neg_integer()}].
Returns a count of children in all partitions.
Returns a property list with counts of active, specs, supervisors, and workers.
-spec count_children(pid() | atom(), partition_index()) -> #{specs := non_neg_integer(), active := non_neg_integer(), supervisors := non_neg_integer(), workers := non_neg_integer()}.
Returns a count of children in a specific partition.
Returns a property list with counts of active, specs, supervisors, and workers.
-spec partition_for(pid() | atom(), partition_key()) -> partition_index().
Returns the partition index for the given partition key.
Uses the configured hash function to determine the partition.
-spec partitions(pid() | atom()) -> pos_integer().
Returns the number of partitions in the supervisor.
-spec start_child(pid() | atom(), partition_key(), [term()]) -> {ok, pid()} | {ok, pid(), term()} | {error, term()}.
Starts a child in the partition determined by the partition key.
The partition is selected using the hash function on the partition key.
-spec start_child(pid() | atom(), partition_key(), [term()], [term()]) -> {ok, pid()} | {ok, pid(), term()} | {error, term()}.
Starts a child in the partition determined by the partition key with options.
Additional options can be passed to modify the child spec.
-spec start_link(partition_options()) -> {ok, pid()} | {error, term()}.
Starts a PartitionSupervisor with the given options.
Options: - partitions: Number of partitions to create (required) - child_spec: Child specification for each partition (required) - hash_function: Custom hash function (optional, defaults to erlang:phash2/2)
-spec start_link(atom(), partition_options()) -> {ok, pid()} | {error, term()}.
Starts a named PartitionSupervisor with the given options.
The supervisor will be registered under the given name.
Synchronously stops the partition supervisor with reason normal.
Synchronously stops the partition supervisor with the given reason.
Synchronously stops the partition supervisor with the given reason and timeout. All partitions and their children are shut down first.
Terminates a child in the partition determined by the partition key.
The child is identified by its PID.
-spec terminate_child(pid() | atom(), partition_index(), pid()) -> ok | {error, term()}.
Terminates a child in a specific partition.
The child is identified by its PID and the partition is specified directly.
-spec whereis_name(pid() | atom(), partition_key()) -> pid() | undefined.
Returns the PID of a child process by partition key.
This is useful for direct communication with processes in specific partitions.
-spec which_children(pid() | atom()) -> [{term(), pid() | undefined, worker | supervisor, [atom()] | dynamic}].
Returns information about all children in all partitions.
Returns a list of {Id, Child, Type, Modules} tuples for all children.
-spec which_children(pid() | atom(), partition_index()) -> [{term(), pid() | undefined, worker | supervisor, [atom()] | dynamic}].
Returns information about children in a specific partition.
Returns a list of {Id, Child, Type, Modules} tuples for children in the partition.