Table of Contents

Class ControlFlowNode<TInstruction>

Namespace
Echo.ControlFlow
Assembly
Echo.ControlFlow.dll

Represents a node in a control flow graph, containing a basic block of instructions that are to be executed in a sequence.

public class ControlFlowNode<TInstruction> : IIdentifiedNode, INode where TInstruction : notnull

Type Parameters

TInstruction

The type of instructions to store in the node.

Inheritance
ControlFlowNode<TInstruction>
Implements
Inherited Members

Constructors

ControlFlowNode()

Creates a new empty control flow node.

public ControlFlowNode()

ControlFlowNode(BasicBlock<TInstruction>)

Creates a new control flow node containing the provided basic block of instructions, to be added to the graph.

public ControlFlowNode(BasicBlock<TInstruction> basicBlock)

Parameters

basicBlock BasicBlock<TInstruction>

The basic block to store in the node.

ControlFlowNode(IEnumerable<TInstruction>)

Creates a new control flow node containing the provided basic block of instructions, to be added to the graph.

public ControlFlowNode(IEnumerable<TInstruction> instructions)

Parameters

instructions IEnumerable<TInstruction>

The basic block to store in the node.

ControlFlowNode(long)

Creates a new empty control flow node for the provided offset.

public ControlFlowNode(long offset)

Parameters

offset long

The offset.

ControlFlowNode(params TInstruction[])

Creates a new control flow node containing the provided basic block of instructions, to be added to the graph.

public ControlFlowNode(params TInstruction[] instructions)

Parameters

instructions TInstruction[]

The basic block to store in the node.

Properties

AbnormalEdges

Gets a collection of abnormal edges that originate from this source.

public AdjacencyCollection<TInstruction> AbnormalEdges { get; }

Property Value

AdjacencyCollection<TInstruction>

Remarks

These edges are typically present when a node is part of a region of code protected by an exception handler.

ConditionalEdges

Gets a collection of conditional edges that originate from this source.

public AdjacencyCollection<TInstruction> ConditionalEdges { get; }

Property Value

AdjacencyCollection<TInstruction>

Remarks

These edges are typically present when a node is a basic block encoding the header of an if statement or a loop.

Contents

Gets the user-defined contents of this node.

public BasicBlock<TInstruction> Contents { get; }

Property Value

BasicBlock<TInstruction>

InDegree

Gets a value indicating the number of incoming edges that this node is incident to.

public int InDegree { get; }

Property Value

int

Offset

Gets the offset of the basic block the node is representing.

public long Offset { get; }

Property Value

long

OutDegree

Gets a value indicating the number of outgoing edges that this node is incident to.

public int OutDegree { get; }

Property Value

int

ParentGraph

Gets the graph that contains this node, or null if the node is not added to any graph yet.

public ControlFlowGraph<TInstruction>? ParentGraph { get; }

Property Value

ControlFlowGraph<TInstruction>

ParentRegion

Gets the graph region that contains this node, or null if the node is not added to any graph yet.

public IScopeControlFlowRegion<TInstruction>? ParentRegion { get; }

Property Value

IScopeControlFlowRegion<TInstruction>

UnconditionalEdge

Gets or sets the edge to the neighbour to which the control is transferred to after execution of this block and no other condition is met.

public ControlFlowEdge<TInstruction>? UnconditionalEdge { get; set; }

Property Value

ControlFlowEdge<TInstruction>

UnconditionalNeighbour

Gets or sets the neighbour to which the control is transferred to after execution of this block and no other condition is met.

public ControlFlowNode<TInstruction>? UnconditionalNeighbour { get; set; }

Property Value

ControlFlowNode<TInstruction>

UserData

Gets or sets user data that is added to the node.

public object? UserData { get; set; }

Property Value

object

Methods

ConnectWith(ControlFlowNode<TInstruction>)

Connects the node to the provided neighbour using a fallthrough edge.

public ControlFlowEdge<TInstruction> ConnectWith(ControlFlowNode<TInstruction> neighbour)

Parameters

neighbour ControlFlowNode<TInstruction>

The node to connect to.

Returns

ControlFlowEdge<TInstruction>

The edge that was used to connect the two nodes together.

Exceptions

ArgumentNullException

Occurs when neighbour is null.

InvalidOperationException

Occurs when the node already contains a fallthrough edge to another node.

ConnectWith(ControlFlowNode<TInstruction>, ControlFlowEdgeType)

Connects the node to the provided neighbour.

public ControlFlowEdge<TInstruction> ConnectWith(ControlFlowNode<TInstruction> neighbour, ControlFlowEdgeType edgeType)

Parameters

neighbour ControlFlowNode<TInstruction>

The node to connect to.

edgeType ControlFlowEdgeType

The type of edge to use for connecting to the other node.

Returns

ControlFlowEdge<TInstruction>

The edge that was used to connect the two nodes together.

Exceptions

ArgumentNullException

Occurs when neighbour is null.

InvalidOperationException

Occurs when edgeType equals FallThrough, and the node already contains a fallthrough edge to another node.

ArgumentOutOfRangeException

Occurs when an invalid edge type was provided.

Disconnect()

Removes all incident edges (both incoming and outgoing edges) from the node, effectively isolating the node in the graph.

public void Disconnect()

GetIncomingEdges()

Gets a collection of all edges that target this node.

public IEnumerable<ControlFlowEdge<TInstruction>> GetIncomingEdges()

Returns

IEnumerable<ControlFlowEdge<TInstruction>>

The incoming edges.

GetOutgoingEdges()

Gets a collection of all outgoing edges originating from this node.

public IEnumerable<ControlFlowEdge<TInstruction>> GetOutgoingEdges()

Returns

IEnumerable<ControlFlowEdge<TInstruction>>

The outgoing edges.

GetParentExceptionHandler()

Obtains the parent exception handler region that this node resides in (if any).

public ExceptionHandlerRegion<TInstruction>? GetParentExceptionHandler()

Returns

ExceptionHandlerRegion<TInstruction>

The parent exception handler region, or null if the node is not part of any exception handler.

GetParentHandler()

Obtains the parent handler region that this node resides in (if any).

public HandlerRegion<TInstruction>? GetParentHandler()

Returns

HandlerRegion<TInstruction>

The parent handler region, or null if the node is not part of any handler.

GetPredecessors()

Gets a collection of nodes that precede this node. This includes any node that might transfer control to node this node in the complete control flow graph, regardless of edge type.

public IEnumerable<ControlFlowNode<TInstruction>> GetPredecessors()

Returns

IEnumerable<ControlFlowNode<TInstruction>>

The predecessor nodes.

GetSituatedRegions()

Traverses the region tree upwards and collects all regions this node is situated in.

public IEnumerable<IControlFlowRegion<TInstruction>> GetSituatedRegions()

Returns

IEnumerable<IControlFlowRegion<TInstruction>>

The regions this node is situated in, starting with the inner-most regions.

GetSuccessors()

Gets a collection of nodes that might be executed after this node. This includes any node that this node might transfer control to, regardless of edge type.

public IEnumerable<ControlFlowNode<TInstruction>> GetSuccessors()

Returns

IEnumerable<ControlFlowNode<TInstruction>>

The successor nodes.

HasPredecessor(ControlFlowNode<TInstruction>)

Determines whether another node is a predecessor of this node.

public bool HasPredecessor(ControlFlowNode<TInstruction> neighbour)

Parameters

neighbour ControlFlowNode<TInstruction>

The potential predecessor.

Returns

bool

True if the provided node is a predecessor, false otherwise.

Exceptions

ArgumentNullException

Occurs when the provided predecessor is null

HasSuccessor(ControlFlowNode<TInstruction>)

Determines whether another node is a successor of this node.

public bool HasSuccessor(ControlFlowNode<TInstruction> neighbour)

Parameters

neighbour ControlFlowNode<TInstruction>

The potential successor.

Returns

bool

True if the provided node is a successor, false otherwise.

Exceptions

ArgumentNullException

Occurs when the provided successor is null

IsInRegion(IControlFlowRegion<TInstruction>)

Gets a value indicating whether the node is in the provided region.

public bool IsInRegion(IControlFlowRegion<TInstruction> region)

Parameters

region IControlFlowRegion<TInstruction>

The region.

Returns

bool

true if the node is within the region, false otherwise.

MergeWithPredecessor()

Merges the current node with its fallthrough predecessor, by combining the two basic blocks together, connecting the predecessor with the successors of the current node. and finally removing the current node.

public void MergeWithPredecessor()

Exceptions

InvalidOperationException

Occurs when the node could not be merged because it has no fallthrough predecessor, has multiple predecessors, or the predecessor has multiple successors which prohibit merging.

MergeWithSuccessor()

Merges the current node with its fallthrough neighbour, by combining the two basic blocks together, connecting the node with the successors of the neighbour. and finally removing the neighbour node.

public void MergeWithSuccessor()

Exceptions

InvalidOperationException

Occurs when the node could not be merged because it has no fallthrough neighbour, or has multiple successors.

MoveToRegion(ScopeRegion<TInstruction>)

Moves the node from its current region (if any) into the provided sub region.

public void MoveToRegion(ScopeRegion<TInstruction> region)

Parameters

region ScopeRegion<TInstruction>

The region to move the node to.

RemoveFromAnyRegion()

Removes the node out of any sub region in the graph.

public void RemoveFromAnyRegion()

SplitAtIndex(int)

Splits the node and its embedded basic block in two nodes at the provided index, and connects the two resulting nodes with a fallthrough edge.

public (ControlFlowNode<TInstruction> First, ControlFlowNode<TInstruction> Second) SplitAtIndex(int index)

Parameters

index int

The index of the instruction

Returns

(ControlFlowNode<TInstruction> First, ControlFlowNode<TInstruction> Second)

The two resulting nodes.

Exceptions

InvalidOperationException

Occurs when the node cannot be split any further.

ArgumentOutOfRangeException

Occurs when the provided index falls outside the range of the instructions in the embedded basic block.

ToString() 

public override string ToString()

Returns

string

UpdateOffset()

Synchronizes the basic block's offset with the offset of the first instruction.

public void UpdateOffset()