o i%@sdZddlmZddlmZddlmZddlmZddl m Z ddl m Z ddl mZe d ed ed ZeGd d d e eZeGddde eZdS)aGParent fork identification and deadlock avoidance in parallel graph execution. This module provides functionality to identify "parent forks" in a graph, which are dominating fork nodes that control access to join nodes. A parent fork is a fork node that: 1. Dominates a join node (all paths to the join must pass through the fork) 2. Does not participate in cycles that bypass it to reach the join Identifying parent forks is crucial for deadlock avoidance in parallel execution. When a join node waits for all its incoming branches, knowing the parent fork helps determine when it's safe to proceed without risking deadlock. In most typical graphs, such dominating forks exist naturally. However, when there are multiple subsequent forks, the choice of parent fork can be ambiguous and may need to be specified by the graph designer. ) annotations)Hashable) dataclass)cached_property)Generic)TypeVar)GraphBuildingErrorTT)boundinfer_variancedefaultc@s$eZdZUdZded< ded<dS) ParentForka3Represents a parent fork node and its relationship to a join node. A parent fork is a dominating fork that controls the execution flow to a join node. It tracks which nodes lie between the fork and the join, which is essential for determining when it's safe to proceed past the join point. r fork_idset[T]intermediate_nodesN)__name__ __module__ __qualname____doc____annotations__rrf/var/www/html/karishye-ai-python/venv/lib/python3.10/site-packages/pydantic_graph/beta/parent_forks.pyr s r c@s|eZdZUdZded< ded< ded< ded< dd d d!ddZed"ddZed#ddZd$ddZ d%dd Z dS)&ParentForkFinderzAnalyzes graph structure to identify parent forks for join nodes. This class implements algorithms to find dominating forks in a directed graph, which is essential for coordinating parallel execution and avoiding deadlocks. rnodes start_idsfork_idsdict[T, list[T]]edgesNF)parent_fork_idprefer_closestjoin_idr rT | NonerboolreturnParentFork[T] | NonecCs|dur |||}|durtd|d|dtt||St}|}d} ||}|dur4 |S||vsEJd|d|d|||||jvrPq'|||}|durftt||}|re|Sn|durl|Sq()a5Find the parent fork for a given join node. Searches for the _most_ ancestral dominating fork that can serve as a parent fork for the specified join node. A valid parent fork must dominate the join without allowing cycles that bypass it. Args: join_id: The identifier of the join node to analyze. parent_fork_id: Optional manually selected node ID to attempt to use as the parent fork node. prefer_closest: If no explicit fork is specified, this argument is used to determine whether to find the closest or farthest (i.e., most ancestral) dominating fork. Returns: A ParentFork object containing the fork ID and intermediate nodes if a valid parent fork exists, or None if no valid parent fork can be found (which would indicate potential deadlock risk). Note: If every dominating fork of the join lets it participate in a cycle that avoids the fork, None is returned since no valid "parent fork" exists. Nz.There is a cycle in the graph passing through z that does not include zJ. Parent forks of a join must be a part of any cycles involving that join.Tz"Cycle detected in dominator tree: u → )_get_upstream_nodes_if_parentrr r set_immediate_dominatoraddr)selfr rrupstream_nodesvisitedcur parent_forkrrrfind_parent_forkHs8  "   z!ParentForkFinder.find_parent_forkcCsBdd|jD}|jD]}|j|gD] }|||qq |S)zCompute and cache the predecessor mapping for all nodes. Returns: A dictionary mapping each node to a list of its immediate predecessors. cSsi|]}|gqSrr.0nrrr sz2ParentForkFinder._predecessors..)rrgetappend)r) predecessors source_iddestination_idrrr _predecessorss  zParentForkFinder._predecessorsdict[T, set[T]]cst|j|j}fddD|D]}|h|<qd}|rXd}|D]0}|j|}|s/q%|r?ttjfdd|Dntt}|h|B}||krU||<d}q%|sS)aJCompute the dominator sets for all nodes using iterative dataflow analysis. A node D dominates node N if every path from a start node to N must pass through D. This is computed using a fixed-point iteration algorithm. Returns: A dictionary mapping each node to its set of dominators. csi|]}|tqSr)r&r/)node_idsrrr2sz0ParentForkFinder._dominators..TFc3s|]}|VqdSNr)r0p)domrr sz/ParentForkFinder._dominators..)r&rrr8r intersection)r)rschangedr1predsr?new_domr)r=r:r _dominatorss(    *   zParentForkFinder._dominatorsnode_idcsB|j||h}|D]tfdd|DrSq dS)aSFind the immediate dominator of a node. The immediate dominator is the closest dominator to a node (other than itself) in the dominator tree. Args: node_id: The node to find the immediate dominator for. Returns: The immediate dominator's ID if one exists, None otherwise. c3s$|] }|kp |vVqdSr;r)r0dcr=rrr>s"z8ParentForkFinder._immediate_dominator..N)rDall)r)rE candidatesrrGrr's z%ParentForkFinder._immediate_dominatorr set[T] | NonecCsdt}|g}|r0|}|j|D]}||krq||krdS||vr-||||q|s|S)aCheck if a fork is a valid parent and return upstream nodes. Tests whether the given fork can serve as a parent fork for the join by checking for cycles that bypass the fork. If valid, returns all nodes that can reach the join without going through the fork. Args: join_id: The join node being analyzed. fork_id: The potential parent fork to test. Returns: The set of node IDs upstream of the join (excluding the fork) if the fork is a valid parent, or None if a cycle exists that bypasses the fork (making it invalid as a parent fork). Note: If, in the graph with fork_id removed, a path exists that starts and ends at the join (i.e., join is on a cycle avoiding the fork), we return None because the fork would not be a valid "parent fork". N)r&popr8r(r4)r)r rupstreamstackvr<rrrr%s   z.ParentForkFinder._get_upstream_nodes_if_parent)r r rr!rr"r#r$)r#r)r#r9)rEr r#r!)r r rr r#rK) rrrrrr.rr8rDr'r%rrrrr4s$ @   rN)r __future__rcollections.abcr dataclassesr functoolsrtypingrtyping_extensionsrpydantic_graph.exceptionsrstrr r rrrrrs