@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.

Rows are never removed here — only the named nodes' entries are.

Options

• :hook_storage - Hook storage to use for dispatching hooks (default: nil)
• :timeout - GenServer call timeout in milliseconds (default: 10_000)
• :on_empty - what becomes of a row that just lost its last node entry:
  • :churn (default) - a stub with a 30 s expiry. For placement churn, where a re-registration from the child's new node is expected imminently.
  • :delete - the row is removed entirely, for a deliberate stop. Stop memory for declared children lives in the declared list, not in the row.
  • :keep - an unbound row with no expiry, for a withdrawn observation. The row is kept rather than erased on someone else's say-so.

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 delete_if_expired(ProcessHub.hub_id(), ProcessHub.child_id()) :: boolean()

Deletes a TTL registry entry, but only if it is still expired.

Expiry is re-validated inside the registry process. If the entry was re-populated since the caller observed it (re-population clears the TTL, turning the row into a permanent 2-tuple) or was given a fresh TTL lease, the delete is skipped. This closes a race where the janitor's registry scan sees an expired stub, but an incoming registration re-populates the entry before the delete is applied — without this guard the cleanup would wipe a freshly re-registered live process.

Returns true if the entry was removed, false otherwise.

@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(),
  keyword()
) :: 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 churn stubs.

Options

• :include_unbound - when false, rows with an empty node list are left out (default: true). This is what dump/1 asks for.

@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 churn stubs).

@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: %{}). The reserved :__process_hub__ key is hub-owned: a caller-supplied value is ignored with a WARN log.
• :table - Alternative table to use for storage (default: hub_id)
• :hook_storage - Hook storage to use for dispatching hooks (default: nil)
• :adopt - When true, the :__process_hub__ map inside :metadata is written verbatim instead of being re-authored. Reserved for the replica merge, which adopts the winner of an epoch comparison rather than authoring a new value (default: false).
• :durable - Marks the row's child as declared (durable: true start); the flag is carried in the hub-owned bookkeeping and survives subsequent writes.

@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.

Options

• :table - alternative table to read from (default: hub_id)
• :with_metadata - include the metadata map in the returned tuple (default: false)
• :include_empty - also return rows whose node_pids list is empty — pending-forward rows and rows whose last observation was withdrawn (default: false, which reports them as absent)

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

Returns every child whose registry metadata carries key, with that key's value: [{child_id, node_pids, value}]. An ETS match over the rows, no row decoding — match_tag/2 generalised to any metadata key and any value.

@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. Deprecated, use dump/1 instead.

@spec update(ProcessHub.hub_id(), ProcessHub.child_id(), function(), keyword()) ::
  :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.

Options

• :propagate - When true, after the local update succeeds the same update_fn is applied on every other hub node's registry (best-effort: unreachable peers are logged and skipped; they converge on rejoin via peer sync; each peer call is bounded to 2s so a slow peer cannot stall the caller). Each peer applies the function to its own current row, so the function must be pure and convergent. Defaults to false — plain updates stay node-local (node-down purging relies on that).
• :timeout - local GenServer call timeout in milliseconds (default: 10_000)

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.

@spec withdraw_observations(
  ProcessHub.hub_id(),
  registry_dump(),
  (ProcessHub.child_id(), node() -> boolean()),
  keyword()
) :: [ProcessHub.child_id()]

Withdraws every {node, pid} observation in registry for which withdraw?.(child_id, node) returns true. Returns the affected child_ids.

Withdrawing is never a delete: an observation says only what its owner sees, so a child left with no observation keeps its row (on_empty: :keep) and becomes a candidate for the next orphan reconcile round rather than being erased on someone else's say-so.

opts are forwarded to bulk_delete/3.