diff options
| author | Benjamin Kosnik <bkoz@redhat.com> | 2008-02-12 02:10:57 +0000 |
|---|---|---|
| committer | Benjamin Kosnik <bkoz@gcc.gnu.org> | 2008-02-12 02:10:57 +0000 |
| commit | c9024a78a93bd19d869f1bd3bb1fdfcc2e540aea (patch) | |
| tree | 030b0bdfc01e0373e710b7f8d33b88d672e88897 | |
| parent | 42d572f5a317cd6f19054e2c9aafad4dc4c96419 (diff) | |
| download | gcc-c9024a78a93bd19d869f1bd3bb1fdfcc2e540aea.zip gcc-c9024a78a93bd19d869f1bd3bb1fdfcc2e540aea.tar.gz gcc-c9024a78a93bd19d869f1bd3bb1fdfcc2e540aea.tar.bz2 | |
mainpage.html: Add in corrected links.
2008-02-11 Benjamin Kosnik <bkoz@redhat.com>
* doc/doxygen/mainpage.html: Add in corrected links.
* README: Edit, move most into...
* doc/xml/manual/appendix_contributing.xml (Directory Layout): ...here.
(Documentation Style): Revise.
* doc/xml/spine.xml: Edit file names.
* doc/Makefile.am: Edit xml_sources.
* doc/Makefile.in: Regenerate.
From-SVN: r132249
| -rw-r--r-- | libstdc++-v3/ChangeLog | 10 | ||||
| -rw-r--r-- | libstdc++-v3/README | 92 | ||||
| -rw-r--r-- | libstdc++-v3/doc/Makefile.am | 3 | ||||
| -rw-r--r-- | libstdc++-v3/doc/Makefile.in | 3 | ||||
| -rw-r--r-- | libstdc++-v3/doc/doxygen/mainpage.html | 16 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/appendix_contributing.xml | 3563 | ||||
| -rw-r--r-- | libstdc++-v3/doc/xml/spine.xml | 4 |
7 files changed, 1955 insertions, 1736 deletions
diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 058efef..6d616d2 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,13 @@ +2008-02-11 Benjamin Kosnik <bkoz@redhat.com> + + * doc/doxygen/mainpage.html: Add in corrected links. + * README: Edit, move most into... + * doc/xml/manual/appendix_contributing.xml (Directory Layout): ...here. + (Documentation Style): Revise. + * doc/xml/spine.xml: Edit file names. + * doc/Makefile.am: Edit xml_sources. + * doc/Makefile.in: Regenerate. + 2008-02-11 Paolo Carlini <pcarlini@suse.de> * configure: Regenerate with documented autoconf and automake diff --git a/libstdc++-v3/README b/libstdc++-v3/README index 1064095..2651ec4 100644 --- a/libstdc++-v3/README +++ b/libstdc++-v3/README @@ -1,96 +1,6 @@ file: libstdc++-v3/README New users may wish to point their web browsers to the file -documentation.html in the 'docs/html' subdirectory. It contains brief +index.html in the 'doc/html' subdirectory. It contains brief building instructions and notes on how to configure the library in interesting ways. - -Instructions for configuring and building appear in -docs/html/install.html. - -This directory contains the files needed to create an ISO Standard C++ -Library. - -It has subdirectories: - - docs - Files in HTML and text format that document usage, quirks of the - implementation, and contributor checklists. - - include - All header files for the C++ library are within this directory, - modulo specific runtime-related files that are in the libsupc++ - directory. - - include/std - Files meant to be found by #include <name> directives in - standard-conforming user programs. - - include/c - Headers intended to directly include standard C headers. - [NB: this can be enabled via --enable-cheaders=c] - - include/c_std - Headers intended to include standard C headers, and put select - names into the std:: namespace. - [NB: this is the default, and is the same as --enable-cheaders=c_std] - - include/bits - Files included by standard headers and by other files in - the bits directory. - - include/backward - Headers provided for backward compatibility, such as <iostream.h>. - They are not used in this library. - - include/ext - Headers that define extensions to the standard library. No - standard header refers to any of them. - - scripts - Scripts that are used during the configure, build, make, or test - process. - - src - Files that are used in constructing the library, but are not - installed. - - testsuites/[backward, demangle, ext, performance, thread, 17_* to 27_*] - Test programs are here, and may be used to begin to exercise the - library. Support for "make check" and "make check-install" is - complete, and runs through all the subdirectories here when this - command is issued from the build directory. Please note that - "make check" requires DejaGNU 1.4 or later to be installed. Please - note that "make check-script" calls the script mkcheck, which - requires bash, and which may need the paths to bash adjusted to - work properly, as /bin/bash is assumed. - -Other subdirectories contain variant versions of certain files -that are meant to be copied or linked by the configure script. -Currently these are: - - config/abi - config/cpu - config/io - config/locale - config/os - -In addition, two subdirectories are convenience libraries: - - libmath - Support routines needed for C++ math. Only needed if the - underlying "C" implementation is non-existent, in particular - required or optimal long double, long long, and C99 functionality. - - libsupc++ - Contains the runtime library for C++, including exception - handling and memory allocation and deallocation, RTTI, terminate - handlers, etc. - -Note that glibc also has a bits/ subdirectory. We will either -need to be careful not to collide with names in its bits/ -directory; or rename bits to (e.g.) cppbits/. - -In files throughout the system, lines marked with an "XXX" indicate -a bug or incompletely-implemented feature. Lines marked "XXX MT" -indicate a place that may require attention for multi-thread safety. diff --git a/libstdc++-v3/doc/Makefile.am b/libstdc++-v3/doc/Makefile.am index 926ceec..8f50008 100644 --- a/libstdc++-v3/doc/Makefile.am +++ b/libstdc++-v3/doc/Makefile.am @@ -73,7 +73,6 @@ xml_srcdir = ${glibcxx_srcdir}/doc/xml xml_sources = \ ${xml_srcdir}/spine.xml \ ${xml_srcdir}/authors.xml \ - ${xml_srcdir}/manual/spine.xml \ ${xml_srcdir}/manual/abi.xml \ ${xml_srcdir}/manual/algorithms.xml \ ${xml_srcdir}/manual/allocator.xml \ @@ -186,7 +185,7 @@ doc-fo: $(xml_sources) ${glibcxx_builddir}/doc/fo # PDF # Points to current best xml to PDF generation process. -doc-pdf: doc-pdf-xmlto +doc-pdf: doc-pdf-prince # PDF 1 # fop diff --git a/libstdc++-v3/doc/Makefile.in b/libstdc++-v3/doc/Makefile.in index 7bbf68c..b40e510 100644 --- a/libstdc++-v3/doc/Makefile.in +++ b/libstdc++-v3/doc/Makefile.in @@ -294,7 +294,6 @@ xml_srcdir = ${glibcxx_srcdir}/doc/xml xml_sources = \ ${xml_srcdir}/spine.xml \ ${xml_srcdir}/authors.xml \ - ${xml_srcdir}/manual/spine.xml \ ${xml_srcdir}/manual/abi.xml \ ${xml_srcdir}/manual/algorithms.xml \ ${xml_srcdir}/manual/allocator.xml \ @@ -617,7 +616,7 @@ doc-fo: $(xml_sources) ${glibcxx_builddir}/doc/fo # PDF # Points to current best xml to PDF generation process. -doc-pdf: doc-pdf-xmlto +doc-pdf: doc-pdf-prince doc-pdf-fop-xml: $(xml_sources) ${glibcxx_builddir}/doc/pdf @echo "Generating pdf fop files from xml..." $(FOP) $(FOP_FLAGS) -xml ${top_srcdir}/doc/xml/spine.xml \ diff --git a/libstdc++-v3/doc/doxygen/mainpage.html b/libstdc++-v3/doc/doxygen/mainpage.html index 941e7a8..2302436 100644 --- a/libstdc++-v3/doc/doxygen/mainpage.html +++ b/libstdc++-v3/doc/doxygen/mainpage.html @@ -28,9 +28,9 @@ <p class="smallertext">Generated on @DATE@.</p> <p>There are two types of documentation for libstdc++. One is the - distribution documentation, which can be read online at - <a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html">http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html</a> - or offline from doc/html/documentation.html in the library source + distribution documentation, which can be read online + <a href="http://gcc.gnu.org/onlinedocs/libstdc++/index.html">here</a> + or offline from the file doc/html/index.html in the library source directory. </p> @@ -64,13 +64,15 @@ </p> <h2>Generating the documentation</h2> -<p>These HTML pages are automatically generated, along with the man pages. - See <code>doc/doxygen/guide.html</code> in the source tree for how to - create (and write) the pages. +<p>These HTML pages are automatically generated, along with the man + pages. See the section "Documentation Style" + in <code>doc/xml/manual/appendix_contributing.xml</code> in the + source tree for how to create (and write) the doxygen markup. + This style guide can also be viewed on the <a href="manual/bk01apas03.html">web</a>. <h2>License, Copyright, and Other Lawyerly Verbosity</h2> <p>The libstdc++ documentation is released under - <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/license.html"> + <a href="manual/bk01pt01ch01s02.html"> these terms</a>. </p> <p>Part of the generated documentation involved comments and notes from diff --git a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml index 033bd7d..543296a 100644 --- a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml +++ b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml @@ -5,7 +5,7 @@ <appendix id="appendix.contrib" xreflabel="Contributing"> <?dbhtml filename="appendix_contributing.html"?> - + <appendixinfo> <keywordset> <keyword> @@ -32,699 +32,853 @@ <sect2 id="list.reading" xreflabel="list.reading"> <title>Reading</title> -<itemizedlist> - <listitem><para> Get and read the relevant sections of the C++ language -specification. Copies of the full ISO 14882 standard are available on -line via the ISO mirror site for committee members. Non-members, or -those who have not paid for the privilege of sitting on the committee -and sustained their two meeting commitment for voting rights, may get -a copy of the standard from their respective national standards -organization. In the USA, this national standards organization is ANSI -and their web-site is right - - <ulink url="http://www.ansi.org">here.</ulink> -(And if you've already registered with them, clicking this link will take you to directly to the place where you can -<ulink url="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%3A2003">buy the standard on-line.)</ulink> -</para></listitem> - -<listitem><para> The library working group bugs, and known defects, can be obtained here: - <ulink url="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21 </ulink> -</para></listitem> - -<listitem><para> The newsgroup dedicated to standardization issues is comp.std.c++: this FAQ for this group is quite useful and can be found <ulink url="http://www.jamesd.demon.co.uk/csc/faq.html"> here </ulink>. -</para></listitem> - - <listitem><para> Peruse the <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU Coding Standards</ulink>, and chuckle when you hit the part about "Using Languages Other Than C." -</para></listitem> - - <listitem><para> Be familiar with the extensions that preceded these general GNU rules. These style issues for libstdc++ can be found in the file C++STYLE, located in the root level of the distribution, or <ulink url="C++STYLE"> here. </ulink> -</para></listitem> - - <listitem><para> And last but certainly not least, read the library-specific information found <ulink url="../documentation.html"> here.</ulink> -</para></listitem> - -</itemizedlist> - - </sect2> - <sect2 id="list.copyright" xreflabel="list.copyright"> - <title>Assignment</title> -<para> -Small changes can be accepted without a copyright assignment form on -file. New code and additions to the library need completed copyright -assignment form on file at the FSF. Note: your employer may be required -to fill out appropriate disclaimer forms as well. -</para> - -<para> - Historically, the libstdc++ assignment form added the following - question: -</para> - -<para> - <quote> - Which Belgian comic book character is better, Tintin or Asterix, and - why? - </quote> -</para> - -<para> -While not strictly necessary, humoring the maintainers and answering -this question would be appreciated. -</para> - -<para> -For more information about getting a copyright assignment, please see -<ulink url="http://www.gnu.org/prep/maintain/html_node/Legal-Matters.html">Legal -Matters</ulink>. -</para> - -<para> -Please contact Benjamin Kosnik at -<email>bkoz+assign@redhat.com</email> if you are confused -about the assignment or have general licensing questions. When -requesting an assignment form from -<email>mailto:assign@gnu.org</email>, please cc the libstdc++ -maintainer above so that progress can be monitored. -</para> - </sect2> - - <sect2 id="list.getting" xreflabel="list.getting"> - <title>Getting Sources</title> - <para> - <ulink url="http://gcc.gnu.org/svnwrite.html">Getting write access - (look for "Write after approval")</ulink> + <itemizedlist> + <listitem> + <para> + Get and read the relevant sections of the C++ language + specification. Copies of the full ISO 14882 standard are + available on line via the ISO mirror site for committee + members. Non-members, or those who have not paid for the + privilege of sitting on the committee and sustained their + two meeting commitment for voting rights, may get a copy of + the standard from their respective national standards + organization. In the USA, this national standards + organization is ANSI and their web-site is right + <ulink url="http://www.ansi.org">here.</ulink> + (And if you've already registered with them, clicking this link will take you to directly to the place where you can + <ulink url="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%3A2003">buy the standard on-line.)</ulink> + </para> + </listitem> + + <listitem> + <para> + The library working group bugs, and known defects, can + be obtained here: + <ulink url="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21 </ulink> + </para> + </listitem> + + <listitem> + <para> + The newsgroup dedicated to standardization issues is + comp.std.c++: this FAQ for this group is quite useful and + can be + found <ulink url="http://www.jamesd.demon.co.uk/csc/faq.html"> + here </ulink>. </para> - </sect2> - - <sect2 id="list.patches" xreflabel="list.patches"> - <title>Submitting Patches</title> - - -<para> -Every patch must have several pieces of information before it can be -properly evaluated. Ideally (and to ensure the fastest possible -response from the maintainers) it would have all of these pieces: -</para> - -<itemizedlist> - - <listitem><para> A description of the bug and how your patch fixes this bug. For - new features a description of the feature and your implementation. </para></listitem> - - <listitem><para> A ChangeLog entry as plain text; see the various ChangeLog files - for format and content. If using you are using emacs as your editor, - simply position the insertion point at the beginning of your change - and hit CX-4a to bring up the appropriate ChangeLog - entry. See--magic! Similar functionality also exists for vi. </para></listitem> - - <listitem><para> A testsuite submission or sample program that will easily and - simply show the existing error or test new functionality. </para></listitem> - - <listitem><para> The patch itself. If you are accessing the SVN repository - use "svn update; svn diff NEW"; else, use "diff -cp OLD NEW" - ... If your version of diff does not support these options, then - get the latest version of GNU diff. The <ulink url="http://gcc.gnu.org/wiki/SvnTricks">SVN Tricks</ulink> wiki page - has information on customising the output of <code>svn diff</code>.</para></listitem> - - <listitem><para> When you have all these pieces, bundle them up in a mail message -and send it to libstdc++@gcc.gnu.org. All patches and related -discussion should be sent to the libstdc++ mailing list. </para></listitem> + </listitem> + + <listitem> + <para> + Peruse + the <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU + Coding Standards</ulink>, and chuckle when you hit the part + about <quote>Using Languages Other Than C</quote>. + </para> + </listitem> + + <listitem> + <para> + Be familiar with the extensions that preceded these + general GNU rules. These style issues for libstdc++ can be + found <link linkend="contrib.coding_style">here</link>. + </para> + </listitem> -</itemizedlist> + <listitem> + <para> + And last but certainly not least, read the + library-specific information + found <link linkend="appendix.porting"> here</link>. + </para> + </listitem> + </itemizedlist> - </sect2> + </sect2> + <sect2 id="list.copyright" xreflabel="list.copyright"> + <title>Assignment</title> + <para> + Small changes can be accepted without a copyright assignment form on + file. New code and additions to the library need completed copyright + assignment form on file at the FSF. Note: your employer may be required + to fill out appropriate disclaimer forms as well. + </para> - </sect1> + <para> + Historically, the libstdc++ assignment form added the following + question: + </para> - <sect1 id="contrib.coding_style" xreflabel="Coding Style"> - <title>Coding Style</title> <para> + <quote> + Which Belgian comic book character is better, Tintin or Asterix, and + why? + </quote> </para> - <sect2 id="coding_style.bad_identifiers" xreflabel="coding_style.bad"> - <title>Bad Itentifiers</title> -<para> -Identifiers that conflict and should be avoided. -</para> - -<literallayout> - -This is the list of names "reserved to the implementation" that -have been claimed by certain compilers and system headers of interest, -and should not be used in the library. It will grow, of course. -We generally are interested in names that are not all-caps, except -for those like "_T" - -For Solarix: -_B -_C -_L -_N -_P -_S -_U -_X -_E1 -.. -_E24 - -Irix adds: -_A -_G - -MS adds: -_T - -BSD adds: -__used -__unused -__inline -_Complex -__istype -__maskrune -__tolower -__toupper -__wchar_t -__wint_t -_res -_res_ext -__tg_* - -For GCC: - - [Note that this list is out of date. It applies to the old - name-mangling; in G++ 3.0 and higher a different name-mangling is - used. In addition, many of the bugs relating to G++ interpreting - these names as operators have been fixed.] - - The full set of __* identifiers (combined from gcc/cp/lex.c and - gcc/cplus-dem.c) that are either old or new, but are definitely - recognized by the demangler, is: - -__aa -__aad -__ad -__addr -__adv -__aer -__als -__alshift -__amd -__ami -__aml -__amu -__aor -__apl -__array -__ars -__arshift -__as -__bit_and -__bit_ior -__bit_not -__bit_xor -__call -__cl -__cm -__cn -__co -__component -__compound -__cond -__convert -__delete -__dl -__dv -__eq -__er -__ge -__gt -__indirect -__le -__ls -__lt -__max -__md -__method_call -__mi -__min -__minus -__ml -__mm -__mn -__mult -__mx -__ne -__negate -__new -__nop -__nt -__nw -__oo -__op -__or -__pl -__plus -__postdecrement -__postincrement -__pp -__pt -__rf -__rm -__rs -__sz -__trunc_div -__trunc_mod -__truth_andif -__truth_not -__truth_orif -__vc -__vd -__vn - -SGI badnames: -__builtin_alloca -__builtin_fsqrt -__builtin_sqrt -__builtin_fabs -__builtin_dabs -__builtin_cast_f2i -__builtin_cast_i2f -__builtin_cast_d2ll -__builtin_cast_ll2d -__builtin_copy_dhi2i -__builtin_copy_i2dhi -__builtin_copy_dlo2i -__builtin_copy_i2dlo -__add_and_fetch -__sub_and_fetch -__or_and_fetch -__xor_and_fetch -__and_and_fetch -__nand_and_fetch -__mpy_and_fetch -__min_and_fetch -__max_and_fetch -__fetch_and_add -__fetch_and_sub -__fetch_and_or -__fetch_and_xor -__fetch_and_and -__fetch_and_nand -__fetch_and_mpy -__fetch_and_min -__fetch_and_max -__lock_test_and_set -__lock_release -__lock_acquire -__compare_and_swap -__synchronize -__high_multiply -__unix -__sgi -__linux__ -__i386__ -__i486__ -__cplusplus -__embedded_cplusplus -// long double conversion members mangled as __opr -// http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html -_opr -</literallayout> - </sect2> - <sect2 id="coding_style.example" xreflabel="coding_style.example"> - <title>By Example</title> -<literallayout> + <para> + While not strictly necessary, humoring the maintainers and answering + this question would be appreciated. + </para> -This library is written to appropriate C++ coding standards. As such, -it is intended to precede the recommendations of the GNU Coding -Standard, which can be referenced in full here: + <para> + For more information about getting a copyright assignment, please see + <ulink url="http://www.gnu.org/prep/maintain/html_node/Legal-Matters.html">Legal + Matters</ulink>. + </para> -http://www.gnu.org/prep/standards/standards.html#Formatting + <para> + Please contact Benjamin Kosnik at + <email>bkoz+assign@redhat.com</email> if you are confused + about the assignment or have general licensing questions. When + requesting an assignment form from + <email>mailto:assign@gnu.org</email>, please cc the libstdc++ + maintainer above so that progress can be monitored. + </para> + </sect2> -The rest of this is also interesting reading, but skip the "Design -Advice" part. + <sect2 id="list.getting" xreflabel="list.getting"> + <title>Getting Sources</title> + <para> + <ulink url="http://gcc.gnu.org/svnwrite.html">Getting write access + (look for "Write after approval")</ulink> + </para> + </sect2> -The GCC coding conventions are here, and are also useful: -http://gcc.gnu.org/codingconventions.html + <sect2 id="list.patches" xreflabel="list.patches"> + <title>Submitting Patches</title> -In addition, because it doesn't seem to be stated explicitly anywhere -else, there is an 80 column source limit. + <para> + Every patch must have several pieces of information before it can be + properly evaluated. Ideally (and to ensure the fastest possible + response from the maintainers) it would have all of these pieces: + </para> -ChangeLog entries for member functions should use the -classname::member function name syntax as follows: + <itemizedlist> + <listitem> + <para> + A description of the bug and how your patch fixes this + bug. For new features a description of the feature and your + implementation. + </para> + </listitem> + + <listitem> + <para> + A ChangeLog entry as plain text; see the various + ChangeLog files for format and content. If using you are + using emacs as your editor, simply position the insertion + point at the beginning of your change and hit CX-4a to bring + up the appropriate ChangeLog entry. See--magic! Similar + functionality also exists for vi. + </para> + </listitem> + + <listitem> + <para> + A testsuite submission or sample program that will + easily and simply show the existing error or test new + functionality. + </para> + </listitem> + + <listitem> + <para> + The patch itself. If you are accessing the SVN + repository use <command>svn update; svn diff NEW</command>; + else, use <command>diff -cp OLD NEW</command> ... If your + version of diff does not support these options, then get the + latest version of GNU + diff. The <ulink url="http://gcc.gnu.org/wiki/SvnTricks">SVN + Tricks</ulink> wiki page has information on customising the + output of <code>svn diff</code>. + </para> + </listitem> + + <listitem> + <para> + When you have all these pieces, bundle them up in a + mail message and send it to libstdc++@gcc.gnu.org. All + patches and related discussion should be sent to the + libstdc++ mailing list. + </para> + </listitem> + </itemizedlist> + + </sect2> + +</sect1> + +<sect1 id="contrib.organization" xreflabel="Source Organization"> + <title>Directory Layout and Source Conventions</title> + + <para> + The unpacked source directory of libstdc++ contains the files + needed to create the GNU C++ Library. + </para> + + <literallayout> +It has subdirectories: + + doc + Files in HTML and text format that document usage, quirks of the + implementation, and contributor checklists. + + include + All header files for the C++ library are within this directory, + modulo specific runtime-related files that are in the libsupc++ + directory. + + include/std + Files meant to be found by #include <name> directives in + standard-conforming user programs. + + include/c + Headers intended to directly include standard C headers. + [NB: this can be enabled via --enable-cheaders=c] + + include/c_global + Headers intended to include standard C headers in + the global namespace, and put select names into the std:: + namespace. [NB: this is the default, and is the same as + --enable-cheaders=c_global] + + include/c_std + Headers intended to include standard C headers + already in namespace std, and put select names into the std:: + namespace. [NB: this is the same as --enable-cheaders=c_std] + + include/bits + Files included by standard headers and by other files in + the bits directory. + + include/backward + Headers provided for backward compatibility, such as <iostream.h>. + They are not used in this library. + + include/ext + Headers that define extensions to the standard library. No + standard header refers to any of them. + + scripts + Scripts that are used during the configure, build, make, or test + process. + + src + Files that are used in constructing the library, but are not + installed. + + testsuites/[backward, demangle, ext, performance, thread, 17_* to 27_*] + Test programs are here, and may be used to begin to exercise the + library. Support for "make check" and "make check-install" is + complete, and runs through all the subdirectories here when this + command is issued from the build directory. Please note that + "make check" requires DejaGNU 1.4 or later to be installed. Please + note that "make check-script" calls the script mkcheck, which + requires bash, and which may need the paths to bash adjusted to + work properly, as /bin/bash is assumed. + +Other subdirectories contain variant versions of certain files +that are meant to be copied or linked by the configure script. +Currently these are: + + config/abi + config/cpu + config/io + config/locale + config/os + +In addition, two subdirectories are convenience libraries: + + libmath + Support routines needed for C++ math. Only needed if the + underlying "C" implementation is non-existent, in particular + required or optimal long double, long long, and C99 functionality. + + libsupc++ + Contains the runtime library for C++, including exception + handling and memory allocation and deallocation, RTTI, terminate + handlers, etc. + +Note that glibc also has a bits/ subdirectory. We will either +need to be careful not to collide with names in its bits/ +directory; or rename bits to (e.g.) cppbits/. + +In files throughout the system, lines marked with an "XXX" indicate +a bug or incompletely-implemented feature. Lines marked "XXX MT" +indicate a place that may require attention for multi-thread safety. + </literallayout> + +</sect1> + +<sect1 id="contrib.coding_style" xreflabel="Coding Style"> + <title>Coding Style</title> + <para> + </para> + <sect2 id="coding_style.bad_identifiers" xreflabel="coding_style.bad"> + <title>Bad Itentifiers</title> + <para> + Identifiers that conflict and should be avoided. + </para> -1999-04-15 Dennis Ritchie <dr@att.com> + <literallayout> + This is the list of names <quote>reserved to the + implementation</quote> that have been claimed by certain + compilers and system headers of interest, and should not be used + in the library. It will grow, of course. We generally are + interested in names that are not all-caps, except for those like + "_T" + + For Solaris: + _B + _C + _L + _N + _P + _S + _U + _X + _E1 + .. + _E24 + + Irix adds: + _A + _G + + MS adds: + _T + + BSD adds: + __used + __unused + __inline + _Complex + __istype + __maskrune + __tolower + __toupper + __wchar_t + __wint_t + _res + _res_ext + __tg_* + + For GCC: + + [Note that this list is out of date. It applies to the old + name-mangling; in G++ 3.0 and higher a different name-mangling is + used. In addition, many of the bugs relating to G++ interpreting + these names as operators have been fixed.] + + The full set of __* identifiers (combined from gcc/cp/lex.c and + gcc/cplus-dem.c) that are either old or new, but are definitely + recognized by the demangler, is: + + __aa + __aad + __ad + __addr + __adv + __aer + __als + __alshift + __amd + __ami + __aml + __amu + __aor + __apl + __array + __ars + __arshift + __as + __bit_and + __bit_ior + __bit_not + __bit_xor + __call + __cl + __cm + __cn + __co + __component + __compound + __cond + __convert + __delete + __dl + __dv + __eq + __er + __ge + __gt + __indirect + __le + __ls + __lt + __max + __md + __method_call + __mi + __min + __minus + __ml + __mm + __mn + __mult + __mx + __ne + __negate + __new + __nop + __nt + __nw + __oo + __op + __or + __pl + __plus + __postdecrement + __postincrement + __pp + __pt + __rf + __rm + __rs + __sz + __trunc_div + __trunc_mod + __truth_andif + __truth_not + __truth_orif + __vc + __vd + __vn + + SGI badnames: + __builtin_alloca + __builtin_fsqrt + __builtin_sqrt + __builtin_fabs + __builtin_dabs + __builtin_cast_f2i + __builtin_cast_i2f + __builtin_cast_d2ll + __builtin_cast_ll2d + __builtin_copy_dhi2i + __builtin_copy_i2dhi + __builtin_copy_dlo2i + __builtin_copy_i2dlo + __add_and_fetch + __sub_and_fetch + __or_and_fetch + __xor_and_fetch + __and_and_fetch + __nand_and_fetch + __mpy_and_fetch + __min_and_fetch + __max_and_fetch + __fetch_and_add + __fetch_and_sub + __fetch_and_or + __fetch_and_xor + __fetch_and_and + __fetch_and_nand + __fetch_and_mpy + __fetch_and_min + __fetch_and_max + __lock_test_and_set + __lock_release + __lock_acquire + __compare_and_swap + __synchronize + __high_multiply + __unix + __sgi + __linux__ + __i386__ + __i486__ + __cplusplus + __embedded_cplusplus + // long double conversion members mangled as __opr + // http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html + _opr + </literallayout> + </sect2> + + <sect2 id="coding_style.example" xreflabel="coding_style.example"> + <title>By Example</title> + <literallayout> + This library is written to appropriate C++ coding standards. As such, + it is intended to precede the recommendations of the GNU Coding + Standard, which can be referenced in full here: + + http://www.gnu.org/prep/standards/standards.html#Formatting + + The rest of this is also interesting reading, but skip the "Design + Advice" part. + + The GCC coding conventions are here, and are also useful: + http://gcc.gnu.org/codingconventions.html + + In addition, because it doesn't seem to be stated explicitly anywhere + else, there is an 80 column source limit. + + ChangeLog entries for member functions should use the + classname::member function name syntax as follows: + + 1999-04-15 Dennis Ritchie <dr@att.com> + + * src/basic_file.cc (__basic_file::open): Fix thinko in + _G_HAVE_IO_FILE_OPEN bits. + + Notable areas of divergence from what may be previous local practice + (particularly for GNU C) include: + + 01. Pointers and references + char* p = "flop"; + char& c = *p; + -NOT- + char *p = "flop"; // wrong + char &c = *p; // wrong + + Reason: In C++, definitions are mixed with executable code. Here, + p is being initialized, not *p. This is near-universal + practice among C++ programmers; it is normal for C hackers + to switch spontaneously as they gain experience. + + 02. Operator names and parentheses + operator==(type) + -NOT- + operator == (type) // wrong + + Reason: The == is part of the function name. Separating + it makes the declaration look like an expression. - * src/basic_file.cc (__basic_file::open): Fix thinko in - _G_HAVE_IO_FILE_OPEN bits. + 03. Function names and parentheses + void mangle() + -NOT- + void mangle () // wrong -Notable areas of divergence from what may be previous local practice -(particularly for GNU C) include: + Reason: no space before parentheses (except after a control-flow + keyword) is near-universal practice for C++. It identifies the + parentheses as the function-call operator or declarator, as + opposed to an expression or other overloaded use of parentheses. -01. Pointers and references - char* p = "flop"; - char& c = *p; - -NOT- - char *p = "flop"; // wrong - char &c = *p; // wrong - - Reason: In C++, definitions are mixed with executable code. Here, - p is being initialized, not *p. This is near-universal - practice among C++ programmers; it is normal for C hackers - to switch spontaneously as they gain experience. - -02. Operator names and parentheses - operator==(type) - -NOT- - operator == (type) // wrong - - Reason: The == is part of the function name. Separating - it makes the declaration look like an expression. - -03. Function names and parentheses - void mangle() - -NOT- - void mangle () // wrong - - Reason: no space before parentheses (except after a control-flow - keyword) is near-universal practice for C++. It identifies the - parentheses as the function-call operator or declarator, as - opposed to an expression or other overloaded use of parentheses. - -04. Template function indentation - template<typename T> - void - template_function(args) - { } + 04. Template function indentation + template<typename T> + void + template_function(args) + { } -NOT- - template<class T> - void template_function(args) {}; - - Reason: In class definitions, without indentation whitespace is - needed both above and below the declaration to distinguish - it visually from other members. (Also, re: "typename" - rather than "class".) T often could be int, which is - not a class. ("class", here, is an anachronism.) - -05. Template class indentation - template<typename _CharT, typename _Traits> - class basic_ios : public ios_base - { - public: + template<class T> + void template_function(args) {}; + + Reason: In class definitions, without indentation whitespace is + needed both above and below the declaration to distinguish + it visually from other members. (Also, re: "typename" + rather than "class".) T often could be int, which is + not a class. ("class", here, is an anachronism.) + + 05. Template class indentation + template<typename _CharT, typename _Traits> + class basic_ios : public ios_base + { + public: // Types: - }; - -NOT- - template<class _CharT, class _Traits> - class basic_ios : public ios_base - { - public: + }; + -NOT- + template<class _CharT, class _Traits> + class basic_ios : public ios_base + { + public: // Types: - }; - -NOT- - template<class _CharT, class _Traits> - class basic_ios : public ios_base - { - public: + }; + -NOT- + template<class _CharT, class _Traits> + class basic_ios : public ios_base + { + public: // Types: - }; - -06. Enumerators - enum - { - space = _ISspace, - print = _ISprint, - cntrl = _IScntrl - }; - -NOT- - enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl }; - -07. Member initialization lists - All one line, separate from class name. - - gribble::gribble() - : _M_private_data(0), _M_more_stuff(0), _M_helper(0); - { } - -NOT- - gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0); - { } - -08. Try/Catch blocks - try - { + }; + + 06. Enumerators + enum + { + space = _ISspace, + print = _ISprint, + cntrl = _IScntrl + }; + -NOT- + enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl }; + + 07. Member initialization lists + All one line, separate from class name. + + gribble::gribble() + : _M_private_data(0), _M_more_stuff(0), _M_helper(0); + { } + -NOT- + gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0); + { } + + 08. Try/Catch blocks + try + { // - } - catch (...) - { + } + catch (...) + { // - } - -NOT- - try { - // - } catch(...) { - // - } + } + -NOT- + try { + // + } catch(...) { + // + } -09. Member functions declarations and definitions - Keywords such as extern, static, export, explicit, inline, etc - go on the line above the function name. Thus + 09. Member functions declarations and definitions + Keywords such as extern, static, export, explicit, inline, etc + go on the line above the function name. Thus - virtual int - foo() - -NOT- - virtual int foo() + virtual int + foo() + -NOT- + virtual int foo() - Reason: GNU coding conventions dictate return types for functions - are on a separate line than the function name and parameter list - for definitions. For C++, where we have member functions that can - be either inline definitions or declarations, keeping to this - standard allows all member function names for a given class to be - aligned to the same margin, increasing readibility. + Reason: GNU coding conventions dictate return types for functions + are on a separate line than the function name and parameter list + for definitions. For C++, where we have member functions that can + be either inline definitions or declarations, keeping to this + standard allows all member function names for a given class to be + aligned to the same margin, increasing readibility. -10. Invocation of member functions with "this->" - For non-uglified names, use this->name to call the function. + 10. Invocation of member functions with "this->" + For non-uglified names, use this->name to call the function. - this->sync() - -NOT- - sync() + this->sync() + -NOT- + sync() - Reason: Koenig lookup. + Reason: Koenig lookup. -11. Namespaces - namespace std - { - blah blah blah; - } // namespace std + 11. Namespaces + namespace std + { + blah blah blah; + } // namespace std - -NOT- + -NOT- - namespace std { - blah blah blah; - } // namespace std + namespace std { + blah blah blah; + } // namespace std -12. Spacing under protected and private in class declarations: - space above, none below - ie + 12. Spacing under protected and private in class declarations: + space above, none below + ie - public: - int foo; + public: + int foo; - -NOT- - public: - - int foo; + -NOT- + public: + + int foo; -13. Spacing WRT return statements. - no extra spacing before returns, no parenthesis - ie + 13. Spacing WRT return statements. + no extra spacing before returns, no parenthesis + ie - } - return __ret; + } + return __ret; - -NOT- - } + -NOT- + } - return __ret; + return __ret; - -NOT- + -NOT- - } - return (__ret); + } + return (__ret); -14. Location of global variables. - All global variables of class type, whether in the "user visable" - space (e.g., cin) or the implementation namespace, must be defined - as a character array with the appropriate alignment and then later - re-initialized to the correct value. + 14. Location of global variables. + All global variables of class type, whether in the "user visable" + space (e.g., cin) or the implementation namespace, must be defined + as a character array with the appropriate alignment and then later + re-initialized to the correct value. - This is due to startup issues on certain platforms, such as AIX. - For more explanation and examples, see src/globals.cc. All such - variables should be contained in that file, for simplicity. + This is due to startup issues on certain platforms, such as AIX. + For more explanation and examples, see src/globals.cc. All such + variables should be contained in that file, for simplicity. -15. Exception abstractions - Use the exception abstractions found in functexcept.h, which allow - C++ programmers to use this library with -fno-exceptions. (Even if - that is rarely advisable, it's a necessary evil for backwards - compatibility.) + 15. Exception abstractions + Use the exception abstractions found in functexcept.h, which allow + C++ programmers to use this library with -fno-exceptions. (Even if + that is rarely advisable, it's a necessary evil for backwards + compatibility.) -16. Exception error messages - All start with the name of the function where the exception is - thrown, and then (optional) descriptive text is added. Example: + 16. Exception error messages + All start with the name of the function where the exception is + thrown, and then (optional) descriptive text is added. Example: - __throw_logic_error(__N("basic_string::_S_construct NULL not valid")); + __throw_logic_error(__N("basic_string::_S_construct NULL not valid")); - Reason: The verbose terminate handler prints out exception::what(), - as well as the typeinfo for the thrown exception. As this is the - default terminate handler, by putting location info into the - exception string, a very useful error message is printed out for - uncaught exceptions. So useful, in fact, that non-programmers can - give useful error messages, and programmers can intelligently - speculate what went wrong without even using a debugger. + Reason: The verbose terminate handler prints out exception::what(), + as well as the typeinfo for the thrown exception. As this is the + default terminate handler, by putting location info into the + exception string, a very useful error message is printed out for + uncaught exceptions. So useful, in fact, that non-programmers can + give useful error messages, and programmers can intelligently + speculate what went wrong without even using a debugger. -17. The doxygen style guide to comments is a separate document, - see index. + 17. The doxygen style guide to comments is a separate document, + see index. -The library currently has a mixture of GNU-C and modern C++ coding -styles. The GNU C usages will be combed out gradually. + The library currently has a mixture of GNU-C and modern C++ coding + styles. The GNU C usages will be combed out gradually. -Name patterns: + Name patterns: -For nonstandard names appearing in Standard headers, we are constrained -to use names that begin with underscores. This is called "uglification". -The convention is: + For nonstandard names appearing in Standard headers, we are constrained + to use names that begin with underscores. This is called "uglification". + The convention is: - Local and argument names: __[a-z].* + Local and argument names: __[a-z].* - Examples: __count __ix __s1 + Examples: __count __ix __s1 - Type names and template formal-argument names: _[A-Z][^_].* + Type names and template formal-argument names: _[A-Z][^_].* - Examples: _Helper _CharT _N + Examples: _Helper _CharT _N - Member data and function names: _M_.* + Member data and function names: _M_.* - Examples: _M_num_elements _M_initialize () + Examples: _M_num_elements _M_initialize () - Static data members, constants, and enumerations: _S_.* + Static data members, constants, and enumerations: _S_.* - Examples: _S_max_elements _S_default_value + Examples: _S_max_elements _S_default_value -Don't use names in the same scope that differ only in the prefix, -e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names. -(The most tempting of these seem to be and "_T" and "__sz".) + Don't use names in the same scope that differ only in the prefix, + e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names. + (The most tempting of these seem to be and "_T" and "__sz".) -Names must never have "__" internally; it would confuse name -unmanglers on some targets. Also, never use "__[0-9]", same reason. + Names must never have "__" internally; it would confuse name + unmanglers on some targets. Also, never use "__[0-9]", same reason. --------------------------- + -------------------------- -[BY EXAMPLE] - -#ifndef _HEADER_ -#define _HEADER_ 1 + [BY EXAMPLE] + + #ifndef _HEADER_ + #define _HEADER_ 1 -namespace std -{ - class gribble - { - public: - gribble() throw(); + namespace std + { + class gribble + { + public: + gribble() throw(); - gribble(const gribble&); + gribble(const gribble&); - explicit - gribble(int __howmany); + explicit + gribble(int __howmany); - gribble& - operator=(const gribble&); + gribble& + operator=(const gribble&); - virtual - ~gribble() throw (); + virtual + ~gribble() throw (); - // Start with a capital letter, end with a period. - inline void - public_member(const char* __arg) const; + // Start with a capital letter, end with a period. + inline void + public_member(const char* __arg) const; - // In-class function definitions should be restricted to one-liners. - int - one_line() { return 0 } + // In-class function definitions should be restricted to one-liners. + int + one_line() { return 0 } - int - two_lines(const char* arg) - { return strchr(arg, 'a'); } + int + two_lines(const char* arg) + { return strchr(arg, 'a'); } - inline int - three_lines(); // inline, but defined below. + inline int + three_lines(); // inline, but defined below. - // Note indentation. - template<typename _Formal_argument> + // Note indentation. + template<typename _Formal_argument> void public_template() const throw(); - template<typename _Iterator> + template<typename _Iterator> void other_template(); - private: - class _Helper; + private: + class _Helper; - int _M_private_data; - int _M_more_stuff; - _Helper* _M_helper; - int _M_private_function(); + int _M_private_data; + int _M_more_stuff; + _Helper* _M_helper; + int _M_private_function(); - enum _Enum + enum _Enum { - _S_one, - _S_two + _S_one, + _S_two }; - static void - _S_initialize_library(); - }; + static void + _S_initialize_library(); + }; -// More-or-less-standard language features described by lack, not presence. -# ifndef _G_NO_LONGLONG - extern long long _G_global_with_a_good_long_name; // avoid globals! -# endif + // More-or-less-standard language features described by lack, not presence. + # ifndef _G_NO_LONGLONG + extern long long _G_global_with_a_good_long_name; // avoid globals! + # endif - // Avoid in-class inline definitions, define separately; - // likewise for member class definitions: - inline int - gribble::public_member() const - { int __local = 0; return __local; } + // Avoid in-class inline definitions, define separately; + // likewise for member class definitions: + inline int + gribble::public_member() const + { int __local = 0; return __local; } - class gribble::_Helper - { - int _M_stuff; + class gribble::_Helper + { + int _M_stuff; - friend class gribble; - }; -} + friend class gribble; + }; + } -// Names beginning with "__": only for arguments and -// local variables; never use "__" in a type name, or -// within any name; never use "__[0-9]". + // Names beginning with "__": only for arguments and + // local variables; never use "__" in a type name, or + // within any name; never use "__[0-9]". -#endif /* _HEADER_ */ + #endif /* _HEADER_ */ -namespace std -{ - template<typename T> // notice: "typename", not "class", no space - long_return_value_type<with_many, args> - function_name(char* pointer, // "char *pointer" is wrong. - char* argument, - const Reference& ref) - { + namespace std + { + template<typename T> // notice: "typename", not "class", no space + long_return_value_type<with_many, args> + function_name(char* pointer, // "char *pointer" is wrong. + char* argument, + const Reference& ref) + { // int a_local; /* wrong; see below. */ if (test) { - nested code + nested code } - + int a_local = 0; // declare variable at first use. // char a, b, *p; /* wrong */ @@ -734,1114 +888,1259 @@ namespace std // except maybe here... for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) { - // ... + // ... } - } - - gribble::gribble() - : _M_private_data(0), _M_more_stuff(0), _M_helper(0); - { } - - inline int - gribble::three_lines() - { - // doesn't fit in one line. - } -} // namespace std - + } + + gribble::gribble() + : _M_private_data(0), _M_more_stuff(0), _M_helper(0); + { } + + inline int + gribble::three_lines() + { + // doesn't fit in one line. + } + } // namespace std + </literallayout> + </sect2> +</sect1> + +<sect1 id="contrib.doc_style" xreflabel="Documentation Style"> + <title>Documentation Style</title> + <sect2 id="doc_style.doxygen" xreflabel="doc_style.doxygen"> + <title>Doxygen</title> + <sect3 id="doxygen.prereq" xreflabel="doxygen.prereq"> + <title>Prerequisites</title> + <para> + Prerequisite tools are Bash 2.x, + <ulink url="http://www.doxygen.org/">Doxygen</ulink>, and + the <ulink url="http://www.gnu.org/software/coreutils/">GNU + coreutils</ulink>. (GNU versions of find, xargs, and possibly + sed and grep are used, just because the GNU versions make + things very easy.) + </para> -</literallayout> - </sect2> - </sect1> + <para> + To generate the pretty pictures and hierarchy + graphs, the + <ulink url="http://www.research.att.com/sw/tools/graphviz/download.html">Graphviz</ulink> + package will need to be installed. + </para> + </sect3> - <sect1 id="contrib.doc_style" xreflabel="Documentation Style"> - <title>Documentation Style</title> - <para> - </para> - <sect2 id="doc_style.doxygen" xreflabel="doc_style.doxygen"> - <title>Doxygen</title> - <sect3 id="doxygen.generating" xreflabel="doxygen.generating"> + <sect3 id="doxygen.rules" xreflabel="doxygen.rules"> <title>Generating the Doxygen Files</title> + <para> + The Makefile rules + </para> + <screen><userinput>make doc-html-doxygen</userinput></screen> + <para> + and + </para> + <screen><userinput>make doc-xml-doxygen</userinput></screen> + <para> + and + </para> + <screen><userinput>make doc-man-doxygen</userinput></screen> + <para> + in the libstdc++ build directory generate the HTML docs, the + XML docs, and the man pages. + </para> -<para>The Makefile rules <code>'make doc-doxygen-html'</code>, - and <code>'make doc-doxygen-man'</code> in the libstdc++ build - directory generate the HTML docs, the and the man pages, - respectively. Prerequisite tools are Bash 2.x, - <ulink url="http://www.doxygen.org/">Doxygen</ulink>, a working version of <code>g++</code> somewhere in the PATH, and - the <ulink url="http://www.gnu.org/software/coreutils/">GNU coreutils</ulink>. - - In addition, to generate the pretty pictures and hierarchy graphs, the - <ulink url= - "http://www.research.att.com/sw/tools/graphviz/download.html">Graphviz</ulink> - package will need to be installed. - (g++ is used to build a program which manipulates man pages. GNU versions - of find, xargs, and possibly sed and grep are used, just because the GNU - versions make things very easy.) -</para> - -<para>Careful observers will see that the Makefile rules simply call a script - from the source tree, <code>run_doxygen</code>, which does the actual work - of running Doxygen and then (most importantly) massaging the output files. - If for some reason you prefer to not go through the Makefile, you can call - this script directly. (Start by passing <code>'--help'</code>.) -</para> + <para> + Careful observers will see that the Makefile rules simply call + a script from the source tree, <filename>run_doxygen</filename>, which + does the actual work of running Doxygen and then (most + importantly) massaging the output files. If for some reason + you prefer to not go through the Makefile, you can call this + script directly. (Start by passing <literal>--help</literal>.) + </para> -<para>If you wish to tweak the Doxygen settings, do so by editing - <code>docs/doxygen/user.cfg.in</code>. Notes to v3-hackers are written in - triple-# comments. -</para> + <para> + If you wish to tweak the Doxygen settings, do so by editing + <filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow + library hackers are written in triple-# comments. + </para> </sect3> <sect3 id="doxygen.markup" xreflabel="doxygen.markup"> <title>Markup</title> -<para>In general, libstdc++ files should be formatted according to the GNU - C++ Coding Standard rules found in the file - <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</ulink>. - Before any doxygen-specific formatting tweaks are made, please try to make - sure that the initial formatting is sound. -</para> + <para> + In general, libstdc++ files should be formatted according to + the rules found in the + <link linkend="contrib.coding_style">Coding Standard</link>. Before + any doxygen-specific formatting tweaks are made, please try to + make sure that the initial formatting is sound. + </para> -<para>Adding Doxygen markup to a file (informally called "doxygenating") is very - simple. The Doxygen manual can be found - <ulink url="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</ulink>. - We try to use a very-recent version of Doxygen. -</para> + <para> + Adding Doxygen markup to a file (informally called + <quote>doxygenating</quote>) is very simple. The Doxygen manual can be + found + <ulink url="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</ulink>. + We try to use a very-recent version of Doxygen. + </para> -<para>For classes, use deque/vector/list and std::pair as examples. For - functions, see their member functions, and the free functions in - <code>stl_algobase.h</code>. Member functions of other container-like - types should read similarly to these member functions. -</para> + <para> + For classes, use + <classname>deque</classname>/<classname>vector</classname>/<classname>list</classname> + and <classname>std::pair</classname> as examples. For + functions, see their member functions, and the free functions + in <filename>stl_algobase.h</filename>. Member functions of + other container-like types should read similarly to these + member functions. + </para> -<para>These points accompany the first list in section 3.1 of the Doxygen manual: -</para> -<orderedlist> - <listitem><para>Use the Javadoc style...</para></listitem> - <listitem><para>...not the Qt style. The intermediate *'s are preferred.</para></listitem> - <listitem><para>Use the triple-slash style only for one-line comments (the "brief" mode). - Very recent versions of Doxygen permit full-mode comments in triple-slash - blocks, but the formatting still comes out wonky.</para></listitem> - <listitem><para>This is disgusting. Don't do this.</para></listitem> -</orderedlist> - -<para>Use the @-style of commands, not the !-style. Please be careful about - whitespace in your markup comments. Most of the time it doesn't matter; - doxygen absorbs most whitespace, and both HTML and *roff are agnostic about - whitespace. However, in <pre> blocks and @code/@endcode sections, - spacing can have "interesting" effects. -</para> + <para> + These points accompany the first list in section 3.1 of the + Doxygen manual: + </para> -<para>Use either kind of grouping, as appropriate. <code>doxygroups.cc</code> - exists for this purpose. See <code>stl_iterator.h</code> for a good - example of the "other" kind of grouping. -</para> + <orderedlist> + <listitem><para>Use the Javadoc style...</para></listitem> + <listitem> + <para> + ...not the Qt style. The intermediate *'s are preferred. + </para> + </listitem> + <listitem> + <para> + Use the triple-slash style only for one-line comments (the + <quote>brief</quote> mode). Very recent versions of Doxygen permit + full-mode comments in triple-slash blocks, but the + formatting still comes out wonky. + </para> + </listitem> + <listitem> + <para> + This is disgusting. Don't do this. + </para> + </listitem> + </orderedlist> -<para>Please use markup tags like @p and @a when referring to things such as the - names of function parameters. Use @e for emphasis when necessary. Use @c - to refer to other standard names. (Examples of all these abound in the - present code.) -</para> + <para> + Use the @-style of commands, not the !-style. Please be + careful about whitespace in your markup comments. Most of the + time it doesn't matter; doxygen absorbs most whitespace, and + both HTML and *roff are agnostic about whitespace. However, + in <pre> blocks and @code/@endcode sections, spacing can + have <quote>interesting</quote> effects. + </para> + + <para> + Use either kind of grouping, as + appropriate. <filename>doxygroups.cc</filename> exists for this + purpose. See <filename>stl_iterator.h</filename> for a good example + of the <quote>other</quote> kind of grouping. + </para> + + <para> + Please use markup tags like @p and @a when referring to things + such as the names of function parameters. Use @e for emphasis + when necessary. Use @c to refer to other standard names. + (Examples of all these abound in the present code.) + </para> </sect3> - </sect2> + </sect2> - <sect2 id="doc_style.docbook" xreflabel="doc_style.docbook"> - <title>Docbook</title> + <sect2 id="doc_style.docbook" xreflabel="doc_style.docbook"> + <title>Docbook</title> -<literallayout> - -Which files are important: + <sect3 id="docbook.prereq" xreflabel="docbook.prereq"> + <title>Prerequisites</title> + <para> + Editing the DocBook sources requires an XML editor. Many + exist: some noteable options + include <command>emacs</command>, <application>Kate</application>, + or <application>Conglomerate</application>. + </para> -Main page -spine.xml - index to documentation set + <para> + Some editors support special <quote>XML Validation</quote> + modes that can validate the file as it is + produced. Recommended is the <command>nXML Mode</command> + for <command>emacs</command>. + </para> -manual/spine.xml - index to manual -manual/*.xml - chapters and sections of the manual + <para> + Besides an editor, additional DocBook files and XML tools are + also required. + </para> -faq.xml - index to FAQ -api.xml - index to source level / API + <para> + Access to the DocBook stylesheets and DTD is required. The + stylesheets are usually packaged by vendor, in something + like <filename>docbook-style-xsl</filename>. The installation + directory for this package corresponds to + the <literal>XSL_STYLE_DIR</literal> + in <filename>doc/Makefile.am</filename> and defaults + to <filename class="directory">/usr/share/sgml/docbook/xsl-stylesheets</filename>. + </para> -All *.txml files are template xml files, ie otherwise empty files with -the correct structure, suitable for filling in. + <para> + For procesessing XML, an XML processor and some style + sheets are necessary. Defaults are <command>xsltproc</command> + provided by <filename>libxslt</filename>. + </para> + <para> + For validating the XML document, you'll need + something like <command>xmllint</command> and access to the + DocBook DTD. These are provided + by a vendor package like <filename>lixml2</filename>. + </para> -Cannonical Writing Style + <para> + For PDF output, something that transforms valid XML to PDF is + required. Possible solutions include <command>xmlto</command>, + <ulink url="http://xmlgraphics.apache.org/fop/">Apache + FOP</ulink>, or <command>prince</command>. Other options are + listed on the DocBook web <ulink + url="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</ulink>. Please + consult the <email>libstdc++@gcc.gnu.org</email> list when + preparing printed manuals for current best practice and suggestions. + </para> + + <para> + Make sure that the XML documentation and markup is valid for + any change. This can be done easily, with the validation rules + in the <filename>Makefile</filename>, which is equivalent to doing: + </para> + + <screen> + <userinput> +xmllint --noout --valid <filename>xml/index.xml</filename> + </userinput> + </screen> + </sect3> + + <sect3 id="docbook.rules" xreflabel="docbook.rules"> + <title>Generating the DocBook Files</title> + + <para> + The Makefile rules + </para> + <screen><userinput>make doc-html</userinput></screen> + <para> + and + </para> + <screen><userinput>make doc-pdf</userinput></screen> + <para> + and + </para> + <screen><userinput>make doc-xml-single</userinput></screen> + <para> + and + </para> + <screen><userinput>make doc-xml-validate</userinput></screen> -class template -function template -member function template -(via C++ Templates, Vandevoorde) + <para> + in the libstdc++ build directory result respectively in the + following: the generation of an HTML version of all the + documentation, a PDF version of the same, a single XML + document, and the results of validating the XML document. + </para> + </sect3> -class in namespace std: allocator, not std::allocator + <sect3 id="docbook.examples" xreflabel="docbook.examples"> + <title>File Organization and Basics</title> -header file: iostream, not <iostream> + <literallayout> + <emphasis>Which files are important</emphasis> + All Docbook files are in the directory + libstdc++-v3/doc/xml -Translation + Inside this directory, the files of importance: + spine.xml - index to documentation set + manual/spine.xml - index to manual + manual/*.xml - individual chapters and sections of the manual + faq.xml - index to FAQ + api.xml - index to source level / API -HTML to XML rough equivalents + All *.txml files are template xml files, ie otherwise empty files with + the correct structure, suitable for filling in with new information. -<p> <para> + <emphasis>Cannonical Writing Style</emphasis> -<pre> <computeroutput> -<pre> <programlisting> -<pre> <literallayout> + class template + function template + member function template + (via C++ Templates, Vandevoorde) -<ul> <itemizedlist> -<ol> <orderedlist> -<il> <listitem> + class in namespace std: allocator, not std::allocator -<dl> <variablelist> + header file: iostream, not <iostream> - <varlistentry> -<dt> <term> -</dt> </term> -<dd> <listitem> -</dt> </listitem> - </varlistentry> -<a href <ulink url -<code> <literal> -<code> <programlisting> + <emphasis>General structure</emphasis> -<strong> <emphasis> -<em> <emphasis> -" <quote> + <set> + <book> + </book> -ctype.h <filename class="headerfile"></filename> + <book> + <chapter> + </chapter> + </book> - -build_dir <filename class="directory">path_to_build_dir</filename> + <book> + <part> + <chapter> + <section> + </section> -Finer gradations of <code> + <sect1> + </sect1> -<classname> <classname>string</classname> - <classname>vector<></classname> - <function>fs.clear()</function> + <sect1> + <sect2> + </sect2> + </sect1> + </chapter> -<structname> + <chapter> + </chapter> + </part> + </book> -<function> <function>clear()</function> + </set> + </literallayout> + </sect3> -<type> <type>long long</type> + <sect3 id="docbook.markup" xreflabel="docbook.markup"> + <title>Markup By Example</title> -<varname> <varname>fs</varname> + <literallayout> + HTML to XML rough equivalents -<literal> <literal>-Weffc++</literal> - <literal>rel_ops</literal> + <p> <para> -<constant> <constant>_GNU_SOURCE</constant> - <constant>3.0</constant> + <pre> <computeroutput> + <pre> <programlisting> + <pre> <literallayout> -<filename> + <ul> <itemizedlist> + <ol> <orderedlist> + <il> <listitem> -<command> <command>g++</command> + <dl> <variablelist> -<errortext> <errortext>foo Concept </errortext> + <varlistentry> + <dt> <term> + </dt> </term> + <dd> <listitem> + </dt> </listitem> + </varlistentry> + <a href <ulink url + <code> <literal> + <code> <programlisting> -General structure + <strong> <emphasis> + <em> <emphasis> + " <quote> -<set> - <book> - </book> + ctype.h <filename class="headerfile"></filename> - <book> - <chapter> - </chapter> - </book> + + build_dir <filename class="directory">path_to_build_dir</filename> + Finer gradations of <code> - <book> - <part> - <chapter> - <section> - </section> + <classname> <classname>string</classname> + <classname>vector<></classname> + <function>fs.clear()</function> - <sect1> - </sect1> + <structname> - <sect1> - <sect2> - </sect2> - </sect1> - </chapter> + <function> <function>clear()</function> - <chapter> - </chapter> - </part> - </book> + <type> <type>long long</type> + <varname> <varname>fs</varname> -</set> + <literal> <literal>-Weffc++</literal> + <literal>rel_ops</literal> -</literallayout> - </sect2> + <constant> <constant>_GNU_SOURCE</constant> + <constant>3.0</constant> - </sect1> + <filename> - <sect1 id="contrib.design_notes" xreflabel="Design Notes"> - <title>Design Notes</title> - <para> - </para> + <command> <command>g++</command> -<literallayout> - -The Library ------------ - -This paper is covers two major areas: - - - Features and policies not mentioned in the standard that - the quality of the library implementation depends on, including - extensions and "implementation-defined" features; - - - Plans for required but unimplemented library features and - optimizations to them. - -Overhead --------- - -The standard defines a large library, much larger than the standard -C library. A naive implementation would suffer substantial overhead -in compile time, executable size, and speed, rendering it unusable -in many (particularly embedded) applications. The alternative demands -care in construction, and some compiler support, but there is no -need for library subsets. - -What are the sources of this overhead? There are four main causes: - - - The library is specified almost entirely as templates, which - with current compilers must be included in-line, resulting in - very slow builds as tens or hundreds of thousands of lines - of function definitions are read for each user source file. - Indeed, the entire SGI STL, as well as the dos Reis valarray, - are provided purely as header files, largely for simplicity in - porting. Iostream/locale is (or will be) as large again. - - - The library is very flexible, specifying a multitude of hooks - where users can insert their own code in place of defaults. - When these hooks are not used, any time and code expended to - support that flexibility is wasted. - - - Templates are often described as causing to "code bloat". In - practice, this refers (when it refers to anything real) to several - independent processes. First, when a class template is manually - instantiated in its entirely, current compilers place the definitions - for all members in a single object file, so that a program linking - to one member gets definitions of all. Second, template functions - which do not actually depend on the template argument are, under - current compilers, generated anew for each instantiation, rather - than being shared with other instantiations. Third, some of the - flexibility mentioned above comes from virtual functions (both in - regular classes and template classes) which current linkers add - to the executable file even when they manifestly cannot be called. - - - The library is specified to use a language feature, exceptions, - which in the current gcc compiler ABI imposes a run time and - code space cost to handle the possibility of exceptions even when - they are not used. Under the new ABI (accessed with -fnew-abi), - there is a space overhead and a small reduction in code efficiency - resulting from lost optimization opportunities associated with - non-local branches associated with exceptions. - -What can be done to eliminate this overhead? A variety of coding -techniques, and compiler, linker and library improvements and -extensions may be used, as covered below. Most are not difficult, -and some are already implemented in varying degrees. - -Overhead: Compilation Time --------------------------- - -Providing "ready-instantiated" template code in object code archives -allows us to avoid generating and optimizing template instantiations -in each compilation unit which uses them. However, the number of such -instantiations that are useful to provide is limited, and anyway this -is not enough, by itself, to minimize compilation time. In particular, -it does not reduce time spent parsing conforming headers. - -Quicker header parsing will depend on library extensions and compiler -improvements. One approach is some variation on the techniques -previously marketed as "pre-compiled headers", now standardized as -support for the "export" keyword. "Exported" template definitions -can be placed (once) in a "repository" -- really just a library, but -of template definitions rather than object code -- to be drawn upon -at link time when an instantiation is needed, rather than placed in -header files to be parsed along with every compilation unit. - -Until "export" is implemented we can put some of the lengthy template -definitions in #if guards or alternative headers so that users can skip -over the the full definitions when they need only the ready-instantiated -specializations. - -To be precise, this means that certain headers which define -templates which users normally use only for certain arguments -can be instrumented to avoid exposing the template definitions -to the compiler unless a macro is defined. For example, in -<string>, we might have: - - template <class _CharT, ... > class basic_string { - ... // member declarations - }; - ... // operator declarations - - #ifdef _STRICT_ISO_ - # if _G_NO_TEMPLATE_EXPORT - # include <bits/std_locale.h> // headers needed by definitions - # ... - # include <bits/string.tcc> // member and global template definitions. - # endif - #endif - -Users who compile without specifying a strict-ISO-conforming flag -would not see many of the template definitions they now see, and rely -instead on ready-instantiated specializations in the library. This -technique would be useful for the following substantial components: -string, locale/iostreams, valarray. It would *not* be useful or -usable with the following: containers, algorithms, iterators, -allocator. Since these constitute a large (though decreasing) -fraction of the library, the benefit the technique offers is -limited. - -The language specifies the semantics of the "export" keyword, but -the gcc compiler does not yet support it. When it does, problems -with large template inclusions can largely disappear, given some -minor library reorganization, along with the need for the apparatus -described above. - -Overhead: Flexibility Cost --------------------------- - -The library offers many places where users can specify operations -to be performed by the library in place of defaults. Sometimes -this seems to require that the library use a more-roundabout, and -possibly slower, way to accomplish the default requirements than -would be used otherwise. - -The primary protection against this overhead is thorough compiler -optimization, to crush out layers of inline function interfaces. -Kuck & Associates has demonstrated the practicality of this kind -of optimization. - -The second line of defense against this overhead is explicit -specialization. By defining helper function templates, and writing -specialized code for the default case, overhead can be eliminated -for that case without sacrificing flexibility. This takes full -advantage of any ability of the optimizer to crush out degenerate -code. - -The library specifies many virtual functions which current linkers -load even when they cannot be called. Some minor improvements to the -compiler and to ld would eliminate any such overhead by simply -omitting virtual functions that the complete program does not call. -A prototype of this work has already been done. For targets where -GNU ld is not used, a "pre-linker" could do the same job. - -The main areas in the standard interface where user flexibility -can result in overhead are: - - - Allocators: Containers are specified to use user-definable - allocator types and objects, making tuning for the container - characteristics tricky. - - - Locales: the standard specifies locale objects used to implement - iostream operations, involving many virtual functions which use - streambuf iterators. - - - Algorithms and containers: these may be instantiated on any type, - frequently duplicating code for identical operations. - - - Iostreams and strings: users are permitted to use these on their - own types, and specify the operations the stream must use on these - types. - -Note that these sources of overhead are _avoidable_. The techniques -to avoid them are covered below. - -Code Bloat ----------- - -In the SGI STL, and in some other headers, many of the templates -are defined "inline" -- either explicitly or by their placement -in class definitions -- which should not be inline. This is a -source of code bloat. Matt had remarked that he was relying on -the compiler to recognize what was too big to benefit from inlining, -and generate it out-of-line automatically. However, this also can -result in code bloat except where the linker can eliminate the extra -copies. - -Fixing these cases will require an audit of all inline functions -defined in the library to determine which merit inlining, and moving -the rest out of line. This is an issue mainly in chapters 23, 25, and -27. Of course it can be done incrementally, and we should generally -accept patches that move large functions out of line and into ".tcc" -files, which can later be pulled into a repository. Compiler/linker -improvements to recognize very large inline functions and move them -out-of-line, but shared among compilation units, could make this -work unnecessary. - -Pre-instantiating template specializations currently produces large -amounts of dead code which bloats statically linked programs. The -current state of the static library, libstdc++.a, is intolerable on -this account, and will fuel further confused speculation about a need -for a library "subset". A compiler improvement that treats each -instantiated function as a separate object file, for linking purposes, -would be one solution to this problem. An alternative would be to -split up the manual instantiation files into dozens upon dozens of -little files, each compiled separately, but an abortive attempt at -this was done for <string> and, though it is far from complete, it -is already a nuisance. A better interim solution (just until we have -"export") is badly needed. - -When building a shared library, the current compiler/linker cannot -automatically generate the instantiatiations needed. This creates a -miserable situation; it means any time something is changed in the -library, before a shared library can be built someone must manually -copy the declarations of all templates that are needed by other parts -of the library to an "instantiation" file, and add it to the build -system to be compiled and linked to the library. This process is -readily automated, and should be automated as soon as possible. -Users building their own shared libraries experience identical -frustrations. - -Sharing common aspects of template definitions among instantiations -can radically reduce code bloat. The compiler could help a great -deal here by recognizing when a function depends on nothing about -a template parameter, or only on its size, and giving the resulting -function a link-name "equate" that allows it to be shared with other -instantiations. Implementation code could take advantage of the -capability by factoring out code that does not depend on the template -argument into separate functions to be merged by the compiler. - -Until such a compiler optimization is implemented, much can be done -manually (if tediously) in this direction. One such optimization is -to derive class templates from non-template classes, and move as much -implementation as possible into the base class. Another is to partial- -specialize certain common instantiations, such as vector<T*>, to share -code for instantiations on all types T. While these techniques work, -they are far from the complete solution that a compiler improvement -would afford. - -Overhead: Expensive Language Features -------------------------------------- - -The main "expensive" language feature used in the standard library -is exception support, which requires compiling in cleanup code with -static table data to locate it, and linking in library code to use -the table. For small embedded programs the amount of such library -code and table data is assumed by some to be excessive. Under the -"new" ABI this perception is generally exaggerated, although in some -cases it may actually be excessive. - -To implement a library which does not use exceptions directly is -not difficult given minor compiler support (to "turn off" exceptions -and ignore exception constructs), and results in no great library -maintenance difficulties. To be precise, given "-fno-exceptions", -the compiler should treat "try" blocks as ordinary blocks, and -"catch" blocks as dead code to ignore or eliminate. Compiler -support is not strictly necessary, except in the case of "function -try blocks"; otherwise the following macros almost suffice: - - #define throw(X) - #define try if (true) - #define catch(X) else if (false) - -However, there may be a need to use function try blocks in the -library implementation, and use of macros in this way can make -correct diagnostics impossible. Furthermore, use of this scheme -would require the library to call a function to re-throw exceptions -from a try block. Implementing the above semantics in the compiler -is preferable. - -Given the support above (however implemented) it only remains to -replace code that "throws" with a call to a well-documented "handler" -function in a separate compilation unit which may be replaced by -the user. The main source of exceptions that would be difficult -for users to avoid is memory allocation failures, but users can -define their own memory allocation primitives that never throw. -Otherwise, the complete list of such handlers, and which library -functions may call them, would be needed for users to be able to -implement the necessary substitutes. (Fortunately, they have the -source code.) - -Opportunities -------------- - -The template capabilities of C++ offer enormous opportunities for -optimizing common library operations, well beyond what would be -considered "eliminating overhead". In particular, many operations -done in Glibc with macros that depend on proprietary language -extensions can be implemented in pristine Standard C++. For example, -the chapter 25 algorithms, and even C library functions such as strchr, -can be specialized for the case of static arrays of known (small) size. - -Detailed optimization opportunities are identified below where -the component where they would appear is discussed. Of course new -opportunities will be identified during implementation. - -Unimplemented Required Library Features ---------------------------------------- - -The standard specifies hundreds of components, grouped broadly by -chapter. These are listed in excruciating detail in the CHECKLIST -file. - - 17 general - 18 support - 19 diagnostics - 20 utilities - 21 string - 22 locale - 23 containers - 24 iterators - 25 algorithms - 26 numerics - 27 iostreams - Annex D backward compatibility - -Anyone participating in implementation of the library should obtain -a copy of the standard, ISO 14882. People in the U.S. can obtain an -electronic copy for US$18 from ANSI's web site. Those from other -countries should visit http://www.iso.ch/ to find out the location -of their country's representation in ISO, in order to know who can -sell them a copy. - -The emphasis in the following sections is on unimplemented features -and optimization opportunities. - -Chapter 17 General -------------------- - -Chapter 17 concerns overall library requirements. - -The standard doesn't mention threads. A multi-thread (MT) extension -primarily affects operators new and delete (18), allocator (20), -string (21), locale (22), and iostreams (27). The common underlying -support needed for this is discussed under chapter 20. - -The standard requirements on names from the C headers create a -lot of work, mostly done. Names in the C headers must be visible -in the std:: and sometimes the global namespace; the names in the -two scopes must refer to the same object. More stringent is that -Koenig lookup implies that any types specified as defined in std:: -really are defined in std::. Names optionally implemented as -macros in C cannot be macros in C++. (An overview may be read at -<http://www.cantrip.org/cheaders.html>). The scripts "inclosure" -and "mkcshadow", and the directories shadow/ and cshadow/, are the -beginning of an effort to conform in this area. - -A correct conforming definition of C header names based on underlying -C library headers, and practical linking of conforming namespaced -customer code with third-party C libraries depends ultimately on -an ABI change, allowing namespaced C type names to be mangled into -type names as if they were global, somewhat as C function names in a -namespace, or C++ global variable names, are left unmangled. Perhaps -another "extern" mode, such as 'extern "C-global"' would be an -appropriate place for such type definitions. Such a type would -affect mangling as follows: - - namespace A { + <errortext> <errortext>foo Concept </errortext> +</literallayout> + </sect3> + </sect2> + +</sect1> + +<sect1 id="contrib.design_notes" xreflabel="Design Notes"> + <title>Design Notes</title> + <para> + </para> + + <literallayout> + + The Library + ----------- + + This paper is covers two major areas: + + - Features and policies not mentioned in the standard that + the quality of the library implementation depends on, including + extensions and "implementation-defined" features; + + - Plans for required but unimplemented library features and + optimizations to them. + + Overhead + -------- + + The standard defines a large library, much larger than the standard + C library. A naive implementation would suffer substantial overhead + in compile time, executable size, and speed, rendering it unusable + in many (particularly embedded) applications. The alternative demands + care in construction, and some compiler support, but there is no + need for library subsets. + + What are the sources of this overhead? There are four main causes: + + - The library is specified almost entirely as templates, which + with current compilers must be included in-line, resulting in + very slow builds as tens or hundreds of thousands of lines + of function definitions are read for each user source file. + Indeed, the entire SGI STL, as well as the dos Reis valarray, + are provided purely as header files, largely for simplicity in + porting. Iostream/locale is (or will be) as large again. + + - The library is very flexible, specifying a multitude of hooks + where users can insert their own code in place of defaults. + When these hooks are not used, any time and code expended to + support that flexibility is wasted. + + - Templates are often described as causing to "code bloat". In + practice, this refers (when it refers to anything real) to several + independent processes. First, when a class template is manually + instantiated in its entirely, current compilers place the definitions + for all members in a single object file, so that a program linking + to one member gets definitions of all. Second, template functions + which do not actually depend on the template argument are, under + current compilers, generated anew for each instantiation, rather + than being shared with other instantiations. Third, some of the + flexibility mentioned above comes from virtual functions (both in + regular classes and template classes) which current linkers add + to the executable file even when they manifestly cannot be called. + + - The library is specified to use a language feature, exceptions, + which in the current gcc compiler ABI imposes a run time and + code space cost to handle the possibility of exceptions even when + they are not used. Under the new ABI (accessed with -fnew-abi), + there is a space overhead and a small reduction in code efficiency + resulting from lost optimization opportunities associated with + non-local branches associated with exceptions. + + What can be done to eliminate this overhead? A variety of coding + techniques, and compiler, linker and library improvements and + extensions may be used, as covered below. Most are not difficult, + and some are already implemented in varying degrees. + + Overhead: Compilation Time + -------------------------- + + Providing "ready-instantiated" template code in object code archives + allows us to avoid generating and optimizing template instantiations + in each compilation unit which uses them. However, the number of such + instantiations that are useful to provide is limited, and anyway this + is not enough, by itself, to minimize compilation time. In particular, + it does not reduce time spent parsing conforming headers. + + Quicker header parsing will depend on library extensions and compiler + improvements. One approach is some variation on the techniques + previously marketed as "pre-compiled headers", now standardized as + support for the "export" keyword. "Exported" template definitions + can be placed (once) in a "repository" -- really just a library, but + of template definitions rather than object code -- to be drawn upon + at link time when an instantiation is needed, rather than placed in + header files to be parsed along with every compilation unit. + + Until "export" is implemented we can put some of the lengthy template + definitions in #if guards or alternative headers so that users can skip + over the full definitions when they need only the ready-instantiated + specializations. + + To be precise, this means that certain headers which define + templates which users normally use only for certain arguments + can be instrumented to avoid exposing the template definitions + to the compiler unless a macro is defined. For example, in + <string>, we might have: + + template <class _CharT, ... > class basic_string { + ... // member declarations + }; + ... // operator declarations + + #ifdef _STRICT_ISO_ + # if _G_NO_TEMPLATE_EXPORT + # include <bits/std_locale.h> // headers needed by definitions + # ... + # include <bits/string.tcc> // member and global template definitions. + # endif + #endif + + Users who compile without specifying a strict-ISO-conforming flag + would not see many of the template definitions they now see, and rely + instead on ready-instantiated specializations in the library. This + technique would be useful for the following substantial components: + string, locale/iostreams, valarray. It would *not* be useful or + usable with the following: containers, algorithms, iterators, + allocator. Since these constitute a large (though decreasing) + fraction of the library, the benefit the technique offers is + limited. + + The language specifies the semantics of the "export" keyword, but + the gcc compiler does not yet support it. When it does, problems + with large template inclusions can largely disappear, given some + minor library reorganization, along with the need for the apparatus + described above. + + Overhead: Flexibility Cost + -------------------------- + + The library offers many places where users can specify operations + to be performed by the library in place of defaults. Sometimes + this seems to require that the library use a more-roundabout, and + possibly slower, way to accomplish the default requirements than + would be used otherwise. + + The primary protection against this overhead is thorough compiler + optimization, to crush out layers of inline function interfaces. + Kuck & Associates has demonstrated the practicality of this kind + of optimization. + + The second line of defense against this overhead is explicit + specialization. By defining helper function templates, and writing + specialized code for the default case, overhead can be eliminated + for that case without sacrificing flexibility. This takes full + advantage of any ability of the optimizer to crush out degenerate + code. + + The library specifies many virtual functions which current linkers + load even when they cannot be called. Some minor improvements to the + compiler and to ld would eliminate any such overhead by simply + omitting virtual functions that the complete program does not call. + A prototype of this work has already been done. For targets where + GNU ld is not used, a "pre-linker" could do the same job. + + The main areas in the standard interface where user flexibility + can result in overhead are: + + - Allocators: Containers are specified to use user-definable + allocator types and objects, making tuning for the container + characteristics tricky. + + - Locales: the standard specifies locale objects used to implement + iostream operations, involving many virtual functions which use + streambuf iterators. + + - Algorithms and containers: these may be instantiated on any type, + frequently duplicating code for identical operations. + + - Iostreams and strings: users are permitted to use these on their + own types, and specify the operations the stream must use on these + types. + + Note that these sources of overhead are _avoidable_. The techniques + to avoid them are covered below. + + Code Bloat + ---------- + + In the SGI STL, and in some other headers, many of the templates + are defined "inline" -- either explicitly or by their placement + in class definitions -- which should not be inline. This is a + source of code bloat. Matt had remarked that he was relying on + the compiler to recognize what was too big to benefit from inlining, + and generate it out-of-line automatically. However, this also can + result in code bloat except where the linker can eliminate the extra + copies. + + Fixing these cases will require an audit of all inline functions + defined in the library to determine which merit inlining, and moving + the rest out of line. This is an issue mainly in chapters 23, 25, and + 27. Of course it can be done incrementally, and we should generally + accept patches that move large functions out of line and into ".tcc" + files, which can later be pulled into a repository. Compiler/linker + improvements to recognize very large inline functions and move them + out-of-line, but shared among compilation units, could make this + work unnecessary. + + Pre-instantiating template specializations currently produces large + amounts of dead code which bloats statically linked programs. The + current state of the static library, libstdc++.a, is intolerable on + this account, and will fuel further confused speculation about a need + for a library "subset". A compiler improvement that treats each + instantiated function as a separate object file, for linking purposes, + would be one solution to this problem. An alternative would be to + split up the manual instantiation files into dozens upon dozens of + little files, each compiled separately, but an abortive attempt at + this was done for <string> and, though it is far from complete, it + is already a nuisance. A better interim solution (just until we have + "export") is badly needed. + + When building a shared library, the current compiler/linker cannot + automatically generate the instantiatiations needed. This creates a + miserable situation; it means any time something is changed in the + library, before a shared library can be built someone must manually + copy the declarations of all templates that are needed by other parts + of the library to an "instantiation" file, and add it to the build + system to be compiled and linked to the library. This process is + readily automated, and should be automated as soon as possible. + Users building their own shared libraries experience identical + frustrations. + + Sharing common aspects of template definitions among instantiations + can radically reduce code bloat. The compiler could help a great + deal here by recognizing when a function depends on nothing about + a template parameter, or only on its size, and giving the resulting + function a link-name "equate" that allows it to be shared with other + instantiations. Implementation code could take advantage of the + capability by factoring out code that does not depend on the template + argument into separate functions to be merged by the compiler. + + Until such a compiler optimization is implemented, much can be done + manually (if tediously) in this direction. One such optimization is + to derive class templates from non-template classes, and move as much + implementation as possible into the base class. Another is to partial- + specialize certain common instantiations, such as vector<T*>, to share + code for instantiations on all types T. While these techniques work, + they are far from the complete solution that a compiler improvement + would afford. + + Overhead: Expensive Language Features + ------------------------------------- + + The main "expensive" language feature used in the standard library + is exception support, which requires compiling in cleanup code with + static table data to locate it, and linking in library code to use + the table. For small embedded programs the amount of such library + code and table data is assumed by some to be excessive. Under the + "new" ABI this perception is generally exaggerated, although in some + cases it may actually be excessive. + + To implement a library which does not use exceptions directly is + not difficult given minor compiler support (to "turn off" exceptions + and ignore exception constructs), and results in no great library + maintenance difficulties. To be precise, given "-fno-exceptions", + the compiler should treat "try" blocks as ordinary blocks, and + "catch" blocks as dead code to ignore or eliminate. Compiler + support is not strictly necessary, except in the case of "function + try blocks"; otherwise the following macros almost suffice: + + #define throw(X) + #define try if (true) + #define catch(X) else if (false) + + However, there may be a need to use function try blocks in the + library implementation, and use of macros in this way can make + correct diagnostics impossible. Furthermore, use of this scheme + would require the library to call a function to re-throw exceptions + from a try block. Implementing the above semantics in the compiler + is preferable. + + Given the support above (however implemented) it only remains to + replace code that "throws" with a call to a well-documented "handler" + function in a separate compilation unit which may be replaced by + the user. The main source of exceptions that would be difficult + for users to avoid is memory allocation failures, but users can + define their own memory allocation primitives that never throw. + Otherwise, the complete list of such handlers, and which library + functions may call them, would be needed for users to be able to + implement the necessary substitutes. (Fortunately, they have the + source code.) + + Opportunities + ------------- + + The template capabilities of C++ offer enormous opportunities for + optimizing common library operations, well beyond what would be + considered "eliminating overhead". In particular, many operations + done in Glibc with macros that depend on proprietary language + extensions can be implemented in pristine Standard C++. For example, + the chapter 25 algorithms, and even C library functions such as strchr, + can be specialized for the case of static arrays of known (small) size. + + Detailed optimization opportunities are identified below where + the component where they would appear is discussed. Of course new + opportunities will be identified during implementation. + + Unimplemented Required Library Features + --------------------------------------- + + The standard specifies hundreds of components, grouped broadly by + chapter. These are listed in excruciating detail in the CHECKLIST + file. + + 17 general + 18 support + 19 diagnostics + 20 utilities + 21 string + 22 locale + 23 containers + 24 iterators + 25 algorithms + 26 numerics + 27 iostreams + Annex D backward compatibility + + Anyone participating in implementation of the library should obtain + a copy of the standard, ISO 14882. People in the U.S. can obtain an + electronic copy for US$18 from ANSI's web site. Those from other + countries should visit http://www.iso.ch/ to find out the location + of their country's representation in ISO, in order to know who can + sell them a copy. + + The emphasis in the following sections is on unimplemented features + and optimization opportunities. + + Chapter 17 General + ------------------- + + Chapter 17 concerns overall library requirements. + + The standard doesn't mention threads. A multi-thread (MT) extension + primarily affects operators new and delete (18), allocator (20), + string (21), locale (22), and iostreams (27). The common underlying + support needed for this is discussed under chapter 20. + + The standard requirements on names from the C headers create a + lot of work, mostly done. Names in the C headers must be visible + in the std:: and sometimes the global namespace; the names in the + two scopes must refer to the same object. More stringent is that + Koenig lookup implies that any types specified as defined in std:: + really are defined in std::. Names optionally implemented as + macros in C cannot be macros in C++. (An overview may be read at + <http://www.cantrip.org/cheaders.html>). The scripts "inclosure" + and "mkcshadow", and the directories shadow/ and cshadow/, are the + beginning of an effort to conform in this area. + + A correct conforming definition of C header names based on underlying + C library headers, and practical linking of conforming namespaced + customer code with third-party C libraries depends ultimately on + an ABI change, allowing namespaced C type names to be mangled into + type names as if they were global, somewhat as C function names in a + namespace, or C++ global variable names, are left unmangled. Perhaps + another "extern" mode, such as 'extern "C-global"' would be an + appropriate place for such type definitions. Such a type would + affect mangling as follows: + + namespace A { struct X {}; extern "C-global" { // or maybe just 'extern "C"' - struct Y {}; + struct Y {}; }; - } - void f(A::X*); // mangles to f__FPQ21A1X - void f(A::Y*); // mangles to f__FP1Y - -(It may be that this is really the appropriate semantics for regular -'extern "C"', and 'extern "C-global"', as an extension, would not be -necessary.) This would allow functions declared in non-standard C headers -(and thus fixable by neither us nor users) to link properly with functions -declared using C types defined in properly-namespaced headers. The -problem this solves is that C headers (which C++ programmers do persist -in using) frequently forward-declare C struct tags without including -the header where the type is defined, as in - - struct tm; - void munge(tm*); - -Without some compiler accommodation, munge cannot be called by correct -C++ code using a pointer to a correctly-scoped tm* value. - -The current C headers use the preprocessor extension "#include_next", -which the compiler complains about when run "-pedantic". -(Incidentally, it appears that "-fpedantic" is currently ignored, -probably a bug.) The solution in the C compiler is to use -"-isystem" rather than "-I", but unfortunately in g++ this seems -also to wrap the whole header in an 'extern "C"' block, so it's -unusable for C++ headers. The correct solution appears to be to -allow the various special include-directory options, if not given -an argument, to affect subsequent include-directory options additively, -so that if one said - - -pedantic -iprefix $(prefix) \ - -idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \ - -iwithprefix -I g++-v3/ext - -the compiler would search $(prefix)/g++-v3 and not report -pedantic warnings for files found there, but treat files in -$(prefix)/g++-v3/ext pedantically. (The undocumented semantics -of "-isystem" in g++ stink. Can they be rescinded? If not it -must be replaced with something more rationally behaved.) - -All the C headers need the treatment above; in the standard these -headers are mentioned in various chapters. Below, I have only -mentioned those that present interesting implementation issues. - -The components identified as "mostly complete", below, have not been -audited for conformance. In many cases where the library passes -conformance tests we have non-conforming extensions that must be -wrapped in #if guards for "pedantic" use, and in some cases renamed -in a conforming way for continued use in the implementation regardless -of conformance flags. - -The STL portion of the library still depends on a header -stl/bits/stl_config.h full of #ifdef clauses. This apparatus -should be replaced with autoconf/automake machinery. - -The SGI STL defines a type_traits<> template, specialized for -many types in their code including the built-in numeric and -pointer types and some library types, to direct optimizations of -standard functions. The SGI compiler has been extended to generate -specializations of this template automatically for user types, -so that use of STL templates on user types can take advantage of -these optimizations. Specializations for other, non-STL, types -would make more optimizations possible, but extending the gcc -compiler in the same way would be much better. Probably the next -round of standardization will ratify this, but probably with -changes, so it probably should be renamed to place it in the -implementation namespace. - -The SGI STL also defines a large number of extensions visible in -standard headers. (Other extensions that appear in separate headers -have been sequestered in subdirectories ext/ and backward/.) All -these extensions should be moved to other headers where possible, -and in any case wrapped in a namespace (not std!), and (where kept -in a standard header) girded about with macro guards. Some cannot be -moved out of standard headers because they are used to implement -standard features. The canonical method for accommodating these -is to use a protected name, aliased in macro guards to a user-space -name. Unfortunately C++ offers no satisfactory template typedef -mechanism, so very ad-hoc and unsatisfactory aliasing must be used -instead. - -Implementation of a template typedef mechanism should have the highest -priority among possible extensions, on the same level as implementation -of the template "export" feature. - -Chapter 18 Language support ----------------------------- - -Headers: <limits> <new> <typeinfo> <exception> -C headers: <cstddef> <climits> <cfloat> <cstdarg> <csetjmp> - <ctime> <csignal> <cstdlib> (also 21, 25, 26) - -This defines the built-in exceptions, rtti, numeric_limits<>, -operator new and delete. Much of this is provided by the -compiler in its static runtime library. - -Work to do includes defining numeric_limits<> specializations in -separate files for all target architectures. Values for integer types -except for bool and wchar_t are readily obtained from the C header -<limits.h>, but values for the remaining numeric types (bool, wchar_t, -float, double, long double) must be entered manually. This is -largely dog work except for those members whose values are not -easily deduced from available documentation. Also, this involves -some work in target configuration to identify the correct choice of -file to build against and to install. - -The definitions of the various operators new and delete must be -made thread-safe, which depends on a portable exclusion mechanism, -discussed under chapter 20. Of course there is always plenty of -room for improvements to the speed of operators new and delete. - -<cstdarg>, in Glibc, defines some macros that gcc does not allow to -be wrapped into an inline function. Probably this header will demand -attention whenever a new target is chosen. The functions atexit(), -exit(), and abort() in cstdlib have different semantics in C++, so -must be re-implemented for C++. - -Chapter 19 Diagnostics ------------------------ - -Headers: <stdexcept> -C headers: <cassert> <cerrno> - -This defines the standard exception objects, which are "mostly complete". -Cygnus has a version, and now SGI provides a slightly different one. -It makes little difference which we use. - -The C global name "errno", which C allows to be a variable or a macro, -is required in C++ to be a macro. For MT it must typically result in -a function call. - -Chapter 20 Utilities ---------------------- -Headers: <utility> <functional> <memory> -C header: <ctime> (also in 18) - -SGI STL provides "mostly complete" versions of all the components -defined in this chapter. However, the auto_ptr<> implementation -is known to be wrong. Furthermore, the standard definition of it -is known to be unimplementable as written. A minor change to the -standard would fix it, and auto_ptr<> should be adjusted to match. - -Multi-threading affects the allocator implementation, and there must -be configuration/installation choices for different users' MT -requirements. Anyway, users will want to tune allocator options -to support different target conditions, MT or no. - -The primitives used for MT implementation should be exposed, as an -extension, for users' own work. We need cross-CPU "mutex" support, -multi-processor shared-memory atomic integer operations, and single- -processor uninterruptible integer operations, and all three configurable -to be stubbed out for non-MT use, or to use an appropriately-loaded -dynamic library for the actual runtime environment, or statically -compiled in for cases where the target architecture is known. - -Chapter 21 String ------------------- -Headers: <string> -C headers: <cctype> <cwctype> <cstring> <cwchar> (also in 27) - <cstdlib> (also in 18, 25, 26) - -We have "mostly-complete" char_traits<> implementations. Many of the -char_traits<char> operations might be optimized further using existing -proprietary language extensions. - -We have a "mostly-complete" basic_string<> implementation. The work -to manually instantiate char and wchar_t specializations in object -files to improve link-time behavior is extremely unsatisfactory, -literally tripling library-build time with no commensurate improvement -in static program link sizes. It must be redone. (Similar work is -needed for some components in chapters 22 and 27.) - -Other work needed for strings is MT-safety, as discussed under the -chapter 20 heading. - -The standard C type mbstate_t from <cwchar> and used in char_traits<> -must be different in C++ than in C, because in C++ the default constructor -value mbstate_t() must be the "base" or "ground" sequence state. -(According to the likely resolution of a recently raised Core issue, -this may become unnecessary. However, there are other reasons to -use a state type not as limited as whatever the C library provides.) -If we might want to provide conversions from (e.g.) internally- -represented EUC-wide to externally-represented Unicode, or vice- -versa, the mbstate_t we choose will need to be more accommodating -than what might be provided by an underlying C library. - -There remain some basic_string template-member functions which do -not overload properly with their non-template brethren. The infamous -hack akin to what was done in vector<> is needed, to conform to -23.1.1 para 10. The CHECKLIST items for basic_string marked 'X', -or incomplete, are so marked for this reason. - -Replacing the string iterators, which currently are simple character -pointers, with class objects would greatly increase the safety of the -client interface, and also permit a "debug" mode in which range, -ownership, and validity are rigorously checked. The current use of -raw pointers as string iterators is evil. vector<> iterators need the -same treatment. Note that the current implementation freely mixes -pointers and iterators, and that must be fixed before safer iterators -can be introduced. - -Some of the functions in <cstring> are different from the C version. -generally overloaded on const and non-const argument pointers. For -example, in <cstring> strchr is overloaded. The functions isupper -etc. in <cctype> typically implemented as macros in C are functions -in C++, because they are overloaded with others of the same name -defined in <locale>. - -Many of the functions required in <cwctype> and <cwchar> cannot be -implemented using underlying C facilities on intended targets because -such facilities only partly exist. - -Chapter 22 Locale ------------------- -Headers: <locale> -C headers: <clocale> - -We have a "mostly complete" class locale, with the exception of -code for constructing, and handling the names of, named locales. -The ways that locales are named (particularly when categories -(e.g. LC_TIME, LC_COLLATE) are different) varies among all target -environments. This code must be written in various versions and -chosen by configuration parameters. - -Members of many of the facets defined in <locale> are stubs. Generally, -there are two sets of facets: the base class facets (which are supposed -to implement the "C" locale) and the "byname" facets, which are supposed -to read files to determine their behavior. The base ctype<>, collate<>, -and numpunct<> facets are "mostly complete", except that the table of -bitmask values used for "is" operations, and corresponding mask values, -are still defined in libio and just included/linked. (We will need to -implement these tables independently, soon, but should take advantage -of libio where possible.) The num_put<>::put members for integer types -are "mostly complete". - -A complete list of what has and has not been implemented may be -found in CHECKLIST. However, note that the current definition of -codecvt<wchar_t,char,mbstate_t> is wrong. It should simply write -out the raw bytes representing the wide characters, rather than -trying to convert each to a corresponding single "char" value. - -Some of the facets are more important than others. Specifically, -the members of ctype<>, numpunct<>, num_put<>, and num_get<> facets -are used by other library facilities defined in <string>, <istream>, -and <ostream>, and the codecvt<> facet is used by basic_filebuf<> -in <fstream>, so a conforming iostream implementation depends on -these. - -The "long long" type eventually must be supported, but code mentioning -it should be wrapped in #if guards to allow pedantic-mode compiling. - -Performance of num_put<> and num_get<> depend critically on -caching computed values in ios_base objects, and on extensions -to the interface with streambufs. - -Specifically: retrieving a copy of the locale object, extracting -the needed facets, and gathering data from them, for each call to -(e.g.) operator<< would be prohibitively slow. To cache format -data for use by num_put<> and num_get<> we have a _Format_cache<> -object stored in the ios_base::pword() array. This is constructed -and initialized lazily, and is organized purely for utility. It -is discarded when a new locale with different facets is imbued. - -Using only the public interfaces of the iterator arguments to the -facet functions would limit performance by forbidding "vector-style" -character operations. The streambuf iterator optimizations are -described under chapter 24, but facets can also bypass the streambuf -iterators via explicit specializations and operate directly on the -streambufs, and use extended interfaces to get direct access to the -streambuf internal buffer arrays. These extensions are mentioned -under chapter 27. These optimizations are particularly important -for input parsing. - -Unused virtual members of locale facets can be omitted, as mentioned -above, by a smart linker. - -Chapter 23 Containers ----------------------- -Headers: <deque> <list> <queue> <stack> <vector> <map> <set> <bitset> - -All the components in chapter 23 are implemented in the SGI STL. -They are "mostly complete"; they include a large number of -nonconforming extensions which must be wrapped. Some of these -are used internally and must be renamed or duplicated. - -The SGI components are optimized for large-memory environments. For -embedded targets, different criteria might be more appropriate. Users -will want to be able to tune this behavior. We should provide -ways for users to compile the library with different memory usage -characteristics. - -A lot more work is needed on factoring out common code from different -specializations to reduce code size here and in chapter 25. The -easiest fix for this would be a compiler/ABI improvement that allows -the compiler to recognize when a specialization depends only on the -size (or other gross quality) of a template argument, and allow the -linker to share the code with similar specializations. In its -absence, many of the algorithms and containers can be partial- -specialized, at least for the case of pointers, but this only solves -a small part of the problem. Use of a type_traits-style template -allows a few more optimization opportunities, more if the compiler -can generate the specializations automatically. - -As an optimization, containers can specialize on the default allocator -and bypass it, or take advantage of details of its implementation -after it has been improved upon. - -Replacing the vector iterators, which currently are simple element -pointers, with class objects would greatly increase the safety of the -client interface, and also permit a "debug" mode in which range, -ownership, and validity are rigorously checked. The current use of -pointers for iterators is evil. - -As mentioned for chapter 24, the deque iterator is a good example of -an opportunity to implement a "staged" iterator that would benefit -from specializations of some algorithms. - -Chapter 24 Iterators ---------------------- -Headers: <iterator> - -Standard iterators are "mostly complete", with the exception of -the stream iterators, which are not yet templatized on the -stream type. Also, the base class template iterator<> appears -to be wrong, so everything derived from it must also be wrong, -currently. - -The streambuf iterators (currently located in stl/bits/std_iterator.h, -but should be under bits/) can be rewritten to take advantage of -friendship with the streambuf implementation. - -Matt Austern has identified opportunities where certain iterator -types, particularly including streambuf iterators and deque -iterators, have a "two-stage" quality, such that an intermediate -limit can be checked much more quickly than the true limit on -range operations. If identified with a member of iterator_traits, -algorithms may be specialized for this case. Of course the -iterators that have this quality can be identified by specializing -a traits class. - -Many of the algorithms must be specialized for the streambuf -iterators, to take advantage of block-mode operations, in order -to allow iostream/locale operations' performance not to suffer. -It may be that they could be treated as staged iterators and -take advantage of those optimizations. - -Chapter 25 Algorithms ----------------------- -Headers: <algorithm> -C headers: <cstdlib> (also in 18, 21, 26)) - -The algorithms are "mostly complete". As mentioned above, they -are optimized for speed at the expense of code and data size. - -Specializations of many of the algorithms for non-STL types would -give performance improvements, but we must use great care not to -interfere with fragile template overloading semantics for the -standard interfaces. Conventionally the standard function template -interface is an inline which delegates to a non-standard function -which is then overloaded (this is already done in many places in -the library). Particularly appealing opportunities for the sake of -iostream performance are for copy and find applied to streambuf -iterators or (as noted elsewhere) for staged iterators, of which -the streambuf iterators are a good example. - -The bsearch and qsort functions cannot be overloaded properly as -required by the standard because gcc does not yet allow overloading -on the extern-"C"-ness of a function pointer. - -Chapter 26 Numerics --------------------- -Headers: <complex> <valarray> <numeric> -C headers: <cmath>, <cstdlib> (also 18, 21, 25) - -Numeric components: Gabriel dos Reis's valarray, Drepper's complex, -and the few algorithms from the STL are "mostly done". Of course -optimization opportunities abound for the numerically literate. It -is not clear whether the valarray implementation really conforms -fully, in the assumptions it makes about aliasing (and lack thereof) -in its arguments. - -The C div() and ldiv() functions are interesting, because they are the -only case where a C library function returns a class object by value. -Since the C++ type div_t must be different from the underlying C type -(which is in the wrong namespace) the underlying functions div() and -ldiv() cannot be re-used efficiently. Fortunately they are trivial to -re-implement. - -Chapter 27 Iostreams ---------------------- -Headers: <iosfwd> <streambuf> <ios> <ostream> <istream> <iostream> - <iomanip> <sstream> <fstream> -C headers: <cstdio> <cwchar> (also in 21) - -Iostream is currently in a very incomplete state. <iosfwd>, <iomanip>, -ios_base, and basic_ios<> are "mostly complete". basic_streambuf<> and -basic_ostream<> are well along, but basic_istream<> has had little work -done. The standard stream objects, <sstream> and <fstream> have been -started; basic_filebuf<> "write" functions have been implemented just -enough to do "hello, world". - -Most of the istream and ostream operators << and >> (with the exception -of the op<<(integer) ones) have not been changed to use locale primitives, -sentry objects, or char_traits members. - -All these templates should be manually instantiated for char and -wchar_t in a way that links only used members into user programs. - -Streambuf is fertile ground for optimization extensions. An extended -interface giving iterator access to its internal buffer would be very -useful for other library components. - -Iostream operations (primarily operators << and >>) can take advantage -of the case where user code has not specified a locale, and bypass locale -operations entirely. The current implementation of op<</num_put<>::put, -for the integer types, demonstrates how they can cache encoding details -from the locale on each operation. There is lots more room for -optimization in this area. - -The definition of the relationship between the standard streams -cout et al. and stdout et al. requires something like a "stdiobuf". -The SGI solution of using double-indirection to actually use a -stdio FILE object for buffering is unsatisfactory, because it -interferes with peephole loop optimizations. - -The <sstream> header work has begun. stringbuf can benefit from -friendship with basic_string<> and basic_string<>::_Rep to use -those objects directly as buffers, and avoid allocating and making -copies. - -The basic_filebuf<> template is a complex beast. It is specified to -use the locale facet codecvt<> to translate characters between native -files and the locale character encoding. In general this involves -two buffers, one of "char" representing the file and another of -"char_type", for the stream, with codecvt<> translating. The process -is complicated by the variable-length nature of the translation, and -the need to seek to corresponding places in the two representations. -For the case of basic_filebuf<char>, when no translation is needed, -a single buffer suffices. A specialized filebuf can be used to reduce -code space overhead when no locale has been imbued. Matt Austern's -work at SGI will be useful, perhaps directly as a source of code, or -at least as an example to draw on. - -Filebuf, almost uniquely (cf. operator new), depends heavily on -underlying environmental facilities. In current releases iostream -depends fairly heavily on libio constant definitions, but it should -be made independent. It also depends on operating system primitives -for file operations. There is immense room for optimizations using -(e.g.) mmap for reading. The shadow/ directory wraps, besides the -standard C headers, the libio.h and unistd.h headers, for use mainly -by filebuf. These wrappings have not been completed, though there -is scaffolding in place. - -The encapulation of certain C header <cstdio> names presents an -interesting problem. It is possible to define an inline std::fprintf() -implemented in terms of the 'extern "C"' vfprintf(), but there is no -standard vfscanf() to use to implement std::fscanf(). It appears that -vfscanf but be re-implemented in C++ for targets where no vfscanf -extension has been defined. This is interesting in that it seems -to be the only significant case in the C library where this kind of -rewriting is necessary. (Of course Glibc provides the vfscanf() -extension.) (The functions related to exit() must be rewritten -for other reasons.) - - -Annex D -------- -Headers: <strstream> - -Annex D defines many non-library features, and many minor -modifications to various headers, and a complete header. -It is "mostly done", except that the libstdc++-2 <strstream> -header has not been adopted into the library, or checked to -verify that it matches the draft in those details that were -clarified by the committee. Certainly it must at least be -moved into the std namespace. - -We still need to wrap all the deprecated features in #if guards -so that pedantic compile modes can detect their use. - -Nonstandard Extensions ----------------------- -Headers: <iostream.h> <strstream.h> <hash> <rbtree> - <pthread_alloc> <stdiobuf> (etc.) - -User code has come to depend on a variety of nonstandard components -that we must not omit. Much of this code can be adopted from -libstdc++-v2 or from the SGI STL. This particularly includes -<iostream.h>, <strstream.h>, and various SGI extensions such -as <hash_map.h>. Many of these are already placed in the -subdirectories ext/ and backward/. (Note that it is better to -include them via "<backward/hash_map.h>" or "<ext/hash_map>" than -to search the subdirectory itself via a "-I" directive. -</literallayout> - </sect1> + } + void f(A::X*); // mangles to f__FPQ21A1X + void f(A::Y*); // mangles to f__FP1Y + + (It may be that this is really the appropriate semantics for regular + 'extern "C"', and 'extern "C-global"', as an extension, would not be + necessary.) This would allow functions declared in non-standard C headers + (and thus fixable by neither us nor users) to link properly with functions + declared using C types defined in properly-namespaced headers. The + problem this solves is that C headers (which C++ programmers do persist + in using) frequently forward-declare C struct tags without including + the header where the type is defined, as in + + struct tm; + void munge(tm*); + + Without some compiler accommodation, munge cannot be called by correct + C++ code using a pointer to a correctly-scoped tm* value. + + The current C headers use the preprocessor extension "#include_next", + which the compiler complains about when run "-pedantic". + (Incidentally, it appears that "-fpedantic" is currently ignored, + probably a bug.) The solution in the C compiler is to use + "-isystem" rather than "-I", but unfortunately in g++ this seems + also to wrap the whole header in an 'extern "C"' block, so it's + unusable for C++ headers. The correct solution appears to be to + allow the various special include-directory options, if not given + an argument, to affect subsequent include-directory options additively, + so that if one said + + -pedantic -iprefix $(prefix) \ + -idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \ + -iwithprefix -I g++-v3/ext + + the compiler would search $(prefix)/g++-v3 and not report + pedantic warnings for files found there, but treat files in + $(prefix)/g++-v3/ext pedantically. (The undocumented semantics + of "-isystem" in g++ stink. Can they be rescinded? If not it + must be replaced with something more rationally behaved.) + + All the C headers need the treatment above; in the standard these + headers are mentioned in various chapters. Below, I have only + mentioned those that present interesting implementation issues. + + The components identified as "mostly complete", below, have not been + audited for conformance. In many cases where the library passes + conformance tests we have non-conforming extensions that must be + wrapped in #if guards for "pedantic" use, and in some cases renamed + in a conforming way for continued use in the implementation regardless + of conformance flags. + + The STL portion of the library still depends on a header + stl/bits/stl_config.h full of #ifdef clauses. This apparatus + should be replaced with autoconf/automake machinery. + + The SGI STL defines a type_traits<> template, specialized for + many types in their code including the built-in numeric and + pointer types and some library types, to direct optimizations of + standard functions. The SGI compiler has been extended to generate + specializations of this template automatically for user types, + so that use of STL templates on user types can take advantage of + these optimizations. Specializations for other, non-STL, types + would make more optimizations possible, but extending the gcc + compiler in the same way would be much better. Probably the next + round of standardization will ratify this, but probably with + changes, so it probably should be renamed to place it in the + implementation namespace. + + The SGI STL also defines a large number of extensions visible in + standard headers. (Other extensions that appear in separate headers + have been sequestered in subdirectories ext/ and backward/.) All + these extensions should be moved to other headers where possible, + and in any case wrapped in a namespace (not std!), and (where kept + in a standard header) girded about with macro guards. Some cannot be + moved out of standard headers because they are used to implement + standard features. The canonical method for accommodating these + is to use a protected name, aliased in macro guards to a user-space + name. Unfortunately C++ offers no satisfactory template typedef + mechanism, so very ad-hoc and unsatisfactory aliasing must be used + instead. + + Implementation of a template typedef mechanism should have the highest + priority among possible extensions, on the same level as implementation + of the template "export" feature. + + Chapter 18 Language support + ---------------------------- + + Headers: <limits> <new> <typeinfo> <exception> + C headers: <cstddef> <climits> <cfloat> <cstdarg> <csetjmp> + <ctime> <csignal> <cstdlib> (also 21, 25, 26) + + This defines the built-in exceptions, rtti, numeric_limits<>, + operator new and delete. Much of this is provided by the + compiler in its static runtime library. + + Work to do includes defining numeric_limits<> specializations in + separate files for all target architectures. Values for integer types + except for bool and wchar_t are readily obtained from the C header + <limits.h>, but values for the remaining numeric types (bool, wchar_t, + float, double, long double) must be entered manually. This is + largely dog work except for those members whose values are not + easily deduced from available documentation. Also, this involves + some work in target configuration to identify the correct choice of + file to build against and to install. + + The definitions of the various operators new and delete must be + made thread-safe, which depends on a portable exclusion mechanism, + discussed under chapter 20. Of course there is always plenty of + room for improvements to the speed of operators new and delete. + + <cstdarg>, in Glibc, defines some macros that gcc does not allow to + be wrapped into an inline function. Probably this header will demand + attention whenever a new target is chosen. The functions atexit(), + exit(), and abort() in cstdlib have different semantics in C++, so + must be re-implemented for C++. + + Chapter 19 Diagnostics + ----------------------- + + Headers: <stdexcept> + C headers: <cassert> <cerrno> + + This defines the standard exception objects, which are "mostly complete". + Cygnus has a version, and now SGI provides a slightly different one. + It makes little difference which we use. + + The C global name "errno", which C allows to be a variable or a macro, + is required in C++ to be a macro. For MT it must typically result in + a function call. + + Chapter 20 Utilities + --------------------- + Headers: <utility> <functional> <memory> + C header: <ctime> (also in 18) + + SGI STL provides "mostly complete" versions of all the components + defined in this chapter. However, the auto_ptr<> implementation + is known to be wrong. Furthermore, the standard definition of it + is known to be unimplementable as written. A minor change to the + standard would fix it, and auto_ptr<> should be adjusted to match. + + Multi-threading affects the allocator implementation, and there must + be configuration/installation choices for different users' MT + requirements. Anyway, users will want to tune allocator options + to support different target conditions, MT or no. + + The primitives used for MT implementation should be exposed, as an + extension, for users' own work. We need cross-CPU "mutex" support, + multi-processor shared-memory atomic integer operations, and single- + processor uninterruptible integer operations, and all three configurable + to be stubbed out for non-MT use, or to use an appropriately-loaded + dynamic library for the actual runtime environment, or statically + compiled in for cases where the target architecture is known. + + Chapter 21 String + ------------------ + Headers: <string> + C headers: <cctype> <cwctype> <cstring> <cwchar> (also in 27) + <cstdlib> (also in 18, 25, 26) + + We have "mostly-complete" char_traits<> implementations. Many of the + char_traits<char> operations might be optimized further using existing + proprietary language extensions. + + We have a "mostly-complete" basic_string<> implementation. The work + to manually instantiate char and wchar_t specializations in object + files to improve link-time behavior is extremely unsatisfactory, + literally tripling library-build time with no commensurate improvement + in static program link sizes. It must be redone. (Similar work is + needed for some components in chapters 22 and 27.) + + Other work needed for strings is MT-safety, as discussed under the + chapter 20 heading. + + The standard C type mbstate_t from <cwchar> and used in char_traits<> + must be different in C++ than in C, because in C++ the default constructor + value mbstate_t() must be the "base" or "ground" sequence state. + (According to the likely resolution of a recently raised Core issue, + this may become unnecessary. However, there are other reasons to + use a state type not as limited as whatever the C library provides.) + If we might want to provide conversions from (e.g.) internally- + represented EUC-wide to externally-represented Unicode, or vice- + versa, the mbstate_t we choose will need to be more accommodating + than what might be provided by an underlying C library. + + There remain some basic_string template-member functions which do + not overload properly with their non-template brethren. The infamous + hack akin to what was done in vector<> is needed, to conform to + 23.1.1 para 10. The CHECKLIST items for basic_string marked 'X', + or incomplete, are so marked for this reason. + + Replacing the string iterators, which currently are simple character + pointers, with class objects would greatly increase the safety of the + client interface, and also permit a "debug" mode in which range, + ownership, and validity are rigorously checked. The current use of + raw pointers as string iterators is evil. vector<> iterators need the + same treatment. Note that the current implementation freely mixes + pointers and iterators, and that must be fixed before safer iterators + can be introduced. + + Some of the functions in <cstring> are different from the C version. + generally overloaded on const and non-const argument pointers. For + example, in <cstring> strchr is overloaded. The functions isupper + etc. in <cctype> typically implemented as macros in C are functions + in C++, because they are overloaded with others of the same name + defined in <locale>. + + Many of the functions required in <cwctype> and <cwchar> cannot be + implemented using underlying C facilities on intended targets because + such facilities only partly exist. + + Chapter 22 Locale + ------------------ + Headers: <locale> + C headers: <clocale> + + We have a "mostly complete" class locale, with the exception of + code for constructing, and handling the names of, named locales. + The ways that locales are named (particularly when categories + (e.g. LC_TIME, LC_COLLATE) are different) varies among all target + environments. This code must be written in various versions and + chosen by configuration parameters. + + Members of many of the facets defined in <locale> are stubs. Generally, + there are two sets of facets: the base class facets (which are supposed + to implement the "C" locale) and the "byname" facets, which are supposed + to read files to determine their behavior. The base ctype<>, collate<>, + and numpunct<> facets are "mostly complete", except that the table of + bitmask values used for "is" operations, and corresponding mask values, + are still defined in libio and just included/linked. (We will need to + implement these tables independently, soon, but should take advantage + of libio where possible.) The num_put<>::put members for integer types + are "mostly complete". + + A complete list of what has and has not been implemented may be + found in CHECKLIST. However, note that the current definition of + codecvt<wchar_t,char,mbstate_t> is wrong. It should simply write + out the raw bytes representing the wide characters, rather than + trying to convert each to a corresponding single "char" value. + + Some of the facets are more important than others. Specifically, + the members of ctype<>, numpunct<>, num_put<>, and num_get<> facets + are used by other library facilities defined in <string>, <istream>, + and <ostream>, and the codecvt<> facet is used by basic_filebuf<> + in <fstream>, so a conforming iostream implementation depends on + these. + + The "long long" type eventually must be supported, but code mentioning + it should be wrapped in #if guards to allow pedantic-mode compiling. + + Performance of num_put<> and num_get<> depend critically on + caching computed values in ios_base objects, and on extensions + to the interface with streambufs. + + Specifically: retrieving a copy of the locale object, extracting + the needed facets, and gathering data from them, for each call to + (e.g.) operator<< would be prohibitively slow. To cache format + data for use by num_put<> and num_get<> we have a _Format_cache<> + object stored in the ios_base::pword() array. This is constructed + and initialized lazily, and is organized purely for utility. It + is discarded when a new locale with different facets is imbued. + + Using only the public interfaces of the iterator arguments to the + facet functions would limit performance by forbidding "vector-style" + character operations. The streambuf iterator optimizations are + described under chapter 24, but facets can also bypass the streambuf + iterators via explicit specializations and operate directly on the + streambufs, and use extended interfaces to get direct access to the + streambuf internal buffer arrays. These extensions are mentioned + under chapter 27. These optimizations are particularly important + for input parsing. + + Unused virtual members of locale facets can be omitted, as mentioned + above, by a smart linker. + + Chapter 23 Containers + ---------------------- + Headers: <deque> <list> <queue> <stack> <vector> <map> <set> <bitset> + + All the components in chapter 23 are implemented in the SGI STL. + They are "mostly complete"; they include a large number of + nonconforming extensions which must be wrapped. Some of these + are used internally and must be renamed or duplicated. + + The SGI components are optimized for large-memory environments. For + embedded targets, different criteria might be more appropriate. Users + will want to be able to tune this behavior. We should provide + ways for users to compile the library with different memory usage + characteristics. + + A lot more work is needed on factoring out common code from different + specializations to reduce code size here and in chapter 25. The + easiest fix for this would be a compiler/ABI improvement that allows + the compiler to recognize when a specialization depends only on the + size (or other gross quality) of a template argument, and allow the + linker to share the code with similar specializations. In its + absence, many of the algorithms and containers can be partial- + specialized, at least for the case of pointers, but this only solves + a small part of the problem. Use of a type_traits-style template + allows a few more optimization opportunities, more if the compiler + can generate the specializations automatically. + + As an optimization, containers can specialize on the default allocator + and bypass it, or take advantage of details of its implementation + after it has been improved upon. + + Replacing the vector iterators, which currently are simple element + pointers, with class objects would greatly increase the safety of the + client interface, and also permit a "debug" mode in which range, + ownership, and validity are rigorously checked. The current use of + pointers for iterators is evil. + + As mentioned for chapter 24, the deque iterator is a good example of + an opportunity to implement a "staged" iterator that would benefit + from specializations of some algorithms. + + Chapter 24 Iterators + --------------------- + Headers: <iterator> + + Standard iterators are "mostly complete", with the exception of + the stream iterators, which are not yet templatized on the + stream type. Also, the base class template iterator<> appears + to be wrong, so everything derived from it must also be wrong, + currently. + + The streambuf iterators (currently located in stl/bits/std_iterator.h, + but should be under bits/) can be rewritten to take advantage of + friendship with the streambuf implementation. + + Matt Austern has identified opportunities where certain iterator + types, particularly including streambuf iterators and deque + iterators, have a "two-stage" quality, such that an intermediate + limit can be checked much more quickly than the true limit on + range operations. If identified with a member of iterator_traits, + algorithms may be specialized for this case. Of course the + iterators that have this quality can be identified by specializing + a traits class. + + Many of the algorithms must be specialized for the streambuf + iterators, to take advantage of block-mode operations, in order + to allow iostream/locale operations' performance not to suffer. + It may be that they could be treated as staged iterators and + take advantage of those optimizations. + + Chapter 25 Algorithms + ---------------------- + Headers: <algorithm> + C headers: <cstdlib> (also in 18, 21, 26)) + + The algorithms are "mostly complete". As mentioned above, they + are optimized for speed at the expense of code and data size. + + Specializations of many of the algorithms for non-STL types would + give performance improvements, but we must use great care not to + interfere with fragile template overloading semantics for the + standard interfaces. Conventionally the standard function template + interface is an inline which delegates to a non-standard function + which is then overloaded (this is already done in many places in + the library). Particularly appealing opportunities for the sake of + iostream performance are for copy and find applied to streambuf + iterators or (as noted elsewhere) for staged iterators, of which + the streambuf iterators are a good example. + + The bsearch and qsort functions cannot be overloaded properly as + required by the standard because gcc does not yet allow overloading + on the extern-"C"-ness of a function pointer. + + Chapter 26 Numerics + -------------------- + Headers: <complex> <valarray> <numeric> + C headers: <cmath>, <cstdlib> (also 18, 21, 25) + + Numeric components: Gabriel dos Reis's valarray, Drepper's complex, + and the few algorithms from the STL are "mostly done". Of course + optimization opportunities abound for the numerically literate. It + is not clear whether the valarray implementation really conforms + fully, in the assumptions it makes about aliasing (and lack thereof) + in its arguments. + + The C div() and ldiv() functions are interesting, because they are the + only case where a C library function returns a class object by value. + Since the C++ type div_t must be different from the underlying C type + (which is in the wrong namespace) the underlying functions div() and + ldiv() cannot be re-used efficiently. Fortunately they are trivial to + re-implement. + + Chapter 27 Iostreams + --------------------- + Headers: <iosfwd> <streambuf> <ios> <ostream> <istream> <iostream> + <iomanip> <sstream> <fstream> + C headers: <cstdio> <cwchar> (also in 21) + + Iostream is currently in a very incomplete state. <iosfwd>, <iomanip>, + ios_base, and basic_ios<> are "mostly complete". basic_streambuf<> and + basic_ostream<> are well along, but basic_istream<> has had little work + done. The standard stream objects, <sstream> and <fstream> have been + started; basic_filebuf<> "write" functions have been implemented just + enough to do "hello, world". + + Most of the istream and ostream operators << and >> (with the exception + of the op<<(integer) ones) have not been changed to use locale primitives, + sentry objects, or char_traits members. + + All these templates should be manually instantiated for char and + wchar_t in a way that links only used members into user programs. + + Streambuf is fertile ground for optimization extensions. An extended + interface giving iterator access to its internal buffer would be very + useful for other library components. + + Iostream operations (primarily operators << and >>) can take advantage + of the case where user code has not specified a locale, and bypass locale + operations entirely. The current implementation of op<</num_put<>::put, + for the integer types, demonstrates how they can cache encoding details + from the locale on each operation. There is lots more room for + optimization in this area. + + The definition of the relationship between the standard streams + cout et al. and stdout et al. requires something like a "stdiobuf". + The SGI solution of using double-indirection to actually use a + stdio FILE object for buffering is unsatisfactory, because it + interferes with peephole loop optimizations. + + The <sstream> header work has begun. stringbuf can benefit from + friendship with basic_string<> and basic_string<>::_Rep to use + those objects directly as buffers, and avoid allocating and making + copies. + + The basic_filebuf<> template is a complex beast. It is specified to + use the locale facet codecvt<> to translate characters between native + files and the locale character encoding. In general this involves + two buffers, one of "char" representing the file and another of + "char_type", for the stream, with codecvt<> translating. The process + is complicated by the variable-length nature of the translation, and + the need to seek to corresponding places in the two representations. + For the case of basic_filebuf<char>, when no translation is needed, + a single buffer suffices. A specialized filebuf can be used to reduce + code space overhead when no locale has been imbued. Matt Austern's + work at SGI will be useful, perhaps directly as a source of code, or + at least as an example to draw on. + + Filebuf, almost uniquely (cf. operator new), depends heavily on + underlying environmental facilities. In current releases iostream + depends fairly heavily on libio constant definitions, but it should + be made independent. It also depends on operating system primitives + for file operations. There is immense room for optimizations using + (e.g.) mmap for reading. The shadow/ directory wraps, besides the + standard C headers, the libio.h and unistd.h headers, for use mainly + by filebuf. These wrappings have not been completed, though there + is scaffolding in place. + + The encapulation of certain C header <cstdio> names presents an + interesting problem. It is possible to define an inline std::fprintf() + implemented in terms of the 'extern "C"' vfprintf(), but there is no + standard vfscanf() to use to implement std::fscanf(). It appears that + vfscanf but be re-implemented in C++ for targets where no vfscanf + extension has been defined. This is interesting in that it seems + to be the only significant case in the C library where this kind of + rewriting is necessary. (Of course Glibc provides the vfscanf() + extension.) (The functions related to exit() must be rewritten + for other reasons.) + + + Annex D + ------- + Headers: <strstream> + + Annex D defines many non-library features, and many minor + modifications to various headers, and a complete header. + It is "mostly done", except that the libstdc++-2 <strstream> + header has not been adopted into the library, or checked to + verify that it matches the draft in those details that were + clarified by the committee. Certainly it must at least be + moved into the std namespace. + + We still need to wrap all the deprecated features in #if guards + so that pedantic compile modes can detect their use. + + Nonstandard Extensions + ---------------------- + Headers: <iostream.h> <strstream.h> <hash> <rbtree> + <pthread_alloc> <stdiobuf> (etc.) + + User code has come to depend on a variety of nonstandard components + that we must not omit. Much of this code can be adopted from + libstdc++-v2 or from the SGI STL. This particularly includes + <iostream.h>, <strstream.h>, and various SGI extensions such + as <hash_map.h>. Many of these are already placed in the + subdirectories ext/ and backward/. (Note that it is better to + include them via "<backward/hash_map.h>" or "<ext/hash_map>" than + to search the subdirectory itself via a "-I" directive. + </literallayout> +</sect1> </appendix> diff --git a/libstdc++-v3/doc/xml/spine.xml b/libstdc++-v3/doc/xml/spine.xml index df30ad9..32f970a 100644 --- a/libstdc++-v3/doc/xml/spine.xml +++ b/libstdc++-v3/doc/xml/spine.xml @@ -6,8 +6,8 @@ <!ENTITY license SYSTEM "license.xml"> ]> -<set id="set-index" xreflabel="set-index"> -<?dbhtml filename="set-index.html"?> +<set id="set-index" xreflabel="The GNU C++ Library Documentation"> +<?dbhtml filename="spine.html"?> <title>The GNU C++ Library Documentation</title> <setinfo> |