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,
};

const NAT: Type = prelude::USIZE_T;

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

    // 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 NAT, or the second branch and pass it nothing.
    let sum_variants = vec![type_row![NAT], 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(), type_row![NAT])?;

    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
    // `NAT` 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(type_row![NAT, NAT], NAT),
        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(NAT), 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_prelude_hugr()?;
    Ok(hugr)
};
#[cfg(not(feature = "extension_inference"))]
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. Extension delta will be inferred.

Errors

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

pub fn block_builder_exts( &mut self, inputs: TypeRow, sum_rows: impl IntoIterator<Item = TypeRow>, other_outputs: TypeRow, extension_delta: impl Into<ExtensionSet>, ) -> 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. Extension delta will be inferred.

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 and extension_delta explicitly specified, 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. Extension delta will be inferred.

Errors

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

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

Return a builder for the entry DataflowBlock child graph with outputs, the variants of the branching Sum value specified by sum_rows, and extension_delta explicitly specified. (entry_builder may be used to infer.)

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 simple_entry_builder_exts( &mut self, outputs: TypeRow, n_cases: usize, extension_delta: impl Into<ExtensionSet>, ) -> Result<BlockBuilder<&mut Hugr>, BuildError>

Return a builder for the entry DataflowBlock child graph with outputs and a Sum of n_cases unit types, and explicit extension_delta. (simple_entry_builder may be used to infer.)

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 define_function( &mut self, name: impl Into<String>, signature: impl Into<PolyFuncType>, ) -> Result<FunctionBuilder<&mut Hugr>, BuildError>

Add a ops::FuncDefn node and returns a builder to define the function body graph.

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

Insert a HUGR as a child of the container.

fn add_hugr_view(&mut self, child: &impl HugrView) -> InsertionResult

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.

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, extension_registry: &ExtensionRegistry, ) -> Result<Hugr, ValidationError>

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

fn finish_prelude_hugr(self) -> Result<Hugr, ValidationError>

where Self: Sized,

Finish building the HUGR (as HugrBuilder::finish_hugr), validating against the prelude extension only

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>