docs: tutorial: insert the basic blocks into the function at construction

[thegameg]

Summary

In the 5th part of Kaleidoscope C++ tutorial, codegen part (5.2.5), the newly created basic blocks are not inserted right away in the parent function of the insertion point.

Inserting them right away makes it look similar to the loop construction, and, in my opinion, avoids confusion.

• docs/tutorial/LangImpl5.rst: Update the tutorial.
• examples/Kaleidoscope/Chapter5/toy.cpp,
• examples/Kaleidoscope/Chapter6/toy.cpp,
• examples/Kaleidoscope/Chapter7/toy.cpp,
• examples/Kaleidoscope/Chapter8/toy.cpp: Propagate changes to next chapters.

[mehdi_amini]

That can sound reasonable, but I'm not sure how much of it was intentional in the first place...

[lhames]

Apologies for the delayed reply on this.

I think the reason for the deferred emission is that it makes the resulting CFG print more neatly when you have nested ifs: the first nested if will appear above the second, and before the join block of the original if.

• Lang.

[thegameg]

Oh, I see, sound reasonable. Thanks @lhames for reviewing this.

docs/tutorial/LangImpl5.rst

       // end of the function.
       BasicBlock *ThenBB =
           BasicBlock::Create(LLVMContext, "then", TheFunction);
-      BasicBlock *ElseBB = BasicBlock::Create(LLVMContext, "else");
-      BasicBlock *MergeBB = BasicBlock::Create(LLVMContext, "ifcont");
+      BasicBlock *ElseBB = BasicBlock::Create(LLVMContext, "else", TheFunction);
+      BasicBlock *MergeBB = BasicBlock::Create(LLVMContext, "ifcont", TheFunction);
 
       Builder.CreateCondBr(CondV, ThenBB, ElseBB);
 

 into).
 
 Once it has that, it creates three blocks. Note that it passes
-"TheFunction" into the constructor for the "then" block. This causes the
+"TheFunction" into the constructor of all the blocks. This causes the
 constructor to automatically insert the new block into the end of the
-specified function. The other two blocks are created, but aren't yet
-inserted into the function.
+specified function.
 
 Once the blocks are created, we can emit the conditional branch that
 chooses between them. Note that creating new blocks does not implicitly
 affect the IRBuilder, so it is still inserting into the block that the
-condition went into. Also note that it is creating a branch to the
-"then" block and the "else" block, even though the "else" block isn't
-inserted into the function yet. This is all ok: it is the standard way
-that LLVM supports forward references.
+condition went into.
 
 .. code-block:: c++
 

 .. code-block:: c++
 
       // Emit else block.
-      TheFunction->getBasicBlockList().push_back(ElseBB);
       Builder.SetInsertPoint(ElseBB);
 
       Value *ElseV = Else->codegen();

       ElseBB = Builder.GetInsertBlock();
 
 Code generation for the 'else' block is basically identical to codegen
-for the 'then' block. The only significant difference is the first line,
-which adds the 'else' block to the function. Recall previously that the
-'else' block was created, but not added to the function. Now that the
-'then' and 'else' blocks are emitted, we can finish up with the merge
-code:
+for the 'then' block. Now that the 'then' and 'else' blocks are emitted,
+we can finish up with the merge code:
 
 .. code-block:: c++
 
       // Emit merge block.
-      TheFunction->getBasicBlockList().push_back(MergeBB);
       Builder.SetInsertPoint(MergeBB);
       PHINode *PN =
         Builder.CreatePHI(Type::getDoubleTy(LLVMContext), 2, "iftmp");

       return PN;
     }
 
-The first two lines here are now familiar: the first adds the "merge"
-block to the Function object (it was previously floating, like the else
-block above). The second changes the insertion point so that newly
-created code will go into the "merge" block. Once that is done, we need
+The first line here is now familiar: it changes the insertion point so that
+newly created code will go into the "merge" block. Once that is done, we need
 to create the PHI node and set up the block/value pairs for the PHI.
 
 Finally, the CodeGen function returns the phi node as the value computed

examples/Kaleidoscope/Chapter5/toy.cpp

 
   Function *TheFunction = Builder.GetInsertBlock()->getParent();
 
-  // Create blocks for the then and else cases.  Insert the 'then' block at the
+  // Create blocks for the then and else cases.  Insert the blocks at the
   // end of the function.
   BasicBlock *ThenBB = BasicBlock::Create(TheContext, "then", TheFunction);
-  BasicBlock *ElseBB = BasicBlock::Create(TheContext, "else");
-  BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont");
+  BasicBlock *ElseBB = BasicBlock::Create(TheContext, "else", TheFunction);
+  BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont", TheFunction);
 
   Builder.CreateCondBr(CondV, ThenBB, ElseBB);
 

   ThenBB = Builder.GetInsertBlock();
 
   // Emit else block.
-  TheFunction->getBasicBlockList().push_back(ElseBB);
   Builder.SetInsertPoint(ElseBB);
 
   Value *ElseV = Else->codegen();

   ElseBB = Builder.GetInsertBlock();
 
   // Emit merge block.
-  TheFunction->getBasicBlockList().push_back(MergeBB);
   Builder.SetInsertPoint(MergeBB);
   PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(TheContext), 2, "iftmp");
 

examples/Kaleidoscope/Chapter6/toy.cpp

 
   Function *TheFunction = Builder.GetInsertBlock()->getParent();
 
-  // Create blocks for the then and else cases.  Insert the 'then' block at the
+  // Create blocks for the then and else cases.  Insert the blocks at the
   // end of the function.
   BasicBlock *ThenBB = BasicBlock::Create(TheContext, "then", TheFunction);
-  BasicBlock *ElseBB = BasicBlock::Create(TheContext, "else");
-  BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont");
+  BasicBlock *ElseBB = BasicBlock::Create(TheContext, "else", TheFunction);
+  BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont", TheFunction);
 
   Builder.CreateCondBr(CondV, ThenBB, ElseBB);
 

   ThenBB = Builder.GetInsertBlock();
 
   // Emit else block.
-  TheFunction->getBasicBlockList().push_back(ElseBB);
   Builder.SetInsertPoint(ElseBB);
 
   Value *ElseV = Else->codegen();

   ElseBB = Builder.GetInsertBlock();
 
   // Emit merge block.
-  TheFunction->getBasicBlockList().push_back(MergeBB);
   Builder.SetInsertPoint(MergeBB);
   PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(TheContext), 2, "iftmp");
 

examples/Kaleidoscope/Chapter7/toy.cpp

 
   Function *TheFunction = Builder.GetInsertBlock()->getParent();
 
-  // Create blocks for the then and else cases.  Insert the 'then' block at the
+  // Create blocks for the then and else cases.  Insert the blocks at the
   // end of the function.
   BasicBlock *ThenBB = BasicBlock::Create(TheContext, "then", TheFunction);
-  BasicBlock *ElseBB = BasicBlock::Create(TheContext, "else");
-  BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont");
+  BasicBlock *ElseBB = BasicBlock::Create(TheContext, "else", TheFunction);
+  BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont", TheFunction);
 
   Builder.CreateCondBr(CondV, ThenBB, ElseBB);
 

   ThenBB = Builder.GetInsertBlock();
 
   // Emit else block.
-  TheFunction->getBasicBlockList().push_back(ElseBB);
   Builder.SetInsertPoint(ElseBB);
 
   Value *ElseV = Else->codegen();

   ElseBB = Builder.GetInsertBlock();
 
   // Emit merge block.
-  TheFunction->getBasicBlockList().push_back(MergeBB);
   Builder.SetInsertPoint(MergeBB);
   PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(TheContext), 2, "iftmp");
 

examples/Kaleidoscope/Chapter8/toy.cpp

 
   Function *TheFunction = Builder.GetInsertBlock()->getParent();
 
-  // Create blocks for the then and else cases.  Insert the 'then' block at the
+  // Create blocks for the then and else cases.  Insert the blocks at the
   // end of the function.
   BasicBlock *ThenBB = BasicBlock::Create(TheContext, "then", TheFunction);
-  BasicBlock *ElseBB = BasicBlock::Create(TheContext, "else");
-  BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont");
+  BasicBlock *ElseBB = BasicBlock::Create(TheContext, "else", TheFunction);
+  BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont", TheFunction);
 
   Builder.CreateCondBr(CondV, ThenBB, ElseBB);
 

   ThenBB = Builder.GetInsertBlock();
 
   // Emit else block.
-  TheFunction->getBasicBlockList().push_back(ElseBB);
   Builder.SetInsertPoint(ElseBB);
 
   Value *ElseV = Else->codegen();

   ElseBB = Builder.GetInsertBlock();
 
   // Emit merge block.
-  TheFunction->getBasicBlockList().push_back(MergeBB);
   Builder.SetInsertPoint(MergeBB);
   PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(TheContext), 2, "iftmp");