Struct CFGBuilder

pub struct CFGBuilder<T> { /* private fields */ }

Builder for a crate::ops::CFG child control flow graph.

These builder methods should ensure that the first two children of a CFG node are the entry node and the exit node.

Example

/*  Build a control flow graph with the following structure:
           +-----------+
           |   Entry   |
           +-/-----\---+
            /       \
           /         \
          /           \
         /             \
  +-----/----+       +--\-------+
  | Branch A |       | Branch B |
  +-----\----+       +----/-----+
         \               /
          \             /
           \           /
            \         /
           +-\-------/--+
           |    Exit    |
           +------------+
*/
use hugr::{
    builder::{BuildError, CFGBuilder, Container, Dataflow, HugrBuilder, endo_sig, inout_sig},
    extension::{prelude, ExtensionSet},
    ops, type_row,
    types::{Signature, SumType, Type},
    Hugr,
    extension::prelude::usize_t,
};

fn make_cfg() -> Result<Hugr, BuildError> {
    let mut cfg_builder = CFGBuilder::new(Signature::new_endo(usize_t()))?;

    // Outputs from basic blocks must be packed in a sum which corresponds to
    // which successor to pick. We'll either choose the first branch and pass
    // it a usize, or the second branch and pass it nothing.
    let sum_variants = vec![vec![usize_t()].into(), type_row![]];

    // The second argument says what types will be passed through to every
    // successor, in addition to the appropriate `sum_variants` type.
    let mut entry_b = cfg_builder.entry_builder(sum_variants.clone(), vec![usize_t()].into())?;

    let [inw] = entry_b.input_wires_arr();
    let entry = {
        // Pack the const "42" into the appropriate sum type.
        let left_42 = ops::Value::sum(
            0,
            [prelude::ConstUsize::new(42).into()],
            SumType::new(sum_variants.clone()),
        )?;
        let sum = entry_b.add_load_value(left_42);

        entry_b.finish_with_outputs(sum, [inw])?
    };

    // This block will be the first successor of the entry node. It takes two
    // `usize` arguments: one from the `sum_variants` type, and another from the
    // entry node's `other_outputs`.
    let mut successor_builder = cfg_builder.simple_block_builder(
        inout_sig(vec![usize_t(), usize_t()], usize_t()),
        1, // only one successor to this block
    )?;
    let successor_a = {
        // This block has one successor. The choice is denoted by a unary sum.
        let sum_unary = successor_builder.add_load_const(ops::Value::unary_unit_sum());

        // The input wires of a node start with the data embedded in the variant
        // which selected this block.
        let [_forty_two, in_wire] = successor_builder.input_wires_arr();
        successor_builder.finish_with_outputs(sum_unary, [in_wire])?
    };

    // The only argument to this block is the entry node's `other_outputs`.
    let mut successor_builder = cfg_builder.simple_block_builder(endo_sig(usize_t()), 1)?;
    let successor_b = {
        let sum_unary = successor_builder.add_load_value(ops::Value::unary_unit_sum());
        let [in_wire] = successor_builder.input_wires_arr();
        successor_builder.finish_with_outputs(sum_unary, [in_wire])?
    };
    let exit = cfg_builder.exit_block();
    cfg_builder.branch(&entry, 0, &successor_a)?; // branch 0 goes to successor_a
    cfg_builder.branch(&entry, 1, &successor_b)?; // branch 1 goes to successor_b
    cfg_builder.branch(&successor_a, 0, &exit)?;
    cfg_builder.branch(&successor_b, 0, &exit)?;
    let hugr = cfg_builder.finish_hugr()?;
    Ok(hugr)
};
assert!(make_cfg().is_ok());

Implementations

impl CFGBuilder<Hugr>

pub fn new(signature: Signature) -> Result<Self, BuildError>

New CFG rooted HUGR builder

impl<B: AsMut<Hugr> + AsRef<Hugr>> CFGBuilder<B>

pub fn block_builder( &mut self, inputs: TypeRow, sum_rows: impl IntoIterator<Item = TypeRow>, other_outputs: TypeRow, ) -> Result<BlockBuilder<&mut Hugr>, BuildError>

Return a builder for a non-entry DataflowBlock child graph with inputs and outputs and the variants of the branching Sum value specified by sum_rows.

Errors

This function will return an error if there is an error adding the node.

pub fn simple_block_builder( &mut self, signature: Signature, n_cases: usize, ) -> Result<BlockBuilder<&mut Hugr>, BuildError>

Return a builder for a non-entry DataflowBlock child graph with inputs and outputs , plus a UnitSum type (a Sum of n_cases unit types) to select the successor.

Errors

This function will return an error if there is an error adding the node.

pub fn entry_builder( &mut self, sum_rows: impl IntoIterator<Item = TypeRow>, other_outputs: TypeRow, ) -> Result<BlockBuilder<&mut Hugr>, BuildError>

Return a builder for the entry DataflowBlock child graph with outputs and the variants of the branching Sum value specified by sum_rows.

Errors

This function will return an error if an entry block has already been built.

pub fn simple_entry_builder( &mut self, outputs: TypeRow, n_cases: usize, ) -> Result<BlockBuilder<&mut Hugr>, BuildError>

Return a builder for the entry DataflowBlock child graph with outputs and a UnitSum type: a Sum of n_cases unit types.

Errors

This function will return an error if there is an error adding the node.

pub fn exit_block(&self) -> BasicBlockID

Returns the exit block of this CFGBuilder.

pub fn branch( &mut self, predecessor: &BasicBlockID, branch: usize, successor: &BasicBlockID, ) -> Result<(), BuildError>

Set the branch index successor block of predecessor.

Errors

This function will return an error if there is an error connecting the blocks.

Trait Implementations

impl<B: AsMut<Hugr> + AsRef<Hugr>> Container for CFGBuilder<B>

fn container_node(&self) -> Node

The container node.

fn hugr_mut(&mut self) -> &mut Hugr

The underlying Hugr being built

fn hugr(&self) -> &Hugr

Immutable reference to HUGR being built

fn add_child_node(&mut self, node: impl Into<OpType>) -> Node

Add an OpType as the final child of the container.

fn add_other_wire(&mut self, src: Node, dst: Node) -> Wire

Adds a non-dataflow edge between two nodes. The kind is given by the operation’s other_inputs or other_outputs

fn add_constant(&mut self, constant: impl Into<Const>) -> ConstID

Add a constant value to the container and return a handle to it.

fn add_hugr(&mut self, child: Hugr) -> InsertionResult

Insert a HUGR as a child of the container.

fn add_hugr_view<H: HugrView>( &mut self, child: &H, ) -> InsertionResult<H::Node, Node>

Insert a copy of a HUGR as a child of the container.

fn set_metadata(&mut self, key: impl AsRef<str>, meta: impl Into<NodeMetadata>)

Add metadata to the container node.

fn set_child_metadata( &mut self, child: Node, key: impl AsRef<str>, meta: impl Into<NodeMetadata>, )

Add metadata to a child node.

fn use_extension(&mut self, ext: impl Into<Arc<Extension>>)

Add an extension to the set of extensions used by the hugr.

fn use_extensions<Reg>(&mut self, registry: impl IntoIterator<Item = Reg>)

where ExtensionRegistry: Extend<Reg>,

Extend the set of extensions used by the hugr with the extensions in the registry.

impl<T: Debug> Debug for CFGBuilder<T>

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

Formats the value using the given formatter.

impl HugrBuilder for CFGBuilder<Hugr>

fn finish_hugr(self) -> Result<Hugr, ValidationError<Node>>

Finish building the HUGR, perform any validation checks and return it.

fn module_root_builder(&mut self) -> ModuleBuilder<&mut Hugr>

Allows adding definitions to the module root of which this builder is building a part

impl<T: PartialEq> PartialEq for CFGBuilder<T>

fn eq(&self, other: &CFGBuilder<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<H: AsMut<Hugr> + AsRef<Hugr>> SubContainer for CFGBuilder<H>

type ContainerHandle = BuildHandle<CfgID>

A handle to the finished container node, typically returned when the child graph has been finished.

fn finish_sub_container(self) -> Result<Self::ContainerHandle, BuildError>

Consume the container builder and return the handle, may perform some checks before finishing.

impl<T> StructuralPartialEq for CFGBuilder<T>