[llvm-commits] [llvm] r99638 - /llvm/trunk/docs/ProgrammersManual.html

[Gabor Greif]

Author: ggreif
Date: Fri Mar 26 14:30:47 2010
New Revision: 99638

URL: http://llvm.org/viewvc/llvm-project?rev=99638&view=rev
Log:
add a blurb on const versions of chain traversals and a word of caution

Modified:
    llvm/trunk/docs/ProgrammersManual.html

Modified: llvm/trunk/docs/ProgrammersManual.html
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/ProgrammersManual.html?rev=99638&r1=99637&r2=99638&view=diff
==============================================================================
--- llvm/trunk/docs/ProgrammersManual.html (original)
+++ llvm/trunk/docs/ProgrammersManual.html Fri Mar 26 14:30:47 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>
 
@@ -1960,6 +1960,10 @@
     errs() << *Inst << "\n";
   }
 </pre>
+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.
+
 </div>
 
 <p>Alternatively, it's common to have an instance of the <a
@@ -1981,11 +1985,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.
 </div>
 
 <!--_______________________________________________________________________-->