[docs] Update DominatorTree docs to clarify expectations around unreachable blocks
authorPhilip Reames <listmail@philipreames.com>
Wed, 23 Sep 2015 18:39:37 +0000 (18:39 +0000)
committerPhilip Reames <listmail@philipreames.com>
Wed, 23 Sep 2015 18:39:37 +0000 (18:39 +0000)
Note: I'm am not trying to describe what "should be"; I'm only describing what is true today.

This came out of my recent question to llvm-dev titled: When can the dominator tree not contain a node for a basic block?

Differential Revision: http://reviews.llvm.org/D13078

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@248417 91177308-0d34-0410-b5e6-96231b3b80d8

include/llvm/IR/Dominators.h
include/llvm/Support/GenericDomTree.h

index f306b0f..37447c3 100644 (file)
@@ -64,6 +64,22 @@ public:
 
 /// \brief Concrete subclass of DominatorTreeBase that is used to compute a
 /// normal dominator tree.
+///
+/// Definition: A block is said to be forward statically reachable if there is
+/// a path from the entry of the function to the block.  A statically reachable
+/// block may become statically unreachable during optimization.
+///
+/// A forward unreachable block may appear in the dominator tree, or it may
+/// not.  If it does, dominance queries will return results as if all reachable
+/// blocks dominate it.  When asking for a Node corresponding to a potentially
+/// unreachable block, calling code must handle the case where the block was
+/// unreachable and the result of getNode() is nullptr.
+///
+/// Generally, a block known to be unreachable when the dominator tree is
+/// constructed will not be in the tree.  One which becomes unreachable after
+/// the dominator tree is initially constructed may still exist in the tree,
+/// even if the tree is properly updated. Calling code should not rely on the
+/// preceding statements; this is stated only to assist human understanding.
 class DominatorTree : public DominatorTreeBase<BasicBlock> {
 public:
   typedef DominatorTreeBase<BasicBlock> Base;
index 63678bb..a790d75 100644 (file)
@@ -371,8 +371,9 @@ public:
   void releaseMemory() { reset(); }
 
   /// getNode - return the (Post)DominatorTree node for the specified basic
-  /// block.  This is the same as using operator[] on this class.
-  ///
+  /// block.  This is the same as using operator[] on this class.  The result
+  /// may (but is not required to) be null for a forward (backwards)
+  /// statically unreachable block.
   DomTreeNodeBase<NodeT> *getNode(NodeT *BB) const {
     auto I = DomTreeNodes.find(BB);
     if (I != DomTreeNodes.end())
@@ -380,6 +381,7 @@ public:
     return nullptr;
   }
 
+  /// See getNode.
   DomTreeNodeBase<NodeT> *operator[](NodeT *BB) const { return getNode(BB); }
 
   /// getRootNode - This returns the entry node for the CFG of the function.  If