partition_supervisor (ex_stdlib v0.2.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.
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.
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.