@spec bulk_delete(
  ProcessHub.hub_id(),
  [{ProcessHub.child_id(), [node()]}],
  keyword()
) :: :ok

Deletes information about multiple child processes from the registry.

Hook Behavior

This function will dispatch the :child_unregistered_hook hook for each child process if the :hook_storage option is provided. If :hook_storage is nil or not provided, no hooks will be fired.

Options

• :hook_storage - Hook storage to use for dispatching hooks (default: nil)
• :timeout - GenServer call timeout in milliseconds (default: 10_000)

Parameters

• hub_id - The hub identifier
• children - List of child_id with nodes to remove
• opts - Options keyword list

@spec bulk_insert(
  ProcessHub.hub_id(),
  %{
    required(ProcessHub.child_id()) =>
      {ProcessHub.child_spec(), [{node(), pid()}], metadata()}
  },
  keyword()
) :: :ok

Inserts information about multiple child processes into the registry.

Hook Behavior

This function will dispatch the :child_registered_hook hook for each child process if the :hook_storage option is provided. If :hook_storage is nil or not provided, no hooks will be fired.

Options

• :hook_storage - Hook storage to use for dispatching hooks (default: nil)
• :timeout - GenServer call timeout in milliseconds (default: 10_000)

Parameters

• hub_id - The hub identifier
• children - Map of child_id to {child_spec, node_pids, metadata} tuples
• opts - Options keyword list

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec clear_all(ProcessHub.hub_id()) :: boolean()

Deletes all objects from the process registry.

@spec contains_children(ProcessHub.hub_id(), [ProcessHub.child_id()]) :: [
  ProcessHub.child_id()
]

Returns a list of child_ids that match the given child_ids variable.

@spec delete(ProcessHub.hub_id(), ProcessHub.child_id(), keyword() | nil) :: :ok

Deletes information about a child process from the registry.

Hook Behavior

This function will dispatch the :child_unregistered_hook hook if the :hook_storage option is provided. If :hook_storage is nil or not provided, no hooks will be fired.

Options

• :hook_storage - Hook storage to use for dispatching hooks (default: nil)

@spec dump(ProcessHub.hub_id()) :: registry_dump()

Dumps the whole registry.

Returns all information about all registered processes including metadata. Entries with empty node lists are excluded.

@spec dump_all(ProcessHub.hub_id()) :: registry_dump()

Dumps the whole registry including entries with empty node lists.

Unlike dump/1, this includes all entries regardless of their node list, such as pending forwarding entries and TTL tombstone entries.

@spec entry_exists?(ProcessHub.hub_id(), ProcessHub.child_id()) :: boolean()

Checks whether an entry exists in the registry for the given child_id.

Unlike lookup/2, this returns true even for entries with empty node lists (e.g., pending forwarding entries or TTL tombstone entries).

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

Returns the first pid for the given child_id.

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

Returns a list of pids for the given child_id.

@spec insert(
  ProcessHub.hub_id(),
  ProcessHub.child_spec(),
  [{node(), pid()}],
  keyword() | nil
) :: :ok

Inserts information about a child process into the registry.

Hook Behavior

This function will dispatch the :child_registered_hook hook if the :hook_storage option is provided. If :hook_storage is nil or not provided, no hooks will be fired.

Options

• :metadata - Additional metadata to store with the process (default: %{})
• :table - Alternative table to use for storage (default: hub_id)
• :hook_storage - Hook storage to use for dispatching hooks (default: nil)

@spec local_child_specs(ProcessHub.hub_id()) :: [ProcessHub.child_spec()]

Returns a list of child specs registered under the local node.

@spec local_children(ProcessHub.hub_id()) :: %{
  required(ProcessHub.child_id()) =>
    {ProcessHub.child_spec(), [{node(), pid()}], metadata()}
}

Returns all children that are running on the local node.

Returns a map of child_id to {child_spec, node_pids, metadata} tuples for all children where the local node has a running process.

@spec local_data(ProcessHub.hub_id()) :: [
  {ProcessHub.child_id(), {ProcessHub.child_spec(), [{node(), pid()}]}}
]

Returns information on all processes that are running on the local node.

@spec local_pid(ProcessHub.hub_id(), ProcessHub.child_id()) :: pid() | nil

Returns the local pid for the given child_id, or nil if not found on local node.

@spec lookup(
  ProcessHub.hub_id(),
  ProcessHub.child_id(),
  keyword()
) ::
  {ProcessHub.child_spec(), [{node(), pid()}]}
  | {ProcessHub.child_spec(), [{node(), pid()}], ProcessHub.child_metadata()}
  | nil

Return the child_spec, nodes, and pids for the given child_id.

@spec match_tag(ProcessHub.hub_id(), String.t()) :: [
  {ProcessHub.child_id(), [{node(), pid()}]}
]

Returns all children that match the given tag.

@spec registry(ProcessHub.hub_id()) :: registry()

Returns information about all registered processes. Will be deprecated in the future.

@spec update(ProcessHub.hub_id(), ProcessHub.child_id(), function()) ::
  :ok | {:error, String.t()}

Updates the row on the registry.

Hook Behavior

This function intentionally skips hook dispatching during the update operation to avoid duplicate or conflicting hook events. Updates are performed as atomic operations.

Parameters

The update_fn must be a function that accepts 3 parameters containing the existing values:

• child_spec - the child specification in map format.
• node_pids - a keyword list containing a list of node pid pairs. Example: [{:mynode, pid()}]
• metadata- a map containing the additional information.

The function should return a tuple in the following format: {child_spec, node_pids, metadata} and those values will be then used to update the row.

Return Values

• :ok - On successful update
• {:error, "No child found"} - If no child is found for the given child_id
• {:error, "Invalid arguments returned from the update function"} - If the update function returns invalid data

Important

Use this function with care as any invalid data may corrupt the registry.