Interface Function

src/function.rs:598–814

A trait defined by the register allocator client to provide access to its machine-instruction / CFG representation. See the [module-level documentation] for more details. [module-level documentation]: self (This trait's design is inspired by, and derives heavily from, the trait of the same name in regalloc2.)

// (This trait's design is inspired by, and derives heavily from, the
// trait of the same name in regalloc2.)
pub trait Function {
    // -------------
    // CFG traversal
    // -------------

    /// How many instructions are there?
    fn num_insts(&self) -> usize;

    /// Iterator over all the [`Inst`]s in this function.
    #[inline]
    fn insts(&self) -> Keys<Inst> {
        Keys::with_len(self.num_insts())
    }

    /// How many blocks are there?
    ///
    /// All blocks must be reachable from at least one entry point.
    fn num_blocks(&self) -> usize;

    /// Iterator over all the [`Block`]s in this function.
    #[inline]
    fn blocks(&self) -> Keys<Block> {
        Keys::with_len(self.num_blocks())
    }

    /// Returns the entry points of the CFG.
    ///
    /// This list must be non-empty and contain no duplicates. Entry points
    /// must have no predecessors and no block parameters.
    fn entry_points(&self) -> &[Block];

    /// Provide the range of instruction indices contained in each block.
    fn block_insts(&self, block: Block) -> InstRange;

    /// Returns the block containing the given instruction.
    fn inst_block(&self, inst: Inst) -> Block;

    /// Get CFG successors for a given block.
    fn block_succs(&self, block: Block) -> &[Block];

    /// Get the CFG predecessors for a given block.
    fn block_preds(&self, block: Block) -> &[Block];

    /// Returns the immediate dominator of the given block.
    ///
    /// This returns `None` for entry points and for blocks whose only common
    /// dominator would be the virtual root of a multi-entry CFG.
    fn block_immediate_dominator(&self, block: Block) -> Option<Block>;

    /// Returns whether block `a` dominates block `b`.
    ///
    /// This should return true if `a == b`.
    fn block_dominates(&self, a: Block, mut b: Block) -> bool {
        // Walk b up the dominator tree until a is reached or we go past it.
        // This works because the block ordering is required to be topologically
        // ordered with regards to the dominator tree.
        while a < b {
            match self.block_immediate_dominator(b) {