Jido.Signal.Topology (Jido v1.1.0-rc.2)

View Source

Provides a data structure for tracking process hierarchies and their states.

This module supports:

  • Registering processes with their PIDs
  • Establishing parent-child relationships between processes
  • Querying the process hierarchy in various ways
  • Accessing process state through GenServer calls

Summary

Types

t()

The complete process hierarchy structure

Functions

Returns the number of processes in the topology.

Retrieves states from all processes in the topology.

Retrieves states from all descendants of a process.

Retrieves state from the GenServer process.

Returns a list of all processes in the topology.

Returns a list of all direct children of a process.

Returns all descendants of a process (children, grandchildren, etc.).

Returns a list of all root processes (those without parents).

Creates a new empty topology.

Prints a visual representation of the hierarchy to the console. If no process ID is provided, prints the entire forest from all root processes.

Registers a new process in the topology.

Establishes a parent-child relationship between two processes.

Returns a tree representation of the hierarchy starting from the given process. If no process ID is provided, returns the entire forest from all root processes.

Unregisters a process and all its descendants from the topology.

Updates a process's metadata.

Types

t()

@type t() :: %Jido.Signal.Topology{
  processes: %{required(String.t()) => Jido.Signal.Topology.ProcessNode.t()},
  root_ids: MapSet.t(String.t())
}

The complete process hierarchy structure

Functions

count(topology)

@spec count(t()) :: non_neg_integer()

Returns the number of processes in the topology.

get_all_states(topology)

@spec get_all_states(t()) :: %{required(String.t()) => term()}

Retrieves states from all processes in the topology.

Returns

  • Map of process IDs to their states

get_descendant_states(topology, id)

@spec get_descendant_states(t(), String.t()) :: %{required(String.t()) => term()}

Retrieves states from all descendants of a process.

Returns

  • Map of process IDs to their states

get_state(topology, id)

@spec get_state(t(), String.t()) :: {:ok, term()} | {:error, term()}

Retrieves state from the GenServer process.

Parameters

  • topology - The current topology
  • id - ID of the process

Returns

  • {:ok, state} - State was retrieved successfully
  • {:error, :not_found} - No process with this ID exists
  • {:error, reason} - GenServer call failed

list_all(topology)

@spec list_all(t()) :: [Jido.Signal.Topology.ProcessNode.t()]

Returns a list of all processes in the topology.

list_children(topology, id)

@spec list_children(t(), String.t()) :: [Jido.Signal.Topology.ProcessNode.t()]

Returns a list of all direct children of a process.

list_descendants(topology, id)

@spec list_descendants(t(), String.t()) :: [Jido.Signal.Topology.ProcessNode.t()]

Returns all descendants of a process (children, grandchildren, etc.).

list_roots(topology)

@spec list_roots(t()) :: [Jido.Signal.Topology.ProcessNode.t()]

Returns a list of all root processes (those without parents).

new()

@spec new() :: t()

Creates a new empty topology.

print(topology, id \\ nil)

@spec print(t(), String.t() | nil) :: :ok

Prints a visual representation of the hierarchy to the console. If no process ID is provided, prints the entire forest from all root processes.

register(topology, id, pid, opts \\ [])

@spec register(t(), String.t(), pid(), keyword()) ::
  {:ok, t()} | {:error, :already_exists | :parent_not_found}

Registers a new process in the topology.

Parameters

  • topology - The current topology
  • id - Unique identifier for the process
  • pid - Process ID
  • opts - Optional parameters:
    • name - Human-readable name
    • metadata - Additional information
    • parent_id - ID of the parent process (if any)

Returns

  • {:ok, updated_topology} - Process was registered successfully
  • {:error, :already_exists} - A process with this ID already exists
  • {:error, :parent_not_found} - The specified parent ID doesn't exist

set_parent(topology, parent_id, child_id)

@spec set_parent(t(), String.t(), String.t()) ::
  {:ok, t()} | {:error, :not_found | :cycle_detected}

Establishes a parent-child relationship between two processes.

Parameters

  • topology - The current topology
  • parent_id - ID of the parent process
  • child_id - ID of the child process

Returns

  • {:ok, updated_topology} - Relationship established successfully
  • {:error, :not_found} - One of the processes doesn't exist
  • {:error, :cycle_detected} - This would create a cycle in the hierarchy

to_tree(topology, id \\ nil)

@spec to_tree(t(), String.t() | nil) :: [map()]

Returns a tree representation of the hierarchy starting from the given process. If no process ID is provided, returns the entire forest from all root processes.

Returns

A tree structure where each node is a map containing:

  • :process - The process node
  • :state - The process state (if available)
  • :children - A list of child tree nodes

unregister(topology, id)

@spec unregister(t(), String.t()) :: {:ok, t()} | {:error, :not_found}

Unregisters a process and all its descendants from the topology.

Parameters

  • topology - The current topology
  • id - ID of the process to remove

Returns

  • {:ok, updated_topology} - Process was removed successfully
  • {:error, :not_found} - No process with this ID exists

update_metadata(topology, id, metadata)

@spec update_metadata(t(), String.t(), map()) :: {:ok, t()} | {:error, :not_found}

Updates a process's metadata.

Returns

  • {:ok, updated_topology} - Metadata was updated successfully
  • {:error, :not_found} - No process with this ID exists