Struct dfir_lang::graph::DfirGraph

pub struct DfirGraph { /* private fields */ }

An abstract “meta graph” representation of a Hydroflow graph.

Can be with or without subgraph partitioning, stratification, and handoff insertion. This is the meta graph used for generating Rust source code in macros from Hydroflow surface sytnax.

This struct has a lot of methods for manipulating the graph, vaguely grouped together in separate impl blocks. You might notice a few particularly specific arbitray-seeming methods in here–those are just what was needed for the compilation algorithms. If you need another method then add it.

Implementations

impl DfirGraph

Basic methods.

pub fn new() -> Self

Create a new empty HydroflowGraph.

impl DfirGraph

Node methods.

pub fn node(&self, node_id: GraphNodeId) -> &GraphNode

Get a node with its operator instance (if applicable).

pub fn node_op_inst(&self, node_id: GraphNodeId) -> Option<&OperatorInstance>

Get the OperatorInstance for a given node. Node must be an operator and have an OperatorInstance present, otherwise will return None.

Note that no operator instances will be persent after deserialization.

pub fn node_varname(&self, node_id: GraphNodeId) -> Option<Ident>

Get the debug variable name attached to a graph node.

pub fn node_subgraph(&self, node_id: GraphNodeId) -> Option<GraphSubgraphId>

Get subgraph for node.

pub fn node_degree_in(&self, node_id: GraphNodeId) -> usize

Degree into a node, i.e. the number of predecessors.

pub fn node_degree_out(&self, node_id: GraphNodeId) -> usize

Degree out of a node, i.e. the number of successors.

pub fn node_successors( &self, src: GraphNodeId, ) -> impl '_ + DoubleEndedIterator<Item = (GraphEdgeId, GraphNodeId)> + ExactSizeIterator + FusedIterator + Clone + Debug

Successors, iterator of (GraphEdgeId, GraphNodeId) of outgoing edges.

pub fn node_predecessors( &self, dst: GraphNodeId, ) -> impl '_ + DoubleEndedIterator<Item = (GraphEdgeId, GraphNodeId)> + ExactSizeIterator + FusedIterator + Clone + Debug

Predecessors, iterator of (GraphEdgeId, GraphNodeId) of incoming edges.

pub fn node_successor_edges( &self, src: GraphNodeId, ) -> impl '_ + DoubleEndedIterator<Item = GraphEdgeId> + ExactSizeIterator + FusedIterator + Clone + Debug

Successor edges, iterator of GraphEdgeId of outgoing edges.

pub fn node_predecessor_edges( &self, dst: GraphNodeId, ) -> impl '_ + DoubleEndedIterator<Item = GraphEdgeId> + ExactSizeIterator + FusedIterator + Clone + Debug

Predecessor edges, iterator of GraphEdgeId of incoming edges.

pub fn node_successor_nodes( &self, src: GraphNodeId, ) -> impl '_ + DoubleEndedIterator<Item = GraphNodeId> + ExactSizeIterator + FusedIterator + Clone + Debug

Successor nodes, iterator of GraphNodeId.

pub fn node_predecessor_nodes( &self, dst: GraphNodeId, ) -> impl '_ + DoubleEndedIterator<Item = GraphNodeId> + ExactSizeIterator + FusedIterator + Clone + Debug

Predecessor nodes, iterator of GraphNodeId.

pub fn node_ids(&self) -> Keys<'_, GraphNodeId, GraphNode>

Iterator of node IDs GraphNodeId.

pub fn nodes(&self) -> Iter<'_, GraphNodeId, GraphNode>

Iterator over (GraphNodeId, &Node) pairs.

pub fn insert_node( &mut self, node: GraphNode, varname_opt: Option<Ident>, loop_opt: Option<GraphLoopId>, ) -> GraphNodeId

Insert a node, assigning the given varname.

pub fn insert_node_op_inst( &mut self, node_id: GraphNodeId, op_inst: OperatorInstance, )

Insert an operator instance for the given node. Panics if already set.

pub fn insert_node_op_insts_all(&mut self, diagnostics: &mut Vec<Diagnostic>)

Assign all operator instances if not set. Write diagnostic messages/errors into diagnostics.

pub fn insert_intermediate_node( &mut self, edge_id: GraphEdgeId, new_node: GraphNode, ) -> (GraphNodeId, GraphEdgeId)

Inserts a node between two existing nodes connected by the given edge_id.

edge: (src, dst, dst_idx)

Before: A (src) ————> B (dst) After: A (src) -> X (new) -> B (dst)

Returns the ID of X & ID of edge OUT of X.

Note that both the edges will be new and edge_id will be removed. Both new edges will get the edge type of the original edge.

pub fn remove_intermediate_node(&mut self, node_id: GraphNodeId)

Remove the node node_id but preserves and connects the single predecessor and single successor. Panics if the node does not have exactly one predecessor and one successor, or is not in the graph.

impl DfirGraph

Singleton references.

pub fn set_node_singleton_references( &mut self, node_id: GraphNodeId, singletons_referenced: Vec<Option<GraphNodeId>>, ) -> Option<Vec<Option<GraphNodeId>>>

Set the singletons referenced for the node_id operator. Each reference corresponds to the same index in the crate::parse::Operator::singletons_referenced vec.

pub fn node_singleton_references( &self, node_id: GraphNodeId, ) -> &[Option<GraphNodeId>]

Gets the singletons referenced by a node. Returns an empty iterator for non-operators and operators that do not reference singletons.

impl DfirGraph

Module methods.

pub fn merge_modules(&mut self) -> Result<(), Diagnostic>

When modules are imported into a flat graph, they come with an input and output ModuleBoundary node. The partitioner doesn’t understand these nodes and will panic if it encounters them. merge_modules removes them from the graph, stitching the input and ouput sides of the ModuleBondaries based on their ports For example: source_iter([]) -> [myport]ModuleBoundary(input)[my_port] -> map(|x| x) -> ModuleBoundary(output) -> null(); in the above eaxmple, the [myport] port will be used to connect the source_iter with the map that is inside of the module. The output module boundary has elided ports, this is also used to match up the input/output across the module boundary.

impl DfirGraph

Edge methods.

pub fn edge(&self, edge_id: GraphEdgeId) -> (GraphNodeId, GraphNodeId)

Get the src and dst for an edge: (src GraphNodeId, dst GraphNodeId).

pub fn edge_ports( &self, edge_id: GraphEdgeId, ) -> (&PortIndexValue, &PortIndexValue)

Get the source and destination ports for an edge: (src &PortIndexValue, dst &PortIndexValue).

pub fn edge_ids(&self) -> Keys<'_, GraphEdgeId, (GraphNodeId, GraphNodeId)>

Iterator of all edge IDs GraphEdgeId.

pub fn edges( &self, ) -> impl '_ + ExactSizeIterator<Item = (GraphEdgeId, (GraphNodeId, GraphNodeId))> + FusedIterator + Clone + Debug

Iterator over all edges: (GraphEdgeId, (src GraphNodeId, dst GraphNodeId)).

pub fn insert_edge( &mut self, src: GraphNodeId, src_port: PortIndexValue, dst: GraphNodeId, dst_port: PortIndexValue, ) -> GraphEdgeId

Insert an edge between nodes thru the given ports.

pub fn remove_edge(&mut self, edge: GraphEdgeId)

Removes an edge and its corresponding ports and edge type info.

impl DfirGraph

Subgraph methods.

pub fn subgraph(&self, subgraph_id: GraphSubgraphId) -> &Vec<GraphNodeId>

Nodes belonging to the given subgraph.

pub fn subgraph_ids(&self) -> Keys<'_, GraphSubgraphId, Vec<GraphNodeId>>

Iterator over all subgraph IDs.

pub fn subgraphs(&self) -> Iter<'_, GraphSubgraphId, Vec<GraphNodeId>>

Iterator over all subgraphs, ID and members: (GraphSubgraphId, Vec<GraphNodeId>).

pub fn insert_subgraph( &mut self, node_ids: Vec<GraphNodeId>, ) -> Result<GraphSubgraphId, (GraphNodeId, GraphSubgraphId)>

Create a subgraph consisting of node_ids. Returns an error if any of the nodes are already in a subgraph.

pub fn remove_from_subgraph(&mut self, node_id: GraphNodeId) -> bool

Removes a node from its subgraph. Returns true if the node was in a subgraph.

pub fn subgraph_stratum(&self, sg_id: GraphSubgraphId) -> Option<usize>

Gets the stratum number of the subgraph.

pub fn set_subgraph_stratum( &mut self, sg_id: GraphSubgraphId, stratum: usize, ) -> Option<usize>

Set subgraph’s stratum number, returning the old value if exists.

pub fn set_subgraph_laziness( &mut self, sg_id: GraphSubgraphId, lazy: bool, ) -> bool

Set subgraph’s laziness, returning the old value.

pub fn max_stratum(&self) -> Option<usize>

Returns the the stratum number of the largest (latest) stratum (inclusive).

impl DfirGraph

Display/output methods.

pub fn as_code( &self, root: &TokenStream, include_type_guards: bool, prefix: TokenStream, diagnostics: &mut Vec<Diagnostic>, ) -> TokenStream

Emit this HydroflowGraph as runnable Rust source code tokens.

pub fn node_color_map(&self) -> SparseSecondaryMap<GraphNodeId, Color>

Color mode (pull vs. push, handoff vs. comp) for nodes. Some nodes can be push OR pull; those nodes will not be set in the returned map.

pub fn to_mermaid(&self, write_config: &WriteConfig) -> String

Writes this graph as mermaid into a string.

pub fn write_mermaid( &self, output: impl Write, write_config: &WriteConfig, ) -> Result

Writes this graph as mermaid into the given Write.

pub fn to_dot(&self, write_config: &WriteConfig) -> String

Writes this graph as DOT (graphviz) into a string.

pub fn write_dot( &self, output: impl Write, write_config: &WriteConfig, ) -> Result

Writes this graph as DOT (graphviz) into the given Write.

pub fn surface_syntax_string(&self) -> String

Convert back into surface syntax.

pub fn write_surface_syntax(&self, write: &mut impl Write) -> Result

Convert back into surface syntax.

pub fn mermaid_string_flat(&self) -> String

Convert into a mermaid graph. Ignores subgraphs.

pub fn write_mermaid_flat(&self, write: &mut impl Write) -> Result

Convert into a mermaid graph. Ignores subgraphs.

impl DfirGraph

Loops

pub fn loop_ids(&self) -> Keys<'_, GraphLoopId, Vec<GraphNodeId>>

Iterator over all loop IDs.

pub fn loops(&self) -> Iter<'_, GraphLoopId, Vec<GraphNodeId>>

Iterator over all loops, ID and members: (GraphLoopId, Vec<GraphNodeId>).

pub fn insert_loop(&mut self, parent_loop: Option<GraphLoopId>) -> GraphLoopId

Create a new loop context, with the given parent loop (or None).

pub fn node_loop(&self, node_id: GraphNodeId) -> Option<GraphLoopId>

Get a node’s loop context (or None for root).

pub fn loop_parent(&self, loop_id: GraphLoopId) -> Option<GraphLoopId>

Get a loop context’s parent loop context (or None for root).

pub fn loop_children(&self, loop_id: GraphLoopId) -> &Vec<GraphLoopId>

Get a loop context’s child loops.

impl DfirGraph

pub fn open_mermaid(&self, write_config: &WriteConfig) -> Result<()>

Opens this as a mermaid graph in the mermaid.live browser editor.

pub fn open_dot(&self, write_config: &WriteConfig) -> Result<()>

Opens this as dot/graphviz graph in the Graphviz Online browser editor.

pub fn open_graph( &self, graph_type: WriteGraphType, write_config: Option<WriteConfig>, ) -> Result<()>

Opens the graph based on graph_type, which can be parsed by clap.

Trait Implementations

impl Debug for DfirGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DfirGraph

fn default() -> DfirGraph

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for DfirGraph

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for DfirGraph

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.