A bunch of work to resolve #569 (#576)

* render-test should not fail on HLSL compiler *warnings*

The logic in `render-test` that invokes `D3DCompile` was causing a test to fail if it produced any warnings (not just if compilation fails).
Warning output can be dealt with by the test runner, since it will compare output between runs anyway, and it is useful to be able to run something through `render-test` that compiles with warnings.

* Be more careful about deleting IR instructions

There was an `IRInst::deallocate()` method that had a precondition that the instruction should already be removed from its parent and clear out all its operands before calling, but it wasn't checking this and the few call sites weren't doing things right either.
I consolidated things on `IRInst::removeAndDeallocate()` which does all the things: removes from the parent, clear out operands, and then deallocates.
I also made sure to clear out the type operand.

This clears up some crashing issues where passes were removing instructions but those instructions would still show up as users of other instructions.

* Don't emit bitwise not for non-Boolean types

It seems like the logic in `emit.cpp` messed things up and decided that `Not` (the IR instruction that is equivalent to `!` in the AST) should emit as `!` for Boolean types and `~` for other types, but this makes no sense (e.g., `~(a & 1)` is very different from `!(a & 1)`, even when interpreted as a condition).

It seems like this logic was intended for the `BitNot` case, where `~a` and `!a` are actually equivalent for Boolean values (but a target language might not like `~a` on `bool` values).

Maybe the original plan was that the `Not` instruction should only apply to Boolean values in the first place, and that other values should be converted to `bool` (or a vector of `bool`) before applying `Not`, but even in that case the emit logic makes no sense.

This caused an actual problem for one of my test cases, so it was important to fix it now.

* Fix issue with cached resolution for overoaded operators

The basic problem was that the lookup logic was forming a key based on the *first* definition it found for the overloaded operator, but that means that when processing a prefix `++a` call we might look up the *postfix* definition of `operator++` and decide to use its opcode as the key.

This "fixes" the logic by looking for the first definition with a "compatible" definition (e.g., a `__prefix` function if we are checking a `PrefixExpr`), and then uses its opcode.

A better fix in the long run would be to make the cache just be keyed on the operator name and the "fixity" of the expression (prefix, postfix, or infix).

* Introduce an intermediate structured control-flow representation

The code previously used a single function called `emitIRStmtsForBlocks` in `emit.cpp` that would take a logical sub-graph of the CFG and emit it as high-level statements.
It would do this by recognizing operations like coniditional branches that it could turn into high-level `if` statements, etc.
The main problem with this function was that it mixed together the logic for how we restructure the program with the logic for how we emit high-level code from that structure.

This change splits those two parts of the algorithm by introducing an intermediate data structure: a tree of `Region`s, which represent single-entry regions of the CFG.
There are subclasses of `Region` corresponding to various structured control-flow constructs, and then a leaf case that wraps a single `IRBlock`.

The new function `generateRegionsForIRBlocks()` (in `ir-restructure.cpp`) now handles the restructuring work, by building one or more `Region`s to represent a sub-graph, while `emitRegion()` handles emitting HLSL/GLSL source code from a region.
Splitting things in this way opens up some opportunities for future changes:

* We can expand the set of IR control-flow constructs allowed, so long as we can still generate structure `Region`s from them, without having to mess with the emit logic (e.g., we could start to support multi-level `break` by introducing temporaries as needed). In the limit we can generate our `Region`s using something like the "Relooper" algorithm.

* We can emit to other representations while retaining the same control-flow restructuring support. E.g., if we drop the structured information from the IR, then emitting to SPIR-V for Vulkan would require us to use the strucured control-flow information from these `Region`s.

* We can do analysis that needs to understand `Region` structure. This is relevant to issue #569, which was what prompted me to start on this work. Now that we have a representation of the nesting of `Region`s, we can use it to reason about visibility of values between blocks.

During development of this change I ran into a gotcha, in that I had been assuming each IR block would map to a single `Region`, forgetting that our current lowering of "continue clauses" in `for` loops leads to them being duplicated. The `Region` representation handles this by having a linked-list struct mapping IR blocks to the `SimpleRegion`s that represent them. I added a test case that includes a `for` loop with a continue clause that is reached along multiple paths just to make sure that we continue to support that case.

The compiler output should not change as a result of this work; this is supposed to be a pure refactoring change.

* Add a pass to resolve scoping issues in generated code

Fixes #569

The basic problem arises because the structured control flow that we output in high-level HLSL/GLSL doesn't match the "scoping" rules of an SSA IR.
In particular, SSA says that a value can be used in any block that is dominated by the definition, but in the presence of `break` and `continue` statements it is easy to construct cases where a block dominates something that is not in its scope for structured control flow. Consider:

```hlsl
for(;;) {
    int a = xyz;
    if(a) { int b = a; break; }
    int c = a;
}
int d = b;
```

This program is invalid as HLSL, because the variable `b` is referenced outside of its scope, but if we look at the CFG for this function, it is clear that the block that computes `b` dominated the block that computes `d`. IR optimizations can easily create code like this, so we need to be ready for it.

The previous change added an explicit `Region` structure to represent the structured control flow that we re-form out of the IR, and this change adds a pass that exploits the structuring information to detect cases like the above and introduce temporaries to fix the scoping issue. For example, the pass would change the earlier code block into something like:

```hlsl
int tmp;
for(;;) {
    int a = xyz;
    if(a) { int b = a; tmp = b; break; }
    int c = a;
}
int d = tmp;
```

That is, we introduce a new `tmp` variable at a scope "above" both the definition and use of `b`, and then we copy `b` into that temporary right where it is computed, and then use the temporary instead of the original `b` at the use site.

A few details that came up during the implementation:

* Downstream compilers may get confused by code like the above, and complain that `tmp` may be used before it is initialized, even though the very definition of dominators in a CFG means we don't have to worry about it. Still, I introduced some one-off code to initialize the temporaries just to silence spurious warnings coming from fxc.

* We need to be careful not to apply this logic to "phi nodes" (the parameters of basic blocks) since they will already be turned into temporaries by the emit logic, and trying to introduce temporaries with this pass led to broken code (I still need to investigate why). It may be that a future version of this pass should also take the code out of SSA form, so that we can introduce both kinds of temporaries in a single pass (and maybe eliminate some unnecessary variables by doing basic register allocation).

There is another transformation that could fix some issues of this kind, by moving code out of a structured control-flow construct and to the "join point" after it. For example, we could turn our loop from the start of this commit message into:

```hlsl
for(;;) {
    int a = xyz;
    if(a) { break; }
    int c = a;
}
int b = a;
int d = b;
```

Moving the definition of `b` to after the loop is possible because there is no way to get out of the loop without executing that code anyway. Now the scoping issue for `d`'s use of `b` has gone away, but of course we've introduced a *new* scoping issue for `a`, when it gets used by `b`.

Adding a pass to re-arrange control flow like this could reduce the cases where we have to apply the current pass, but it wouldn't eliminate them entirely. That means such a pass can be deferred to future work.

This change includes a test case the reproduces the original issue, so that we can confirm the fix works.

1 files changed, 662 insertions, 0 deletions

diff --git a/source/slang/ir-restructure.cpp b/source/slang/ir-restructure.cpp
new file mode 100644
index 000000000..98311b11b
--- /dev/null
+++ b/source/slang/ir-restructure.cpp
@@ -0,0 +1,662 @@
+// ir-restructure.cpp
+#include "ir-restructure.h"
+
+#include "ir.h"
+#include "ir-insts.h"
+
+namespace Slang
+{
+    bool Region::isDescendentOf(Region* other)
+    {
+        Region* rr = this;
+        while( rr )
+        {
+            if(rr == other)
+                return true;
+
+            rr = rr->getParent();
+        }
+        return false;
+    }
+
+    bool Region::isDescendentOf(IRBlock* block)
+    {
+        Region* rr = this;
+        while( rr )
+        {
+            if( rr->getFlavor() == Region::Flavor::Simple )
+            {
+                SimpleRegion* simpleRegion = (SimpleRegion*) rr;
+                if(simpleRegion->block == block)
+                    return true;
+            }
+
+            rr = rr->getParent();
+        }
+        return false;
+    }
+
+    /// An "active" label during control flow (re)structuring.
+    struct LabelStack
+    {
+        /// Possible operations associated with labels.
+        enum class Op
+        {
+            Break,
+            Continue,
+
+            CountOf,
+        };
+
+        /// What kind of operation does a branch to this label represent?
+        Op          op;
+
+        /// The next label down on the stack
+        LabelStack* parent;
+
+        /// The block the represents this label in the IR control flow graph.
+        IRBlock*    block;
+
+        /// The region that represents this label in the structured program
+        Region*     region;
+    };
+
+    /// State used when restructuring control flow.
+    struct ControlFlowRestructuringContext
+    {
+        /// Sink to use when diagnosing errors in control-flow restructuring.
+        ///
+        /// The restructuring pass should be able to handle anything the front-end
+        /// throws at it, so these errors will all be unexpected. Still, we need
+        /// a way to report them cleanly without crashing the process.
+        ///
+        DiagnosticSink* sink = nullptr;
+        DiagnosticSink* getSink() { return sink; }
+
+        /// The region tree we are in the process of building.
+        RegionTree* regionTree = nullptr;
+    };
+
+    /// Convert a range of blocks in the IR CFG into a region.
+    ///
+    /// We want to generate a region that stands in for the
+    /// blocks that are logically in the internal [begin, end)
+    /// which we consider as representing a single-entry multiple-exit
+    /// sub-graph. Note that `end` is *not* part of the sub-graph,
+    /// but instead points to a block that is logically "after"
+    /// the sub-graph. `end` can be `null` to indicate that the
+    /// sub-graph extends as far as possible.
+    ///
+    /// Because there can be multiple exits, control flow may
+    /// exit the sub-graph without branching to `end`, any
+    /// such "non-local" branching should be to one of the
+    /// blocks stored in the current `LabelStack`.
+    ///
+    // TODO: Eventually we should replace all of this logic with
+    // a variation on the "Relooper" algorithm as it is used
+    // in Emscripten.
+    //
+    static RefPtr<Region> generateRegionsForIRBlocks(
+        ControlFlowRestructuringContext*    ctx,
+        Region*                             inParentRegion,
+        IRBlock*                            begin,
+        IRBlock*                            end,
+        LabelStack*                         initialLabels,      // Labels to use at the start
+        LabelStack*                         labels = nullptr)   // Labels to switch to after emitting first basic block
+    {
+        if(!labels)
+            labels = initialLabels;
+        auto useLabels = initialLabels;
+
+        //
+        // We will try to build up as long of a sequential/simple region
+        // as possible, to avoid deep recursion in this algorithm.
+        //
+        RefPtr<Region> resultRegion = nullptr;
+        RefPtr<Region>* resultLink = &resultRegion;
+
+        // As we move along, the parent region to use for regions
+        // we create will shift, so we need a temporary to track
+        // the current parent region.
+        //
+        Region* parentRegion = inParentRegion;
+
+        //
+        // We will start with the `begin` block, and try to proceed
+        // sequentially until we see the `end` block, or run into
+        // an edge that exits teh region.
+        //
+        IRBlock* block = begin;
+        while(block != end)
+        {
+            // If the block we are trying to emit has been registered as a
+            // destination label (e.g. for a loop or `switch`) then we
+            // need to exit the current region, which amounts to generating
+            // a `break` or `continue` operation.
+            //
+            // TODO: we eventually need to handle the possibility of
+            // multi-level break/continue targets, which could be challenging.
+
+            // Because we will only support single-level break/continue, we
+            // want to resolve what is the most recent label that is "active"
+            // for the given operation (`break` or `continue`).
+            //
+            // We will do this with a naive loop, just to keep things simple.
+            // We start with no block "regsitered" as the target for each
+            // operation.
+            //
+            IRBlock* registeredBlock[(int)LabelStack::Op::CountOf] = {};
+            for( auto ll = useLabels; ll; ll = ll->parent )
+            {
+                // For each active label, see if it is the first one
+                // we encounter for the given op.
+                //
+                if(!registeredBlock[(int)ll->op])
+                {
+                    registeredBlock[(int)ll->op] = ll->block;
+                }
+            }
+
+            // Next we will search through *all* of the registered labels,
+            // and see if one of them matches the current `block`.
+            //
+            for(auto ll = useLabels; ll; ll = ll->parent)
+            {
+                // Does this label match the block we are trying to translate?
+                if(ll->block != block)
+                    continue;
+
+                // Okay, the block we are trying to generate code for is a label
+                // that we should branch to (we shouldn't just emit the code here
+                // and now...)
+                //
+                // We should first confirm that the block is the inner-most label
+                // registered for the given control-flow op (`break` or `continue`)
+                // because if it *isn't* we currently can't generate code.
+                //
+                if(block != registeredBlock[(int)ll->op])
+                {
+                    ctx->getSink()->diagnose(block, Diagnostics::multiLevelBreakUnsupported);
+                }
+
+                // Now we need to create a structured `break` or `continue` operation
+                // to match the operation associated with the target.
+                //
+                switch(ll->op)
+                {
+                case LabelStack::Op::Break:
+                    {
+                        auto outerRegion = (BreakableRegion*) ll->region;
+                        RefPtr<BreakRegion> breakRegion = new BreakRegion(parentRegion, outerRegion);
+
+                        *resultLink = breakRegion;
+                        resultLink = nullptr;
+                    }
+                    break;
+
+                case LabelStack::Op::Continue:
+                    {
+                        auto outerRegion = (LoopRegion*) ll->region;
+                        RefPtr<ContinueRegion> continueRegion = new ContinueRegion(parentRegion, outerRegion);
+
+                        *resultLink = continueRegion;
+                        resultLink = nullptr;
+                    }
+                    break;
+                }
+
+                // If the `block` matched an active label, then we should have
+                // created a branch, and there is nothing to be done here.
+                return resultRegion;
+            }
+
+            // We now know that the given `block` is part of our control-flow region,
+            // so we need to output a simple region that executes the code in that block.
+            //
+            RefPtr<SimpleRegion> simpleRegion = new SimpleRegion(parentRegion, block);
+
+            // We need to register the mapping from `block` to this region, but in
+            // general this isn't a one-to-one mapping, but rather one-to-many.
+            // This is because a "continue clause" in a `for` loop might get duplicated
+            // at each `continue` site in the output code. To deal with this
+            // we build a singly-linked list of regions for each block.
+            //
+            // TODO: confirm that continue clauses are the only case that leads
+            // to duplication.
+            //
+            // TODO: remove this workaround once we have a more powerful restructuring
+            // pass that avoids duplicating blocks (by introducing new temporaries...)
+            //
+            SimpleRegion* nextSimpleRegionForSameBlock = nullptr;
+            ctx->regionTree->mapBlockToRegion.TryGetValue(block, nextSimpleRegionForSameBlock);
+            ctx->regionTree->mapBlockToRegion[block] = simpleRegion;
+
+            *resultLink = simpleRegion;
+            resultLink = &simpleRegion->nextRegion;
+            parentRegion = simpleRegion;
+
+            // The simple region we created will represent all of the non-terminator
+            // instructions in the `block`, so now we need to figure out what to
+            // create to represent that terminator.
+            //
+            auto terminator = block->getTerminator();
+            SLANG_ASSERT(terminator != nullptr);
+            switch (terminator->op)
+            {
+            default:
+            case kIROp_conditionalBranch:
+                // Note: we don't currently generate ordinary `conditionalBranch` instructions,
+                // and instead only generate `ifElse` instructions, which include additional
+                // information that can inform our control-flow restructuring pass.
+                //
+                SLANG_UNEXPECTED("unhandled terminator instruction opcode");
+                // fall through to:
+            case kIROp_unreachable:
+            case kIROp_ReturnVal:
+            case kIROp_ReturnVoid:
+            case kIROp_discard:
+                // These cases are all simple terminators that can be handled as-is
+                // without needing to construct a separate `Region` to encapsulate them.
+                //
+                // We will cap off the current sequence of simple regions and return.
+                //
+                *resultLink = nullptr;
+                return resultRegion;
+
+            case kIROp_ifElse:
+                {
+                    // Here we have a two-way branch, so that we will construct a
+                    // region representing an `if` statement.
+                    //
+                    auto ifInst = (IRIfElse*)terminator;
+                    auto condition = ifInst->getCondition();
+                    auto trueBlock = ifInst->getTrueBlock();
+                    auto falseBlock = ifInst->getFalseBlock();
+                    auto afterBlock = ifInst->getAfterBlock();
+
+
+                    RefPtr<IfRegion> ifRegion = new IfRegion(parentRegion, condition);
+
+                    // The region for the "then" part of things will consist of
+                    // the range of blocks `[trueBlock, afterBlock)`.
+                    //
+                    // This logic assumes that `afterBlock` is a valid structured
+                    // "join point" such that any branch out of the sub-region
+                    // either leads to `afterBlock` *or* one of the labels
+                    // that is already present on our label stack.
+                    //
+                    ifRegion->thenRegion = generateRegionsForIRBlocks(
+                        ctx,
+                        ifRegion,
+                        trueBlock,
+                        afterBlock,
+                        labels);
+
+                    // Generating a region for the `else` part is similar.
+                    // Note that it is possible for this to be a `null`
+                    // region, if `falseBlock == afterBlock`.
+                    //
+                    ifRegion->elseRegion = generateRegionsForIRBlocks(
+                        ctx,
+                        ifRegion,
+                        falseBlock,
+                        afterBlock,
+                        labels);
+
+                    *resultLink = ifRegion;
+                    resultLink = &ifRegion->nextRegion;
+                    parentRegion = ifRegion;
+
+                    // Continue with the block after the `ifElse` instruction.
+                    block = afterBlock;
+                }
+                break;
+
+            case kIROp_loop:
+                {
+                    // The terminator in this case is the header for a structured loop.
+                    //
+                    auto loopInst = (IRLoop*) terminator;
+                    auto bodyBlock = loopInst->getTargetBlock();
+                    auto afterBlock = loopInst->getBreakBlock();
+
+                    RefPtr<LoopRegion> loopRegion = new LoopRegion(parentRegion, loopInst);
+
+                    // We will need to set up entries on our label stack to
+                    // represent the targets for `break` or `continue`
+                    // operations inside the loop.
+                    //
+                    // First we set up the stack entry for the `break` label,
+                    // which will refer to the block *after* the loop.
+                    //
+                    // The region we specify for the label will still be
+                    // the loop region, though, because the loop is what
+                    // we are breaking out of.
+                    //
+                    LabelStack loopBreakLabelStack;
+                    loopBreakLabelStack.parent = labels;
+                    loopBreakLabelStack.block = afterBlock;
+                    loopBreakLabelStack.region = loopRegion;
+                    loopBreakLabelStack.op = LabelStack::Op::Break;
+
+                    //
+                    // The `continue` label warrants a bit more careful explanation,
+                    // because it will *not* refer to the block that was regsitered
+                    // as the continue target in the IR `loop` instruction. This
+                    // is because we will always emit our loops as `for(;;) { ... }`
+                    // with no continue clause at all, so that a `continue` in
+                    // the output code will always refer to the top of the loop.
+                    //
+                    // This means that the `continue` label for the purposes of
+                    // structured control flow will be the start of the loop body:
+                    //
+                    LabelStack loopContinueLabelStack;
+                    loopContinueLabelStack.parent = &loopBreakLabelStack;
+                    loopContinueLabelStack.block = bodyBlock;
+                    loopContinueLabelStack.region = loopRegion;
+                    loopContinueLabelStack.op = LabelStack::Op::Continue;
+                    //
+                    // Note: by ignoring the original continue block from the
+                    // high-level loop, we create a situation where that code
+                    // might get emitted more than once (once per implicit
+                    // or explicit `continue` site in the original program).
+                    //
+                    // That is an acceptable trade-off for now, because continue
+                    // blocks will usually be small (and fxc makes the same choice),
+                    // but it could lead to Bad Things if somebody were to call
+                    // a function in their continue clause, and that function does
+                    // a compute shader barrier operation.
+                    //
+                    // A better long-term fix is to take a high-level loop like:
+                    //
+                    //      for(A; B; C) { ... continue; ... break; ... }
+                    //
+                    // and translate it into something like the following (assuming
+                    // we have labeled statements and multi-level `break`):
+                    //
+                    //      A;
+                    //      Outer: for(;;) {
+                    //          Inner: for(;;) {
+                    //              if(B) {} else break Outer;
+                    //              ...
+                    //              break Inner; // `continue` becomes break of inner loop
+                    //              ...
+                    //              break Outer; // `break` becomes break of outer loop
+                    //              ...
+                    //              break; // inner loop unconditionally breaks at the end
+                    //          }
+                    //          C;  // continue clause comes after inner loop
+                    //      }
+                    //
+                    // If you draw up a control flow graph for that code, you'll find
+                    // it is equivalent to the orignal `for` loop, but now supports
+                    // arbitrary code (not just a single expression) for the continue clause.
+                    // Unlike the current code-duplication solution, `C` appears only once
+                    // in the output, and seems to clearly be at a "joint point" for control
+                    // flow so that it is clear that a barrier there is valid in GLSL.
+                    //
+                    // Anyway, back our regularly scheduled programming.
+                    //
+                    // With the label stack stuff set up, we want to take the region
+                    // of the CFG defined by `[bodyBlock, afterBlock)` and turn it into
+                    // the body region for our loop.
+                    //
+                    // The only thing we want to be a little bit careful about is
+                    // that we don't want the logic at the top of this function
+                    // that looks for a block it can translate into a `continue`
+                    // to trigger on `bodyBlock`, since that means we'd just turn
+                    // the whole body into a single `continue`.
+                    //
+                    // To avoid this problem, we pass in two different label stacks:
+                    // one to use for the first block, and one to use for subsequent
+                    // blocks.
+                    //
+                    loopRegion->body = generateRegionsForIRBlocks(
+                        ctx,
+                        loopRegion,
+                        bodyBlock,
+                        // TODO: should we pass `afterBlock` here instead of `null`?
+                        nullptr,
+                        // For the first block, we only want the `break` label active
+                        &loopBreakLabelStack,
+                        // After the first block, we can safely use the `continue` label too
+                        &loopContinueLabelStack);
+
+                    *resultLink = loopRegion;
+                    resultLink = &loopRegion->nextRegion;
+                    parentRegion = loopRegion;
+
+                    // Continue with the block after the loop
+                    block = afterBlock;
+                }
+                break;
+
+            case kIROp_unconditionalBranch:
+                {
+                    // Here we have an unconditional branch that was
+                    // not covered by one of our labels for non-local
+                    // branches (`break` or `continue`).
+                    //
+                    // We will thus assume that the target of the
+                    // branch is part of the same region we are building,
+                    // and continue with the target block;
+                    //
+                    auto branchInst = (IRUnconditionalBranch*) terminator;
+                    block = branchInst->getTargetBlock();
+                }
+                break;
+
+            case kIROp_switch:
+                {
+                    // A `switch` instruction will always translate
+                    // to a `SwitchRegion` and then to a `switch` statement.
+                    //
+                    // We will need to take care to emit `case`s in ways
+                    // that avoid code duplication.
+                    //
+                    // The logic here isn't going to be robust in edge cases
+                    // (please don't write Duff's Device in Slang just yet).
+                    // Doing significantly better than what is here would
+                    // require something like the Relooper algorithm, though.
+                    //
+                    auto switchInst = (IRSwitch*) terminator;
+                    auto condition = switchInst->getCondition();
+                    auto breakLabel = switchInst->getBreakLabel();
+                    auto defaultLabel = switchInst->getDefaultLabel();
+
+                    RefPtr<SwitchRegion> switchRegion = new SwitchRegion(parentRegion, condition);
+
+                    // A direct branch to the block after the `switch` can
+                    // be emitted as a `break` statement, so we will register
+                    // the appropriate label on a label stack:
+                    //
+                    LabelStack switchBreakLabelStack;
+                    switchBreakLabelStack.parent = labels;
+                    switchBreakLabelStack.op = LabelStack::Op::Break;
+                    switchBreakLabelStack.block = breakLabel;
+                    switchBreakLabelStack.region = switchRegion;
+
+                    // We need to track whether we've dealt with
+                    // the `default` case already.
+                    //
+                    bool defaultLabelHandled = false;
+
+                    // If the `default` case just branches to
+                    // the join point, then we don't need to
+                    // do anything with it.
+                    //
+                    if(defaultLabel == breakLabel)
+                        defaultLabelHandled = true;
+
+                    // We will now iterate over the different `case`s, and
+                    // try to group them together to minimize the number of
+                    // sub-regions we have to create.
+                    //
+                    UInt caseIndex = 0;
+                    UInt caseCount = switchInst->getCaseCount();
+                    while(caseIndex < caseCount)
+                    {
+                        // We are going to extract one case here,
+                        // but we might need to fold additional
+                        // cases into it, if they share the
+                        // same label.
+                        //
+                        // Note: this makes assumptions that the
+                        // IR code generator orders cases such
+                        // that: (1) cases with the same label
+                        // are consecutive, and (2) any case
+                        // that "falls through" to another must
+                        // come right before it in the list.
+
+                        auto caseVal = switchInst->getCaseValue(caseIndex);
+                        auto caseLabel = switchInst->getCaseLabel(caseIndex);
+                        caseIndex++;
+
+                        RefPtr<SwitchRegion::Case> currentCase = new SwitchRegion::Case();
+                        switchRegion->cases.Add(currentCase);
+
+                        // Add the case value for this case, and any
+                        // others that share the same label
+                        //
+                        for(;;)
+                        {
+                            currentCase->values.Add(caseVal);
+
+                            // Are there any more `case`s left?
+                            //
+                            if(caseIndex >= caseCount)
+                                break;
+
+                            // Does the next `case` share the same target label?
+                            auto nextCaseLabel = switchInst->getCaseLabel(caseIndex);
+                            if(nextCaseLabel != caseLabel)
+                                break;
+
+                            // If those checks passed, then we will fold
+                            // the next `case` into the same region, and
+                            // keep looking.
+                            caseVal = switchInst->getCaseValue(caseIndex);
+                            caseIndex++;
+                        }
+
+                        // The label for the current `case` might also
+                        // be the label used by the `default` case, so
+                        // check for that here.
+                        //
+                        if(caseLabel == defaultLabel)
+                        {
+                            switchRegion->defaultCase = currentCase;
+                            defaultLabelHandled = true;
+                        }
+
+                        // Now we need to generate a region for the instructions
+                        // that make up this case. The 99% case will be that it
+                        // will terminate with a `break` (or a `return`,
+                        // `continue`, etc.) and so we can pass in `nullptr`
+                        // for the ending block.
+                        //
+                        IRBlock* caseEndLabel = nullptr;
+
+                        // However, there is also the possibility that
+                        // this `case` will fall through to the next, and
+                        // so we need to prepare for that possibility here.
+                        //
+                        // If there *is* a next `case`, then we will set its
+                        // label up as the "end" label when emitting
+                        // the statements inside the block.
+                        if(caseIndex < caseCount)
+                        {
+                            caseEndLabel = switchInst->getCaseLabel(caseIndex);
+                        }
+
+                        // Now we can actually generate the region.
+                        //
+                        currentCase->body = generateRegionsForIRBlocks(
+                            ctx,
+                            switchRegion,
+                            caseLabel,
+                            caseEndLabel,
+                            &switchBreakLabelStack);
+                    }
+
+                    // If we've gone through all the cases and haven't
+                    // managed to encounter the `default:` label,
+                    // then assume it is a distinct case and handle it here.
+                    if(!defaultLabelHandled)
+                    {
+                        RefPtr<SwitchRegion::Case> defaultCase = new SwitchRegion::Case();
+                        switchRegion->cases.Add(defaultCase);
+
+                        // Note: we use `null` instead of `breakLabel` as the end block
+                        // here, to ensure that the `default` region will end with an
+                        // explicit `break` rather than just falling off the end.
+
+                        defaultCase->body = generateRegionsForIRBlocks(
+                            ctx,
+                            switchRegion,
+                            defaultLabel,
+                            nullptr,
+                            &switchBreakLabelStack);
+
+                        switchRegion->defaultCase = defaultCase;
+                    }
+
+                    *resultLink = switchRegion;
+                    resultLink = &switchRegion->nextRegion;
+                    parentRegion = switchRegion;
+
+                    // Continue with the block after the `switch`
+                    block = breakLabel;
+                }
+                break;
+            }
+
+            // After we've emitted the first block, we are safe from accidental
+            // cases where we'd emit an entire loop body as a single `continue`,
+            // so we can safely switch in whatever labels are intended to be used.
+            useLabels = labels;
+
+            // If we reach this point, then we've emitted
+            // one block, and we have a new block where
+            // control flow continues.
+            //
+            // We need to handle a special case here,
+            // when control flow jumps back to the
+            // starting block of the range we were
+            // asked to work with:
+            if (block == begin)
+            {
+                break;
+            }
+        }
+
+        // We seem to have reached the rend of the region
+        // without anything special happening. This means
+        // we should cap off the current sequence of regions
+        // and return what we have.
+        //
+        *resultLink = nullptr;
+        return resultRegion;
+    }
+
+    RefPtr<RegionTree> generateRegionTreeForFunc(
+        IRGlobalValueWithCode*  code,
+        DiagnosticSink*         sink)
+    {
+        RefPtr<RegionTree> regionTree = new RegionTree();
+        regionTree->irCode = code;
+
+        ControlFlowRestructuringContext restructuringContext;
+        restructuringContext.sink = sink;
+        restructuringContext.regionTree = regionTree;
+
+        regionTree->rootRegion = generateRegionsForIRBlocks(
+            &restructuringContext,
+            nullptr,
+            code->getFirstBlock(),
+            nullptr,
+            nullptr);
+
+        return regionTree;
+    }
+}