Jido.Signal.Topology (Jido v1.1.0-rc.2)
View SourceProvides 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
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
@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
@spec count(t()) :: non_neg_integer()
Returns the number of processes in the topology.
Retrieves states from all processes in the topology.
Returns
- Map of process IDs to their states
Retrieves states from all descendants of a process.
Returns
- Map of process IDs to their states
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
@spec list_all(t()) :: [Jido.Signal.Topology.ProcessNode.t()]
Returns a list of all processes in the topology.
@spec list_children(t(), String.t()) :: [Jido.Signal.Topology.ProcessNode.t()]
Returns a list of all direct children of a process.
@spec list_descendants(t(), String.t()) :: [Jido.Signal.Topology.ProcessNode.t()]
Returns all descendants of a process (children, grandchildren, etc.).
@spec list_roots(t()) :: [Jido.Signal.Topology.ProcessNode.t()]
Returns a list of all root processes (those without parents).
@spec new() :: t()
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.
@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
@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
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
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
Updates a process's metadata.
Returns
{:ok, updated_topology}
- Metadata was updated successfully{:error, :not_found}
- No process with this ID exists