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