@spec await(function() | {:error, term()}) ::
  {:ok, [start_result() | stop_result()]}
  | {:error,
     {[start_failure() | stop_failure()], [start_result() | stop_result()]}}
  | {:error,
     {[start_failure() | stop_failure()], [start_result() | stop_result()]},
     :rollback}

This function can be used to wait for the ProcessHub child start or stop functions to complete.

The await/1 function should be used with the async_wait: true option.

Keep in mind that the await/1 function will block the calling process until the response is received. If the response is not received within the timeout period, the function will return {:error, term()}.

Example

iex> ref = ProcessHub.start_child(:my_hub, child_spec, [async_wait: true])
iex> ProcessHub.await(ref)
{:ok, {:my_child, [{:mynode, #PID<0.123.0>}]}}

@spec child_lookup(hub_id(), child_id()) :: {child_spec(), [{node(), pid()}]} | nil

Returns information about processes that are registered with the given child_id/0.

This function queries results from the local ets table and does not make any network calls.

The return results contain the child_spec/0 and a list of tuples where the first element is the node where the child is started, and the second element is the pid() of the started child.

Example

iex> {_child_spec, _node_pid_tuples} = ProcessHub.child_lookup(:my_hub, :my_child)
{%{id: :my_child, start: {MyProcess, :start_link, []}}, [{:mynode, #PID<0.123.0>}]}

@spec child_spec(t()) :: %{
  id: ProcessHub,
  start: {ProcessHub.Initializer, :start_link, [...]},
  type: :supervisor
}

Returns the child specification for the ProcessHub.Initializer supervisor.

@spec get_pid(hub_id(), child_id()) :: pid() | nil

Returns the first pid for the given child_id.

Although the function can be handy to quickly get the pid of the child, it is not recommended to use with replication strategies as it will return the first pid only.

Example

iex> ProcessHub.get_pid(:my_hub, :my_child)
#PID<0.123.0>

@spec get_pids(hub_id(), child_id()) :: [pid()]

Returns a list of pids for the given child_id.

Example

iex> ProcessHub.get_pids(:my_hub, :my_child)
[#PID<0.123.0>]

@spec is_alive?(hub_id()) :: boolean()

Checks if the ProcessHub with the given hub_id/0 is alive.

A hub is considered alive if the ProcessHub.Initializer supervisor process is running along with the required child processes for the hub to function.

Example

iex> ProcessHub.is_alive?(:not_existing)
false

@spec is_locked?(hub_id()) :: boolean()

Checks if the ProcessHub with the given hub_id/0 is locked.

A hub is considered locked if the ProcessHub local event queue has a priority level greater than or equal to 10. This is used to throttle the hub from processing any new events and conserve data integrity.

Example

iex> ProcessHub.is_locked?(:my_hub)
false

@spec is_partitioned?(hub_id()) :: boolean()

Checks if the ProcessHub with the given hub_id/0 is in a network-partitioned state.

A hub is considered partitioned if the ProcessHub.Strategy.PartitionTolerance strategy has detected a network partition. When a network partition is detected, the hub will terminate the ProcessHub.DistributedSupervisor process along with its children.

Example

iex> ProcessHub.is_partitioned?(:my_hub)
false

@spec nodes(hub_id(), [:include_local] | nil) :: [node()]

Returns a list of nodes where the ProcessHub with the given hub_id/0 is running.

Nodes where the ProcessHub is running with the same hub_id/0 are considered to be part of the same cluster.

Example

iex> ProcessHub.nodes(:my_hub, [:include_local])
[:remote_node]

@spec process_list(hub_id(), :global | :local) :: [
  {child_id(), [{node(), pid()}] | pid()}
]

Returns a list of processes that are registered.

The process list contains the child_id/0 and depending on the scope option, it may contain the node and pid() of the child.

This function queries results from the local ets table and does not make any network calls.

Available options:

• :global - returns a list of all child processes on all nodes in the cluster. The return result will be in the format of [{child_id, [{:node, pid}]}].
• :local - returns a list of child processes that belong to the local node. The return result will be in the format of [{child_id, [pid]}] but only the processes that belong to the local node will be returned.

Example

iex> ProcessHub.process_list(:my_hub, :global)
[
  {:my_child1, [{:node1, #PID<0.123.0>}, {:node2, #PID<2.123.0>}]},
  {:my_child2, [{:node2, #PID<5.124.0>}]}
]
iex> ProcessHub.process_list(:my_hub, :local)
[{:my_child1, #PID<0.123.0>}]

@spec process_registry(hub_id()) :: ProcessHub.Service.ProcessRegistry.registry()

Returns all information in the registry.

This function queries results from the local ets table and does not make any network calls.

Promotes the ProcessHub with the given hub_id/0 to a node.

This function should be used when the ProcessHub has been started in a non-node mode and you want to promote it to a node.

The function will update all existing child processes on the registry to match the new node name.

Optionally, you can pass the node_name argument to specify the name of the node. By default, the current node name will be used.

@spec start_child(hub_id(), child_spec(), init_opts()) ::
  {:ok, :start_initiated}
  | {:error, :no_children | {:already_started, [atom() | binary(), ...]}}
  | (-> {:ok, start_result()})
  | (-> {:error, start_failure()}
        | {:error, start_failure(), start_result(), :rollback})

Starts a child process that will be distributed across the cluster. The t:child_spec() :id must be unique.

Example

iex> child_spec = %{id: :my_child, start: {MyProcess, :start_link, []}}
iex> ProcessHub.start_child(:my_hub, child_spec)
{:ok, :start_initiated}

By default, the start_child/3 function is asynchronous and returns immediately. To wait for the child to start, you can pass async_wait: true to the opts argument. When async_wait: true, you must await the response from the function.

See init_opts/0 for more options.

Example with synchronous wait

The synchronous response includes the status code :ok or :error, a tuple containing the child_id/0 and a list of tuples where the first key is the node where the child is started, and the second key is the pid() of the started child. By default, the list should contain only one tuple, but if the redundancy strategy is configured for replicas, it may contain more than one tuple.

iex> child_spec = %{id: :my_child, start: {MyProcess, :start_link, []}}
iex> ProcessHub.start_child(:my_hub, child_spec, [async_wait: true]) |> ProcessHub.await()
{:ok, {:my_child, [{:mynode, #PID<0.123.0>}]}}

@spec start_children(hub_id(), [child_spec()], init_opts()) ::
  {:ok, :start_initiated}
  | {:error,
     :no_children
     | {:error, :children_not_list}
     | {:already_started, [atom() | binary(), ...]}}
  | (-> {:ok, [start_result()]})
  | (-> {:error, [start_failure()], [start_result()]}
        | {:error, [start_failure()], [start_result()], :rollback})

Starts multiple child processes that will be distributed across the cluster.

Same as start_child/3, except it starts multiple children at once and is more efficient than calling start_child/3 multiple times.

Warning

Using start_children/3 with async_wait: true can lead to timeout errors, especially when the number of children is large. When async_wait: true, you must await the response from the function.

@spec start_link(t()) :: {:ok, pid()} | {:error, term()}

Starts the ProcessHub with the given hub_id/0 and settings.

It is recommended to start the ProcessHub under a supervision tree.

@spec stop(atom()) :: :ok | {:error, :not_alive}

Stops the ProcessHub with the given hub_id/0.

@spec stop_child(hub_id(), child_id(), stop_opts()) ::
  {:ok, :stop_initiated}
  | (-> {:ok, stop_result()})
  | (-> {:error, stop_failure()})

Stops a child process in the cluster.

By default, this function is asynchronous and returns immediately. You can wait for the child to stop by passing async_wait: true in the opts argument. When async_wait: true, you must await the response from the function.

Example

iex> ProcessHub.stop_child(:my_hub, :my_child)
{:ok, :stop_initiated}

See stop_opts/0 for more options.

Example with synchronous wait

iex> ProcessHub.stop_child(:my_hub, :my_child, [async_wait: true]) |> ProcessHub.await()
{:ok, {:my_child, [:mynode]}}

@spec stop_children(hub_id(), [child_id()], stop_opts()) ::
  {:ok, :stop_initiated}
  | {:error, list()}
  | (-> {:ok, [stop_result()]})
  | (-> {:error, [stop_failure()], [stop_result()]})

Stops multiple child processes in the cluster.

This function is similar to stop_child/3, but it stops multiple children at once, making it more efficient than calling stop_child/3 multiple times.

Warning

Using stop_children/3 with async_wait: true can lead to timeout errors, especially when stopping a large number of child processes.

@spec which_children(hub_id(), [:global | :local] | nil) ::
  list()
  | {node(),
     [
       {any(), :restarting | :undefined | pid(), :supervisor | :worker,
        :dynamic | list()}
     ]}

Works similarly to Supervisor.which_children/1, but wraps the result in a tuple containing the node name and the children.

Info

The Supervisor.which_children/1 function is known to consume a lot of memory and this can affect performance. The problem is even more relevant when using the :global option as it will make a network call to all nodes in the cluster.

It is highly recommended to use ProcessHub.process_list/2 instead.

Available options:

• :global - returns a list of all child processes started by all nodes in the cluster. The return result will be in the format of [{:node, children}].
• :local - returns a list of all child processes started by the local node. The return result will be in the format of {:node, children}.