| | 1 | <?xml version='1.0'?> |
| | 2 | <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" |
| | 4 | [ ]> |
| | 5 | |
| | 6 | <appendix id="appendix.contrib" xreflabel="Contributing"> |
| | 7 | <?dbhtml filename="appendix_contributing.html"?> |
| | 8 | |
| | 9 | <appendixinfo> |
| | 10 | <keywordset> |
| | 11 | <keyword> |
| | 12 | ISO C++ |
| | 13 | </keyword> |
| | 14 | <keyword> |
| | 15 | library |
| | 16 | </keyword> |
| | 17 | </keywordset> |
| | 18 | </appendixinfo> |
| | 19 | |
| | 20 | <title> |
| | 21 | Contributing |
| | 22 | <indexterm> |
| | 23 | <primary>Appendix</primary> |
| | 24 | <secondary>Contributing</secondary> |
| | 25 | </indexterm> |
| | 26 | </title> |
| | 27 | |
| | 28 | <para> |
| | 29 | The GNU C++ Library follows an open development model. Active |
| | 30 | contributors are assigned maintainer-ship responsibility, and given |
| | 31 | write access to the source repository. First time contributors |
| | 32 | should follow this procedure: |
| | 33 | </para> |
| | 34 | |
| | 35 | <sect1 id="contrib.list" xreflabel="Contributor Checklist"> |
| | 36 | <title>Contributor Checklist</title> |
| | 37 | |
| | 38 | <sect2 id="list.reading"> |
| | 39 | <title>Reading</title> |
| | 40 | |
| | 41 | <itemizedlist> |
| | 42 | <listitem> |
| | 43 | <para> |
| | 44 | Get and read the relevant sections of the C++ language |
| | 45 | specification. Copies of the full ISO 14882 standard are |
| | 46 | available on line via the ISO mirror site for committee |
| | 47 | members. Non-members, or those who have not paid for the |
| | 48 | privilege of sitting on the committee and sustained their |
| | 49 | two meeting commitment for voting rights, may get a copy of |
| | 50 | the standard from their respective national standards |
| | 51 | organization. In the USA, this national standards |
| | 52 | organization is ANSI and their web-site is right |
| | 53 | <ulink url="http://www.ansi.org">here.</ulink> |
| | 54 | (And if you've already registered with them, clicking this link will take you to directly to the place where you can |
| | 55 | <ulink url="http://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC+14882:2003">buy the standard on-line</ulink>.) |
| | 56 | </para> |
| | 57 | </listitem> |
| | 58 | |
| | 59 | <listitem> |
| | 60 | <para> |
| | 61 | The library working group bugs, and known defects, can |
| | 62 | be obtained here: |
| | 63 | <ulink url="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21 </ulink> |
| | 64 | </para> |
| | 65 | </listitem> |
| | 66 | |
| | 67 | <listitem> |
| | 68 | <para> |
| | 69 | The newsgroup dedicated to standardization issues is |
| | 70 | comp.std.c++: this FAQ for this group is quite useful and |
| | 71 | can be |
| | 72 | found <ulink url="http://www.comeaucomputing.com/csc/faq.html"> |
| | 73 | here </ulink>. |
| | 74 | </para> |
| | 75 | </listitem> |
| | 76 | |
| | 77 | <listitem> |
| | 78 | <para> |
| | 79 | Peruse |
| | 80 | the <ulink url="http://www.gnu.org/prep/standards">GNU |
| | 81 | Coding Standards</ulink>, and chuckle when you hit the part |
| | 82 | about <quote>Using Languages Other Than C</quote>. |
| | 83 | </para> |
| | 84 | </listitem> |
| | 85 | |
| | 86 | <listitem> |
| | 87 | <para> |
| | 88 | Be familiar with the extensions that preceded these |
| | 89 | general GNU rules. These style issues for libstdc++ can be |
| | 90 | found <link linkend="contrib.coding_style">here</link>. |
| | 91 | </para> |
| | 92 | </listitem> |
| | 93 | |
| | 94 | <listitem> |
| | 95 | <para> |
| | 96 | And last but certainly not least, read the |
| | 97 | library-specific information |
| | 98 | found <link linkend="appendix.porting"> here</link>. |
| | 99 | </para> |
| | 100 | </listitem> |
| | 101 | </itemizedlist> |
| | 102 | |
| | 103 | </sect2> |
| | 104 | <sect2 id="list.copyright"> |
| | 105 | <title>Assignment</title> |
| | 106 | <para> |
| | 107 | Small changes can be accepted without a copyright assignment form on |
| | 108 | file. New code and additions to the library need completed copyright |
| | 109 | assignment form on file at the FSF. Note: your employer may be required |
| | 110 | to fill out appropriate disclaimer forms as well. |
| | 111 | </para> |
| | 112 | |
| | 113 | <para> |
| | 114 | Historically, the libstdc++ assignment form added the following |
| | 115 | question: |
| | 116 | </para> |
| | 117 | |
| | 118 | <para> |
| | 119 | <quote> |
| | 120 | Which Belgian comic book character is better, Tintin or Asterix, and |
| | 121 | why? |
| | 122 | </quote> |
| | 123 | </para> |
| | 124 | |
| | 125 | <para> |
| | 126 | While not strictly necessary, humoring the maintainers and answering |
| | 127 | this question would be appreciated. |
| | 128 | </para> |
| | 129 | |
| | 130 | <para> |
| | 131 | For more information about getting a copyright assignment, please see |
| | 132 | <ulink url="http://www.gnu.org/prep/maintain/html_node/Legal-Matters.html">Legal |
| | 133 | Matters</ulink>. |
| | 134 | </para> |
| | 135 | |
| | 136 | <para> |
| | 137 | Please contact Benjamin Kosnik at |
| | 138 | <email>bkoz+assign@redhat.com</email> if you are confused |
| | 139 | about the assignment or have general licensing questions. When |
| | 140 | requesting an assignment form from |
| | 141 | <email>mailto:assign@gnu.org</email>, please cc the libstdc++ |
| | 142 | maintainer above so that progress can be monitored. |
| | 143 | </para> |
| | 144 | </sect2> |
| | 145 | |
| | 146 | <sect2 id="list.getting"> |
| | 147 | <title>Getting Sources</title> |
| | 148 | <para> |
| | 149 | <ulink url="http://gcc.gnu.org/svnwrite.html">Getting write access |
| | 150 | (look for "Write after approval")</ulink> |
| | 151 | </para> |
| | 152 | </sect2> |
| | 153 | |
| | 154 | <sect2 id="list.patches"> |
| | 155 | <title>Submitting Patches</title> |
| | 156 | |
| | 157 | <para> |
| | 158 | Every patch must have several pieces of information before it can be |
| | 159 | properly evaluated. Ideally (and to ensure the fastest possible |
| | 160 | response from the maintainers) it would have all of these pieces: |
| | 161 | </para> |
| | 162 | |
| | 163 | <itemizedlist> |
| | 164 | <listitem> |
| | 165 | <para> |
| | 166 | A description of the bug and how your patch fixes this |
| | 167 | bug. For new features a description of the feature and your |
| | 168 | implementation. |
| | 169 | </para> |
| | 170 | </listitem> |
| | 171 | |
| | 172 | <listitem> |
| | 173 | <para> |
| | 174 | A ChangeLog entry as plain text; see the various |
| | 175 | ChangeLog files for format and content. If you are |
| | 176 | using emacs as your editor, simply position the insertion |
| | 177 | point at the beginning of your change and hit CX-4a to bring |
| | 178 | up the appropriate ChangeLog entry. See--magic! Similar |
| | 179 | functionality also exists for vi. |
| | 180 | </para> |
| | 181 | </listitem> |
| | 182 | |
| | 183 | <listitem> |
| | 184 | <para> |
| | 185 | A testsuite submission or sample program that will |
| | 186 | easily and simply show the existing error or test new |
| | 187 | functionality. |
| | 188 | </para> |
| | 189 | </listitem> |
| | 190 | |
| | 191 | <listitem> |
| | 192 | <para> |
| | 193 | The patch itself. If you are accessing the SVN |
| | 194 | repository use <command>svn update; svn diff NEW</command>; |
| | 195 | else, use <command>diff -cp OLD NEW</command> ... If your |
| | 196 | version of diff does not support these options, then get the |
| | 197 | latest version of GNU |
| | 198 | diff. The <ulink url="http://gcc.gnu.org/wiki/SvnTricks">SVN |
| | 199 | Tricks</ulink> wiki page has information on customising the |
| | 200 | output of <code>svn diff</code>. |
| | 201 | </para> |
| | 202 | </listitem> |
| | 203 | |
| | 204 | <listitem> |
| | 205 | <para> |
| | 206 | When you have all these pieces, bundle them up in a |
| | 207 | mail message and send it to libstdc++@gcc.gnu.org. All |
| | 208 | patches and related discussion should be sent to the |
| | 209 | libstdc++ mailing list. |
| | 210 | </para> |
| | 211 | </listitem> |
| | 212 | </itemizedlist> |
| | 213 | |
| | 214 | </sect2> |
| | 215 | |
| | 216 | </sect1> |
| | 217 | |
| | 218 | <sect1 id="contrib.organization" xreflabel="Source Organization"> |
| | 219 | <?dbhtml filename="source_organization.html"?> |
| | 220 | <title>Directory Layout and Source Conventions</title> |
| | 221 | |
| | 222 | <para> |
| | 223 | The unpacked source directory of libstdc++ contains the files |
| | 224 | needed to create the GNU C++ Library. |
| | 225 | </para> |
| | 226 | |
| | 227 | <literallayout> |
| | 228 | It has subdirectories: |
| | 229 | |
| | 230 | doc |
| | 231 | Files in HTML and text format that document usage, quirks of the |
| | 232 | implementation, and contributor checklists. |
| | 233 | |
| | 234 | include |
| | 235 | All header files for the C++ library are within this directory, |
| | 236 | modulo specific runtime-related files that are in the libsupc++ |
| | 237 | directory. |
| | 238 | |
| | 239 | include/std |
| | 240 | Files meant to be found by #include <name> directives in |
| | 241 | standard-conforming user programs. |
| | 242 | |
| | 243 | include/c |
| | 244 | Headers intended to directly include standard C headers. |
| | 245 | [NB: this can be enabled via --enable-cheaders=c] |
| | 246 | |
| | 247 | include/c_global |
| | 248 | Headers intended to include standard C headers in |
| | 249 | the global namespace, and put select names into the std:: |
| | 250 | namespace. [NB: this is the default, and is the same as |
| | 251 | --enable-cheaders=c_global] |
| | 252 | |
| | 253 | include/c_std |
| | 254 | Headers intended to include standard C headers |
| | 255 | already in namespace std, and put select names into the std:: |
| | 256 | namespace. [NB: this is the same as --enable-cheaders=c_std] |
| | 257 | |
| | 258 | include/bits |
| | 259 | Files included by standard headers and by other files in |
| | 260 | the bits directory. |
| | 261 | |
| | 262 | include/backward |
| | 263 | Headers provided for backward compatibility, such as <iostream.h>. |
| | 264 | They are not used in this library. |
| | 265 | |
| | 266 | include/ext |
| | 267 | Headers that define extensions to the standard library. No |
| | 268 | standard header refers to any of them. |
| | 269 | |
| | 270 | scripts |
| | 271 | Scripts that are used during the configure, build, make, or test |
| | 272 | process. |
| | 273 | |
| | 274 | src |
| | 275 | Files that are used in constructing the library, but are not |
| | 276 | installed. |
| | 277 | |
| | 278 | testsuites/[backward, demangle, ext, performance, thread, 17_* to 27_*] |
| | 279 | Test programs are here, and may be used to begin to exercise the |
| | 280 | library. Support for "make check" and "make check-install" is |
| | 281 | complete, and runs through all the subdirectories here when this |
| | 282 | command is issued from the build directory. Please note that |
| | 283 | "make check" requires DejaGNU 1.4 or later to be installed. Please |
| | 284 | note that "make check-script" calls the script mkcheck, which |
| | 285 | requires bash, and which may need the paths to bash adjusted to |
| | 286 | work properly, as /bin/bash is assumed. |
| | 287 | |
| | 288 | Other subdirectories contain variant versions of certain files |
| | 289 | that are meant to be copied or linked by the configure script. |
| | 290 | Currently these are: |
| | 291 | |
| | 292 | config/abi |
| | 293 | config/cpu |
| | 294 | config/io |
| | 295 | config/locale |
| | 296 | config/os |
| | 297 | |
| | 298 | In addition, a subdirectory holds the convenience library libsupc++. |
| | 299 | |
| | 300 | libsupc++ |
| | 301 | Contains the runtime library for C++, including exception |
| | 302 | handling and memory allocation and deallocation, RTTI, terminate |
| | 303 | handlers, etc. |
| | 304 | |
| | 305 | Note that glibc also has a bits/ subdirectory. We will either |
| | 306 | need to be careful not to collide with names in its bits/ |
| | 307 | directory; or rename bits to (e.g.) cppbits/. |
| | 308 | |
| | 309 | In files throughout the system, lines marked with an "XXX" indicate |
| | 310 | a bug or incompletely-implemented feature. Lines marked "XXX MT" |
| | 311 | indicate a place that may require attention for multi-thread safety. |
| | 312 | </literallayout> |
| | 313 | |
| | 314 | </sect1> |
| | 315 | |
| | 316 | <sect1 id="contrib.coding_style" xreflabel="Coding Style"> |
| | 317 | <?dbhtml filename="source_code_style.html"?> |
| | 318 | <title>Coding Style</title> |
| | 319 | <para> |
| | 320 | </para> |
| | 321 | <sect2 id="coding_style.bad_identifiers"> |
| | 322 | <title>Bad Identifiers</title> |
| | 323 | <para> |
| | 324 | Identifiers that conflict and should be avoided. |
| | 325 | </para> |
| | 326 | |
| | 327 | <literallayout> |
| | 328 | This is the list of names <quote>reserved to the |
| | 329 | implementation</quote> that have been claimed by certain |
| | 330 | compilers and system headers of interest, and should not be used |
| | 331 | in the library. It will grow, of course. We generally are |
| | 332 | interested in names that are not all-caps, except for those like |
| | 333 | "_T" |
| | 334 | |
| | 335 | For Solaris: |
| | 336 | _B |
| | 337 | _C |
| | 338 | _L |
| | 339 | _N |
| | 340 | _P |
| | 341 | _S |
| | 342 | _U |
| | 343 | _X |
| | 344 | _E1 |
| | 345 | .. |
| | 346 | _E24 |
| | 347 | |
| | 348 | Irix adds: |
| | 349 | _A |
| | 350 | _G |
| | 351 | |
| | 352 | MS adds: |
| | 353 | _T |
| | 354 | |
| | 355 | BSD adds: |
| | 356 | __used |
| | 357 | __unused |
| | 358 | __inline |
| | 359 | _Complex |
| | 360 | __istype |
| | 361 | __maskrune |
| | 362 | __tolower |
| | 363 | __toupper |
| | 364 | __wchar_t |
| | 365 | __wint_t |
| | 366 | _res |
| | 367 | _res_ext |
| | 368 | __tg_* |
| | 369 | |
| | 370 | SPU adds: |
| | 371 | __ea |
| | 372 | |
| | 373 | For GCC: |
| | 374 | |
| | 375 | [Note that this list is out of date. It applies to the old |
| | 376 | name-mangling; in G++ 3.0 and higher a different name-mangling is |
| | 377 | used. In addition, many of the bugs relating to G++ interpreting |
| | 378 | these names as operators have been fixed.] |
| | 379 | |
| | 380 | The full set of __* identifiers (combined from gcc/cp/lex.c and |
| | 381 | gcc/cplus-dem.c) that are either old or new, but are definitely |
| | 382 | recognized by the demangler, is: |
| | 383 | |
| | 384 | __aa |
| | 385 | __aad |
| | 386 | __ad |
| | 387 | __addr |
| | 388 | __adv |
| | 389 | __aer |
| | 390 | __als |
| | 391 | __alshift |
| | 392 | __amd |
| | 393 | __ami |
| | 394 | __aml |
| | 395 | __amu |
| | 396 | __aor |
| | 397 | __apl |
| | 398 | __array |
| | 399 | __ars |
| | 400 | __arshift |
| | 401 | __as |
| | 402 | __bit_and |
| | 403 | __bit_ior |
| | 404 | __bit_not |
| | 405 | __bit_xor |
| | 406 | __call |
| | 407 | __cl |
| | 408 | __cm |
| | 409 | __cn |
| | 410 | __co |
| | 411 | __component |
| | 412 | __compound |
| | 413 | __cond |
| | 414 | __convert |
| | 415 | __delete |
| | 416 | __dl |
| | 417 | __dv |
| | 418 | __eq |
| | 419 | __er |
| | 420 | __ge |
| | 421 | __gt |
| | 422 | __indirect |
| | 423 | __le |
| | 424 | __ls |
| | 425 | __lt |
| | 426 | __max |
| | 427 | __md |
| | 428 | __method_call |
| | 429 | __mi |
| | 430 | __min |
| | 431 | __minus |
| | 432 | __ml |
| | 433 | __mm |
| | 434 | __mn |
| | 435 | __mult |
| | 436 | __mx |
| | 437 | __ne |
| | 438 | __negate |
| | 439 | __new |
| | 440 | __nop |
| | 441 | __nt |
| | 442 | __nw |
| | 443 | __oo |
| | 444 | __op |
| | 445 | __or |
| | 446 | __pl |
| | 447 | __plus |
| | 448 | __postdecrement |
| | 449 | __postincrement |
| | 450 | __pp |
| | 451 | __pt |
| | 452 | __rf |
| | 453 | __rm |
| | 454 | __rs |
| | 455 | __sz |
| | 456 | __trunc_div |
| | 457 | __trunc_mod |
| | 458 | __truth_andif |
| | 459 | __truth_not |
| | 460 | __truth_orif |
| | 461 | __vc |
| | 462 | __vd |
| | 463 | __vn |
| | 464 | |
| | 465 | SGI badnames: |
| | 466 | __builtin_alloca |
| | 467 | __builtin_fsqrt |
| | 468 | __builtin_sqrt |
| | 469 | __builtin_fabs |
| | 470 | __builtin_dabs |
| | 471 | __builtin_cast_f2i |
| | 472 | __builtin_cast_i2f |
| | 473 | __builtin_cast_d2ll |
| | 474 | __builtin_cast_ll2d |
| | 475 | __builtin_copy_dhi2i |
| | 476 | __builtin_copy_i2dhi |
| | 477 | __builtin_copy_dlo2i |
| | 478 | __builtin_copy_i2dlo |
| | 479 | __add_and_fetch |
| | 480 | __sub_and_fetch |
| | 481 | __or_and_fetch |
| | 482 | __xor_and_fetch |
| | 483 | __and_and_fetch |
| | 484 | __nand_and_fetch |
| | 485 | __mpy_and_fetch |
| | 486 | __min_and_fetch |
| | 487 | __max_and_fetch |
| | 488 | __fetch_and_add |
| | 489 | __fetch_and_sub |
| | 490 | __fetch_and_or |
| | 491 | __fetch_and_xor |
| | 492 | __fetch_and_and |
| | 493 | __fetch_and_nand |
| | 494 | __fetch_and_mpy |
| | 495 | __fetch_and_min |
| | 496 | __fetch_and_max |
| | 497 | __lock_test_and_set |
| | 498 | __lock_release |
| | 499 | __lock_acquire |
| | 500 | __compare_and_swap |
| | 501 | __synchronize |
| | 502 | __high_multiply |
| | 503 | __unix |
| | 504 | __sgi |
| | 505 | __linux__ |
| | 506 | __i386__ |
| | 507 | __i486__ |
| | 508 | __cplusplus |
| | 509 | __embedded_cplusplus |
| | 510 | // long double conversion members mangled as __opr |
| | 511 | // http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html |
| | 512 | __opr |
| | 513 | </literallayout> |
| | 514 | </sect2> |
| | 515 | |
| | 516 | <sect2 id="coding_style.example"> |
| | 517 | <title>By Example</title> |
| | 518 | <literallayout> |
| | 519 | This library is written to appropriate C++ coding standards. As such, |
| | 520 | it is intended to precede the recommendations of the GNU Coding |
| | 521 | Standard, which can be referenced in full here: |
| | 522 | |
| | 523 | <ulink url="http://www.gnu.org/prep/standards/standards.html#Formatting">http://www.gnu.org/prep/standards/standards.html#Formatting</ulink> |
| | 524 | |
| | 525 | The rest of this is also interesting reading, but skip the "Design |
| | 526 | Advice" part. |
| | 527 | |
| | 528 | The GCC coding conventions are here, and are also useful: |
| | 529 | <ulink url="http://gcc.gnu.org/codingconventions.html">http://gcc.gnu.org/codingconventions.html</ulink> |
| | 530 | |
| | 531 | In addition, because it doesn't seem to be stated explicitly anywhere |
| | 532 | else, there is an 80 column source limit. |
| | 533 | |
| | 534 | <filename>ChangeLog</filename> entries for member functions should use the |
| | 535 | classname::member function name syntax as follows: |
| | 536 | |
| | 537 | <code> |
| | 538 | 1999-04-15 Dennis Ritchie <dr@att.com> |
| | 539 | |
| | 540 | * src/basic_file.cc (__basic_file::open): Fix thinko in |
| | 541 | _G_HAVE_IO_FILE_OPEN bits. |
| | 542 | </code> |
| | 543 | |
| | 544 | Notable areas of divergence from what may be previous local practice |
| | 545 | (particularly for GNU C) include: |
| | 546 | |
| | 547 | 01. Pointers and references |
| | 548 | <code> |
| | 549 | char* p = "flop"; |
| | 550 | char& c = *p; |
| | 551 | -NOT- |
| | 552 | char *p = "flop"; // wrong |
| | 553 | char &c = *p; // wrong |
| | 554 | </code> |
| | 555 | |
| | 556 | Reason: In C++, definitions are mixed with executable code. Here, |
| | 557 | <code>p</code> is being initialized, not <code>*p</code>. This is near-universal |
| | 558 | practice among C++ programmers; it is normal for C hackers |
| | 559 | to switch spontaneously as they gain experience. |
| | 560 | |
| | 561 | 02. Operator names and parentheses |
| | 562 | <code> |
| | 563 | operator==(type) |
| | 564 | -NOT- |
| | 565 | operator == (type) // wrong |
| | 566 | </code> |
| | 567 | |
| | 568 | Reason: The <code>==</code> is part of the function name. Separating |
| | 569 | it makes the declaration look like an expression. |
| | 570 | |
| | 571 | 03. Function names and parentheses |
| | 572 | <code> |
| | 573 | void mangle() |
| | 574 | -NOT- |
| | 575 | void mangle () // wrong |
| | 576 | </code> |
| | 577 | |
| | 578 | Reason: no space before parentheses (except after a control-flow |
| | 579 | keyword) is near-universal practice for C++. It identifies the |
| | 580 | parentheses as the function-call operator or declarator, as |
| | 581 | opposed to an expression or other overloaded use of parentheses. |
| | 582 | |
| | 583 | 04. Template function indentation |
| | 584 | <code> |
| | 585 | template<typename T> |
| | 586 | void |
| | 587 | template_function(args) |
| | 588 | { } |
| | 589 | -NOT- |
| | 590 | template<class T> |
| | 591 | void template_function(args) {}; |
| | 592 | </code> |
| | 593 | |
| | 594 | Reason: In class definitions, without indentation whitespace is |
| | 595 | needed both above and below the declaration to distinguish |
| | 596 | it visually from other members. (Also, re: "typename" |
| | 597 | rather than "class".) <code>T</code> often could be <code>int</code>, which is |
| | 598 | not a class. ("class", here, is an anachronism.) |
| | 599 | |
| | 600 | 05. Template class indentation |
| | 601 | <code> |
| | 602 | template<typename _CharT, typename _Traits> |
| | 603 | class basic_ios : public ios_base |
| | 604 | { |
| | 605 | public: |
| | 606 | // Types: |
| | 607 | }; |
| | 608 | -NOT- |
| | 609 | template<class _CharT, class _Traits> |
| | 610 | class basic_ios : public ios_base |
| | 611 | { |
| | 612 | public: |
| | 613 | // Types: |
| | 614 | }; |
| | 615 | -NOT- |
| | 616 | template<class _CharT, class _Traits> |
| | 617 | class basic_ios : public ios_base |
| | 618 | { |
| | 619 | public: |
| | 620 | // Types: |
| | 621 | }; |
| | 622 | </code> |
| | 623 | |
| | 624 | 06. Enumerators |
| | 625 | <code> |
| | 626 | enum |
| | 627 | { |
| | 628 | space = _ISspace, |
| | 629 | print = _ISprint, |
| | 630 | cntrl = _IScntrl |
| | 631 | }; |
| | 632 | -NOT- |
| | 633 | enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl }; |
| | 634 | </code> |
| | 635 | |
| | 636 | 07. Member initialization lists |
| | 637 | All one line, separate from class name. |
| | 638 | |
| | 639 | <code> |
| | 640 | gribble::gribble() |
| | 641 | : _M_private_data(0), _M_more_stuff(0), _M_helper(0) |
| | 642 | { } |
| | 643 | -NOT- |
| | 644 | gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0) |
| | 645 | { } |
| | 646 | </code> |
| | 647 | |
| | 648 | 08. Try/Catch blocks |
| | 649 | <code> |
| | 650 | try |
| | 651 | { |
| | 652 | // |
| | 653 | } |
| | 654 | catch (...) |
| | 655 | { |
| | 656 | // |
| | 657 | } |
| | 658 | -NOT- |
| | 659 | try { |
| | 660 | // |
| | 661 | } catch(...) { |
| | 662 | // |
| | 663 | } |
| | 664 | </code> |
| | 665 | |
| | 666 | 09. Member functions declarations and definitions |
| | 667 | Keywords such as extern, static, export, explicit, inline, etc |
| | 668 | go on the line above the function name. Thus |
| | 669 | |
| | 670 | <code> |
| | 671 | virtual int |
| | 672 | foo() |
| | 673 | -NOT- |
| | 674 | virtual int foo() |
| | 675 | </code> |
| | 676 | |
| | 677 | Reason: GNU coding conventions dictate return types for functions |
| | 678 | are on a separate line than the function name and parameter list |
| | 679 | for definitions. For C++, where we have member functions that can |
| | 680 | be either inline definitions or declarations, keeping to this |
| | 681 | standard allows all member function names for a given class to be |
| | 682 | aligned to the same margin, increasing readability. |
| | 683 | |
| | 684 | |
| | 685 | 10. Invocation of member functions with "this->" |
| | 686 | For non-uglified names, use <code>this->name</code> to call the function. |
| | 687 | |
| | 688 | <code> |
| | 689 | this->sync() |
| | 690 | -NOT- |
| | 691 | sync() |
| | 692 | </code> |
| | 693 | |
| | 694 | Reason: Koenig lookup. |
| | 695 | |
| | 696 | 11. Namespaces |
| | 697 | <code> |
| | 698 | namespace std |
| | 699 | { |
| | 700 | blah blah blah; |
| | 701 | } // namespace std |
| | 702 | |
| | 703 | -NOT- |
| | 704 | |
| | 705 | namespace std { |
| | 706 | blah blah blah; |
| | 707 | } // namespace std |
| | 708 | </code> |
| | 709 | |
| | 710 | 12. Spacing under protected and private in class declarations: |
| | 711 | space above, none below |
| | 712 | i.e. |
| | 713 | |
| | 714 | <code> |
| | 715 | public: |
| | 716 | int foo; |
| | 717 | |
| | 718 | -NOT- |
| | 719 | public: |
| | 720 | |
| | 721 | int foo; |
| | 722 | </code> |
| | 723 | |
| | 724 | 13. Spacing WRT return statements. |
| | 725 | no extra spacing before returns, no parenthesis |
| | 726 | i.e. |
| | 727 | |
| | 728 | <code> |
| | 729 | } |
| | 730 | return __ret; |
| | 731 | |
| | 732 | -NOT- |
| | 733 | } |
| | 734 | |
| | 735 | return __ret; |
| | 736 | |
| | 737 | -NOT- |
| | 738 | |
| | 739 | } |
| | 740 | return (__ret); |
| | 741 | </code> |
| | 742 | |
| | 743 | |
| | 744 | 14. Location of global variables. |
| | 745 | All global variables of class type, whether in the "user visible" |
| | 746 | space (e.g., <code>cin</code>) or the implementation namespace, must be defined |
| | 747 | as a character array with the appropriate alignment and then later |
| | 748 | re-initialized to the correct value. |
| | 749 | |
| | 750 | This is due to startup issues on certain platforms, such as AIX. |
| | 751 | For more explanation and examples, see <filename>src/globals.cc</filename>. All such |
| | 752 | variables should be contained in that file, for simplicity. |
| | 753 | |
| | 754 | 15. Exception abstractions |
| | 755 | Use the exception abstractions found in <filename class="headerfile">functexcept.h</filename>, which allow |
| | 756 | C++ programmers to use this library with <literal>-fno-exceptions</literal>. (Even if |
| | 757 | that is rarely advisable, it's a necessary evil for backwards |
| | 758 | compatibility.) |
| | 759 | |
| | 760 | 16. Exception error messages |
| | 761 | All start with the name of the function where the exception is |
| | 762 | thrown, and then (optional) descriptive text is added. Example: |
| | 763 | |
| | 764 | <code> |
| | 765 | __throw_logic_error(__N("basic_string::_S_construct NULL not valid")); |
| | 766 | </code> |
| | 767 | |
| | 768 | Reason: The verbose terminate handler prints out <code>exception::what()</code>, |
| | 769 | as well as the typeinfo for the thrown exception. As this is the |
| | 770 | default terminate handler, by putting location info into the |
| | 771 | exception string, a very useful error message is printed out for |
| | 772 | uncaught exceptions. So useful, in fact, that non-programmers can |
| | 773 | give useful error messages, and programmers can intelligently |
| | 774 | speculate what went wrong without even using a debugger. |
| | 775 | |
| | 776 | 17. The doxygen style guide to comments is a separate document, |
| | 777 | see index. |
| | 778 | |
| | 779 | The library currently has a mixture of GNU-C and modern C++ coding |
| | 780 | styles. The GNU C usages will be combed out gradually. |
| | 781 | |
| | 782 | Name patterns: |
| | 783 | |
| | 784 | For nonstandard names appearing in Standard headers, we are constrained |
| | 785 | to use names that begin with underscores. This is called "uglification". |
| | 786 | The convention is: |
| | 787 | |
| | 788 | Local and argument names: <literal>__[a-z].*</literal> |
| | 789 | |
| | 790 | Examples: <code>__count __ix __s1</code> |
| | 791 | |
| | 792 | Type names and template formal-argument names: <literal>_[A-Z][^_].*</literal> |
| | 793 | |
| | 794 | Examples: <code>_Helper _CharT _N</code> |
| | 795 | |
| | 796 | Member data and function names: <literal>_M_.*</literal> |
| | 797 | |
| | 798 | Examples: <code>_M_num_elements _M_initialize ()</code> |
| | 799 | |
| | 800 | Static data members, constants, and enumerations: <literal>_S_.*</literal> |
| | 801 | |
| | 802 | Examples: <code>_S_max_elements _S_default_value</code> |
| | 803 | |
| | 804 | Don't use names in the same scope that differ only in the prefix, |
| | 805 | e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names. |
| | 806 | (The most tempting of these seem to be and "_T" and "__sz".) |
| | 807 | |
| | 808 | Names must never have "__" internally; it would confuse name |
| | 809 | unmanglers on some targets. Also, never use "__[0-9]", same reason. |
| | 810 | |
| | 811 | -------------------------- |
| | 812 | |
| | 813 | [BY EXAMPLE] |
| | 814 | <code> |
| | 815 | |
| | 816 | #ifndef _HEADER_ |
| | 817 | #define _HEADER_ 1 |
| | 818 | |
| | 819 | namespace std |
| | 820 | { |
| | 821 | class gribble |
| | 822 | { |
| | 823 | public: |
| | 824 | gribble() throw(); |
| | 825 | |
| | 826 | gribble(const gribble&); |
| | 827 | |
| | 828 | explicit |
| | 829 | gribble(int __howmany); |
| | 830 | |
| | 831 | gribble& |
| | 832 | operator=(const gribble&); |
| | 833 | |
| | 834 | virtual |
| | 835 | ~gribble() throw (); |
| | 836 | |
| | 837 | // Start with a capital letter, end with a period. |
| | 838 | inline void |
| | 839 | public_member(const char* __arg) const; |
| | 840 | |
| | 841 | // In-class function definitions should be restricted to one-liners. |
| | 842 | int |
| | 843 | one_line() { return 0 } |
| | 844 | |
| | 845 | int |
| | 846 | two_lines(const char* arg) |
| | 847 | { return strchr(arg, 'a'); } |
| | 848 | |
| | 849 | inline int |
| | 850 | three_lines(); // inline, but defined below. |
| | 851 | |
| | 852 | // Note indentation. |
| | 853 | template<typename _Formal_argument> |
| | 854 | void |
| | 855 | public_template() const throw(); |
| | 856 | |
| | 857 | template<typename _Iterator> |
| | 858 | void |
| | 859 | other_template(); |
| | 860 | |
| | 861 | private: |
| | 862 | class _Helper; |
| | 863 | |
| | 864 | int _M_private_data; |
| | 865 | int _M_more_stuff; |
| | 866 | _Helper* _M_helper; |
| | 867 | int _M_private_function(); |
| | 868 | |
| | 869 | enum _Enum |
| | 870 | { |
| | 871 | _S_one, |
| | 872 | _S_two |
| | 873 | }; |
| | 874 | |
| | 875 | static void |
| | 876 | _S_initialize_library(); |
| | 877 | }; |
| | 878 | |
| | 879 | // More-or-less-standard language features described by lack, not presence. |
| | 880 | # ifndef _G_NO_LONGLONG |
| | 881 | extern long long _G_global_with_a_good_long_name; // avoid globals! |
| | 882 | # endif |
| | 883 | |
| | 884 | // Avoid in-class inline definitions, define separately; |
| | 885 | // likewise for member class definitions: |
| | 886 | inline int |
| | 887 | gribble::public_member() const |
| | 888 | { int __local = 0; return __local; } |
| | 889 | |
| | 890 | class gribble::_Helper |
| | 891 | { |
| | 892 | int _M_stuff; |
| | 893 | |
| | 894 | friend class gribble; |
| | 895 | }; |
| | 896 | } |
| | 897 | |
| | 898 | // Names beginning with "__": only for arguments and |
| | 899 | // local variables; never use "__" in a type name, or |
| | 900 | // within any name; never use "__[0-9]". |
| | 901 | |
| | 902 | #endif /* _HEADER_ */ |
| | 903 | |
| | 904 | |
| | 905 | namespace std |
| | 906 | { |
| | 907 | template<typename T> // notice: "typename", not "class", no space |
| | 908 | long_return_value_type<with_many, args> |
| | 909 | function_name(char* pointer, // "char *pointer" is wrong. |
| | 910 | char* argument, |
| | 911 | const Reference& ref) |
| | 912 | { |
| | 913 | // int a_local; /* wrong; see below. */ |
| | 914 | if (test) |
| | 915 | { |
| | 916 | nested code |
| | 917 | } |
| | 918 | |
| | 919 | int a_local = 0; // declare variable at first use. |
| | 920 | |
| | 921 | // char a, b, *p; /* wrong */ |
| | 922 | char a = 'a'; |
| | 923 | char b = a + 1; |
| | 924 | char* c = "abc"; // each variable goes on its own line, always. |
| | 925 | |
| | 926 | // except maybe here... |
| | 927 | for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) { |
| | 928 | // ... |
| | 929 | } |
| | 930 | } |
| | 931 | |
| | 932 | gribble::gribble() |
| | 933 | : _M_private_data(0), _M_more_stuff(0), _M_helper(0) |
| | 934 | { } |
| | 935 | |
| | 936 | int |
| | 937 | gribble::three_lines() |
| | 938 | { |
| | 939 | // doesn't fit in one line. |
| | 940 | } |
| | 941 | } // namespace std |
| | 942 | </code> |
| | 943 | </literallayout> |
| | 944 | </sect2> |
| | 945 | </sect1> |
| | 946 | |
| | 947 | <sect1 id="contrib.doc_style" xreflabel="Documentation Style"> |
| | 948 | <?dbhtml filename="documentation_style.html"?> |
| | 949 | <title>Documentation Style</title> |
| | 950 | <sect2 id="doc_style.doxygen"> |
| | 951 | <title>Doxygen</title> |
| | 952 | <sect3 id="doxygen.prereq"> |
| | 953 | <title>Prerequisites</title> |
| | 954 | <para> |
| | 955 | Prerequisite tools are Bash 2.0 or later, |
| | 956 | <ulink url="http://www.doxygen.org/">Doxygen</ulink>, and |
| | 957 | the <ulink url="http://www.gnu.org/software/coreutils/">GNU |
| | 958 | coreutils</ulink>. (GNU versions of find, xargs, and possibly |
| | 959 | sed and grep are used, just because the GNU versions make |
| | 960 | things very easy.) |
| | 961 | </para> |
| | 962 | |
| | 963 | <para> |
| | 964 | To generate the pretty pictures and hierarchy |
| | 965 | graphs, the |
| | 966 | <ulink url="http://www.graphviz.org">Graphviz</ulink> package |
| | 967 | will need to be installed. For PDF |
| | 968 | output, <ulink url="http://www.tug.org/applications/pdftex/"> |
| | 969 | pdflatex</ulink> is required. |
| | 970 | </para> |
| | 971 | </sect3> |
| | 972 | |
| | 973 | <sect3 id="doxygen.rules"> |
| | 974 | <title>Generating the Doxygen Files</title> |
| | 975 | <para> |
| | 976 | The following Makefile rules run Doxygen to generate HTML |
| | 977 | docs, XML docs, XML docs as a single file, PDF docs, and the man pages. |
| | 978 | </para> |
| | 979 | |
| | 980 | <para> |
| | 981 | Generated files are output into separate sub directores of |
| | 982 | <filename class="directory">doc/doxygen/</filename> in the |
| | 983 | build directory, based on the output format. For instance, the |
| | 984 | HTML docs will be in <filename |
| | 985 | class="directory">doc/doxygen/html</filename>. |
| | 986 | </para> |
| | 987 | |
| | 988 | <para> |
| | 989 | <screen><userinput>make doc-html-doxygen</userinput></screen> |
| | 990 | </para> |
| | 991 | |
| | 992 | <para> |
| | 993 | <screen><userinput>make doc-xml-doxygen</userinput></screen> |
| | 994 | </para> |
| | 995 | |
| | 996 | <para> |
| | 997 | <screen><userinput>make doc-xml-single-doxygen</userinput></screen> |
| | 998 | </para> |
| | 999 | |
| | 1000 | <para> |
| | 1001 | <screen><userinput>make doc-pdf-doxygen</userinput></screen> |
| | 1002 | </para> |
| | 1003 | |
| | 1004 | <para> |
| | 1005 | <screen><userinput>make doc-man-doxygen</userinput></screen> |
| | 1006 | </para> |
| | 1007 | |
| | 1008 | <para> |
| | 1009 | Careful observers will see that the Makefile rules simply call |
| | 1010 | a script from the source tree, <filename>run_doxygen</filename>, which |
| | 1011 | does the actual work of running Doxygen and then (most |
| | 1012 | importantly) massaging the output files. If for some reason |
| | 1013 | you prefer to not go through the Makefile, you can call this |
| | 1014 | script directly. (Start by passing <literal>--help</literal>.) |
| | 1015 | </para> |
| | 1016 | |
| | 1017 | <para> |
| | 1018 | If you wish to tweak the Doxygen settings, do so by editing |
| | 1019 | <filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow |
| | 1020 | library hackers are written in triple-# comments. |
| | 1021 | </para> |
| | 1022 | |
| | 1023 | </sect3> |
| | 1024 | |
| | 1025 | <sect3 id="doxygen.markup"> |
| | 1026 | <title>Markup</title> |
| | 1027 | |
| | 1028 | <para> |
| | 1029 | In general, libstdc++ files should be formatted according to |
| | 1030 | the rules found in the |
| | 1031 | <link linkend="contrib.coding_style">Coding Standard</link>. Before |
| | 1032 | any doxygen-specific formatting tweaks are made, please try to |
| | 1033 | make sure that the initial formatting is sound. |
| | 1034 | </para> |
| | 1035 | |
| | 1036 | <para> |
| | 1037 | Adding Doxygen markup to a file (informally called |
| | 1038 | <quote>doxygenating</quote>) is very simple. The Doxygen manual can be |
| | 1039 | found |
| | 1040 | <ulink url="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</ulink>. |
| | 1041 | We try to use a very-recent version of Doxygen. |
| | 1042 | </para> |
| | 1043 | |
| | 1044 | <para> |
| | 1045 | For classes, use |
| | 1046 | <classname>deque</classname>/<classname>vector</classname>/<classname>list</classname> |
| | 1047 | and <classname>std::pair</classname> as examples. For |
| | 1048 | functions, see their member functions, and the free functions |
| | 1049 | in <filename>stl_algobase.h</filename>. Member functions of |
| | 1050 | other container-like types should read similarly to these |
| | 1051 | member functions. |
| | 1052 | </para> |
| | 1053 | |
| | 1054 | <para> |
| | 1055 | Some commentary to accompany |
| | 1056 | the first list in the <ulink url="http://www.stack.nl/~dimitri/doxygen/docblocks.html">Special |
| | 1057 | Documentation Blocks</ulink> section of |
| | 1058 | the Doxygen manual: |
| | 1059 | </para> |
| | 1060 | |
| | 1061 | <orderedlist> |
| | 1062 | <listitem> |
| | 1063 | <para>For longer comments, use the Javadoc style...</para> |
| | 1064 | </listitem> |
| | 1065 | |
| | 1066 | <listitem> |
| | 1067 | <para> |
| | 1068 | ...not the Qt style. The intermediate *'s are preferred. |
| | 1069 | </para> |
| | 1070 | </listitem> |
| | 1071 | |
| | 1072 | <listitem> |
| | 1073 | <para> |
| | 1074 | Use the triple-slash style only for one-line comments (the |
| | 1075 | <quote>brief</quote> mode). |
| | 1076 | </para> |
| | 1077 | </listitem> |
| | 1078 | |
| | 1079 | <listitem> |
| | 1080 | <para> |
| | 1081 | This is disgusting. Don't do this. |
| | 1082 | </para> |
| | 1083 | </listitem> |
| | 1084 | </orderedlist> |
| | 1085 | |
| | 1086 | <para> |
| | 1087 | Some specific guidelines: |
| | 1088 | </para> |
| | 1089 | |
| | 1090 | <para> |
| | 1091 | Use the @-style of commands, not the !-style. Please be |
| | 1092 | careful about whitespace in your markup comments. Most of the |
| | 1093 | time it doesn't matter; doxygen absorbs most whitespace, and |
| | 1094 | both HTML and *roff are agnostic about whitespace. However, |
| | 1095 | in <pre> blocks and @code/@endcode sections, spacing can |
| | 1096 | have <quote>interesting</quote> effects. |
| | 1097 | </para> |
| | 1098 | |
| | 1099 | <para> |
| | 1100 | Use either kind of grouping, as |
| | 1101 | appropriate. <filename>doxygroups.cc</filename> exists for this |
| | 1102 | purpose. See <filename>stl_iterator.h</filename> for a good example |
| | 1103 | of the <quote>other</quote> kind of grouping. |
| | 1104 | </para> |
| | 1105 | |
| | 1106 | <para> |
| | 1107 | Please use markup tags like @p and @a when referring to things |
| | 1108 | such as the names of function parameters. Use @e for emphasis |
| | 1109 | when necessary. Use @c to refer to other standard names. |
| | 1110 | (Examples of all these abound in the present code.) |
| | 1111 | </para> |
| | 1112 | |
| | 1113 | <para> |
| | 1114 | Complicated math functions should use the multi-line |
| | 1115 | format. An example from <filename>random.h</filename>: |
| | 1116 | </para> |
| | 1117 | |
| | 1118 | <para> |
| | 1119 | <literallayout> |
| | 1120 | /** |
| | 1121 | * @brief A model of a linear congruential random number generator. |
| | 1122 | * |
| | 1123 | * @f[ |
| | 1124 | * x_{i+1}\leftarrow(ax_{i} + c) \bmod m |
| | 1125 | * @f] |
| | 1126 | */ |
| | 1127 | </literallayout> |
| | 1128 | </para> |
| | 1129 | |
| | 1130 | <para> |
| | 1131 | Be careful about using certain, special characters when |
| | 1132 | writing Doxygen comments. Single and double quotes, and |
| | 1133 | separators in filenames are two common trouble spots. When in |
| | 1134 | doubt, consult the following table. |
| | 1135 | </para> |
| | 1136 | |
| | 1137 | <table frame='all'> |
| | 1138 | <title>HTML to Doxygen Markup Comparison</title> |
| | 1139 | <tgroup cols='2' align='left' colsep='1' rowsep='1'> |
| | 1140 | <colspec colname='c1'></colspec> |
| | 1141 | <colspec colname='c2'></colspec> |
| | 1142 | |
| | 1143 | <thead> |
| | 1144 | <row> |
| | 1145 | <entry>HTML</entry> |
| | 1146 | <entry>Doxygen</entry> |
| | 1147 | </row> |
| | 1148 | </thead> |
| | 1149 | |
| | 1150 | <tbody> |
| | 1151 | <row> |
| | 1152 | <entry>\</entry> |
| | 1153 | <entry>\\</entry> |
| | 1154 | </row> |
| | 1155 | |
| | 1156 | <row> |
| | 1157 | <entry>"</entry> |
| | 1158 | <entry>\"</entry> |
| | 1159 | </row> |
| | 1160 | |
| | 1161 | <row> |
| | 1162 | <entry>'</entry> |
| | 1163 | <entry>\'</entry> |
| | 1164 | </row> |
| | 1165 | |
| | 1166 | <row> |
| | 1167 | <entry><i></entry> |
| | 1168 | <entry>@a word</entry> |
| | 1169 | </row> |
| | 1170 | |
| | 1171 | <row> |
| | 1172 | <entry><b></entry> |
| | 1173 | <entry>@b word</entry> |
| | 1174 | </row> |
| | 1175 | |
| | 1176 | <row> |
| | 1177 | <entry><code></entry> |
| | 1178 | <entry>@c word</entry> |
| | 1179 | </row> |
| | 1180 | |
| | 1181 | <row> |
| | 1182 | <entry><em></entry> |
| | 1183 | <entry>@a word</entry> |
| | 1184 | </row> |
| | 1185 | |
| | 1186 | <row> |
| | 1187 | <entry><em></entry> |
| | 1188 | <entry><em>two words or more</em></entry> |
| | 1189 | </row> |
| | 1190 | </tbody> |
| | 1191 | |
| | 1192 | </tgroup> |
| | 1193 | </table> |
| | 1194 | |
| | 1195 | |
| | 1196 | </sect3> |
| | 1197 | |
| | 1198 | </sect2> |
| | 1199 | |
| | 1200 | <sect2 id="doc_style.docbook"> |
| | 1201 | <title>Docbook</title> |
| | 1202 | |
| | 1203 | <sect3 id="docbook.prereq"> |
| | 1204 | <title>Prerequisites</title> |
| | 1205 | <para> |
| | 1206 | Editing the DocBook sources requires an XML editor. Many |
| | 1207 | exist: some notable options |
| | 1208 | include <command>emacs</command>, <application>Kate</application>, |
| | 1209 | or <application>Conglomerate</application>. |
| | 1210 | </para> |
| | 1211 | |
| | 1212 | <para> |
| | 1213 | Some editors support special <quote>XML Validation</quote> |
| | 1214 | modes that can validate the file as it is |
| | 1215 | produced. Recommended is the <command>nXML Mode</command> |
| | 1216 | for <command>emacs</command>. |
| | 1217 | </para> |
| | 1218 | |
| | 1219 | <para> |
| | 1220 | Besides an editor, additional DocBook files and XML tools are |
| | 1221 | also required. |
| | 1222 | </para> |
| | 1223 | |
| | 1224 | <para> |
| | 1225 | Access to the DocBook stylesheets and DTD is required. The |
| | 1226 | stylesheets are usually packaged by vendor, in something |
| | 1227 | like <filename>docbook-style-xsl</filename>. To exactly match |
| | 1228 | generated output, please use a version of the stylesheets |
| | 1229 | equivalent |
| | 1230 | to <filename>docbook-style-xsl-1.74.0-5</filename>. The |
| | 1231 | installation directory for this package corresponds to |
| | 1232 | the <literal>XSL_STYLE_DIR</literal> |
| | 1233 | in <filename>doc/Makefile.am</filename> and defaults |
| | 1234 | to <filename class="directory">/usr/share/sgml/docbook/xsl-stylesheets</filename>. |
| | 1235 | </para> |
| | 1236 | |
| | 1237 | <para> |
| | 1238 | For processing XML, an XML processor and some style |
| | 1239 | sheets are necessary. Defaults are <command>xsltproc</command> |
| | 1240 | provided by <filename>libxslt</filename>. |
| | 1241 | </para> |
| | 1242 | |
| | 1243 | <para> |
| | 1244 | For validating the XML document, you'll need |
| | 1245 | something like <command>xmllint</command> and access to the |
| | 1246 | DocBook DTD. These are provided |
| | 1247 | by a vendor package like <filename>libxml2</filename>. |
| | 1248 | </para> |
| | 1249 | |
| | 1250 | <para> |
| | 1251 | For PDF output, something that transforms valid Docbook XML to PDF is |
| | 1252 | required. Possible solutions include <ulink |
| | 1253 | url="http://dblatex.sourceforge.net">dblatex</ulink>, |
| | 1254 | <command>xmlto</command>, or <command>prince</command>. Of |
| | 1255 | these, <command>dblatex</command> is the default. Other |
| | 1256 | options are listed on the DocBook web <ulink |
| | 1257 | url="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</ulink>. Please |
| | 1258 | consult the <email>libstdc++@gcc.gnu.org</email> list when |
| | 1259 | preparing printed manuals for current best practice and |
| | 1260 | suggestions. |
| | 1261 | </para> |
| | 1262 | |
| | 1263 | <para> |
| | 1264 | For Texinfo output, something that transforms valid Docbook |
| | 1265 | XML to Texinfo is required. The default choice is <ulink |
| | 1266 | url="http://docbook2x.sourceforge.net/">docbook2X</ulink>. |
| | 1267 | </para> |
| | 1268 | |
| | 1269 | <para> |
| | 1270 | Please make sure that the XML documentation and markup is valid for |
| | 1271 | any change. This can be done easily, with the validation rule |
| | 1272 | detailed below, which is equivalent to doing: |
| | 1273 | </para> |
| | 1274 | |
| | 1275 | <screen> |
| | 1276 | <userinput> |
| | 1277 | xmllint --noout --valid <filename>xml/index.xml</filename> |
| | 1278 | </userinput> |
| | 1279 | </screen> |
| | 1280 | </sect3> |
| | 1281 | |
| | 1282 | <sect3 id="docbook.rules"> |
| | 1283 | <title>Generating the DocBook Files</title> |
| | 1284 | |
| | 1285 | <para> |
| | 1286 | The following Makefile rules generate (in order): an HTML |
| | 1287 | version of all the DocBook documentation, a PDF version of the same, a |
| | 1288 | single XML document, and the result of validating the entire XML |
| | 1289 | document. |
| | 1290 | </para> |
| | 1291 | |
| | 1292 | <para> |
| | 1293 | Generated files are output into separate sub directores of |
| | 1294 | <filename class="directory">doc/docbook/</filename> in the |
| | 1295 | build directory, based on the output format. For instance, the |
| | 1296 | HTML docs will be in <filename |
| | 1297 | class="directory">doc/docbook/html</filename>. |
| | 1298 | </para> |
| | 1299 | |
| | 1300 | <para> |
| | 1301 | <screen><userinput>make doc-html-docbook</userinput></screen> |
| | 1302 | </para> |
| | 1303 | |
| | 1304 | <para> |
| | 1305 | <screen><userinput>make doc-pdf-docbook</userinput></screen> |
| | 1306 | </para> |
| | 1307 | |
| | 1308 | <para> |
| | 1309 | <screen><userinput>make doc-xml-single-docbook</userinput></screen> |
| | 1310 | </para> |
| | 1311 | |
| | 1312 | <para> |
| | 1313 | <screen><userinput>make doc-xml-validate-docbook</userinput></screen> |
| | 1314 | </para> |
| | 1315 | |
| | 1316 | </sect3> |
| | 1317 | |
| | 1318 | <sect3 id="docbook.examples"> |
| | 1319 | <title>File Organization and Basics</title> |
| | 1320 | |
| | 1321 | <literallayout> |
| | 1322 | <emphasis>Which files are important</emphasis> |
| | 1323 | |
| | 1324 | All Docbook files are in the directory |
| | 1325 | libstdc++-v3/doc/xml |
| | 1326 | |
| | 1327 | Inside this directory, the files of importance: |
| | 1328 | spine.xml - index to documentation set |
| | 1329 | manual/spine.xml - index to manual |
| | 1330 | manual/*.xml - individual chapters and sections of the manual |
| | 1331 | faq.xml - index to FAQ |
| | 1332 | api.xml - index to source level / API |
| | 1333 | |
| | 1334 | All *.txml files are template xml files, i.e., otherwise empty files with |
| | 1335 | the correct structure, suitable for filling in with new information. |
| | 1336 | |
| | 1337 | <emphasis>Canonical Writing Style</emphasis> |
| | 1338 | |
| | 1339 | class template |
| | 1340 | function template |
| | 1341 | member function template |
| | 1342 | (via C++ Templates, Vandevoorde) |
| | 1343 | |
| | 1344 | class in namespace std: allocator, not std::allocator |
| | 1345 | |
| | 1346 | header file: iostream, not <iostream> |
| | 1347 | |
| | 1348 | |
| | 1349 | <emphasis>General structure</emphasis> |
| | 1350 | |
| | 1351 | <set> |
| | 1352 | <book> |
| | 1353 | </book> |
| | 1354 | |
| | 1355 | <book> |
| | 1356 | <chapter> |
| | 1357 | </chapter> |
| | 1358 | </book> |
| | 1359 | |
| | 1360 | <book> |
| | 1361 | <part> |
| | 1362 | <chapter> |
| | 1363 | <section> |
| | 1364 | </section> |
| | 1365 | |
| | 1366 | <sect1> |
| | 1367 | </sect1> |
| | 1368 | |
| | 1369 | <sect1> |
| | 1370 | <sect2> |
| | 1371 | </sect2> |
| | 1372 | </sect1> |
| | 1373 | </chapter> |
| | 1374 | |
| | 1375 | <chapter> |
| | 1376 | </chapter> |
| | 1377 | </part> |
| | 1378 | </book> |
| | 1379 | |
| | 1380 | </set> |
| | 1381 | </literallayout> |
| | 1382 | </sect3> |
| | 1383 | |
| | 1384 | <sect3 id="docbook.markup"> |
| | 1385 | <title>Markup By Example</title> |
| | 1386 | |
| | 1387 | <para> |
| | 1388 | Complete details on Docbook markup can be found in the DocBook |
| | 1389 | Element Reference, |
| | 1390 | <ulink url="http://www.docbook.org/tdg/en/html/part2.html">online</ulink>. |
| | 1391 | An incomplete reference for HTML to Docbook conversion is |
| | 1392 | detailed in the table below. |
| | 1393 | </para> |
| | 1394 | |
| | 1395 | <table frame='all'> |
| | 1396 | <title>HTML to Docbook XML Markup Comparison</title> |
| | 1397 | <tgroup cols='2' align='left' colsep='1' rowsep='1'> |
| | 1398 | <colspec colname='c1'></colspec> |
| | 1399 | <colspec colname='c2'></colspec> |
| | 1400 | |
| | 1401 | <thead> |
| | 1402 | <row> |
| | 1403 | <entry>HTML</entry> |
| | 1404 | <entry>Docbook</entry> |
| | 1405 | </row> |
| | 1406 | </thead> |
| | 1407 | |
| | 1408 | <tbody> |
| | 1409 | <row> |
| | 1410 | <entry><p></entry> |
| | 1411 | <entry><para></entry> |
| | 1412 | </row> |
| | 1413 | <row> |
| | 1414 | <entry><pre></entry> |
| | 1415 | <entry><computeroutput>, <programlisting>, |
| | 1416 | <literallayout></entry> |
| | 1417 | </row> |
| | 1418 | <row> |
| | 1419 | <entry><ul></entry> |
| | 1420 | <entry><itemizedlist></entry> |
| | 1421 | </row> |
| | 1422 | <row> |
| | 1423 | <entry><ol></entry> |
| | 1424 | <entry><orderedlist></entry> |
| | 1425 | </row> |
| | 1426 | <row> |
| | 1427 | <entry><il></entry> |
| | 1428 | <entry><listitem></entry> |
| | 1429 | </row> |
| | 1430 | <row> |
| | 1431 | <entry><dl></entry> |
| | 1432 | <entry><variablelist></entry> |
| | 1433 | </row> |
| | 1434 | <row> |
| | 1435 | <entry><dt></entry> |
| | 1436 | <entry><term></entry> |
| | 1437 | </row> |
| | 1438 | <row> |
| | 1439 | <entry><dd></entry> |
| | 1440 | <entry><listitem></entry> |
| | 1441 | </row> |
| | 1442 | |
| | 1443 | <row> |
| | 1444 | <entry><a href=""></entry> |
| | 1445 | <entry><ulink url=""></entry> |
| | 1446 | </row> |
| | 1447 | <row> |
| | 1448 | <entry><code></entry> |
| | 1449 | <entry><literal>, <programlisting></entry> |
| | 1450 | </row> |
| | 1451 | <row> |
| | 1452 | <entry><strong></entry> |
| | 1453 | <entry><emphasis></entry> |
| | 1454 | </row> |
| | 1455 | <row> |
| | 1456 | <entry><em></entry> |
| | 1457 | <entry><emphasis></entry> |
| | 1458 | </row> |
| | 1459 | <row> |
| | 1460 | <entry>"</entry> |
| | 1461 | <entry><quote></entry> |
| | 1462 | </row> |
| | 1463 | </tbody> |
| | 1464 | </tgroup> |
| | 1465 | </table> |
| | 1466 | |
| | 1467 | <para> |
| | 1468 | And examples of detailed markup for which there are no real HTML |
| | 1469 | equivalents are listed in the table below. |
| | 1470 | </para> |
| | 1471 | |
| | 1472 | <table frame='all'> |
| | 1473 | <title>Docbook XML Element Use</title> |
| | 1474 | <tgroup cols='2' align='left' colsep='1' rowsep='1'> |
| | 1475 | <colspec colname='c1'></colspec> |
| | 1476 | <colspec colname='c2'></colspec> |
| | 1477 | |
| | 1478 | <thead> |
| | 1479 | <row> |
| | 1480 | <entry>Element</entry> |
| | 1481 | <entry>Use</entry> |
| | 1482 | </row> |
| | 1483 | </thead> |
| | 1484 | |
| | 1485 | <tbody> |
| | 1486 | <row> |
| | 1487 | <entry><structname></entry> |
| | 1488 | <entry><structname>char_traits</structname></entry> |
| | 1489 | </row> |
| | 1490 | <row> |
| | 1491 | <entry><classname></entry> |
| | 1492 | <entry><classname>string</classname></entry> |
| | 1493 | </row> |
| | 1494 | <row> |
| | 1495 | <entry><function></entry> |
| | 1496 | <entry> |
| | 1497 | <para><function>clear()</function></para> |
| | 1498 | <para><function>fs.clear()</function></para> |
| | 1499 | </entry> |
| | 1500 | </row> |
| | 1501 | <row> |
| | 1502 | <entry><type></entry> |
| | 1503 | <entry><type>long long</type></entry> |
| | 1504 | </row> |
| | 1505 | <row> |
| | 1506 | <entry><varname></entry> |
| | 1507 | <entry><varname>fs</varname></entry> |
| | 1508 | </row> |
| | 1509 | <row> |
| | 1510 | <entry><literal></entry> |
| | 1511 | <entry> |
| | 1512 | <para><literal>-Weffc++</literal></para> |
| | 1513 | <para><literal>rel_ops</literal></para> |
| | 1514 | </entry> |
| | 1515 | </row> |
| | 1516 | <row> |
| | 1517 | <entry><constant></entry> |
| | 1518 | <entry> |
| | 1519 | <para><constant>_GNU_SOURCE</constant></para> |
| | 1520 | <para><constant>3.0</constant></para> |
| | 1521 | </entry> |
| | 1522 | </row> |
| | 1523 | <row> |
| | 1524 | <entry><command></entry> |
| | 1525 | <entry><command>g++</command></entry> |
| | 1526 | </row> |
| | 1527 | <row> |
| | 1528 | <entry><errortext></entry> |
| | 1529 | <entry><errortext>In instantiation of</errortext></entry> |
| | 1530 | </row> |
| | 1531 | <row> |
| | 1532 | <entry><filename></entry> |
| | 1533 | <entry> |
| | 1534 | <para><filename class="headerfile">ctype.h</filename></para> |
| | 1535 | <para><filename class="directory">/home/gcc/build</filename></para> |
| | 1536 | <para><filename class="libraryfile">libstdc++.so</filename></para> |
| | 1537 | </entry> |
| | 1538 | </row> |
| | 1539 | </tbody> |
| | 1540 | </tgroup> |
| | 1541 | </table> |
| | 1542 | |
| | 1543 | </sect3> |
| | 1544 | </sect2> |
| | 1545 | |
| | 1546 | <sect2 id="doc_style.combines"> |
| | 1547 | <title>Combines</title> |
| | 1548 | |
| | 1549 | <sect3 id="combines.rules"> |
| | 1550 | <title>Generating Combines and Assemblages</title> |
| | 1551 | |
| | 1552 | <para> |
| | 1553 | The following Makefile rules are defaults, and are usually |
| | 1554 | aliased to more detailed rules. They are shortcuts for |
| | 1555 | generating HTML, PDF, Texinfo, XML, or man files and then collecting |
| | 1556 | the generated files into the build directory's doc directory. |
| | 1557 | </para> |
| | 1558 | |
| | 1559 | <variablelist> |
| | 1560 | |
| | 1561 | <varlistentry><term> |
| | 1562 | <emphasis>make doc-html</emphasis> |
| | 1563 | </term> |
| | 1564 | <listitem> |
| | 1565 | <para> |
| | 1566 | Generates multi-page HTML documentation in the following directories: |
| | 1567 | </para> |
| | 1568 | <para> |
| | 1569 | <filename class="directory">doc/libstdc++-api.html</filename> |
| | 1570 | </para> |
| | 1571 | <para> |
| | 1572 | <filename class="directory">doc/libstdc++-manual.html</filename> |
| | 1573 | </para> |
| | 1574 | </listitem> |
| | 1575 | </varlistentry> |
| | 1576 | |
| | 1577 | <varlistentry><term> |
| | 1578 | <emphasis>make doc-man</emphasis> |
| | 1579 | </term> |
| | 1580 | <listitem> |
| | 1581 | <para> |
| | 1582 | Generates man pages in the following directory: |
| | 1583 | </para> |
| | 1584 | <para> |
| | 1585 | <filename class="directory">doc/libstdc++-api.man</filename> |
| | 1586 | </para> |
| | 1587 | </listitem> |
| | 1588 | </varlistentry> |
| | 1589 | |
| | 1590 | <varlistentry><term> |
| | 1591 | <emphasis>make doc-pdf</emphasis> |
| | 1592 | </term> |
| | 1593 | <listitem> |
| | 1594 | <para> |
| | 1595 | Generates indexed PDF documentation in the following files: |
| | 1596 | </para> |
| | 1597 | <para> |
| | 1598 | <filename>doc/libstdc++-api.pdf</filename> |
| | 1599 | </para> |
| | 1600 | <para> |
| | 1601 | <filename>doc/libstdc++-manual.pdf</filename> |
| | 1602 | </para> |
| | 1603 | </listitem> |
| | 1604 | </varlistentry> |
| | 1605 | |
| | 1606 | <varlistentry><term> |
| | 1607 | <emphasis>make doc-texinfo</emphasis> |
| | 1608 | </term> |
| | 1609 | <listitem> |
| | 1610 | <para> |
| | 1611 | Generates Texinfo documentation in the following files: |
| | 1612 | </para> |
| | 1613 | <para> |
| | 1614 | <filename>doc/libstdc++-manual.texinfo</filename> |
| | 1615 | </para> |
| | 1616 | </listitem> |
| | 1617 | </varlistentry> |
| | 1618 | |
| | 1619 | <varlistentry><term> |
| | 1620 | <emphasis>make doc-xml</emphasis> |
| | 1621 | </term> |
| | 1622 | <listitem> |
| | 1623 | <para> |
| | 1624 | Generates single-file XML documentation in the following files: |
| | 1625 | </para> |
| | 1626 | <para> |
| | 1627 | <filename>doc/libstdc++-api.xml</filename> |
| | 1628 | </para> |
| | 1629 | <para> |
| | 1630 | <filename>doc/libstdc++-manual.xml</filename> |
| | 1631 | </para> |
| | 1632 | </listitem> |
| | 1633 | </varlistentry> |
| | 1634 | |
| | 1635 | </variablelist> |
| | 1636 | |
| | 1637 | |
| | 1638 | </sect3> |
| | 1639 | </sect2> |
| | 1640 | </sect1> |
| | 1641 | |
| | 1642 | <sect1 id="contrib.design_notes" xreflabel="Design Notes"> |
| | 1643 | <?dbhtml filename="source_design_notes.html"?> |
| | 1644 | <title>Design Notes</title> |
| | 1645 | <para> |
| | 1646 | </para> |
| | 1647 | |
| | 1648 | <literallayout> |
| | 1649 | |
| | 1650 | The Library |
| | 1651 | ----------- |
| | 1652 | |
| | 1653 | This paper is covers two major areas: |
| | 1654 | |
| | 1655 | - Features and policies not mentioned in the standard that |
| | 1656 | the quality of the library implementation depends on, including |
| | 1657 | extensions and "implementation-defined" features; |
| | 1658 | |
| | 1659 | - Plans for required but unimplemented library features and |
| | 1660 | optimizations to them. |
| | 1661 | |
| | 1662 | Overhead |
| | 1663 | -------- |
| | 1664 | |
| | 1665 | The standard defines a large library, much larger than the standard |
| | 1666 | C library. A naive implementation would suffer substantial overhead |
| | 1667 | in compile time, executable size, and speed, rendering it unusable |
| | 1668 | in many (particularly embedded) applications. The alternative demands |
| | 1669 | care in construction, and some compiler support, but there is no |
| | 1670 | need for library subsets. |
| | 1671 | |
| | 1672 | What are the sources of this overhead? There are four main causes: |
| | 1673 | |
| | 1674 | - The library is specified almost entirely as templates, which |
| | 1675 | with current compilers must be included in-line, resulting in |
| | 1676 | very slow builds as tens or hundreds of thousands of lines |
| | 1677 | of function definitions are read for each user source file. |
| | 1678 | Indeed, the entire SGI STL, as well as the dos Reis valarray, |
| | 1679 | are provided purely as header files, largely for simplicity in |
| | 1680 | porting. Iostream/locale is (or will be) as large again. |
| | 1681 | |
| | 1682 | - The library is very flexible, specifying a multitude of hooks |
| | 1683 | where users can insert their own code in place of defaults. |
| | 1684 | When these hooks are not used, any time and code expended to |
| | 1685 | support that flexibility is wasted. |
| | 1686 | |
| | 1687 | - Templates are often described as causing to "code bloat". In |
| | 1688 | practice, this refers (when it refers to anything real) to several |
| | 1689 | independent processes. First, when a class template is manually |
| | 1690 | instantiated in its entirely, current compilers place the definitions |
| | 1691 | for all members in a single object file, so that a program linking |
| | 1692 | to one member gets definitions of all. Second, template functions |
| | 1693 | which do not actually depend on the template argument are, under |
| | 1694 | current compilers, generated anew for each instantiation, rather |
| | 1695 | than being shared with other instantiations. Third, some of the |
| | 1696 | flexibility mentioned above comes from virtual functions (both in |
| | 1697 | regular classes and template classes) which current linkers add |
| | 1698 | to the executable file even when they manifestly cannot be called. |
| | 1699 | |
| | 1700 | - The library is specified to use a language feature, exceptions, |
| | 1701 | which in the current gcc compiler ABI imposes a run time and |
| | 1702 | code space cost to handle the possibility of exceptions even when |
| | 1703 | they are not used. Under the new ABI (accessed with -fnew-abi), |
| | 1704 | there is a space overhead and a small reduction in code efficiency |
| | 1705 | resulting from lost optimization opportunities associated with |
| | 1706 | non-local branches associated with exceptions. |
| | 1707 | |
| | 1708 | What can be done to eliminate this overhead? A variety of coding |
| | 1709 | techniques, and compiler, linker and library improvements and |
| | 1710 | extensions may be used, as covered below. Most are not difficult, |
| | 1711 | and some are already implemented in varying degrees. |
| | 1712 | |
| | 1713 | Overhead: Compilation Time |
| | 1714 | -------------------------- |
| | 1715 | |
| | 1716 | Providing "ready-instantiated" template code in object code archives |
| | 1717 | allows us to avoid generating and optimizing template instantiations |
| | 1718 | in each compilation unit which uses them. However, the number of such |
| | 1719 | instantiations that are useful to provide is limited, and anyway this |
| | 1720 | is not enough, by itself, to minimize compilation time. In particular, |
| | 1721 | it does not reduce time spent parsing conforming headers. |
| | 1722 | |
| | 1723 | Quicker header parsing will depend on library extensions and compiler |
| | 1724 | improvements. One approach is some variation on the techniques |
| | 1725 | previously marketed as "pre-compiled headers", now standardized as |
| | 1726 | support for the "export" keyword. "Exported" template definitions |
| | 1727 | can be placed (once) in a "repository" -- really just a library, but |
| | 1728 | of template definitions rather than object code -- to be drawn upon |
| | 1729 | at link time when an instantiation is needed, rather than placed in |
| | 1730 | header files to be parsed along with every compilation unit. |
| | 1731 | |
| | 1732 | Until "export" is implemented we can put some of the lengthy template |
| | 1733 | definitions in #if guards or alternative headers so that users can skip |
| | 1734 | over the full definitions when they need only the ready-instantiated |
| | 1735 | specializations. |
| | 1736 | |
| | 1737 | To be precise, this means that certain headers which define |
| | 1738 | templates which users normally use only for certain arguments |
| | 1739 | can be instrumented to avoid exposing the template definitions |
| | 1740 | to the compiler unless a macro is defined. For example, in |
| | 1741 | <string>, we might have: |
| | 1742 | |
| | 1743 | template <class _CharT, ... > class basic_string { |
| | 1744 | ... // member declarations |
| | 1745 | }; |
| | 1746 | ... // operator declarations |
| | 1747 | |
| | 1748 | #ifdef _STRICT_ISO_ |
| | 1749 | # if _G_NO_TEMPLATE_EXPORT |
| | 1750 | # include <bits/std_locale.h> // headers needed by definitions |
| | 1751 | # ... |
| | 1752 | # include <bits/string.tcc> // member and global template definitions. |
| | 1753 | # endif |
| | 1754 | #endif |
| | 1755 | |
| | 1756 | Users who compile without specifying a strict-ISO-conforming flag |
| | 1757 | would not see many of the template definitions they now see, and rely |
| | 1758 | instead on ready-instantiated specializations in the library. This |
| | 1759 | technique would be useful for the following substantial components: |
| | 1760 | string, locale/iostreams, valarray. It would *not* be useful or |
| | 1761 | usable with the following: containers, algorithms, iterators, |
| | 1762 | allocator. Since these constitute a large (though decreasing) |
| | 1763 | fraction of the library, the benefit the technique offers is |
| | 1764 | limited. |
| | 1765 | |
| | 1766 | The language specifies the semantics of the "export" keyword, but |
| | 1767 | the gcc compiler does not yet support it. When it does, problems |
| | 1768 | with large template inclusions can largely disappear, given some |
| | 1769 | minor library reorganization, along with the need for the apparatus |
| | 1770 | described above. |
| | 1771 | |
| | 1772 | Overhead: Flexibility Cost |
| | 1773 | -------------------------- |
| | 1774 | |
| | 1775 | The library offers many places where users can specify operations |
| | 1776 | to be performed by the library in place of defaults. Sometimes |
| | 1777 | this seems to require that the library use a more-roundabout, and |
| | 1778 | possibly slower, way to accomplish the default requirements than |
| | 1779 | would be used otherwise. |
| | 1780 | |
| | 1781 | The primary protection against this overhead is thorough compiler |
| | 1782 | optimization, to crush out layers of inline function interfaces. |
| | 1783 | Kuck & Associates has demonstrated the practicality of this kind |
| | 1784 | of optimization. |
| | 1785 | |
| | 1786 | The second line of defense against this overhead is explicit |
| | 1787 | specialization. By defining helper function templates, and writing |
| | 1788 | specialized code for the default case, overhead can be eliminated |
| | 1789 | for that case without sacrificing flexibility. This takes full |
| | 1790 | advantage of any ability of the optimizer to crush out degenerate |
| | 1791 | code. |
| | 1792 | |
| | 1793 | The library specifies many virtual functions which current linkers |
| | 1794 | load even when they cannot be called. Some minor improvements to the |
| | 1795 | compiler and to ld would eliminate any such overhead by simply |
| | 1796 | omitting virtual functions that the complete program does not call. |
| | 1797 | A prototype of this work has already been done. For targets where |
| | 1798 | GNU ld is not used, a "pre-linker" could do the same job. |
| | 1799 | |
| | 1800 | The main areas in the standard interface where user flexibility |
| | 1801 | can result in overhead are: |
| | 1802 | |
| | 1803 | - Allocators: Containers are specified to use user-definable |
| | 1804 | allocator types and objects, making tuning for the container |
| | 1805 | characteristics tricky. |
| | 1806 | |
| | 1807 | - Locales: the standard specifies locale objects used to implement |
| | 1808 | iostream operations, involving many virtual functions which use |
| | 1809 | streambuf iterators. |
| | 1810 | |
| | 1811 | - Algorithms and containers: these may be instantiated on any type, |
| | 1812 | frequently duplicating code for identical operations. |
| | 1813 | |
| | 1814 | - Iostreams and strings: users are permitted to use these on their |
| | 1815 | own types, and specify the operations the stream must use on these |
| | 1816 | types. |
| | 1817 | |
| | 1818 | Note that these sources of overhead are _avoidable_. The techniques |
| | 1819 | to avoid them are covered below. |
| | 1820 | |
| | 1821 | Code Bloat |
| | 1822 | ---------- |
| | 1823 | |
| | 1824 | In the SGI STL, and in some other headers, many of the templates |
| | 1825 | are defined "inline" -- either explicitly or by their placement |
| | 1826 | in class definitions -- which should not be inline. This is a |
| | 1827 | source of code bloat. Matt had remarked that he was relying on |
| | 1828 | the compiler to recognize what was too big to benefit from inlining, |
| | 1829 | and generate it out-of-line automatically. However, this also can |
| | 1830 | result in code bloat except where the linker can eliminate the extra |
| | 1831 | copies. |
| | 1832 | |
| | 1833 | Fixing these cases will require an audit of all inline functions |
| | 1834 | defined in the library to determine which merit inlining, and moving |
| | 1835 | the rest out of line. This is an issue mainly in chapters 23, 25, and |
| | 1836 | 27. Of course it can be done incrementally, and we should generally |
| | 1837 | accept patches that move large functions out of line and into ".tcc" |
| | 1838 | files, which can later be pulled into a repository. Compiler/linker |
| | 1839 | improvements to recognize very large inline functions and move them |
| | 1840 | out-of-line, but shared among compilation units, could make this |
| | 1841 | work unnecessary. |
| | 1842 | |
| | 1843 | Pre-instantiating template specializations currently produces large |
| | 1844 | amounts of dead code which bloats statically linked programs. The |
| | 1845 | current state of the static library, libstdc++.a, is intolerable on |
| | 1846 | this account, and will fuel further confused speculation about a need |
| | 1847 | for a library "subset". A compiler improvement that treats each |
| | 1848 | instantiated function as a separate object file, for linking purposes, |
| | 1849 | would be one solution to this problem. An alternative would be to |
| | 1850 | split up the manual instantiation files into dozens upon dozens of |
| | 1851 | little files, each compiled separately, but an abortive attempt at |
| | 1852 | this was done for <string> and, though it is far from complete, it |
| | 1853 | is already a nuisance. A better interim solution (just until we have |
| | 1854 | "export") is badly needed. |
| | 1855 | |
| | 1856 | When building a shared library, the current compiler/linker cannot |
| | 1857 | automatically generate the instantiations needed. This creates a |
| | 1858 | miserable situation; it means any time something is changed in the |
| | 1859 | library, before a shared library can be built someone must manually |
| | 1860 | copy the declarations of all templates that are needed by other parts |
| | 1861 | of the library to an "instantiation" file, and add it to the build |
| | 1862 | system to be compiled and linked to the library. This process is |
| | 1863 | readily automated, and should be automated as soon as possible. |
| | 1864 | Users building their own shared libraries experience identical |
| | 1865 | frustrations. |
| | 1866 | |
| | 1867 | Sharing common aspects of template definitions among instantiations |
| | 1868 | can radically reduce code bloat. The compiler could help a great |
| | 1869 | deal here by recognizing when a function depends on nothing about |
| | 1870 | a template parameter, or only on its size, and giving the resulting |
| | 1871 | function a link-name "equate" that allows it to be shared with other |
| | 1872 | instantiations. Implementation code could take advantage of the |
| | 1873 | capability by factoring out code that does not depend on the template |
| | 1874 | argument into separate functions to be merged by the compiler. |
| | 1875 | |
| | 1876 | Until such a compiler optimization is implemented, much can be done |
| | 1877 | manually (if tediously) in this direction. One such optimization is |
| | 1878 | to derive class templates from non-template classes, and move as much |
| | 1879 | implementation as possible into the base class. Another is to partial- |
| | 1880 | specialize certain common instantiations, such as vector<T*>, to share |
| | 1881 | code for instantiations on all types T. While these techniques work, |
| | 1882 | they are far from the complete solution that a compiler improvement |
| | 1883 | would afford. |
| | 1884 | |
| | 1885 | Overhead: Expensive Language Features |
| | 1886 | ------------------------------------- |
| | 1887 | |
| | 1888 | The main "expensive" language feature used in the standard library |
| | 1889 | is exception support, which requires compiling in cleanup code with |
| | 1890 | static table data to locate it, and linking in library code to use |
| | 1891 | the table. For small embedded programs the amount of such library |
| | 1892 | code and table data is assumed by some to be excessive. Under the |
| | 1893 | "new" ABI this perception is generally exaggerated, although in some |
| | 1894 | cases it may actually be excessive. |
| | 1895 | |
| | 1896 | To implement a library which does not use exceptions directly is |
| | 1897 | not difficult given minor compiler support (to "turn off" exceptions |
| | 1898 | and ignore exception constructs), and results in no great library |
| | 1899 | maintenance difficulties. To be precise, given "-fno-exceptions", |
| | 1900 | the compiler should treat "try" blocks as ordinary blocks, and |
| | 1901 | "catch" blocks as dead code to ignore or eliminate. Compiler |
| | 1902 | support is not strictly necessary, except in the case of "function |
| | 1903 | try blocks"; otherwise the following macros almost suffice: |
| | 1904 | |
| | 1905 | #define throw(X) |
| | 1906 | #define try if (true) |
| | 1907 | #define catch(X) else if (false) |
| | 1908 | |
| | 1909 | However, there may be a need to use function try blocks in the |
| | 1910 | library implementation, and use of macros in this way can make |
| | 1911 | correct diagnostics impossible. Furthermore, use of this scheme |
| | 1912 | would require the library to call a function to re-throw exceptions |
| | 1913 | from a try block. Implementing the above semantics in the compiler |
| | 1914 | is preferable. |
| | 1915 | |
| | 1916 | Given the support above (however implemented) it only remains to |
| | 1917 | replace code that "throws" with a call to a well-documented "handler" |
| | 1918 | function in a separate compilation unit which may be replaced by |
| | 1919 | the user. The main source of exceptions that would be difficult |
| | 1920 | for users to avoid is memory allocation failures, but users can |
| | 1921 | define their own memory allocation primitives that never throw. |
| | 1922 | Otherwise, the complete list of such handlers, and which library |
| | 1923 | functions may call them, would be needed for users to be able to |
| | 1924 | implement the necessary substitutes. (Fortunately, they have the |
| | 1925 | source code.) |
| | 1926 | |
| | 1927 | Opportunities |
| | 1928 | ------------- |
| | 1929 | |
| | 1930 | The template capabilities of C++ offer enormous opportunities for |
| | 1931 | optimizing common library operations, well beyond what would be |
| | 1932 | considered "eliminating overhead". In particular, many operations |
| | 1933 | done in Glibc with macros that depend on proprietary language |
| | 1934 | extensions can be implemented in pristine Standard C++. For example, |
| | 1935 | the chapter 25 algorithms, and even C library functions such as strchr, |
| | 1936 | can be specialized for the case of static arrays of known (small) size. |
| | 1937 | |
| | 1938 | Detailed optimization opportunities are identified below where |
| | 1939 | the component where they would appear is discussed. Of course new |
| | 1940 | opportunities will be identified during implementation. |
| | 1941 | |
| | 1942 | Unimplemented Required Library Features |
| | 1943 | --------------------------------------- |
| | 1944 | |
| | 1945 | The standard specifies hundreds of components, grouped broadly by |
| | 1946 | chapter. These are listed in excruciating detail in the CHECKLIST |
| | 1947 | file. |
| | 1948 | |
| | 1949 | 17 general |
| | 1950 | 18 support |
| | 1951 | 19 diagnostics |
| | 1952 | 20 utilities |
| | 1953 | 21 string |
| | 1954 | 22 locale |
| | 1955 | 23 containers |
| | 1956 | 24 iterators |
| | 1957 | 25 algorithms |
| | 1958 | 26 numerics |
| | 1959 | 27 iostreams |
| | 1960 | Annex D backward compatibility |
| | 1961 | |
| | 1962 | Anyone participating in implementation of the library should obtain |
| | 1963 | a copy of the standard, ISO 14882. People in the U.S. can obtain an |
| | 1964 | electronic copy for US$18 from ANSI's web site. Those from other |
| | 1965 | countries should visit http://www.iso.org/ to find out the location |
| | 1966 | of their country's representation in ISO, in order to know who can |
| | 1967 | sell them a copy. |
| | 1968 | |
| | 1969 | The emphasis in the following sections is on unimplemented features |
| | 1970 | and optimization opportunities. |
| | 1971 | |
| | 1972 | Chapter 17 General |
| | 1973 | ------------------- |
| | 1974 | |
| | 1975 | Chapter 17 concerns overall library requirements. |
| | 1976 | |
| | 1977 | The standard doesn't mention threads. A multi-thread (MT) extension |
| | 1978 | primarily affects operators new and delete (18), allocator (20), |
| | 1979 | string (21), locale (22), and iostreams (27). The common underlying |
| | 1980 | support needed for this is discussed under chapter 20. |
| | 1981 | |
| | 1982 | The standard requirements on names from the C headers create a |
| | 1983 | lot of work, mostly done. Names in the C headers must be visible |
| | 1984 | in the std:: and sometimes the global namespace; the names in the |
| | 1985 | two scopes must refer to the same object. More stringent is that |
| | 1986 | Koenig lookup implies that any types specified as defined in std:: |
| | 1987 | really are defined in std::. Names optionally implemented as |
| | 1988 | macros in C cannot be macros in C++. (An overview may be read at |
| | 1989 | <http://www.cantrip.org/cheaders.html>). The scripts "inclosure" |
| | 1990 | and "mkcshadow", and the directories shadow/ and cshadow/, are the |
| | 1991 | beginning of an effort to conform in this area. |
| | 1992 | |
| | 1993 | A correct conforming definition of C header names based on underlying |
| | 1994 | C library headers, and practical linking of conforming namespaced |
| | 1995 | customer code with third-party C libraries depends ultimately on |
| | 1996 | an ABI change, allowing namespaced C type names to be mangled into |
| | 1997 | type names as if they were global, somewhat as C function names in a |
| | 1998 | namespace, or C++ global variable names, are left unmangled. Perhaps |
| | 1999 | another "extern" mode, such as 'extern "C-global"' would be an |
| | 2000 | appropriate place for such type definitions. Such a type would |
| | 2001 | affect mangling as follows: |
| | 2002 | |
| | 2003 | namespace A { |
| | 2004 | struct X {}; |
| | 2005 | extern "C-global" { // or maybe just 'extern "C"' |
| | 2006 | struct Y {}; |
| | 2007 | }; |
| | 2008 | } |
| | 2009 | void f(A::X*); // mangles to f__FPQ21A1X |
| | 2010 | void f(A::Y*); // mangles to f__FP1Y |
| | 2011 | |
| | 2012 | (It may be that this is really the appropriate semantics for regular |
| | 2013 | 'extern "C"', and 'extern "C-global"', as an extension, would not be |
| | 2014 | necessary.) This would allow functions declared in non-standard C headers |
| | 2015 | (and thus fixable by neither us nor users) to link properly with functions |
| | 2016 | declared using C types defined in properly-namespaced headers. The |
| | 2017 | problem this solves is that C headers (which C++ programmers do persist |
| | 2018 | in using) frequently forward-declare C struct tags without including |
| | 2019 | the header where the type is defined, as in |
| | 2020 | |
| | 2021 | struct tm; |
| | 2022 | void munge(tm*); |
| | 2023 | |
| | 2024 | Without some compiler accommodation, munge cannot be called by correct |
| | 2025 | C++ code using a pointer to a correctly-scoped tm* value. |
| | 2026 | |
| | 2027 | The current C headers use the preprocessor extension "#include_next", |
| | 2028 | which the compiler complains about when run "-pedantic". |
| | 2029 | (Incidentally, it appears that "-fpedantic" is currently ignored, |
| | 2030 | probably a bug.) The solution in the C compiler is to use |
| | 2031 | "-isystem" rather than "-I", but unfortunately in g++ this seems |
| | 2032 | also to wrap the whole header in an 'extern "C"' block, so it's |
| | 2033 | unusable for C++ headers. The correct solution appears to be to |
| | 2034 | allow the various special include-directory options, if not given |
| | 2035 | an argument, to affect subsequent include-directory options additively, |
| | 2036 | so that if one said |
| | 2037 | |
| | 2038 | -pedantic -iprefix $(prefix) \ |
| | 2039 | -idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \ |
| | 2040 | -iwithprefix -I g++-v3/ext |
| | 2041 | |
| | 2042 | the compiler would search $(prefix)/g++-v3 and not report |
| | 2043 | pedantic warnings for files found there, but treat files in |
| | 2044 | $(prefix)/g++-v3/ext pedantically. (The undocumented semantics |
| | 2045 | of "-isystem" in g++ stink. Can they be rescinded? If not it |
| | 2046 | must be replaced with something more rationally behaved.) |
| | 2047 | |
| | 2048 | All the C headers need the treatment above; in the standard these |
| | 2049 | headers are mentioned in various chapters. Below, I have only |
| | 2050 | mentioned those that present interesting implementation issues. |
| | 2051 | |
| | 2052 | The components identified as "mostly complete", below, have not been |
| | 2053 | audited for conformance. In many cases where the library passes |
| | 2054 | conformance tests we have non-conforming extensions that must be |
| | 2055 | wrapped in #if guards for "pedantic" use, and in some cases renamed |
| | 2056 | in a conforming way for continued use in the implementation regardless |
| | 2057 | of conformance flags. |
| | 2058 | |
| | 2059 | The STL portion of the library still depends on a header |
| | 2060 | stl/bits/stl_config.h full of #ifdef clauses. This apparatus |
| | 2061 | should be replaced with autoconf/automake machinery. |
| | 2062 | |
| | 2063 | The SGI STL defines a type_traits<> template, specialized for |
| | 2064 | many types in their code including the built-in numeric and |
| | 2065 | pointer types and some library types, to direct optimizations of |
| | 2066 | standard functions. The SGI compiler has been extended to generate |
| | 2067 | specializations of this template automatically for user types, |
| | 2068 | so that use of STL templates on user types can take advantage of |
| | 2069 | these optimizations. Specializations for other, non-STL, types |
| | 2070 | would make more optimizations possible, but extending the gcc |
| | 2071 | compiler in the same way would be much better. Probably the next |
| | 2072 | round of standardization will ratify this, but probably with |
| | 2073 | changes, so it probably should be renamed to place it in the |
| | 2074 | implementation namespace. |
| | 2075 | |
| | 2076 | The SGI STL also defines a large number of extensions visible in |
| | 2077 | standard headers. (Other extensions that appear in separate headers |
| | 2078 | have been sequestered in subdirectories ext/ and backward/.) All |
| | 2079 | these extensions should be moved to other headers where possible, |
| | 2080 | and in any case wrapped in a namespace (not std!), and (where kept |
| | 2081 | in a standard header) girded about with macro guards. Some cannot be |
| | 2082 | moved out of standard headers because they are used to implement |
| | 2083 | standard features. The canonical method for accommodating these |
| | 2084 | is to use a protected name, aliased in macro guards to a user-space |
| | 2085 | name. Unfortunately C++ offers no satisfactory template typedef |
| | 2086 | mechanism, so very ad-hoc and unsatisfactory aliasing must be used |
| | 2087 | instead. |
| | 2088 | |
| | 2089 | Implementation of a template typedef mechanism should have the highest |
| | 2090 | priority among possible extensions, on the same level as implementation |
| | 2091 | of the template "export" feature. |
| | 2092 | |
| | 2093 | Chapter 18 Language support |
| | 2094 | ---------------------------- |
| | 2095 | |
| | 2096 | Headers: <limits> <new> <typeinfo> <exception> |
| | 2097 | C headers: <cstddef> <climits> <cfloat> <cstdarg> <csetjmp> |
| | 2098 | <ctime> <csignal> <cstdlib> (also 21, 25, 26) |
| | 2099 | |
| | 2100 | This defines the built-in exceptions, rtti, numeric_limits<>, |
| | 2101 | operator new and delete. Much of this is provided by the |
| | 2102 | compiler in its static runtime library. |
| | 2103 | |
| | 2104 | Work to do includes defining numeric_limits<> specializations in |
| | 2105 | separate files for all target architectures. Values for integer types |
| | 2106 | except for bool and wchar_t are readily obtained from the C header |
| | 2107 | <limits.h>, but values for the remaining numeric types (bool, wchar_t, |
| | 2108 | float, double, long double) must be entered manually. This is |
| | 2109 | largely dog work except for those members whose values are not |
| | 2110 | easily deduced from available documentation. Also, this involves |
| | 2111 | some work in target configuration to identify the correct choice of |
| | 2112 | file to build against and to install. |
| | 2113 | |
| | 2114 | The definitions of the various operators new and delete must be |
| | 2115 | made thread-safe, which depends on a portable exclusion mechanism, |
| | 2116 | discussed under chapter 20. Of course there is always plenty of |
| | 2117 | room for improvements to the speed of operators new and delete. |
| | 2118 | |
| | 2119 | <cstdarg>, in Glibc, defines some macros that gcc does not allow to |
| | 2120 | be wrapped into an inline function. Probably this header will demand |
| | 2121 | attention whenever a new target is chosen. The functions atexit(), |
| | 2122 | exit(), and abort() in cstdlib have different semantics in C++, so |
| | 2123 | must be re-implemented for C++. |
| | 2124 | |
| | 2125 | Chapter 19 Diagnostics |
| | 2126 | ----------------------- |
| | 2127 | |
| | 2128 | Headers: <stdexcept> |
| | 2129 | C headers: <cassert> <cerrno> |
| | 2130 | |
| | 2131 | This defines the standard exception objects, which are "mostly complete". |
| | 2132 | Cygnus has a version, and now SGI provides a slightly different one. |
| | 2133 | It makes little difference which we use. |
| | 2134 | |
| | 2135 | The C global name "errno", which C allows to be a variable or a macro, |
| | 2136 | is required in C++ to be a macro. For MT it must typically result in |
| | 2137 | a function call. |
| | 2138 | |
| | 2139 | Chapter 20 Utilities |
| | 2140 | --------------------- |
| | 2141 | Headers: <utility> <functional> <memory> |
| | 2142 | C header: <ctime> (also in 18) |
| | 2143 | |
| | 2144 | SGI STL provides "mostly complete" versions of all the components |
| | 2145 | defined in this chapter. However, the auto_ptr<> implementation |
| | 2146 | is known to be wrong. Furthermore, the standard definition of it |
| | 2147 | is known to be unimplementable as written. A minor change to the |
| | 2148 | standard would fix it, and auto_ptr<> should be adjusted to match. |
| | 2149 | |
| | 2150 | Multi-threading affects the allocator implementation, and there must |
| | 2151 | be configuration/installation choices for different users' MT |
| | 2152 | requirements. Anyway, users will want to tune allocator options |
| | 2153 | to support different target conditions, MT or no. |
| | 2154 | |
| | 2155 | The primitives used for MT implementation should be exposed, as an |
| | 2156 | extension, for users' own work. We need cross-CPU "mutex" support, |
| | 2157 | multi-processor shared-memory atomic integer operations, and single- |
| | 2158 | processor uninterruptible integer operations, and all three configurable |
| | 2159 | to be stubbed out for non-MT use, or to use an appropriately-loaded |
| | 2160 | dynamic library for the actual runtime environment, or statically |
| | 2161 | compiled in for cases where the target architecture is known. |
| | 2162 | |
| | 2163 | Chapter 21 String |
| | 2164 | ------------------ |
| | 2165 | Headers: <string> |
| | 2166 | C headers: <cctype> <cwctype> <cstring> <cwchar> (also in 27) |
| | 2167 | <cstdlib> (also in 18, 25, 26) |
| | 2168 | |
| | 2169 | We have "mostly-complete" char_traits<> implementations. Many of the |
| | 2170 | char_traits<char> operations might be optimized further using existing |
| | 2171 | proprietary language extensions. |
| | 2172 | |
| | 2173 | We have a "mostly-complete" basic_string<> implementation. The work |
| | 2174 | to manually instantiate char and wchar_t specializations in object |
| | 2175 | files to improve link-time behavior is extremely unsatisfactory, |
| | 2176 | literally tripling library-build time with no commensurate improvement |
| | 2177 | in static program link sizes. It must be redone. (Similar work is |
| | 2178 | needed for some components in chapters 22 and 27.) |
| | 2179 | |
| | 2180 | Other work needed for strings is MT-safety, as discussed under the |
| | 2181 | chapter 20 heading. |
| | 2182 | |
| | 2183 | The standard C type mbstate_t from <cwchar> and used in char_traits<> |
| | 2184 | must be different in C++ than in C, because in C++ the default constructor |
| | 2185 | value mbstate_t() must be the "base" or "ground" sequence state. |
| | 2186 | (According to the likely resolution of a recently raised Core issue, |
| | 2187 | this may become unnecessary. However, there are other reasons to |
| | 2188 | use a state type not as limited as whatever the C library provides.) |
| | 2189 | If we might want to provide conversions from (e.g.) internally- |
| | 2190 | represented EUC-wide to externally-represented Unicode, or vice- |
| | 2191 | versa, the mbstate_t we choose will need to be more accommodating |
| | 2192 | than what might be provided by an underlying C library. |
| | 2193 | |
| | 2194 | There remain some basic_string template-member functions which do |
| | 2195 | not overload properly with their non-template brethren. The infamous |
| | 2196 | hack akin to what was done in vector<> is needed, to conform to |
| | 2197 | 23.1.1 para 10. The CHECKLIST items for basic_string marked 'X', |
| | 2198 | or incomplete, are so marked for this reason. |
| | 2199 | |
| | 2200 | Replacing the string iterators, which currently are simple character |
| | 2201 | pointers, with class objects would greatly increase the safety of the |
| | 2202 | client interface, and also permit a "debug" mode in which range, |
| | 2203 | ownership, and validity are rigorously checked. The current use of |
| | 2204 | raw pointers as string iterators is evil. vector<> iterators need the |
| | 2205 | same treatment. Note that the current implementation freely mixes |
| | 2206 | pointers and iterators, and that must be fixed before safer iterators |
| | 2207 | can be introduced. |
| | 2208 | |
| | 2209 | Some of the functions in <cstring> are different from the C version. |
| | 2210 | generally overloaded on const and non-const argument pointers. For |
| | 2211 | example, in <cstring> strchr is overloaded. The functions isupper |
| | 2212 | etc. in <cctype> typically implemented as macros in C are functions |
| | 2213 | in C++, because they are overloaded with others of the same name |
| | 2214 | defined in <locale>. |
| | 2215 | |
| | 2216 | Many of the functions required in <cwctype> and <cwchar> cannot be |
| | 2217 | implemented using underlying C facilities on intended targets because |
| | 2218 | such facilities only partly exist. |
| | 2219 | |
| | 2220 | Chapter 22 Locale |
| | 2221 | ------------------ |
| | 2222 | Headers: <locale> |
| | 2223 | C headers: <clocale> |
| | 2224 | |
| | 2225 | We have a "mostly complete" class locale, with the exception of |
| | 2226 | code for constructing, and handling the names of, named locales. |
| | 2227 | The ways that locales are named (particularly when categories |
| | 2228 | (e.g. LC_TIME, LC_COLLATE) are different) varies among all target |
| | 2229 | environments. This code must be written in various versions and |
| | 2230 | chosen by configuration parameters. |
| | 2231 | |
| | 2232 | Members of many of the facets defined in <locale> are stubs. Generally, |
| | 2233 | there are two sets of facets: the base class facets (which are supposed |
| | 2234 | to implement the "C" locale) and the "byname" facets, which are supposed |
| | 2235 | to read files to determine their behavior. The base ctype<>, collate<>, |
| | 2236 | and numpunct<> facets are "mostly complete", except that the table of |
| | 2237 | bitmask values used for "is" operations, and corresponding mask values, |
| | 2238 | are still defined in libio and just included/linked. (We will need to |
| | 2239 | implement these tables independently, soon, but should take advantage |
| | 2240 | of libio where possible.) The num_put<>::put members for integer types |
| | 2241 | are "mostly complete". |
| | 2242 | |
| | 2243 | A complete list of what has and has not been implemented may be |
| | 2244 | found in CHECKLIST. However, note that the current definition of |
| | 2245 | codecvt<wchar_t,char,mbstate_t> is wrong. It should simply write |
| | 2246 | out the raw bytes representing the wide characters, rather than |
| | 2247 | trying to convert each to a corresponding single "char" value. |
| | 2248 | |
| | 2249 | Some of the facets are more important than others. Specifically, |
| | 2250 | the members of ctype<>, numpunct<>, num_put<>, and num_get<> facets |
| | 2251 | are used by other library facilities defined in <string>, <istream>, |
| | 2252 | and <ostream>, and the codecvt<> facet is used by basic_filebuf<> |
| | 2253 | in <fstream>, so a conforming iostream implementation depends on |
| | 2254 | these. |
| | 2255 | |
| | 2256 | The "long long" type eventually must be supported, but code mentioning |
| | 2257 | it should be wrapped in #if guards to allow pedantic-mode compiling. |
| | 2258 | |
| | 2259 | Performance of num_put<> and num_get<> depend critically on |
| | 2260 | caching computed values in ios_base objects, and on extensions |
| | 2261 | to the interface with streambufs. |
| | 2262 | |
| | 2263 | Specifically: retrieving a copy of the locale object, extracting |
| | 2264 | the needed facets, and gathering data from them, for each call to |
| | 2265 | (e.g.) operator<< would be prohibitively slow. To cache format |
| | 2266 | data for use by num_put<> and num_get<> we have a _Format_cache<> |
| | 2267 | object stored in the ios_base::pword() array. This is constructed |
| | 2268 | and initialized lazily, and is organized purely for utility. It |
| | 2269 | is discarded when a new locale with different facets is imbued. |
| | 2270 | |
| | 2271 | Using only the public interfaces of the iterator arguments to the |
| | 2272 | facet functions would limit performance by forbidding "vector-style" |
| | 2273 | character operations. The streambuf iterator optimizations are |
| | 2274 | described under chapter 24, but facets can also bypass the streambuf |
| | 2275 | iterators via explicit specializations and operate directly on the |
| | 2276 | streambufs, and use extended interfaces to get direct access to the |
| | 2277 | streambuf internal buffer arrays. These extensions are mentioned |
| | 2278 | under chapter 27. These optimizations are particularly important |
| | 2279 | for input parsing. |
| | 2280 | |
| | 2281 | Unused virtual members of locale facets can be omitted, as mentioned |
| | 2282 | above, by a smart linker. |
| | 2283 | |
| | 2284 | Chapter 23 Containers |
| | 2285 | ---------------------- |
| | 2286 | Headers: <deque> <list> <queue> <stack> <vector> <map> <set> <bitset> |
| | 2287 | |
| | 2288 | All the components in chapter 23 are implemented in the SGI STL. |
| | 2289 | They are "mostly complete"; they include a large number of |
| | 2290 | nonconforming extensions which must be wrapped. Some of these |
| | 2291 | are used internally and must be renamed or duplicated. |
| | 2292 | |
| | 2293 | The SGI components are optimized for large-memory environments. For |
| | 2294 | embedded targets, different criteria might be more appropriate. Users |
| | 2295 | will want to be able to tune this behavior. We should provide |
| | 2296 | ways for users to compile the library with different memory usage |
| | 2297 | characteristics. |
| | 2298 | |
| | 2299 | A lot more work is needed on factoring out common code from different |
| | 2300 | specializations to reduce code size here and in chapter 25. The |
| | 2301 | easiest fix for this would be a compiler/ABI improvement that allows |
| | 2302 | the compiler to recognize when a specialization depends only on the |
| | 2303 | size (or other gross quality) of a template argument, and allow the |
| | 2304 | linker to share the code with similar specializations. In its |
| | 2305 | absence, many of the algorithms and containers can be partial- |
| | 2306 | specialized, at least for the case of pointers, but this only solves |
| | 2307 | a small part of the problem. Use of a type_traits-style template |
| | 2308 | allows a few more optimization opportunities, more if the compiler |
| | 2309 | can generate the specializations automatically. |
| | 2310 | |
| | 2311 | As an optimization, containers can specialize on the default allocator |
| | 2312 | and bypass it, or take advantage of details of its implementation |
| | 2313 | after it has been improved upon. |
| | 2314 | |
| | 2315 | Replacing the vector iterators, which currently are simple element |
| | 2316 | pointers, with class objects would greatly increase the safety of the |
| | 2317 | client interface, and also permit a "debug" mode in which range, |
| | 2318 | ownership, and validity are rigorously checked. The current use of |
| | 2319 | pointers for iterators is evil. |
| | 2320 | |
| | 2321 | As mentioned for chapter 24, the deque iterator is a good example of |
| | 2322 | an opportunity to implement a "staged" iterator that would benefit |
| | 2323 | from specializations of some algorithms. |
| | 2324 | |
| | 2325 | Chapter 24 Iterators |
| | 2326 | --------------------- |
| | 2327 | Headers: <iterator> |
| | 2328 | |
| | 2329 | Standard iterators are "mostly complete", with the exception of |
| | 2330 | the stream iterators, which are not yet templatized on the |
| | 2331 | stream type. Also, the base class template iterator<> appears |
| | 2332 | to be wrong, so everything derived from it must also be wrong, |
| | 2333 | currently. |
| | 2334 | |
| | 2335 | The streambuf iterators (currently located in stl/bits/std_iterator.h, |
| | 2336 | but should be under bits/) can be rewritten to take advantage of |
| | 2337 | friendship with the streambuf implementation. |
| | 2338 | |
| | 2339 | Matt Austern has identified opportunities where certain iterator |
| | 2340 | types, particularly including streambuf iterators and deque |
| | 2341 | iterators, have a "two-stage" quality, such that an intermediate |
| | 2342 | limit can be checked much more quickly than the true limit on |
| | 2343 | range operations. If identified with a member of iterator_traits, |
| | 2344 | algorithms may be specialized for this case. Of course the |
| | 2345 | iterators that have this quality can be identified by specializing |
| | 2346 | a traits class. |
| | 2347 | |
| | 2348 | Many of the algorithms must be specialized for the streambuf |
| | 2349 | iterators, to take advantage of block-mode operations, in order |
| | 2350 | to allow iostream/locale operations' performance not to suffer. |
| | 2351 | It may be that they could be treated as staged iterators and |
| | 2352 | take advantage of those optimizations. |
| | 2353 | |
| | 2354 | Chapter 25 Algorithms |
| | 2355 | ---------------------- |
| | 2356 | Headers: <algorithm> |
| | 2357 | C headers: <cstdlib> (also in 18, 21, 26)) |
| | 2358 | |
| | 2359 | The algorithms are "mostly complete". As mentioned above, they |
| | 2360 | are optimized for speed at the expense of code and data size. |
| | 2361 | |
| | 2362 | Specializations of many of the algorithms for non-STL types would |
| | 2363 | give performance improvements, but we must use great care not to |
| | 2364 | interfere with fragile template overloading semantics for the |
| | 2365 | standard interfaces. Conventionally the standard function template |
| | 2366 | interface is an inline which delegates to a non-standard function |
| | 2367 | which is then overloaded (this is already done in many places in |
| | 2368 | the library). Particularly appealing opportunities for the sake of |
| | 2369 | iostream performance are for copy and find applied to streambuf |
| | 2370 | iterators or (as noted elsewhere) for staged iterators, of which |
| | 2371 | the streambuf iterators are a good example. |
| | 2372 | |
| | 2373 | The bsearch and qsort functions cannot be overloaded properly as |
| | 2374 | required by the standard because gcc does not yet allow overloading |
| | 2375 | on the extern-"C"-ness of a function pointer. |
| | 2376 | |
| | 2377 | Chapter 26 Numerics |
| | 2378 | -------------------- |
| | 2379 | Headers: <complex> <valarray> <numeric> |
| | 2380 | C headers: <cmath>, <cstdlib> (also 18, 21, 25) |
| | 2381 | |
| | 2382 | Numeric components: Gabriel dos Reis's valarray, Drepper's complex, |
| | 2383 | and the few algorithms from the STL are "mostly done". Of course |
| | 2384 | optimization opportunities abound for the numerically literate. It |
| | 2385 | is not clear whether the valarray implementation really conforms |
| | 2386 | fully, in the assumptions it makes about aliasing (and lack thereof) |
| | 2387 | in its arguments. |
| | 2388 | |
| | 2389 | The C div() and ldiv() functions are interesting, because they are the |
| | 2390 | only case where a C library function returns a class object by value. |
| | 2391 | Since the C++ type div_t must be different from the underlying C type |
| | 2392 | (which is in the wrong namespace) the underlying functions div() and |
| | 2393 | ldiv() cannot be re-used efficiently. Fortunately they are trivial to |
| | 2394 | re-implement. |
| | 2395 | |
| | 2396 | Chapter 27 Iostreams |
| | 2397 | --------------------- |
| | 2398 | Headers: <iosfwd> <streambuf> <ios> <ostream> <istream> <iostream> |
| | 2399 | <iomanip> <sstream> <fstream> |
| | 2400 | C headers: <cstdio> <cwchar> (also in 21) |
| | 2401 | |
| | 2402 | Iostream is currently in a very incomplete state. <iosfwd>, <iomanip>, |
| | 2403 | ios_base, and basic_ios<> are "mostly complete". basic_streambuf<> and |
| | 2404 | basic_ostream<> are well along, but basic_istream<> has had little work |
| | 2405 | done. The standard stream objects, <sstream> and <fstream> have been |
| | 2406 | started; basic_filebuf<> "write" functions have been implemented just |
| | 2407 | enough to do "hello, world". |
| | 2408 | |
| | 2409 | Most of the istream and ostream operators << and >> (with the exception |
| | 2410 | of the op<<(integer) ones) have not been changed to use locale primitives, |
| | 2411 | sentry objects, or char_traits members. |
| | 2412 | |
| | 2413 | All these templates should be manually instantiated for char and |
| | 2414 | wchar_t in a way that links only used members into user programs. |
| | 2415 | |
| | 2416 | Streambuf is fertile ground for optimization extensions. An extended |
| | 2417 | interface giving iterator access to its internal buffer would be very |
| | 2418 | useful for other library components. |
| | 2419 | |
| | 2420 | Iostream operations (primarily operators << and >>) can take advantage |
| | 2421 | of the case where user code has not specified a locale, and bypass locale |
| | 2422 | operations entirely. The current implementation of op<</num_put<>::put, |
| | 2423 | for the integer types, demonstrates how they can cache encoding details |
| | 2424 | from the locale on each operation. There is lots more room for |
| | 2425 | optimization in this area. |
| | 2426 | |
| | 2427 | The definition of the relationship between the standard streams |
| | 2428 | cout et al. and stdout et al. requires something like a "stdiobuf". |
| | 2429 | The SGI solution of using double-indirection to actually use a |
| | 2430 | stdio FILE object for buffering is unsatisfactory, because it |
| | 2431 | interferes with peephole loop optimizations. |
| | 2432 | |
| | 2433 | The <sstream> header work has begun. stringbuf can benefit from |
| | 2434 | friendship with basic_string<> and basic_string<>::_Rep to use |
| | 2435 | those objects directly as buffers, and avoid allocating and making |
| | 2436 | copies. |
| | 2437 | |
| | 2438 | The basic_filebuf<> template is a complex beast. It is specified to |
| | 2439 | use the locale facet codecvt<> to translate characters between native |
| | 2440 | files and the locale character encoding. In general this involves |
| | 2441 | two buffers, one of "char" representing the file and another of |
| | 2442 | "char_type", for the stream, with codecvt<> translating. The process |
| | 2443 | is complicated by the variable-length nature of the translation, and |
| | 2444 | the need to seek to corresponding places in the two representations. |
| | 2445 | For the case of basic_filebuf<char>, when no translation is needed, |
| | 2446 | a single buffer suffices. A specialized filebuf can be used to reduce |
| | 2447 | code space overhead when no locale has been imbued. Matt Austern's |
| | 2448 | work at SGI will be useful, perhaps directly as a source of code, or |
| | 2449 | at least as an example to draw on. |
| | 2450 | |
| | 2451 | Filebuf, almost uniquely (cf. operator new), depends heavily on |
| | 2452 | underlying environmental facilities. In current releases iostream |
| | 2453 | depends fairly heavily on libio constant definitions, but it should |
| | 2454 | be made independent. It also depends on operating system primitives |
| | 2455 | for file operations. There is immense room for optimizations using |
| | 2456 | (e.g.) mmap for reading. The shadow/ directory wraps, besides the |
| | 2457 | standard C headers, the libio.h and unistd.h headers, for use mainly |
| | 2458 | by filebuf. These wrappings have not been completed, though there |
| | 2459 | is scaffolding in place. |
| | 2460 | |
| | 2461 | The encapsulation of certain C header <cstdio> names presents an |
| | 2462 | interesting problem. It is possible to define an inline std::fprintf() |
| | 2463 | implemented in terms of the 'extern "C"' vfprintf(), but there is no |
| | 2464 | standard vfscanf() to use to implement std::fscanf(). It appears that |
| | 2465 | vfscanf but be re-implemented in C++ for targets where no vfscanf |
| | 2466 | extension has been defined. This is interesting in that it seems |
| | 2467 | to be the only significant case in the C library where this kind of |
| | 2468 | rewriting is necessary. (Of course Glibc provides the vfscanf() |
| | 2469 | extension.) (The functions related to exit() must be rewritten |
| | 2470 | for other reasons.) |
| | 2471 | |
| | 2472 | |
| | 2473 | Annex D |
| | 2474 | ------- |
| | 2475 | Headers: <strstream> |
| | 2476 | |
| | 2477 | Annex D defines many non-library features, and many minor |
| | 2478 | modifications to various headers, and a complete header. |
| | 2479 | It is "mostly done", except that the libstdc++-2 <strstream> |
| | 2480 | header has not been adopted into the library, or checked to |
| | 2481 | verify that it matches the draft in those details that were |
| | 2482 | clarified by the committee. Certainly it must at least be |
| | 2483 | moved into the std namespace. |
| | 2484 | |
| | 2485 | We still need to wrap all the deprecated features in #if guards |
| | 2486 | so that pedantic compile modes can detect their use. |
| | 2487 | |
| | 2488 | Nonstandard Extensions |
| | 2489 | ---------------------- |
| | 2490 | Headers: <iostream.h> <strstream.h> <hash> <rbtree> |
| | 2491 | <pthread_alloc> <stdiobuf> (etc.) |
| | 2492 | |
| | 2493 | User code has come to depend on a variety of nonstandard components |
| | 2494 | that we must not omit. Much of this code can be adopted from |
| | 2495 | libstdc++-v2 or from the SGI STL. This particularly includes |
| | 2496 | <iostream.h>, <strstream.h>, and various SGI extensions such |
| | 2497 | as <hash_map.h>. Many of these are already placed in the |
| | 2498 | subdirectories ext/ and backward/. (Note that it is better to |
| | 2499 | include them via "<backward/hash_map.h>" or "<ext/hash_map>" than |
| | 2500 | to search the subdirectory itself via a "-I" directive. |
| | 2501 | </literallayout> |
| | 2502 | </sect1> |
| | 2503 | |
| | 2504 | </appendix> |
projects / thirdparty / gcc.git / blame_incremental