[llvm-branch-commits] [llvm-branch] r99645 - /llvm/branches/ggreif/const-CallSite/docs/ProgrammersManual.html

[Gabor Greif]

Author: ggreif
Date: Fri Mar 26 14:56:25 2010
New Revision: 99645

URL: http://llvm.org/viewvc/llvm-project?rev=99645&view=rev
Log:
rebase with trunk

Modified:
    llvm/branches/ggreif/const-CallSite/docs/ProgrammersManual.html   (contents, props changed)

Modified: llvm/branches/ggreif/const-CallSite/docs/ProgrammersManual.html
URL: http://llvm.org/viewvc/llvm-project/llvm/branches/ggreif/const-CallSite/docs/ProgrammersManual.html?rev=99645&r1=99644&r2=99645&view=diff
==============================================================================
--- llvm/branches/ggreif/const-CallSite/docs/ProgrammersManual.html (original)
+++ llvm/branches/ggreif/const-CallSite/docs/ProgrammersManual.html Fri Mar 26 14:56:25 2010
@@ -1211,14 +1211,14 @@
 
 <div class="doc_text">
 
-<p>SmallPtrSet has all the advantages of SmallSet (and a SmallSet of pointers is 
-transparently implemented with a SmallPtrSet), but also supports iterators.  If
+<p>SmallPtrSet has all the advantages of <tt>SmallSet</tt> (and a <tt>SmallSet</tt> of pointers is 
+transparently implemented with a <tt>SmallPtrSet</tt>), but also supports iterators.  If
 more than 'N' insertions are performed, a single quadratically
 probed hash table is allocated and grows as needed, providing extremely
 efficient access (constant time insertion/deleting/queries with low constant
 factors) and is very stingy with malloc traffic.</p>
 
-<p>Note that, unlike std::set, the iterators of SmallPtrSet are invalidated
+<p>Note that, unlike <tt>std::set</tt>, the iterators of <tt>SmallPtrSet</tt> are invalidated
 whenever an insertion occurs.  Also, the values visited by the iterators are not
 visited in sorted order.</p>
 
@@ -1843,6 +1843,21 @@
 </pre>
 </div>
 
+<p>Unfortunately, these implicit conversions come at a cost; they prevent
+these iterators from conforming to standard iterator conventions, and thus
+from being usable with standard algorithms and containers. For example, it
+prevents the following code, where <tt>B</tt> is a <tt>BasicBlock</tt>,
+from compiling:</p>
+
+<div class="doc_code">
+<pre>
+  llvm::SmallVector<llvm::Instruction *, 16>(B->begin(), B->end());
+</pre>
+</div>
+
+<p>Because of this, these implicit conversions may be removed some day,
+and <tt>operator*</tt> changed to return a pointer instead of a reference.
+
 </div>
 
 <!--_______________________________________________________________________-->
@@ -1962,7 +1977,11 @@
 </pre>
 </div>
 
-<p>Alternately, it's common to have an instance of the <a
+<p>Note that dereferencing a <tt>Value::use_iterator</tt> is not a very cheap
+operation. Instead of performing <tt>*i</tt> above several times, consider
+doing it only once in the loop body and reusing its result.</p>
+
+<p>Alternatively, it's common to have an instance of the <a
 href="/doxygen/classllvm_1_1User.html">User Class</a> and need to know what
 <tt>Value</tt>s are used by it.  The list of all <tt>Value</tt>s used by a
 <tt>User</tt> is known as a <i>use-def</i> chain.  Instances of class
@@ -1981,10 +2000,13 @@
 </pre>
 </div>
 
-<!--
-  def-use chains ("finding all users of"): Value::use_begin/use_end
-  use-def chains ("finding all values used"): User::op_begin/op_end [op=operand]
--->
+<p>Declaring objects as <tt>const</tt> is an important tool of enforcing
+mutation free algorithms (such as analyses, etc.). For this purpose above
+iterators come in constant flavors as <tt>Value::const_use_iterator</tt>
+and <tt>Value::const_op_iterator</tt>.  They automatically arise when
+calling <tt>use/op_begin()</tt> on <tt>const Value*</tt>s or
+<tt>const User*</tt>s respectively.  Upon dereferencing, they return
+<tt>const Use*</tt>s. Otherwise the above patterns remain unchanged.</p>
 
 </div>
 

Propchange: llvm/branches/ggreif/const-CallSite/docs/ProgrammersManual.html
------------------------------------------------------------------------------
--- svn:mergeinfo (added)
+++ svn:mergeinfo Fri Mar 26 14:56:25 2010
@@ -0,0 +1,2 @@
+/llvm/branches/ggreif/InvokeInst-operands/docs/ProgrammersManual.html:98645-99398
+/llvm/trunk/docs/ProgrammersManual.html:70891,99517-99643