extensions.xml revision 1.12
1<part xmlns="http://docbook.org/ns/docbook" version="5.0" 2 xml:id="manual.ext" xreflabel="Extensions"> 3<?dbhtml filename="extensions.html"?> 4 5<info><title> 6 Extensions 7 <indexterm><primary>Extensions</primary></indexterm> 8</title> 9 <keywordset> 10 <keyword>ISO C++</keyword> 11 <keyword>library</keyword> 12 </keywordset> 13</info> 14 15 16<preface xml:id="manual.ext.preface"><info><title/></info> 17<?dbhtml filename="ext_preface.html"?> 18<para> 19 Here we will make an attempt at describing the non-Standard 20 extensions to the library. Some of these are from older versions of 21 standard library components, namely SGI's STL, and some of these are 22 GNU's. 23</para> 24<para><emphasis>Before</emphasis> you leap in and use any of these 25extensions, be aware of two things: 26</para> 27<orderedlist inheritnum="ignore" continuation="restarts"> 28 <listitem> 29 <para> 30 Non-Standard means exactly that. 31 </para> 32 <para> 33 The behavior, and the very 34 existence, of these extensions may change with little or no 35 warning. (Ideally, the really good ones will appear in the next 36 revision of C++.) Also, other platforms, other compilers, other 37 versions of g++ or libstdc++ may not recognize these names, or 38 treat them differently, or... 39 </para> 40 </listitem> 41 <listitem> 42 <para> 43 You should know how to access these headers properly. 44 </para> 45 </listitem> 46</orderedlist> 47</preface> 48 49<!-- Chapter 01 : Compile Time Checks --> 50<chapter xml:id="manual.ext.compile_checks" xreflabel="Compile Time Checks"><info><title>Compile Time Checks</title></info> 51<?dbhtml filename="ext_compile_checks.html"?> 52 53 <para> 54 Also known as concept checking. 55 </para> 56 <para>In 1999, SGI added <emphasis>concept checkers</emphasis> to their implementation 57 of the STL: code which checked the template parameters of 58 instantiated pieces of the STL, in order to insure that the parameters 59 being used met the requirements of the standard. For example, 60 the Standard requires that types passed as template parameters to 61 <code>vector</code> be <quote>Assignable</quote> (which means what you think 62 it means). The checking was done during compilation, and none of 63 the code was executed at runtime. 64 </para> 65 <para>Unfortunately, the size of the compiler files grew significantly 66 as a result. The checking code itself was cumbersome. And bugs 67 were found in it on more than one occasion. 68 </para> 69 <para>The primary author of the checking code, Jeremy Siek, had already 70 started work on a replacement implementation. The new code has been 71 formally reviewed and accepted into 72 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/concept_check/concept_check.htm">the 73 Boost libraries</link>, and we are pleased to incorporate it into the 74 GNU C++ library. 75 </para> 76 <para>The new version imposes a much smaller space overhead on the generated 77 object file. The checks are also cleaner and easier to read and 78 understand. 79 </para> 80 <para>They are off by default for all versions of GCC from 3.0 to 3.4 (the 81 latest release at the time of writing). 82 They can be enabled at configure time with 83 <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>. 84 You can enable them on a per-translation-unit basis with 85 <link linkend="manual.intro.using.macros"><code>#define 86 _GLIBCXX_CONCEPT_CHECKS</code></link> for GCC 3.4 and higher 87 (or with <code>#define _GLIBCPP_CONCEPT_CHECKS</code> for versions 88 3.1, 3.2 and 3.3). 89 </para> 90 91 <para>Please note that the concept checks only validate the requirements 92 of the old C++03 standard. C++11 was expected to have first-class 93 support for template parameter constraints based on concepts in the core 94 language. This would have obviated the need for the library-simulated concept 95 checking described above, but was not part of C++11. 96 </para> 97 98</chapter> 99 100<!-- Chapter 02 : Debug Mode --> 101<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" 102 href="debug_mode.xml"> 103</xi:include> 104 105<!-- Chapter 03 : Parallel Mode --> 106<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" 107 href="parallel_mode.xml"> 108</xi:include> 109 110<!-- Chapter 04 : Profile Mode --> 111<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" 112 href="profile_mode.xml"> 113</xi:include> 114 115 116<!-- XXX --> 117<!-- Allocators --> 118<!-- Chapter 05 : __mt_alloc --> 119<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" 120 href="mt_allocator.xml"> 121</xi:include> 122 123<!-- Chapter 06 : bitmap_allocator --> 124<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" 125 href="bitmap_allocator.xml"> 126</xi:include> 127 128<!-- Containers --> 129<!-- Chapter 07 : Policy-Based Data Structures --> 130<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" 131 href="policy_data_structures.xml"> 132</xi:include> 133 134<!-- Chapter 08 : HP/SGI --> 135<chapter xml:id="manual.ext.containers" xreflabel="Containers"> 136 <info><title>HP/SGI Extensions</title></info> 137<?dbhtml filename="ext_containers.html"?> 138 139 <section xml:id="manual.ext.containers.sgi" xreflabel="SGI ext"> 140 <info><title>Backwards Compatibility</title></info> 141 142 <para>A few extensions and nods to backwards-compatibility have 143 been made with containers. Those dealing with older SGI-style 144 allocators are dealt with elsewhere. The remaining ones all deal 145 with bits: 146 </para> 147 <para>The old pre-standard <code>bit_vector</code> class is 148 present for backwards compatibility. It is simply a typedef for 149 the <code>vector<bool></code> specialization. 150 </para> 151 152<para>The <code>bitset</code> class has a number of extensions, described in the 153 rest of this item. First, we'll mention that this implementation of 154 <code>bitset<N></code> is specialized for cases where N number of 155 bits will fit into a single word of storage. If your choice of N is 156 within that range (<=32 on i686-pc-linux-gnu, for example), then all 157 of the operations will be faster. 158</para> 159<para>There are 160 versions of single-bit test, set, reset, and flip member functions which 161 do no range-checking. If we call them member functions of an instantiation 162 of <code>bitset<N></code>, then their names and signatures are: 163</para> 164 <programlisting> 165 bitset<N>& _Unchecked_set (size_t pos); 166 bitset<N>& _Unchecked_set (size_t pos, int val); 167 bitset<N>& _Unchecked_reset (size_t pos); 168 bitset<N>& _Unchecked_flip (size_t pos); 169 bool _Unchecked_test (size_t pos); 170 </programlisting> 171 <para>Note that these may in fact be removed in the future, although we have 172 no present plans to do so (and there doesn't seem to be any immediate 173 reason to). 174</para> 175<para>The member function <code>operator[]</code> on a const bitset returns 176 a bool, and for a non-const bitset returns a <code>reference</code> (a 177 nested type). No range-checking is done on the index argument, in keeping 178 with other containers' <code>operator[]</code> requirements. 179</para> 180<para>Finally, two additional searching functions have been added. They return 181 the index of the first "on" bit, and the index of the first 182 "on" bit that is after <code>prev</code>, respectively: 183</para> 184 <programlisting> 185 size_t _Find_first() const; 186 size_t _Find_next (size_t prev) const;</programlisting> 187<para>The same caveat given for the _Unchecked_* functions applies here also. 188</para> 189 </section> 190 191 192 <section xml:id="manual.ext.containers.deprecated_sgi" xreflabel="SGI ext dep"><info><title>Deprecated</title></info> 193 <?dbhtml filename="ext_sgi.html"?> 194 195 196 <para> 197 The SGI hashing classes <classname>hash_set</classname> and 198 <classname>hash_set</classname> have been deprecated by the 199 unordered_set, unordered_multiset, unordered_map, 200 unordered_multimap containers in TR1 and C++11, and 201 may be removed in future releases. 202 </para> 203 204 <para>The SGI headers</para> 205 <programlisting> 206 <hash_map> 207 <hash_set> 208 <rope> 209 <slist> 210 <rb_tree> 211 </programlisting> 212 <para>are all here; 213 <filename class="headerfile"><backwards/hash_map></filename> and 214 <filename class="headerfile"><backwards/hash_set></filename> 215 are deprecated but available as backwards-compatible extensions, 216 as discussed further below. 217 <filename class="headerfile"><ext/rope></filename> is the SGI 218 specialization for large strings ("rope," "large strings," get it? Love 219 that geeky humor.) 220 <filename class="headerfile"><ext/slist></filename> (superseded in 221 C++11 by <filename class="headerfile"><forward_list></filename>) 222 is a singly-linked list, for when the doubly-linked <code>list<></code> 223 is too much space overhead, and 224 <filename class="headerfile"><ext/rb_tree></filename> exposes the 225 red-black tree classes used in the implementation of the standard maps 226 and sets. 227 </para> 228 <para>Each of the associative containers map, multimap, set, and multiset 229 have a counterpart which uses a 230 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/HashFunction.html">hashing 231 function</link> to do the arranging, instead of a strict weak ordering 232 function. The classes take as one of their template parameters a 233 function object that will return the hash value; by default, an 234 instantiation of 235 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/hash.html">hash</link>. 236 You should specialize this functor for your class, or define your own, 237 before trying to use one of the hashing classes. 238 </para> 239 <para>The hashing classes support all the usual associative container 240 functions, as well as some extra constructors specifying the number 241 of buckets, etc. 242 </para> 243 <para>Why would you want to use a hashing class instead of the 244 <quote>normal</quote>implementations? Matt Austern writes: 245 </para> 246 <blockquote> 247 <para> 248 <emphasis>[W]ith a well chosen hash function, hash tables 249 generally provide much better average-case performance than 250 binary search trees, and much worse worst-case performance. So 251 if your implementation has hash_map, if you don't mind using 252 nonstandard components, and if you aren't scared about the 253 possibility of pathological cases, you'll probably get better 254 performance from hash_map. 255 </emphasis> 256 </para> 257 </blockquote> 258 259 <para> 260 The deprecated hash tables are superseded by the standard unordered 261 associative containers defined in the ISO C++ 2011 standard in the 262 headers <filename class="headerfile"><unordered_map></filename> 263 and <filename class="headerfile"><unordered_set></filename>. 264 </para> 265 266 </section> 267</chapter> 268 269<!-- Chapter 09 : Utilities --> 270<chapter xml:id="manual.ext.util" xreflabel="Utilities"><info><title>Utilities</title></info> 271<?dbhtml filename="ext_utilities.html"?> 272 273 <para> 274 The <filename class="headerfile"><functional></filename> header 275 contains many additional functors 276 and helper functions, extending section 20.3. They are 277 implemented in the file stl_function.h: 278 </para> 279 <itemizedlist> 280 <listitem> 281 <para><code>identity_element</code> for addition and multiplication. 282 </para> 283 </listitem> 284 <listitem> 285 <para>The functor <code>identity</code>, whose <code>operator()</code> 286 returns the argument unchanged. 287 </para> 288 </listitem> 289 <listitem> 290 <para>Composition functors <code>unary_function</code> and 291 <code>binary_function</code>, and their helpers <code>compose1</code> 292 and <code>compose2</code>. 293 </para> 294 </listitem> 295 <listitem> 296 <para><code>select1st</code> and <code>select2nd</code>, to strip pairs. 297 </para> 298 </listitem> 299 <listitem><para><code>project1st</code> and <code>project2nd</code>. </para></listitem> 300 <listitem><para>A set of functors/functions which always return the same result. They 301 are <code>constant_void_fun</code>, <code>constant_binary_fun</code>, 302 <code>constant_unary_fun</code>, <code>constant0</code>, 303 <code>constant1</code>, and <code>constant2</code>. </para></listitem> 304 <listitem><para>The class <code>subtractive_rng</code>. </para></listitem> 305 <listitem><para>mem_fun adaptor helpers <code>mem_fun1</code> and 306 <code>mem_fun1_ref</code> are provided for backwards compatibility. </para></listitem> 307</itemizedlist> 308<para> 309 20.4.1 can use several different allocators; they are described on the 310 main extensions page. 311</para> 312<para> 313 20.4.3 is extended with a special version of 314 <code>get_temporary_buffer</code> taking a second argument. The 315 argument is a pointer, which is ignored, but can be used to specify 316 the template type (instead of using explicit function template 317 arguments like the standard version does). That is, in addition to 318</para> 319<programlisting> 320get_temporary_buffer<int>(5); 321</programlisting> 322 323<para> 324you can also use 325</para> 326 327<programlisting> 328get_temporary_buffer(5, (int*)0); 329</programlisting> 330<para> 331 A class <code>temporary_buffer</code> is given in stl_tempbuf.h. 332</para> 333<para> 334 The specialized algorithms of section 20.4.4 are extended with 335 <code>uninitialized_copy_n</code>. 336</para> 337 338</chapter> 339 340<!-- Chapter 10 : Algorithms --> 341<chapter xml:id="manual.ext.algorithms" xreflabel="Algorithms"><info><title>Algorithms</title></info> 342<?dbhtml filename="ext_algorithms.html"?> 343 344<para>25.1.6 (count, count_if) is extended with two more versions of count 345 and count_if. The standard versions return their results. The 346 additional signatures return void, but take a final parameter by 347 reference to which they assign their results, e.g., 348</para> 349 <programlisting> 350 void count (first, last, value, n);</programlisting> 351<para>25.2 (mutating algorithms) is extended with two families of signatures, 352 random_sample and random_sample_n. 353</para> 354<para>25.2.1 (copy) is extended with 355</para> 356 <programlisting> 357 copy_n (_InputIter first, _Size count, _OutputIter result);</programlisting> 358<para>which copies the first 'count' elements at 'first' into 'result'. 359</para> 360<para>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper 361 predicates. Look in the doxygen-generated pages for notes on these. 362</para> 363 <itemizedlist> 364 <listitem><para><code>is_heap</code> tests whether or not a range is a heap.</para></listitem> 365 <listitem><para><code>is_sorted</code> tests whether or not a range is sorted in 366 nondescending order.</para></listitem> 367 </itemizedlist> 368<para>25.3.8 (lexicographical_compare) is extended with 369</para> 370 <programlisting> 371 lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1, 372 _InputIter2 first2, _InputIter2 last2)</programlisting> 373<para>which does... what? 374</para> 375 376</chapter> 377 378<!-- Chapter 11 : Numerics --> 379<chapter xml:id="manual.ext.numerics" xreflabel="Numerics"><info><title>Numerics</title></info> 380<?dbhtml filename="ext_numerics.html"?> 381 382<para>26.4, the generalized numeric operations such as <code>accumulate</code>, 383 are extended with the following functions: 384</para> 385 <programlisting> 386 power (x, n); 387 power (x, n, monoid_operation);</programlisting> 388<para>Returns, in FORTRAN syntax, "<code>x ** n</code>" where 389 <code>n >= 0</code>. In the 390 case of <code>n == 0</code>, returns the identity element for the 391 monoid operation. The two-argument signature uses multiplication (for 392 a true "power" implementation), but addition is supported as well. 393 The operation functor must be associative. 394</para> 395<para>The <code>iota</code> function wins the award for Extension With the 396 Coolest Name (the name comes from Ken Iverson's APL language.) As 397 described in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/iota.html">SGI 398 documentation</link>, it "assigns sequentially increasing values to a range. 399 That is, it assigns <code>value</code> to <code>*first</code>, 400 <code>value + 1</code> to<code> *(first + 1)</code> and so on." 401</para> 402 <programlisting> 403 void iota(_ForwardIter first, _ForwardIter last, _Tp value);</programlisting> 404<para>The <code>iota</code> function is included in the ISO C++ 2011 standard. 405</para> 406</chapter> 407 408<!-- Chapter 12 : Iterators --> 409<chapter xml:id="manual.ext.iterators" xreflabel="Iterators"><info><title>Iterators</title></info> 410<?dbhtml filename="ext_iterators.html"?> 411 412<para>24.3.2 describes <code>struct iterator</code>, which didn't exist in the 413 original HP STL implementation (the language wasn't rich enough at the 414 time). For backwards compatibility, base classes are provided which 415 declare the same nested typedefs: 416</para> 417 <itemizedlist> 418 <listitem><para>input_iterator</para></listitem> 419 <listitem><para>output_iterator</para></listitem> 420 <listitem><para>forward_iterator</para></listitem> 421 <listitem><para>bidirectional_iterator</para></listitem> 422 <listitem><para>random_access_iterator</para></listitem> 423 </itemizedlist> 424<para>24.3.4 describes iterator operation <code>distance</code>, which takes 425 two iterators and returns a result. It is extended by another signature 426 which takes two iterators and a reference to a result. The result is 427 modified, and the function returns nothing. 428</para> 429 430</chapter> 431 432<!-- Chapter 13 : IO --> 433<chapter xml:id="manual.ext.io" xreflabel="IO"><info><title>Input and Output</title></info> 434<?dbhtml filename="ext_io.html"?> 435 436 437 <para> 438 Extensions allowing <code>filebuf</code>s to be constructed from 439 "C" types like FILE*s and file descriptors. 440 </para> 441 442 <section xml:id="manual.ext.io.filebuf_derived" xreflabel="Derived filebufs"><info><title>Derived filebufs</title></info> 443 444 445 <para>The v2 library included non-standard extensions to construct 446 <code>std::filebuf</code>s from C stdio types such as 447 <code>FILE*</code>s and POSIX file descriptors. 448 Today the recommended way to use stdio types with libstdc++ 449 IOStreams is via the <code>stdio_filebuf</code> class (see below), 450 but earlier releases provided slightly different mechanisms. 451 </para> 452 <itemizedlist> 453 <listitem><para>3.0.x <code>filebuf</code>s have another ctor with this signature: 454 <code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type); 455 </code> 456 This comes in very handy in a number of places, such as 457 attaching Unix sockets, pipes, and anything else which uses file 458 descriptors, into the IOStream buffering classes. The three 459 arguments are as follows: 460 <itemizedlist> 461 <listitem><para><code>__c_file_type* F </code> 462 // the __c_file_type typedef usually boils down to stdio's FILE 463 </para></listitem> 464 <listitem><para><code>ios_base::openmode M </code> 465 // same as all the other uses of openmode 466 </para></listitem> 467 <listitem><para><code>int_type B </code> 468 // buffer size, defaults to BUFSIZ if not specified 469 </para></listitem> 470 </itemizedlist> 471 For those wanting to use file descriptors instead of FILE*'s, I 472 invite you to contemplate the mysteries of C's <code>fdopen()</code>. 473 </para></listitem> 474 <listitem><para>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring 475 back an old extension: the <code>fd()</code> member function. The 476 integer returned from this function can be used for whatever file 477 descriptors can be used for on your platform. Naturally, the 478 library cannot track what you do on your own with a file descriptor, 479 so if you perform any I/O directly, don't expect the library to be 480 aware of it. 481 </para></listitem> 482 <listitem><para>Beginning with 3.1, the extra 483 <classname>basic_filebuf</classname> constructor and 484 the <code>fd()</code> function were removed from the standard 485 filebuf. Instead, 486 <filename class="headerfile"><ext/stdio_filebuf.h></filename> 487 contains a derived class template called 488 <classname>__gnu_cxx::stdio_filebuf</classname>. 489 This class can be constructed from a C <code>FILE*</code> or a file 490 descriptor, and provides the <code>fd()</code> function. 491 </para></listitem> 492 </itemizedlist> 493 494 </section> 495</chapter> 496 497<!-- Chapter 14 : Demangling --> 498<chapter xml:id="manual.ext.demangle" xreflabel="Demangling"><info><title>Demangling</title></info> 499<?dbhtml filename="ext_demangling.html"?> 500 501 <para> 502 Transforming C++ ABI identifiers (like RTTI symbols) into the 503 original C++ source identifiers is called 504 <quote>demangling.</quote> 505 </para> 506 <para> 507 If you have read the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">source 508 documentation for <code>namespace abi</code></link> then you are 509 aware of the cross-vendor C++ ABI in use by GCC. One of the 510 exposed functions is used for demangling, 511 <code>abi::__cxa_demangle</code>. 512 </para> 513 <para> 514 In programs like <command>c++filt</command>, the linker, and other tools 515 have the ability to decode C++ ABI names, and now so can you. 516 </para> 517 <para> 518 (The function itself might use different demanglers, but that's the 519 whole point of abstract interfaces. If we change the implementation, 520 you won't notice.) 521 </para> 522 <para> 523 Probably the only times you'll be interested in demangling at runtime 524 are when you're seeing <code>typeid</code> strings in RTTI, or when 525 you're handling the runtime-support exception classes. For example: 526 </para> 527 <programlisting> 528#include <exception> 529#include <iostream> 530#include <cxxabi.h> 531 532struct empty { }; 533 534template <typename T, int N> 535 struct bar { }; 536 537 538int main() 539{ 540 int status; 541 char *realname; 542 543 // exception classes not in <stdexcept>, thrown by the implementation 544 // instead of the user 545 std::bad_exception e; 546 realname = abi::__cxa_demangle(e.what(), 0, 0, &status); 547 std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n'; 548 free(realname); 549 550 551 // typeid 552 bar<empty,17> u; 553 const std::type_info &ti = typeid(u); 554 555 realname = abi::__cxa_demangle(ti.name(), 0, 0, &status); 556 std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n'; 557 free(realname); 558 559 return 0; 560} 561 </programlisting> 562 <para> 563 This prints 564 </para> 565 566 <screen> 567 <computeroutput> 568 St13bad_exception => std::bad_exception : 0 569 3barI5emptyLi17EE => bar<empty, 17> : 0 570 </computeroutput> 571 </screen> 572 573 <para> 574 The demangler interface is described in the source documentation 575 linked to above. It is actually written in C, so you don't need to 576 be writing C++ in order to demangle C++. (That also means we have to 577 use crummy memory management facilities, so don't forget to free() 578 the returned char array.) 579 </para> 580</chapter> 581 582<!-- Chapter 15 : Concurrency --> 583<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="concurrency_extensions.xml"> 584</xi:include> 585 586</part> 587