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

[Philip Reames via llvm-commits]

reames created this revision.
reames added reviewers: dberlin, JosephTremoulet, kparzysz.
reames added a subscriber: llvm-commits.

Note: I'm am not trying to describe what "should be"; I'm only describing what is true today.

The text has been discussed offline with DannyB, but I wanted to a) give him a final chance to comment and b) make sure others were okay with the proposed wording.

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

http://reviews.llvm.org/D13078

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

Index: include/llvm/Support/GenericDomTree.h
===================================================================
--- include/llvm/Support/GenericDomTree.h
+++ 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 an 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: include/llvm/IR/Dominators.h
===================================================================
--- include/llvm/IR/Dominators.h
+++ 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.35438.patch
Type: text/x-patch
Size: 2381 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20150922/986dc0da/attachment.bin>