libstdc++-v3/docs/html/23_containers/howto.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5    <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
   6    <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL">
   7    <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 23.">
   8    <meta name="GENERATOR" content="vi and eight fingers">
   9    <title>libstdc++-v3 HOWTO:  Chapter 23</title>
  10 <link rel="StyleSheet" href="../lib3styles.css">
  11 </head>
  12 <body>
  13
  14 <h1 class="centered"><a name="top">Chapter 23:  Containers</a></h1>
  15
  16 <p>Chapter 23 deals with container classes and what they offer.
  17 </p>
  18
  19
  20 <!-- ####################################################### -->
  21 <hr>
  22 <h1>Contents</h1>
  23 <ul>
  24    <li><a href="#1">Making code unaware of the container/array difference</a>
  25    <li><a href="#2">Variable-sized bitmasks</a>
  26    <li><a href="#3">Containers and multithreading</a>
  27    <li><a href="#4">&quot;Hinting&quot; during insertion</a>
  28    <li><a href="#5">Bitmasks and string arguments</a>
  29    <li><a href="#6"><code>std::list::size()</code> is O(n)!</a>
  30 </ul>
  31
  32 <hr>
  33
  34 <!-- ####################################################### -->
  35
  36 <h2><a name="1">Making code unaware of the container/array difference</a></h2>
  37    <p>You're writing some code and can't decide whether to use builtin
  38       arrays or some kind of container.  There are compelling reasons
  39       to use one of the container classes, but you're afraid that you'll
  40       eventually run into difficulties, change everything back to arrays,
  41       and then have to change all the code that uses those data types to
  42       keep up with the change.
  43    </p>
  44    <p>If your code makes use of the standard algorithms, this isn't as
  45       scary as it sounds.  The algorithms don't know, nor care, about
  46       the kind of &quot;container&quot; on which they work, since the
  47       algorithms are only given endpoints to work with.  For the container
  48       classes, these are iterators (usually <code>begin()</code> and
  49       <code>end()</code>, but not always).  For builtin arrays, these are
  50       the address of the first element and the
  51       <a href="../24_iterators/howto.html#2">past-the-end</a> element.
  52    </p>
  53    <p>Some very simple wrapper functions can hide all of that from the
  54       rest of the code.  For example, a pair of functions called
  55       <code>beginof</code> can be written, one that takes an array, another
  56       that takes a vector.  The first returns a pointer to the first
  57       element, and the second returns the vector's <code>begin()</code>
  58       iterator.
  59    </p>
  60    <p>The functions should be made template functions, and should also
  61       be declared inline.  As pointed out in the comments in the code
  62       below, this can lead to <code>beginof</code> being optimized out of
  63       existence, so you pay absolutely nothing in terms of increased
  64       code size or execution time.
  65    </p>
  66    <p>The result is that if all your algorithm calls look like
  67       <pre>
  68    std::transform(beginof(foo), endof(foo), beginof(foo), SomeFunction);</pre>
  69       then the type of foo can change from an array of ints to a vector
  70       of ints to a deque of ints and back again, without ever changing any
  71       client code.
  72    </p>
  73    <p>This author has a collection of such functions, called &quot;*of&quot;
  74       because they all extend the builtin &quot;sizeof&quot;.  It started
  75       with some Usenet discussions on a transparent way to find the length
  76       of an array.  A simplified and much-reduced version for easier
  77       reading is <a href="wrappers_h.txt">given here</a>.
  78    </p>
  79    <p>Astute readers will notice two things at once:  first, that the
  80       container class is still a <code>vector&lt;T&gt;</code> instead of a
  81       more general <code>Container&lt;T&gt;</code>.  This would mean that
  82       three functions for <code>deque</code> would have to be added, another
  83       three for <code>list</code>, and so on.  This is due to problems with
  84       getting template resolution correct; I find it easier just to
  85       give the extra three lines and avoid confusion.
  86    </p>
  87    <p>Second, the line
  88       <pre>
  89     inline unsigned int lengthof (T (&amp;)[sz]) { return sz; } </pre>
  90       looks just weird!  Hint:  unused parameters can be left nameless.
  91    </p>
  92    <p>Return <a href="#top">to top of page</a> or
  93       <a href="../faq/index.html">to the FAQ</a>.
  94    </p>
  95
  96 <hr>
  97 <h2><a name="2">Variable-sized bitmasks</a></h2>
  98    <p>No, you cannot write code of the form
  99       <!-- Careful, the leading spaces in PRE show up directly. -->
 100       <pre>
 101       #include &lt;bitset&gt;
 102
 103       void foo (size_t n)
 104       {
 105           std::bitset&lt;n&gt;   bits;
 106           ....
 107       } </pre>
 108       because <code>n</code> must be known at compile time.  Your compiler is
 109       correct; it is not a bug.  That's the way templates work.  (Yes, it
 110       <em>is</em> a feature.)
 111    </p>
 112    <p>There are a couple of ways to handle this kind of thing.  Please
 113       consider all of them before passing judgement.  They include, in
 114       no particular order:
 115       <ul>
 116         <li>A very large N in <code>bitset&lt;N&gt;</code>.
 117         <li>A container&lt;bool&gt;.
 118         <li>Extremely weird solutions.
 119       </ul>
 120    </p>
 121    <p><strong>A very large N in
 122       <code>bitset&lt;N&gt;</code>.&nbsp;&nbsp;</strong>  It has
 123       been pointed out a few times in newsgroups that N bits only takes up
 124       (N/8) bytes on most systems, and division by a factor of eight is pretty
 125       impressive when speaking of memory.  Half a megabyte given over to a
 126       bitset (recall that there is zero space overhead for housekeeping info;
 127       it is known at compile time exactly how large the set is) will hold over
 128       four million bits.  If you're using those bits as status flags (e.g.,
 129       &quot;changed&quot;/&quot;unchanged&quot; flags), that's a <em>lot</em>
 130       of state.
 131    </p>
 132    <p>You can then keep track of the &quot;maximum bit used&quot; during some
 133       testing runs on representative data, make note of how many of those bits
 134       really need to be there, and then reduce N to a smaller number.  Leave
 135       some extra space, of course.  (If you plan to write code like the
 136       incorrect example above, where the bitset is a local variable, then you
 137       may have to talk your compiler into allowing that much stack space;
 138       there may be zero space overhead, but it's all allocated inside the
 139       object.)
 140    </p>
 141    <p><strong>A container&lt;bool&gt;.&nbsp;&nbsp;</strong>  The Committee
 142       made provision
 143       for the space savings possible with that (N/8) usage previously mentioned,
 144       so that you don't have to do wasteful things like
 145       <code>Container&lt;char&gt;</code> or
 146       <code>Container&lt;short int&gt;</code>.
 147       Specifically, <code>vector&lt;bool&gt;</code> is required to be
 148       specialized for that space savings.
 149    </p>
 150    <p>The problem is that <code>vector&lt;bool&gt;</code> doesn't behave like a
 151       normal vector anymore.  There have been recent journal articles which
 152       discuss the problems (the ones by Herb Sutter in the May and
 153       July/August 1999 issues of
 154       <u>C++ Report</u> cover it well).  Future revisions of the ISO C++
 155       Standard will change the requirement for <code>vector&lt;bool&gt;</code>
 156       specialization.  In the meantime, <code>deque&lt;bool&gt;</code> is
 157       recommended (although its behavior is sane, you probably will not get
 158       the space savings, but the allocation scheme is different than that
 159       of vector).
 160    </p>
 161    <p><strong>Extremely weird solutions.&nbsp;&nbsp;</strong>  If you have
 162       access to
 163       the compiler and linker at runtime, you can do something insane, like
 164       figuring out just how many bits you need, then writing a temporary
 165       source code file.  That file contains an instantiation of
 166       <code>bitset</code>
 167       for the required number of bits, inside some wrapper functions with
 168       unchanging signatures.  Have your program then call the
 169       compiler on that file using Position Independent Code, then open the
 170       newly-created object file and load those wrapper functions.  You'll have
 171       an instantiation of <code>bitset&lt;N&gt;</code> for the exact
 172       <code>N</code>
 173       that you need at the time.  Don't forget to delete the temporary files.
 174       (Yes, this <em>can</em> be, and <em>has been</em>, done.)
 175    </p>
 176    <!-- I wonder if this next paragraph will get me in trouble... -->
 177    <p>This would be the approach of either a visionary genius or a raving
 178       lunatic, depending on your programming and management style.  Probably
 179       the latter.
 180    </p>
 181    <p>Which of the above techniques you use, if any, are up to you and your
 182       intended application.  Some time/space profiling is indicated if it
 183       really matters (don't just guess).  And, if you manage to do anything
 184       along the lines of the third category, the author would love to hear
 185       from you...
 186    </p>
 187    <p>Also note that the implementation of bitset used in libstdc++-v3 has
 188       <a href="../ext/sgiexts.html#ch23">some extensions</a>.
 189    </p>
 190    <p>Return <a href="#top">to top of page</a> or
 191       <a href="../faq/index.html">to the FAQ</a>.
 192    </p>
 193
 194 <hr>
 195 <h2><a name="3">Containers and multithreading</a></h2>
 196    <p>This section discusses issues surrounding the design of
 197       multithreaded applications which use Standard C++ containers.
 198       All information in this section is current as of the gcc 3.0
 199       release and all later point releases.  Although earlier gcc
 200       releases had a different approach to threading configuration and
 201       proper compilation, the basic code design rules presented here
 202       were similar.  For information on all other aspects of
 203       multithreading as it relates to libstdc++, including details on
 204       the proper compilation of threaded code (and compatibility between
 205       threaded and non-threaded code), see Chapter 17.
 206   </p>
 207    <p>Two excellent pages to read when working with the Standard C++
 208       containers and threads are
 209       <a href="http://www.sgi.com/tech/stl/thread_safety.html">SGI's
 210       http://www.sgi.com/tech/stl/thread_safety.html</a> and
 211       <a href="http://www.sgi.com/tech/stl/Allocators.html">SGI's
 212       http://www.sgi.com/tech/stl/Allocators.html</a>.
 213   </p>
 214    <p><em>However, please ignore all discussions about the user-level
 215       configuration of the lock implementation inside the STL
 216       container-memory allocator on those pages.  For the sake of this
 217       discussion, libstdc++-v3 configures the SGI STL implementation,
 218       not you.  This is quite different from how gcc pre-3.0 worked.
 219       In particular, past advice was for people using g++ to
 220       explicitly define _PTHREADS or other macros or port-specific
 221       compilation options on the command line to get a thread-safe
 222       STL.  This is no longer required for any port and should no
 223       longer be done unless you really know what you are doing and
 224       assume all responsibility.</em>
 225   </p>
 226    <p>Since the container implementation of libstdc++-v3 uses the SGI
 227       code, we use the same definition of thread safety as SGI when
 228       discussing design.  A key point that beginners may miss is the
 229       fourth major paragraph of the first page mentioned above
 230       (&quot;For most clients,&quot;...), which points out that
 231       locking must nearly always be done outside the container, by
 232       client code (that'd be you, not us).  There is a notable
 233       exceptions to this rule.  Allocators called while a container or
 234       element is constructed uses an internal lock obtained and
 235       released solely within libstdc++-v3 code (in fact, this is the
 236       reason STL requires any knowledge of the thread configuration).
 237   </p>
 238    <p>For implementing a container which does its own locking, it is
 239       trivial to provide a wrapper class which obtains the lock (as
 240       SGI suggests), performs the container operation, and then
 241       releases the lock.  This could be templatized <em>to a certain
 242       extent</em>, on the underlying container and/or a locking
 243       mechanism.  Trying to provide a catch-all general template
 244       solution would probably be more trouble than it's worth.
 245    </p>
 246    <p>The STL implementation is currently configured to use the
 247       high-speed caching memory allocator.  If you absolutely think
 248       you must change this on a global basis for your platform to better
 249       support multi-threading, then please consult all commentary in
 250       include/bits/stl_alloc.h and the allocators link below.
 251       <blockquote>
 252       <p>(Explicit warning since so many people get confused while
 253       attempting this:)
 254       </p>
 255       <p><strong>Adding -D__USE_MALLOC on the command
 256       line is almost certainly a bad idea.</strong>  Memory efficiency is
 257       almost guaranteed to suffer as a result; this is
 258       <a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00136.html">why
 259       we disabled it for 3.0 in the first place</a>.
 260       </p>
 261       <p>Related to threading or otherwise, the current recommendation is
 262       that users not add any macro defines on the command line to remove or
 263       otherwise disable features of libstdc++-v3.  There is
 264       no condition under which it will help you without causing other
 265       issues to perhaps raise up (possible linkage/ABI problems).  In
 266       particular, __USE_MALLOC should only be added to a libstdc++-v3
 267       configuration file, include/bits/c++config (where such user
 268       action is cautioned against), and the entire library should be
 269       rebuilt.  If you do not, then you might be violating the
 270       one-definition rule of C/C++ and you might cause yourself untold
 271       problems.
 272       </p>
 273       </blockquote>
 274       If you find any platform where gcc reports a
 275       threading model other than single, and where libstdc++-v3 builds
 276       a buggy container allocator when used with threads unless you
 277       define __USE_MALLOC, we want to hear about it ASAP.  In the
 278       past, correctness was the main reason people were led to believe
 279       that they should define __USE_MALLOC when using threads.
 280    </p>
 281    <p>There is a better way (not standardized yet):  It is possible to
 282       force the malloc-based allocator on a per-case-basis for some
 283       application code.  The library team generally believes that this
 284       is a better way to tune an application for high-speed using this
 285       implementation of the STL.  There is
 286       <a href="../ext/howto.html#3">more information on allocators here</a>.
 287    </p>
 288    <p>Return <a href="#top">to top of page</a> or
 289       <a href="../faq/index.html">to the FAQ</a>.
 290    </p>
 291
 292 <hr>
 293 <h2><a name="4">&quot;Hinting&quot; during insertion</a></h2>
 294    <p>Section [23.1.2], Table 69, of the C++ standard lists this function
 295       for all of the associative containers (map, set, etc):
 296       <pre>
 297       a.insert(p,t);</pre>
 298       where 'p' is an iterator into the container 'a', and 't' is the item
 299       to insert.  The standard says that &quot;iterator p is a hint
 300       pointing to where the insert should start to search,&quot; but
 301       specifies nothing more.  (LWG Issue #233, currently in review,
 302       addresses this topic, but I will ignore it here because it is not yet
 303       finalized.)
 304    </p>
 305    <p>Here we'll describe how the hinting works in the libstdc++-v3
 306       implementation, and what you need to do in order to take advantage of
 307       it.  (Insertions can change from logarithmic complexity to amortized
 308       constant time, if the hint is properly used.)  Also, since the current
 309       implementation is based on the SGI STL one, these points may hold true
 310       for other library implementations also, since the HP/SGI code is used
 311       in a lot of places.
 312    </p>
 313    <p>In the following text, the phrases <em>greater than</em> and <em>less
 314       than</em> refer to the results of the strict weak ordering imposed on
 315       the container by its comparison object, which defaults to (basically)
 316       &quot;&lt;&quot;.  Using those phrases is semantically sloppy, but I
 317       didn't want to get bogged down in syntax.  I assume that if you are
 318       intelligent enough to use your own comparison objects, you are also
 319       intelligent enough to assign &quot;greater&quot; and &quot;lesser&quot;
 320       their new meanings in the next paragraph.  *grin*
 321    </p>
 322    <p>If the <code>hint</code> parameter ('p' above) is equivalent to:
 323      <ul>
 324       <li><code>begin()</code>, then the item being inserted should have a key
 325           less than all the other keys in the container.  The item will
 326           be inserted at the beginning of the container, becoming the new
 327           entry at <code>begin()</code>.
 328       <li><code>end()</code>, then the item being inserted should have a key
 329           greater than all the other keys in the container.  The item will
 330           be inserted at the end of the container, becoming the new entry
 331           at <code>end()</code>.
 332       <li>neither <code>begin()</code> nor <code>end()</code>, then:  Let <code>h</code>
 333           be the entry in the container pointed to by <code>hint</code>, that
 334           is, <code>h = *hint</code>.  Then the item being inserted should have
 335           a key less than that of <code>h</code>, and greater than that of the
 336           item preceding <code>h</code>.  The new item will be inserted
 337           between <code>h</code> and <code>h</code>'s predecessor.
 338      </ul>
 339    </p>
 340    <p>For <code>multimap</code> and <code>multiset</code>, the restrictions are
 341       slightly looser:  &quot;greater than&quot; should be replaced by
 342       &quot;not less than&quot; and &quot;less than&quot; should be replaced
 343       by &quot;not greater than.&quot;  (Why not replace greater with
 344       greater-than-or-equal-to?  You probably could in your head, but the
 345       mathematicians will tell you that it isn't the same thing.)
 346    </p>
 347    <p>If the conditions are not met, then the hint is not used, and the
 348       insertion proceeds as if you had called <code> a.insert(t) </code>
 349       instead.  (<strong>Note </strong> that GCC releases prior to 3.0.2
 350       had a bug in the case with <code>hint == begin()</code> for the
 351       <code>map</code> and <code>set</code> classes.  You should not use a hint
 352       argument in those releases.)
 353    </p>
 354    <p>This behavior goes well with other container's <code>insert()</code>
 355       functions which take an iterator:  if used, the new item will be
 356       inserted before the iterator passed as an argument, same as the other
 357       containers.  The exception
 358       (in a sense) is with a hint of <code>end()</code>:  the new item will
 359       actually be inserted after <code>end()</code>, but it also becomes the
 360       new <code>end()</code>.
 361    </p>
 362    <p><strong>Note </strong> also that the hint in this implementation is a
 363       one-shot.  The insertion-with-hint routines check the immediately
 364       surrounding entries to ensure that the new item would in fact belong
 365       there.  If the hint does not point to the correct place, then no
 366       further local searching is done; the search begins from scratch in
 367       logarithmic time.  (Further local searching would only increase the
 368       time required when the hint is too far off.)
 369    </p>
 370    <p>Return <a href="#top">to top of page</a> or
 371       <a href="../faq/index.html">to the FAQ</a>.
 372    </p>
 373
 374 <hr>
 375 <h2><a name="5">Bitmasks and string arguments</a></h2>
 376    <p>Bitmasks do not take char* nor const char* arguments in their
 377       constructors.  This is something of an accident, but you can read
 378       about the problem:  follow the library's &quot;Links&quot; from the
 379       homepage, and from the C++ information &quot;defect reflector&quot;
 380       link, select the library issues list.  Issue number 116 describes the
 381       problem.
 382    </p>
 383    <p>For now you can simply make a temporary string object using the
 384       constructor expression:
 385       <pre>
 386       std::bitset&lt;5&gt; b ( std::string(&quot;10110&quot;) );
 387       </pre>
 388       instead of
 389       <pre>
 390       std::bitset&lt;5&gt; b ( &quot;10110&quot; );    // invalid
 391       </pre>
 392    </p>
 393    <p>Return <a href="#top">to top of page</a> or
 394       <a href="../faq/index.html">to the FAQ</a>.
 395    </p>
 396
 397 <hr>
 398 <h2><a name="6"><code>std::list::size()</code> is O(n)!</a></h2>
 399    <p>Yes it is, and that's okay.  This is a decision that we preserved when
 400       we imported SGI's STL implementation.  The following is quoted from
 401       <a href="http://www.sgi.com/tech/stl/FAQ.html">their FAQ</a>:
 402       <blockquote>
 403       <p>The size() member function, for list and slist, takes time
 404       proportional to the number of elements in the list.  This was a
 405       deliberate tradeoff.  The only way to get a constant-time size() for
 406       linked lists would be to maintain an extra member variable containing
 407       the list's size.  This would require taking extra time to update that
 408       variable (it would make splice() a linear time operation, for example),
 409       and it would also make the list larger.  Many list algorithms don't
 410       require that extra word (algorithms that do require it might do better
 411       with vectors than with lists), and, when it is necessary to maintain
 412       an explicit size count, it's something that users can do themselves.
 413       </p>
 414       <p>This choice is permitted by the C++ standard. The standard says that
 415       size() &quot;should&quot; be constant time, and &quot;should&quot;
 416       does not mean the same thing as &quot;shall&quot;.  This is the
 417       officially recommended ISO wording for saying that an implementation
 418       is supposed to do something unless there is a good reason not to.
 419       </p>
 420       <p>One implication of linear time size(): you should never write
 421          <pre>
 422          if (L.size() == 0)
 423              ...</pre>
 424          Instead, you should write
 425          <pre>
 426          if (L.empty())
 427              ...</pre>
 428       </p>
 429       </blockquote>
 430    </p>
 431    <p>Return <a href="#top">to top of page</a> or
 432       <a href="../faq/index.html">to the FAQ</a>.
 433    </p>
 434
 435
 436 <!-- ####################################################### -->
 437
 438 <hr>
 439 <p class="fineprint"><em>
 440 See <a href="../17_intro/license.html">license.html</a> for copying conditions.
 441 Comments and suggestions are welcome, and may be sent to
 442 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 443 </em></p>
 444
 445
 446 </body>
 447 </html>