From 710fde88688bb4919404f37fa54ae9272bccea2f Mon Sep 17 00:00:00 2001 From: Philip Reames Date: Wed, 23 Sep 2015 18:39:37 +0000 Subject: [PATCH] [docs] Update DominatorTree docs to clarify expectations around unreachable blocks 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 | 16 ++++++++++++++++ include/llvm/Support/GenericDomTree.h | 6 ++++-- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/include/llvm/IR/Dominators.h b/include/llvm/IR/Dominators.h index f306b0fccc7..37447c353b1 100644 --- a/include/llvm/IR/Dominators.h +++ b/include/llvm/IR/Dominators.h @@ -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 { public: typedef DominatorTreeBase Base; diff --git a/include/llvm/Support/GenericDomTree.h b/include/llvm/Support/GenericDomTree.h index 63678bb98bb..a790d754d20 100644 --- a/include/llvm/Support/GenericDomTree.h +++ b/include/llvm/Support/GenericDomTree.h @@ -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 *getNode(NodeT *BB) const { auto I = DomTreeNodes.find(BB); if (I != DomTreeNodes.end()) @@ -380,6 +381,7 @@ public: return nullptr; } + /// See getNode. DomTreeNodeBase *operator[](NodeT *BB) const { return getNode(BB); } /// getRootNode - This returns the entry node for the CFG of the function. If -- 2.34.1