1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
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="Notes for the libstdc++ extensions.">
8 <meta name="GENERATOR" content="vi and eight fingers">
9 <title>libstdc++-v3 HOWTO: Extensions</title>
10 <link rel="StyleSheet" href="../lib3styles.css">
14 <h1 class="centered"><a name="top">Extensions</a></h1>
16 <p>Here we will make an attempt at describing the non-Standard extensions to
17 the library. Some of these are from SGI's STL, some of these are GNU's,
18 and some just seemed to appear on the doorstep.
20 <p><strong>Before you leap in and use these</strong>, be aware of two things:
22 <li>Non-Standard means exactly that. The behavior, and the very
23 existence, of these extensions may change with little or no
24 warning. (Ideally, the really good ones will appear in the next
25 revision of C++.) Also, other platforms, other compilers, other
26 versions of g++ or libstdc++-v3 may not recognize these names, or
27 treat them differently, or...
28 <li>You should know how to <a href="../faq/index.html#5_4">access
29 these headers properly</a>.
34 <!-- ####################################################### -->
38 <li><a href="#1">Ropes and trees and hashes, oh my!</a>
39 <li><a href="#2">Added members and types</a>
40 <li><a href="#3">Allocators</a>
41 <li><a href="#4">Compile-time checks</a>
42 <li><a href="#5">LWG Issues</a>
47 <!-- ####################################################### -->
49 <h2><a name="1">Ropes and trees and hashes, oh my!</a></h2>
58 </pre> are all here; <code><bvector></code> exposes the old bit_vector
59 class that was used before specialization of vector<bool> was
60 available (it's actually a typedef for the specialization now).
61 <code><hash_map></code> and <code><hash_set></code>
62 are discussed further below. <code><rope></code> is the SGI
63 specialization for large strings ("rope," "large
64 strings," get it? love those SGI folks).
65 <code><slist></code> is a singly-linked list, for when the
66 doubly-linked <code>list<></code> is too much space overhead, and
67 <code><tree></code> exposes the red-black tree classes used in the
68 implementation of the standard maps and sets.
70 <p>Okay, about those hashing classes... I'm going to foist most of the
71 work off onto SGI's own site.
73 <p>Each of the associative containers map, multimap, set, and multiset
74 have a counterpart which uses a
75 <a href="http://www.sgi.com/Technology/STL/HashFunction.html">hashing
76 function</a> to do the arranging, instead of a strict weak ordering
77 function. The classes take as one of their template parameters a
78 function object that will return the hash value; by default, an
80 <a href="http://www.sgi.com/Technology/STL/hash.html">hash</a>.
81 You should specialize this functor for your class, or define your own,
82 before trying to use one of the hashing classes.
84 <p>The hashing classes support all the usual associative container
85 functions, as well as some extra constructors specifying the number
88 <p>Why would you want to use a hashing class instead of the
89 "normal" implementations? Matt Austern writes:
90 <blockquote><em>[W]ith a well chosen hash function, hash tables
91 generally provide much better average-case performance than binary
92 search trees, and much worse worst-case performance. So if your
93 implementation has hash_map, if you don't mind using nonstandard
94 components, and if you aren't scared about the possibility of
95 pathological cases, you'll probably get better performance from
96 hash_map.</em></blockquote>
98 <p>(Side note: for those of you wondering, <strong>"Why wasn't a hash
99 table included in the Standard in the first #!$@ place?"</strong>
100 I'll give a quick answer: it was proposed, but too late and in too
101 unorganized a fashion. Some sort of hashing will undoubtedly be
102 included in a future Standard.
104 <p>Return <a href="#top">to top of page</a> or
105 <a href="../faq/index.html">to the FAQ</a>.
109 <h2><a name="2">Added members and types</a></h2>
110 <p>Some of the classes in the Standard Library have additional
111 publicly-available members, and some classes are themselves not in
112 the standard. Of those, some are intended purely for the implementors,
113 for example, additional typedefs. Those won't be described here
118 <li>The extensions added by SGI are so numerous that they have
119 <a href="sgiexts.html">their own page</a>. Since the SGI STL is no
120 longer actively maintained, we will try and keep this code working
122 <li>3.0.x <code>filebuf</code>s have another ctor with this signature:<br>
123 <code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);</code>
124 <br>This comes in very handy in a number of places, such as
125 attaching Unix sockets, pipes, and anything else which uses file
126 descriptors, into the IOStream buffering classes. The three
127 arguments are as follows:
129 <li><code>__c_file_type* F </code>
130 // the __c_file_type typedef usually boils down to stdio's FILE
131 <li><code>ios_base::openmode M </code>
132 // same as all the other uses of openmode
133 <li><code>int_type B </code>
134 // buffer size, defaults to BUFSIZ if not specified
136 For those wanting to use file descriptors instead of FILE*'s, I
137 invite you to contemplate the mysteries of C's <code>fdopen()</code>.
139 <li>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring
140 back an old extension: the <code>fd()</code> member function. The
141 integer returned from this function can be used for whatever file
142 descriptors can be used for on your platform. Naturally, the
143 library cannot track what you do on your own with a file descriptor,
144 so if you perform any I/O directly, don't expect the library to be
146 <li>Beginning with 3.1, the extra <code>filebuf</code> constructor and
147 the <code>fd()</code> function were removed from the standard
148 filebuf. Instead, <code><ext/stdio_filebuf.h></code> contains
149 a derived class called <code>__gnu_cxx::stdio_filebuf</code>.
152 <p>Return <a href="#top">to top of page</a> or
153 <a href="../faq/index.html">to the FAQ</a>.
157 <h2><a name="3">Allocators</a></h2>
158 <p>Thread-safety, space efficiency, high speed, portability... this is a
159 mess. Where to begin?
162 <p>The C++ standard only gives a few directives in this area:
164 <li>When you add elements to a container, and the container must allocate
165 more memory to hold them, the container makes the request via its
166 <code>Allocator</code> template parameter. This includes adding
167 char's to the string class, which acts as a regular STL container
169 <li>The default <code>Allocator</code> of every container-of-T is
170 <code>std::allocator<T></code>.
171 <li>The interface of the <code>allocator<T></code> class is
172 extremely simple. It has about 20 public declarations (nested
173 typedefs, member functions, etc), but the two which concern us most
176 T* allocate (size_type n, const void* hint = 0);
177 void deallocate (T* p, size_type n);</pre>
178 (This is a simplicifcation; the real signatures use nested typedefs.)
179 The <code>"n"</code> arguments in both those functions is a
180 <em>count</em> of the number of T's to allocate space for,
181 <em>not their total size</em>.
182 <li>"The storage is obtained by calling
183 <code>::operator new(size_t)</code>, but it is unspecified when or
184 how often this function is called. The use of <code>hint</code>
185 is unspecified, but intended as an aid to locality if an
186 implementation so desires." [20.4.1.1]/6
189 <h3>Problems and Possibilities</h3>
190 <p>The easiest way of fulfilling the requirements is to call operator new
191 each time a container needs memory, and to call operator delete each
192 time the container releases memory. <strong>BUT</strong>
193 <a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00105.html">this
194 method is horribly slow</a>.
196 <p>Or we can keep old memory around, and reuse it in a pool to save time.
197 The old libstdc++-v2 used a memory pool, and so do we. As of 3.0,
198 <a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00136.html">it's
199 on by default</a>. The pool is shared among all the containers in the
200 program: when your program's std::vector<int> gets cut in half
201 and frees a bunch of its storage, that memory can be reused by the
202 private std::list<WonkyWidget> brought in from a KDE library
203 that you linked against. And we don't have to call operators new and
204 delete to pass the memory on, either, which is a speed bonus.
205 <strong>BUT</strong>...
207 <p>What about threads? No problem: in a threadsafe environment, the
208 memory pool is manipulated atomically, so you can grow a container in
209 one thread and shrink it in another, etc. <strong>BUT</strong> what
210 if threads in libstdc++-v3 aren't set up properly?
211 <a href="../faq/index.html#5_6">That's been answered already</a>.
213 <p><strong>BUT</strong> what if you want to use your own allocator? What
214 if you plan on using a runtime-loadable version of malloc() which uses
215 shared telepathic anonymous mmap'd sections serializable over a
216 network, so that memory requests <em>should</em> go through malloc?
217 And what if you need to debug it?
221 <h3>Available allocators in namespace std</h3>
222 <p>First I'll describe the situation as it exists for the code which will
223 be released in GCC 3.1. This situation is extremely fluid. Then I'll
224 describe the differences for 3.0.x, which will not change much in
227 <p>As a general rule of thumb, users are not allowed to use names which
228 begin with an underscore. This means that to be portable between
229 compilers, none of the following may be used in your program directly.
230 (If you decide to be unportable, then you're free do do what you want,
231 but it's not our fault if stuff breaks.) They are presented here for
232 information for maintainers and contributors in addition to users, but
233 we will probably make them available for users in 3.2 somehow.
235 <p>These classes are always available:
237 <li><code>__new_alloc</code> simply wraps <code>::operator new</code>
238 and <code>::operator delete</code>.
239 <li><code>__malloc_alloc_template<int inst></code> simply wraps
240 <code>malloc</code> and <code>free</code>. There is also a hook
241 for an out-of-memory handler (for new/delete this is taken care of
242 elsewhere). The <code>inst</code> parameter is described below.
243 This class was called <code>malloc_alloc</code> in earlier versions.
244 <li><code>allocator<T></code> has already been described; it is
245 The Standard Allocator for instances of T. It uses the internal
246 <code>__alloc</code> typedef (see below) to satisy its requests.
247 <li><code>__simple_alloc<T,A></code> is a wrapper around another
248 allocator, A, which itself is an allocator for instances of T.
249 This is primarily used in an internal "allocator traits"
250 class which helps encapsulate the different styles of allocators.
251 <li><code>__debug_alloc<A></code> is also a wrapper around an
252 arbitrary allocator A. It passes on slightly increased size
253 requests to A, and uses the extra memory to store size information.
254 When a pointer is passed to <code>deallocate()</code>, the stored
255 size is checked, and assert() is used to guarantee they match.
256 <li><code>__allocator<T,A></code> is an adaptor. Many of these
257 allocator classes have a consistent yet non-standard interface.
258 Such classes can be changed to a conforming interface with this
259 wrapper: <code>__allocator<T, __alloc></code> is thus the
260 same as <code>allocator<T></code>.
263 <p>An internal typedef, <code> __mem_interface </code>, is defined to be
264 <code>__new_alloc</code> by default.
267 <code> __default_alloc_template<bool thr, int inst> </code>
268 is also available. This is the high-speed pool, called the default
269 node allocator. The reusable memory is shared among identical
271 this type. It calls through <code>__mem_interface</code> to obtain
272 new memory when its lists run out. If a client container requests a
273 block larger than a certain threshold size, then the pool is bypassed,
274 and the allocate/deallocate request is passed to
275 <code>__mem_interface</code> directly.
277 <p>Its <code>inst</code> parameter is described below. The
278 <code>thr</code> boolean determines whether the pool should be
279 manipulated atomically or not. Two typedefs are provided:
280 <code>__alloc</code> is defined as this node allocator with thr=true,
281 and therefore is threadsafe, while <code>__single_client_alloc</code>
282 defines thr=false, and is slightly faster but unsafe for multiple
285 <p>(Note that the GCC thread abstraction layer allows us to provide safe
286 zero-overhead stubs for the threading routines, if threads were
287 disabled at configuration time. In this situation,
288 <code>__alloc</code> should not be noticably slower than
289 <code>__single_client_alloc</code>.)
291 <p>[Another threadsafe allocator where each thread keeps its own free
292 list, so that no locking is needed, might be described here.]
294 <h3>A cannon to swat a fly:<code> __USE_MALLOC</code></h3>
295 <p>If you've already read <a href="../23_containers/howto.html#3">this
296 advice</a> and decided to define this macro, then the situation changes
299 <li><code>__mem_interface</code>, and
300 <li><code>__alloc</code>, and
301 <li><code>__single_client_alloc</code> are all typedef'd to
302 <code>__malloc_alloc_template</code>.
303 <li><code>__default_alloc_template</code> is no longer available.
304 At all. Anywhere. <!-- might change? -->
307 <h3>Writing your own allocators</h3>
308 <p>Depending on your application (a specific program, a generic library,
309 etc), allocator classes tend to be one of two styles: "SGI"
310 or "standard". See the comments in stl_alloc.h for more
311 information on this crucial difference.
313 <p>At the bottom of that header is a helper type,
314 <code>_Alloc_traits</code>, and various specializations of it. This
315 allows the container classes to make possible compile-time
316 optimizations based on features of the allocator. You should provide
317 a specialization of this type for your allocator (doing so takes only
318 two or three statements).
320 <h3>Using non-default allocators</h3>
321 <p>You can specify different memory management schemes on a per-container
322 basis, by overriding the default <code>Allocator</code> template
323 parameter. For example, an easy
325 method of specifying that only malloc/free should be used instead of
326 the default node allocator is:
328 std::list <my_type, std::__malloc_alloc_template<0> > my_malloc_based_list;</pre>
329 Likewise, a debugging form of whichever allocator is currently in use:
331 std::deque <my_type, std::__debug_alloc<std::__alloc> > debug_deque;</pre>
333 <h3><code>inst</code></h3>
334 <p>The <code>__malloc_alloc_template</code> and
335 <code>__default_alloc_template</code> classes take an integer parameter,
336 called inst here. This number is completely unused.
338 <p>The point of the number is to allow multiple instantiations of the
339 classes without changing the semantics at all. All three of
341 typedef __default_alloc_template<true,0> normal;
342 typedef __default_alloc_template<true,1> private;
343 typedef __default_alloc_template<true,42> also_private;</pre>
344 behave exactly the same way. However, the memory pool for each type
345 (and remember that different instantiations result in different types)
348 <p>The library uses <strong>0</strong> in all its instantiations. If you
349 wish to keep separate free lists for a particular purpose, use a
353 <p>For 3.0.x, many of the names were incorrectly <em>not</em> prefixed
354 with underscores. So symbols such as "std::single_client_alloc"
355 are present. Be very careful to not depend on these names any more
356 than you would depend on implementation-only names.
358 <p>Certain macros like <code>_NOTHREADS</code> and <code>__STL_THREADS</code>
359 can affect the 3.0.x allocators. Do not use them. Those macros have
360 been completely removed for 3.1.
362 <p>More notes as we remember them...
364 <p>Return <a href="#top">to top of page</a> or
365 <a href="../faq/index.html">to the FAQ</a>.
369 <h2><a name="4">Compile-time checks</a></h2>
370 <p>Currently libstdc++-v3 uses the concept checkers from the Boost
371 library to perform <a href="../19_diagnostics/howto.html#3">optional
372 compile-time checking</a> of template instantiations of the standard
373 containers. They are described in the linked-to page.
375 <p>Return <a href="#top">to top of page</a> or
376 <a href="../faq/index.html">to the FAQ</a>.
380 <h2><a name="5">LWG Issues</a></h2>
381 <p>Everybody's got issues. Even the C++ Standard Library.
383 <p>The Library Working Group, or LWG, is the ISO subcommittee responsible
384 for making changes to the library. They periodically publish an
385 Issues List containing problems and possible solutions. As they reach
386 a consensus on proposed solutions, we often incorporate the solution
389 <p>Here are the issues which have resulted in code changes to the library.
390 The links are to the specific defect reports from a <strong>partial
391 copy</strong> of the Issues List. You can read the full version online
392 at the <a href="http://www.dkuug.dk/jtc1/sc22/wg21/">ISO C++
393 Committee homepage</a>, linked to on the
394 <a href="http://gcc.gnu.org/readings.html">GCC "Readings"
396 you spend a lot of time reading the issues, we recommend downloading
397 the ZIP file and reading them locally.
399 <p>(NB: <strong>partial copy</strong> means that not all links within
400 the lwg-*.html pages will work.
401 Specifically, links to defect reports that have not been accorded full
402 DR status will probably break. Rather than trying to mirror the
403 entire issues list on our overworked web server, we recommend you go
404 to the LWG homepage instead.)
407 If a DR is not listed here, we may simply not have gotten to it yet;
408 feel free to submit a patch. Search the include/bits and src
409 directories for appearances of _GLIBCPP_RESOLVE_LIB_DEFECTS for
410 examples of style. Note that we usually do not make changes to the code
411 until an issue has reached <a href="lwg-active.html#DR">DR</a> status.
414 <dt><a href="lwg-defects.html#5">5</a>:
415 <em>string::compare specification questionable</em>
416 <dd>This should be two overloaded functions rather than a single function.
418 <dt><a href="lwg-defects.html#17">17</a>:
419 <em>Bad bool parsing</em>
420 <dd>Apparently extracting Boolean values was messed up...
422 <dt><a href="lwg-defects.html#22">22</a>:
423 <em>Member open vs flags</em>
424 <dd>Re-opening a file stream does <em>not</em> clear the state flags.
426 <dt><a href="lwg-defects.html#25">25</a>:
427 <em>String operator<< uses width() value wrong</em>
430 <dt><a href="lwg-defects.html#48">48</a>:
431 <em>Use of non-existent exception constructor</em>
432 <dd>An instance of <code>ios_base::failure</code> is constructed instead.
434 <dt><a href="lwg-defects.html#49">49</a>:
435 <em>Underspecification of ios_base::sync_with_stdio</em>
436 <dd>The return type is the <em>previous</em> state of synchronization.
438 <dt><a href="lwg-defects.html#50">50</a>:
439 <em>Copy constructor and assignment operator of ios_base</em>
440 <dd>These members functions are declared <code>private</code> and are
441 thus inaccessible. Specifying the correct semantics of
442 "copying stream state" was deemed too complicated.
444 <dt><a href="lwg-defects.html#68">68</a>:
445 <em>Extractors for char* should store null at end</em>
446 <dd>And they do now. An editing glitch in the last item in the list of
449 <dt><a href="lwg-defects.html#74">74</a>:
450 <em>Garbled text for codecvt::do_max_length</em>
451 <dd>The text of the standard was gibberish. Typos gone rampant.
453 <dt><a href="lwg-defects.html#83">83</a>:
454 <em>string::npos vs. string::max_size()</em>
455 <dd>Safety checks on the size of the string should test against
456 <code>max_size()</code> rather than <code>npos</code>.
458 <dt><a href="lwg-defects.html#109">109</a>:
459 <em>Missing binders for non-const sequence elements</em>
460 <dd>The <code>binder1st</code> and <code>binder2nd</code> didn't have an
461 <code>operator()</code> taking a non-const parameter.
463 <dt><a href="lwg-defects.html#110">110</a>:
464 <em>istreambuf_iterator::equal not const</em>
465 <dd>This was not a const member function. Note that the DR says to
466 replace the function with a const one; we have instead provided an
467 overloaded version with identical contents.
469 <dt><a href="lwg-defects.html#117">117</a>:
470 <em>basic_ostream uses nonexistent num_put member functions</em>
471 <dd><code>num_put::put()</code> was overloaded on the wrong types.
473 <dt><a href="lwg-defects.html#118">118</a>:
474 <em>basic_istream uses nonexistent num_get member functions</em>
475 <dd>Same as 117, but for <code>num_get::get()</code>.
477 <dt><a href="lwg-defects.html#129">129</a>:
478 <em>Need error indication from seekp() and seekg()</em>
479 <dd>These functions set <code>failbit</code> on error now.
481 <dt><a href="lwg-defects.html#136">136</a>:
482 <em>seekp, seekg setting wrong streams?</em>
483 <dd><code>seekp</code> should only set the output stream, and
484 <code>seekg</code> should only set the input stream.
486 <!--<dt><a href="lwg-defects.html#159">159</a>:
487 <em>Strange use of underflow()</em>
488 <dd>In fstream.tcc, the basic_filebuf<>::showmanyc() function
489 should probably not be calling <code>underflow()</code>.-->
491 <dt><a href="lwg-active.html#167">167</a>:
492 <em>Improper use of traits_type::length()</em>
493 <dd><code>op<<</code> with a <code>const char*</code> was
494 calculating an incorrect number of characters to write.
496 <dt><a href="lwg-defects.html#181">181</a>:
497 <em>make_pair() unintended behavior</em>
498 <dd>This function used to take its arguments as reference-to-const, now
499 it copies them (pass by value).
501 <dt><a href="lwg-defects.html#195">195</a>:
502 <em>Should basic_istream::sentry's constructor ever set eofbit?</em>
503 <dd>Yes, it can, specifically if EOF is reached while skipping whitespace.
505 <dt><a href="lwg-defects.html#211">211</a>:
506 <em>operator>>(istream&, string&) doesn't set failbit</em>
507 <dd>If nothing is extracted into the string, <code>op>></code> now
508 sets <code>failbit</code> (which can cause an exception, etc, etc).
510 <dt><a href="lwg-defects.html#214">214</a>:
511 <em>set::find() missing const overload</em>
512 <dd>Both <code>set</code> and <code>multiset</code> were missing
513 overloaded find, lower_bound, upper_bound, and equal_range functions
516 <dt><a href="lwg-defects.html#251">251</a>:
517 <em>basic_stringbuf missing allocator_type</em>
518 <dd>This nested typdef was originally not specified.
520 <dt><a href="lwg-defects.html#265">265</a>:
521 <em>std::pair::pair() effects overly restrictive</em>
522 <dd>The default ctor would build its members from copies of temporaries;
523 now it simply uses their respective default ctors.
525 <dt><a href="lwg-defects.html#266">266</a>:
526 <em>bad_exception::~bad_exception() missing Effects clause</em>
527 <dd>The <code>bad_</code>* classes no longer have destructors (they
528 are trivial), since no description of them was ever given.
530 <dt><a href="lwg-defects.html#275">275</a>:
531 <em>Wrong type in num_get::get() overloads</em>
535 <dt><a href="lwg-defects.html#"></a>:
541 <p>Return <a href="#top">to top of page</a> or
542 <a href="../faq/index.html">to the FAQ</a>.
545 <!-- ####################################################### -->
548 <p class="fineprint"><em>
549 See <a href="../17_intro/license.html">license.html</a> for copying conditions.
550 Comments and suggestions are welcome, and may be sent to
551 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.