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

[Gabor Greif]

Author: ggreif
Date: Thu Mar 12 05:30:31 2009
New Revision: 66790

URL: http://llvm.org/viewvc/llvm-project?rev=66790&view=rev
Log:
add some text to explain sentinels

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=66790&r1=66789&r2=66790&view=diff

==============================================================================
--- llvm/trunk/docs/ProgrammersManual.html (original)
+++ llvm/trunk/docs/ProgrammersManual.html Thu Mar 12 05:30:31 2009
@@ -901,6 +901,7 @@
       <li><a href="#dss_ilist_traits">ilist_traits</a></li>
       <li><a href="#dss_iplist">iplist</a></li>
       <li><a href="#dss_ilist_node">llvm/ADT/ilist_node.h</a></li>
+      <li><a href="#dss_ilist_sentinel">Sentinels</a></li>
     </ul>
 </div>
 
@@ -946,6 +947,44 @@
 
 <!-- _______________________________________________________________________ -->
 <div class="doc_subsubsection">
+  <a name="dss_ilist_sentinel">Sentinels</a>
+</div>
+
+<div class="doc_text">
+<p><tt>ilist</tt>s have another speciality that must be considered. To be a good
+citizen in the C++ ecosystem, it needs to support the standard container
+operations, such as <tt>begin</tt> and <tt>end</tt> iterators, etc. Also, the
+<tt>operator--</tt> must work correctly on the <tt>end</tt> iterator in the
+case of non-empty <tt>ilist</tt>s.</p>
+
+<p>The only sensible solution to this problem is to allocate a so-called
+<i>sentinel</i> along with the intrusive list, which serves as the <tt>end</tt>
+iterator, providing the back-link to the last element. However conforming to the
+C++ convention it is illegal to <tt>operator++</tt> beyond the sentinel and it
+also must not be dereferenced.</p>
+
+<p>These constraints allow for some implementation freedom to the <tt>ilist</tt>
+how to allocate and store the sentinel. The corresponding policy is dictated
+by <tt>ilist_traits<T></tt>. By default a <tt>T</tt> gets heap-allocated
+whenever the need for a sentinel arises.</p>
+
+<p>While the default policy is sufficient in most cases, it may break down when
+<tt>T</tt> does not provide a default constructor. Also, in the case of many
+instances of <tt>ilist</tt>s, the memory overhead of the associated sentinels
+is wasted. To alleviate the situation with numerous and voluminous
+<tt>T</tt>-sentinels, sometimes a trick is employed, leading to <i>ghostly
+sentinels</i>.</p>
+
+<p>Ghostly sentinels are obtained by specially-crafted <tt>ilist_traits<T></tt>
+which superpose the sentinel with the <tt>ilist</tt> instance in memory. Pointer
+arithmetic is used to obtain the sentinel, which is relative to the
+<tt>ilist</tt>'s <tt>this</tt> pointer. The <tt>ilist</tt> is augmented by an
+extra pointer, which serves as the back-link of the sentinel. This is the only
+field in the ghostly sentinel which can be legally accessed.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
   <a name="dss_other">Other Sequential Container options</a>
 </div>