[PATCH] D13078: [docs] Update DominatorTree docs to clarify expectations around unreachable blocks

[Philip Reames via llvm-commits]

This revision was automatically updated to reflect the committed changes.
Closed by commit rL248417: [docs] Update DominatorTree docs to clarify expectations around unreachable… (authored by reames).

Changed prior to commit:
  http://reviews.llvm.org/D13078?vs=35438&id=35540#toc

Repository:
  rL LLVM

http://reviews.llvm.org/D13078

Files:
  llvm/trunk/include/llvm/IR/Dominators.h
  llvm/trunk/include/llvm/Support/GenericDomTree.h

Index: llvm/trunk/include/llvm/Support/GenericDomTree.h
===================================================================
--- llvm/trunk/include/llvm/Support/GenericDomTree.h
+++ llvm/trunk/include/llvm/Support/GenericDomTree.h
@@ -371,15 +371,17 @@
   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())
       return I->second.get();
     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
Index: llvm/trunk/include/llvm/IR/Dominators.h
===================================================================
--- llvm/trunk/include/llvm/IR/Dominators.h
+++ llvm/trunk/include/llvm/IR/Dominators.h
@@ -64,6 +64,22 @@
 
 /// \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;


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D13078.35540.patch
Type: text/x-patch
Size: 2446 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20150923/58e9ed76/attachment.bin>