148fb7bfaSmrg<appendix xmlns="http://docbook.org/ns/docbook" version="5.0" 248fb7bfaSmrg xml:id="appendix.contrib" xreflabel="Contributing"> 34fee23f9Smrg<?dbhtml filename="appendix_contributing.html"?> 44fee23f9Smrg 548fb7bfaSmrg<info><title> 64fee23f9Smrg Contributing 74fee23f9Smrg <indexterm> 84fee23f9Smrg <primary>Appendix</primary> 94fee23f9Smrg <secondary>Contributing</secondary> 104fee23f9Smrg </indexterm> 114fee23f9Smrg</title> 1248fb7bfaSmrg <keywordset> 1348fb7bfaSmrg <keyword>ISO C++</keyword> 1448fb7bfaSmrg <keyword>library</keyword> 1548fb7bfaSmrg </keywordset> 1648fb7bfaSmrg</info> 1748fb7bfaSmrg 1848fb7bfaSmrg 194fee23f9Smrg 204fee23f9Smrg<para> 214d5abbe8Smrg The GNU C++ Library is part of GCC and follows the same development model, 224d5abbe8Smrg so the general rules for 23*0a307195Smrg <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/contribute.html">contributing 244d5abbe8Smrg to GCC</link> apply. Active 254d5abbe8Smrg contributors are assigned maintainership responsibility, and given 264d5abbe8Smrg write access to the source repository. First-time contributors 274fee23f9Smrg should follow this procedure: 284fee23f9Smrg</para> 294fee23f9Smrg 3048fb7bfaSmrg<section xml:id="contrib.list" xreflabel="Contributor Checklist"><info><title>Contributor Checklist</title></info> 314fee23f9Smrg 3248fb7bfaSmrg 3348fb7bfaSmrg <section xml:id="list.reading"><info><title>Reading</title></info> 3448fb7bfaSmrg 354fee23f9Smrg 364fee23f9Smrg <itemizedlist> 374fee23f9Smrg <listitem> 384fee23f9Smrg <para> 394fee23f9Smrg Get and read the relevant sections of the C++ language 404fee23f9Smrg specification. Copies of the full ISO 14882 standard are 414fee23f9Smrg available on line via the ISO mirror site for committee 424fee23f9Smrg members. Non-members, or those who have not paid for the 434fee23f9Smrg privilege of sitting on the committee and sustained their 444fee23f9Smrg two meeting commitment for voting rights, may get a copy of 454fee23f9Smrg the standard from their respective national standards 464fee23f9Smrg organization. In the USA, this national standards 4748fb7bfaSmrg organization is 48b17d1066Smrg <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.ansi.org">ANSI</link>. 49b17d1066Smrg (And if you've already registered with them you can <link 50b17d1066Smrg xmlns:xlink="http://www.w3.org/1999/xlink" 51fb8a8121Smrg xlink:href="https://webstore.ansi.org/Standards/ISO/ISOIEC148822014">buy 52b17d1066Smrg the standard on-line</link>.) 534fee23f9Smrg </para> 544fee23f9Smrg </listitem> 554fee23f9Smrg 564fee23f9Smrg <listitem> 574fee23f9Smrg <para> 584fee23f9Smrg The library working group bugs, and known defects, can 594fee23f9Smrg be obtained here: 6048fb7bfaSmrg <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21</link> 614fee23f9Smrg </para> 624fee23f9Smrg </listitem> 634fee23f9Smrg 644fee23f9Smrg <listitem> 654fee23f9Smrg <para> 664fee23f9Smrg Peruse 67*0a307195Smrg the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.gnu.org/prep/standards/">GNU 6848fb7bfaSmrg Coding Standards</link>, and chuckle when you hit the part 694fee23f9Smrg about <quote>Using Languages Other Than C</quote>. 704fee23f9Smrg </para> 714fee23f9Smrg </listitem> 724fee23f9Smrg 734fee23f9Smrg <listitem> 744fee23f9Smrg <para> 754fee23f9Smrg Be familiar with the extensions that preceded these 764fee23f9Smrg general GNU rules. These style issues for libstdc++ can be 7748fb7bfaSmrg found in <link linkend="contrib.coding_style">Coding Style</link>. 784fee23f9Smrg </para> 794fee23f9Smrg </listitem> 804fee23f9Smrg 814fee23f9Smrg <listitem> 824fee23f9Smrg <para> 834fee23f9Smrg And last but certainly not least, read the 8448fb7bfaSmrg library-specific information found in 8548fb7bfaSmrg <link linkend="appendix.porting">Porting and Maintenance</link>. 864fee23f9Smrg </para> 874fee23f9Smrg </listitem> 884fee23f9Smrg </itemizedlist> 894fee23f9Smrg 9048fb7bfaSmrg </section> 9148fb7bfaSmrg <section xml:id="list.copyright"><info><title>Assignment</title></info> 9248fb7bfaSmrg 934fee23f9Smrg <para> 94*0a307195Smrg See the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/contribute.html#legal">legal prerequisites</link> for all GCC contributions. 954fee23f9Smrg </para> 964fee23f9Smrg 974fee23f9Smrg <para> 984fee23f9Smrg Historically, the libstdc++ assignment form added the following 994fee23f9Smrg question: 1004fee23f9Smrg </para> 1014fee23f9Smrg 1024fee23f9Smrg <para> 1034fee23f9Smrg <quote> 1044fee23f9Smrg Which Belgian comic book character is better, Tintin or Asterix, and 1054fee23f9Smrg why? 1064fee23f9Smrg </quote> 1074fee23f9Smrg </para> 1084fee23f9Smrg 1094fee23f9Smrg <para> 1104fee23f9Smrg While not strictly necessary, humoring the maintainers and answering 1114fee23f9Smrg this question would be appreciated. 1124fee23f9Smrg </para> 1134fee23f9Smrg 1144fee23f9Smrg <para> 1154d5abbe8Smrg Please contact 1164d5abbe8Smrg Paolo Carlini at <email>paolo.carlini@oracle.com</email> 1174d5abbe8Smrg or 1184d5abbe8Smrg Jonathan Wakely at <email>jwakely+assign@redhat.com</email> 1194d5abbe8Smrg if you are confused about the assignment or have general licensing 1204d5abbe8Smrg questions. When requesting an assignment form from 1214d5abbe8Smrg <email>assign@gnu.org</email>, please CC the libstdc++ 1224d5abbe8Smrg maintainers above so that progress can be monitored. 1234fee23f9Smrg </para> 12448fb7bfaSmrg </section> 1254fee23f9Smrg 12648fb7bfaSmrg <section xml:id="list.getting"><info><title>Getting Sources</title></info> 12748fb7bfaSmrg 1284fee23f9Smrg <para> 129fb8a8121Smrg <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/gitwrite.html">Getting write access 13048fb7bfaSmrg (look for "Write after approval")</link> 1314fee23f9Smrg </para> 13248fb7bfaSmrg </section> 1334fee23f9Smrg 13448fb7bfaSmrg <section xml:id="list.patches"><info><title>Submitting Patches</title></info> 13548fb7bfaSmrg 1364fee23f9Smrg 1374fee23f9Smrg <para> 1384fee23f9Smrg Every patch must have several pieces of information before it can be 1394fee23f9Smrg properly evaluated. Ideally (and to ensure the fastest possible 1404fee23f9Smrg response from the maintainers) it would have all of these pieces: 1414fee23f9Smrg </para> 1424fee23f9Smrg 1434fee23f9Smrg <itemizedlist> 1444fee23f9Smrg <listitem> 1454fee23f9Smrg <para> 1464fee23f9Smrg A description of the bug and how your patch fixes this 1474fee23f9Smrg bug. For new features a description of the feature and your 1484fee23f9Smrg implementation. 1494fee23f9Smrg </para> 1504fee23f9Smrg </listitem> 1514fee23f9Smrg 1524fee23f9Smrg <listitem> 1534fee23f9Smrg <para> 154*0a307195Smrg A ChangeLog entry as part of the Git commit message. Check 155*0a307195Smrg some recent commits for format and content. The 156*0a307195Smrg <filename>contrib/mklog.py</filename> script can be used to 157*0a307195Smrg generate a ChangeLog template for commit messages. See 158*0a307195Smrg <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/gitwrite.html">Read-write Git access</link> 159*0a307195Smrg for scripts and aliases that are useful here. 1604fee23f9Smrg </para> 1614fee23f9Smrg </listitem> 1624fee23f9Smrg 1634fee23f9Smrg <listitem> 1644fee23f9Smrg <para> 1654fee23f9Smrg A testsuite submission or sample program that will 1664fee23f9Smrg easily and simply show the existing error or test new 1674fee23f9Smrg functionality. 1684fee23f9Smrg </para> 1694fee23f9Smrg </listitem> 1704fee23f9Smrg 1714fee23f9Smrg <listitem> 1724fee23f9Smrg <para> 173a3e9eb18Smrg The patch itself. If you are using the Git repository use 174*0a307195Smrg <command>git show</command> or <command>git format-patch</command> 175a3e9eb18Smrg to produce a patch; 176a3e9eb18Smrg otherwise, use <command>diff -cp OLD NEW</command>. If your 1774fee23f9Smrg version of diff does not support these options, then get the 178a3e9eb18Smrg latest version of GNU diff. 1794fee23f9Smrg </para> 1804fee23f9Smrg </listitem> 1814fee23f9Smrg 1824fee23f9Smrg <listitem> 1834fee23f9Smrg <para> 1844fee23f9Smrg When you have all these pieces, bundle them up in a 1854fee23f9Smrg mail message and send it to libstdc++@gcc.gnu.org. All 1864fee23f9Smrg patches and related discussion should be sent to the 187f9a78e0eSmrg libstdc++ mailing list. In common with the rest of GCC, 188f9a78e0eSmrg patches should also be sent to the gcc-patches mailing list. 189*0a307195Smrg So you could send your email To:libstdc++@gcc.gnu.org and 190*0a307195Smrg Cc:gcc-patches@gcc.gnu.org for example. 1914fee23f9Smrg </para> 1924fee23f9Smrg </listitem> 1934fee23f9Smrg </itemizedlist> 1944fee23f9Smrg 19548fb7bfaSmrg </section> 1964fee23f9Smrg 19748fb7bfaSmrg</section> 1984fee23f9Smrg 19948fb7bfaSmrg<section xml:id="contrib.organization" xreflabel="Source Organization"><info><title>Directory Layout and Source Conventions</title></info> 2004fee23f9Smrg <?dbhtml filename="source_organization.html"?> 20148fb7bfaSmrg 2024fee23f9Smrg 2034fee23f9Smrg <para> 2043f4ceed9Smrg The <filename class="directory">libstdc++-v3</filename> directory in the 2053f4ceed9Smrg GCC sources contains the files needed to create the GNU C++ Library. 2064fee23f9Smrg </para> 2074fee23f9Smrg 2083f4ceed9Smrg<para> 2094fee23f9SmrgIt has subdirectories: 2103f4ceed9Smrg</para> 2114fee23f9Smrg 2123f4ceed9Smrg<variablelist> 2133f4ceed9Smrg <varlistentry> 2143f4ceed9Smrg <term><filename class="directory">doc</filename></term> 2153f4ceed9Smrg <listitem> 2164fee23f9Smrg Files in HTML and text format that document usage, quirks of the 2174fee23f9Smrg implementation, and contributor checklists. 2183f4ceed9Smrg </listitem> 2193f4ceed9Smrg </varlistentry> 2204fee23f9Smrg 2213f4ceed9Smrg <varlistentry> 2223f4ceed9Smrg <term><filename class="directory">include</filename></term> 2233f4ceed9Smrg <listitem> 2244fee23f9Smrg All header files for the C++ library are within this directory, 2254fee23f9Smrg modulo specific runtime-related files that are in the libsupc++ 2264fee23f9Smrg directory. 2274fee23f9Smrg 2283f4ceed9Smrg <variablelist> 2293f4ceed9Smrg <varlistentry> 2303f4ceed9Smrg <term><filename class="directory">include/std</filename></term> 2313f4ceed9Smrg <listitem> 2323f4ceed9Smrg Files meant to be found by <code>#include <name></code> directives 2333f4ceed9Smrg in standard-conforming user programs. 2343f4ceed9Smrg </listitem> 2353f4ceed9Smrg </varlistentry> 2364fee23f9Smrg 2373f4ceed9Smrg <varlistentry> 2383f4ceed9Smrg <term><filename class="directory">include/c</filename></term> 2393f4ceed9Smrg <listitem> 2404fee23f9Smrg Headers intended to directly include standard C headers. 2413f4ceed9Smrg [NB: this can be enabled via <option>--enable-cheaders=c</option>] 2423f4ceed9Smrg </listitem> 2433f4ceed9Smrg </varlistentry> 2444fee23f9Smrg 2453f4ceed9Smrg <varlistentry> 2463f4ceed9Smrg <term><filename class="directory">include/c_global</filename></term> 2473f4ceed9Smrg <listitem> 2484fee23f9Smrg Headers intended to include standard C headers in 2493f4ceed9Smrg the global namespace, and put select names into the <code>std::</code> 2504fee23f9Smrg namespace. [NB: this is the default, and is the same as 2513f4ceed9Smrg <option>--enable-cheaders=c_global</option>] 2523f4ceed9Smrg </listitem> 2533f4ceed9Smrg </varlistentry> 2544fee23f9Smrg 2553f4ceed9Smrg <varlistentry> 2563f4ceed9Smrg <term><filename class="directory">include/c_std</filename></term> 2573f4ceed9Smrg <listitem> 2584fee23f9Smrg Headers intended to include standard C headers 2593f4ceed9Smrg already in namespace std, and put select names into the <code>std::</code> 2603f4ceed9Smrg namespace. [NB: this is the same as 2613f4ceed9Smrg <option>--enable-cheaders=c_std</option>] 2623f4ceed9Smrg </listitem> 2633f4ceed9Smrg </varlistentry> 2644fee23f9Smrg 2653f4ceed9Smrg <varlistentry> 2663f4ceed9Smrg <term><filename class="directory">include/bits</filename></term> 2673f4ceed9Smrg <listitem> 2684fee23f9Smrg Files included by standard headers and by other files in 2694fee23f9Smrg the bits directory. 2703f4ceed9Smrg </listitem> 2713f4ceed9Smrg </varlistentry> 2724fee23f9Smrg 2733f4ceed9Smrg <varlistentry> 2743f4ceed9Smrg <term><filename class="directory">include/backward</filename></term> 2753f4ceed9Smrg <listitem> 2763f4ceed9Smrg Headers provided for backward compatibility, such as 2773f4ceed9Smrg <filename class="headerfile"><backward/hash_map></filename>. 2784fee23f9Smrg They are not used in this library. 2793f4ceed9Smrg </listitem> 2803f4ceed9Smrg </varlistentry> 2814fee23f9Smrg 2823f4ceed9Smrg <varlistentry> 2833f4ceed9Smrg <term><filename class="directory">include/ext</filename></term> 2843f4ceed9Smrg <listitem> 2854fee23f9Smrg Headers that define extensions to the standard library. No 2863f4ceed9Smrg standard header refers to any of them, in theory (there are some 2873f4ceed9Smrg exceptions). 2883f4ceed9Smrg </listitem> 2893f4ceed9Smrg </varlistentry> 290b17d1066Smrg 291b17d1066Smrg <varlistentry> 292b17d1066Smrg <term> 293b17d1066Smrg <filename class="directory">include/debug</filename>, 294b17d1066Smrg <filename class="directory">include/parallel</filename>, and 295b17d1066Smrg </term> 296b17d1066Smrg <listitem> 297fb8a8121Smrg Headers that implement the Debug Mode and Parallel Mode extensions. 298b17d1066Smrg </listitem> 299b17d1066Smrg </varlistentry> 3003f4ceed9Smrg </variablelist> 3013f4ceed9Smrg </listitem> 3023f4ceed9Smrg </varlistentry> 3034fee23f9Smrg 3043f4ceed9Smrg <varlistentry> 3053f4ceed9Smrg <term><filename class="directory">scripts</filename></term> 3063f4ceed9Smrg <listitem> 3074fee23f9Smrg Scripts that are used during the configure, build, make, or test 3084fee23f9Smrg process. 3093f4ceed9Smrg </listitem> 3103f4ceed9Smrg </varlistentry> 3114fee23f9Smrg 3123f4ceed9Smrg <varlistentry> 3133f4ceed9Smrg <term><filename class="directory">src</filename></term> 3143f4ceed9Smrg <listitem> 3154fee23f9Smrg Files that are used in constructing the library, but are not 3164fee23f9Smrg installed. 3174fee23f9Smrg 3183f4ceed9Smrg <variablelist> 3193f4ceed9Smrg <varlistentry> 3203f4ceed9Smrg <term><filename class="directory">src/c++98</filename></term> 3213f4ceed9Smrg <listitem> 3223f4ceed9Smrg Source files compiled using <option>-std=gnu++98</option>. 3233f4ceed9Smrg </listitem> 3243f4ceed9Smrg </varlistentry> 3253f4ceed9Smrg 3263f4ceed9Smrg <varlistentry> 3273f4ceed9Smrg <term><filename class="directory">src/c++11</filename></term> 3283f4ceed9Smrg <listitem> 3293f4ceed9Smrg Source files compiled using <option>-std=gnu++11</option>. 3303f4ceed9Smrg </listitem> 3313f4ceed9Smrg </varlistentry> 3323f4ceed9Smrg 3333f4ceed9Smrg <varlistentry> 3343f4ceed9Smrg <term><filename class="directory">src/filesystem</filename></term> 3353f4ceed9Smrg <listitem> 3363f4ceed9Smrg Source files for the Filesystem TS. 3373f4ceed9Smrg </listitem> 3383f4ceed9Smrg </varlistentry> 3393f4ceed9Smrg 3403f4ceed9Smrg <varlistentry> 3413f4ceed9Smrg <term><filename class="directory">src/shared</filename></term> 3423f4ceed9Smrg <listitem> 3433f4ceed9Smrg Source code included by other files under both 3443f4ceed9Smrg <filename class="directory">src/c++98</filename> and 3453f4ceed9Smrg <filename class="directory">src/c++11</filename> 3463f4ceed9Smrg </listitem> 3473f4ceed9Smrg </varlistentry> 3483f4ceed9Smrg </variablelist> 3493f4ceed9Smrg </listitem> 3503f4ceed9Smrg </varlistentry> 3513f4ceed9Smrg 3523f4ceed9Smrg <varlistentry> 3533f4ceed9Smrg <term><filename class="directory">testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*]</filename></term> 3543f4ceed9Smrg <listitem> 3554fee23f9Smrg Test programs are here, and may be used to begin to exercise the 3564fee23f9Smrg library. Support for "make check" and "make check-install" is 3574fee23f9Smrg complete, and runs through all the subdirectories here when this 3584fee23f9Smrg command is issued from the build directory. Please note that 3593f4ceed9Smrg "make check" requires DejaGnu 1.4 or later to be installed, 3603f4ceed9Smrg or for extra <link linkend="test.run.permutations">permutations</link> 3613f4ceed9Smrg DejaGnu 1.5.3 or later. 3623f4ceed9Smrg </listitem> 3633f4ceed9Smrg </varlistentry> 3643f4ceed9Smrg</variablelist> 3654fee23f9Smrg 3663f4ceed9Smrg<para> 3674fee23f9SmrgOther subdirectories contain variant versions of certain files 3684fee23f9Smrgthat are meant to be copied or linked by the configure script. 3694fee23f9SmrgCurrently these are: 3703f4ceed9Smrg<literallayout><filename class="directory">config/abi</filename> 3713f4ceed9Smrg<filename class="directory">config/allocator</filename> 3723f4ceed9Smrg<filename class="directory">config/cpu</filename> 3733f4ceed9Smrg<filename class="directory">config/io</filename> 3743f4ceed9Smrg<filename class="directory">config/locale</filename> 3753f4ceed9Smrg<filename class="directory">config/os</filename> 3763f4ceed9Smrg</literallayout> 3773f4ceed9Smrg</para> 3784fee23f9Smrg 3793f4ceed9Smrg<para> 3804fee23f9SmrgIn addition, a subdirectory holds the convenience library libsupc++. 3813f4ceed9Smrg</para> 3824fee23f9Smrg 3833f4ceed9Smrg<variablelist> 3843f4ceed9Smrg<varlistentry> 3853f4ceed9Smrg <term><filename class="directory">libsupc++</filename></term> 3863f4ceed9Smrg <listitem> 3874fee23f9Smrg Contains the runtime library for C++, including exception 3884fee23f9Smrg handling and memory allocation and deallocation, RTTI, terminate 3894fee23f9Smrg handlers, etc. 3903f4ceed9Smrg </listitem> 3913f4ceed9Smrg</varlistentry> 3923f4ceed9Smrg</variablelist> 3934fee23f9Smrg 3943f4ceed9Smrg<para> 3953f4ceed9SmrgNote that glibc also has a <filename class="directory">bits/</filename> 3963f4ceed9Smrgsubdirectory. We need to be careful not to collide with names in its 397f9a78e0eSmrg<filename class="directory">bits/</filename> directory. For example 398f9a78e0eSmrg<filename class="headerfile"><bits/std_mutex.h></filename> has to be 399f9a78e0eSmrgrenamed from <filename class="headerfile"><bits/mutex.h></filename>. 4003f4ceed9SmrgAnother solution would be to rename <filename class="directory">bits</filename> 4013f4ceed9Smrgto (e.g.) <filename class="directory">cppbits</filename>. 4023f4ceed9Smrg</para> 4034fee23f9Smrg 4043f4ceed9Smrg<para> 4054fee23f9SmrgIn files throughout the system, lines marked with an "XXX" indicate 4064fee23f9Smrga bug or incompletely-implemented feature. Lines marked "XXX MT" 4074fee23f9Smrgindicate a place that may require attention for multi-thread safety. 4083f4ceed9Smrg</para> 4094fee23f9Smrg 41048fb7bfaSmrg</section> 4114fee23f9Smrg 41248fb7bfaSmrg<section xml:id="contrib.coding_style" xreflabel="Coding Style"><info><title>Coding Style</title></info> 4134fee23f9Smrg <?dbhtml filename="source_code_style.html"?> 41448fb7bfaSmrg 4154fee23f9Smrg <para> 4164fee23f9Smrg </para> 417fb8a8121Smrg 418fb8a8121Smrg <section xml:id="coding_style.bad_identifiers"><info><title>Bad Identifiers</title></info> <!-- BADNAMES --> 41948fb7bfaSmrg 4204fee23f9Smrg <para> 4214fee23f9Smrg Identifiers that conflict and should be avoided. 4224fee23f9Smrg </para> 4234fee23f9Smrg 42448fb7bfaSmrg <literallayout class="normal"> 4254fee23f9Smrg This is the list of names <quote>reserved to the 4264fee23f9Smrg implementation</quote> that have been claimed by certain 4274fee23f9Smrg compilers and system headers of interest, and should not be used 4284fee23f9Smrg in the library. It will grow, of course. We generally are 4294fee23f9Smrg interested in names that are not all-caps, except for those like 4304fee23f9Smrg "_T" 4314fee23f9Smrg 4324fee23f9Smrg For Solaris: 4334fee23f9Smrg _B 4344fee23f9Smrg _C 4354fee23f9Smrg _L 4364fee23f9Smrg _N 4374fee23f9Smrg _P 4384fee23f9Smrg _S 4394fee23f9Smrg _U 4404fee23f9Smrg _X 4414fee23f9Smrg _E1 4424fee23f9Smrg .. 4434fee23f9Smrg _E24 4444fee23f9Smrg 4454fee23f9Smrg Irix adds: 4464fee23f9Smrg _A 4474fee23f9Smrg _G 4484fee23f9Smrg 4494fee23f9Smrg MS adds: 4504fee23f9Smrg _T 451fb8a8121Smrg __deref 4524fee23f9Smrg 4534fee23f9Smrg BSD adds: 4544fee23f9Smrg __used 4554fee23f9Smrg __unused 4564fee23f9Smrg __inline 4574fee23f9Smrg _Complex 4584fee23f9Smrg __istype 4594fee23f9Smrg __maskrune 4604fee23f9Smrg __tolower 4614fee23f9Smrg __toupper 4624fee23f9Smrg __wchar_t 4634fee23f9Smrg __wint_t 4644fee23f9Smrg _res 4654fee23f9Smrg _res_ext 4664fee23f9Smrg __tg_* 4674fee23f9Smrg 468fb8a8121Smrg VxWorks adds: 469fb8a8121Smrg _C2 4704fee23f9Smrg 4714fee23f9Smrg For GCC: 4724fee23f9Smrg 4734fee23f9Smrg [Note that this list is out of date. It applies to the old 4744fee23f9Smrg name-mangling; in G++ 3.0 and higher a different name-mangling is 4754fee23f9Smrg used. In addition, many of the bugs relating to G++ interpreting 4764fee23f9Smrg these names as operators have been fixed.] 4774fee23f9Smrg 4784fee23f9Smrg The full set of __* identifiers (combined from gcc/cp/lex.c and 4794fee23f9Smrg gcc/cplus-dem.c) that are either old or new, but are definitely 4804fee23f9Smrg recognized by the demangler, is: 4814fee23f9Smrg 4824fee23f9Smrg __aa 4834fee23f9Smrg __aad 4844fee23f9Smrg __ad 4854fee23f9Smrg __addr 4864fee23f9Smrg __adv 4874fee23f9Smrg __aer 4884fee23f9Smrg __als 4894fee23f9Smrg __alshift 4904fee23f9Smrg __amd 4914fee23f9Smrg __ami 4924fee23f9Smrg __aml 4934fee23f9Smrg __amu 4944fee23f9Smrg __aor 4954fee23f9Smrg __apl 4964fee23f9Smrg __array 4974fee23f9Smrg __ars 4984fee23f9Smrg __arshift 4994fee23f9Smrg __as 5004fee23f9Smrg __bit_and 5014fee23f9Smrg __bit_ior 5024fee23f9Smrg __bit_not 5034fee23f9Smrg __bit_xor 5044fee23f9Smrg __call 5054fee23f9Smrg __cl 5064fee23f9Smrg __cm 5074fee23f9Smrg __cn 5084fee23f9Smrg __co 5094fee23f9Smrg __component 5104fee23f9Smrg __compound 5114fee23f9Smrg __cond 5124fee23f9Smrg __convert 5134fee23f9Smrg __delete 5144fee23f9Smrg __dl 5154fee23f9Smrg __dv 5164fee23f9Smrg __eq 5174fee23f9Smrg __er 5184fee23f9Smrg __ge 5194fee23f9Smrg __gt 5204fee23f9Smrg __indirect 5214fee23f9Smrg __le 5224fee23f9Smrg __ls 5234fee23f9Smrg __lt 5244fee23f9Smrg __max 5254fee23f9Smrg __md 5264fee23f9Smrg __method_call 5274fee23f9Smrg __mi 5284fee23f9Smrg __min 5294fee23f9Smrg __minus 5304fee23f9Smrg __ml 5314fee23f9Smrg __mm 5324fee23f9Smrg __mn 5334fee23f9Smrg __mult 5344fee23f9Smrg __mx 5354fee23f9Smrg __ne 5364fee23f9Smrg __negate 5374fee23f9Smrg __new 5384fee23f9Smrg __nop 5394fee23f9Smrg __nt 5404fee23f9Smrg __nw 5414fee23f9Smrg __oo 5424fee23f9Smrg __op 5434fee23f9Smrg __or 5444fee23f9Smrg __pl 5454fee23f9Smrg __plus 5464fee23f9Smrg __postdecrement 5474fee23f9Smrg __postincrement 5484fee23f9Smrg __pp 5494fee23f9Smrg __pt 5504fee23f9Smrg __rf 5514fee23f9Smrg __rm 5524fee23f9Smrg __rs 5534fee23f9Smrg __sz 5544fee23f9Smrg __trunc_div 5554fee23f9Smrg __trunc_mod 5564fee23f9Smrg __truth_andif 5574fee23f9Smrg __truth_not 5584fee23f9Smrg __truth_orif 5594fee23f9Smrg __vc 5604fee23f9Smrg __vd 5614fee23f9Smrg __vn 5624fee23f9Smrg 5634fee23f9Smrg SGI badnames: 5644fee23f9Smrg __builtin_alloca 5654fee23f9Smrg __builtin_fsqrt 5664fee23f9Smrg __builtin_sqrt 5674fee23f9Smrg __builtin_fabs 5684fee23f9Smrg __builtin_dabs 5694fee23f9Smrg __builtin_cast_f2i 5704fee23f9Smrg __builtin_cast_i2f 5714fee23f9Smrg __builtin_cast_d2ll 5724fee23f9Smrg __builtin_cast_ll2d 5734fee23f9Smrg __builtin_copy_dhi2i 5744fee23f9Smrg __builtin_copy_i2dhi 5754fee23f9Smrg __builtin_copy_dlo2i 5764fee23f9Smrg __builtin_copy_i2dlo 5774fee23f9Smrg __add_and_fetch 5784fee23f9Smrg __sub_and_fetch 5794fee23f9Smrg __or_and_fetch 5804fee23f9Smrg __xor_and_fetch 5814fee23f9Smrg __and_and_fetch 5824fee23f9Smrg __nand_and_fetch 5834fee23f9Smrg __mpy_and_fetch 5844fee23f9Smrg __min_and_fetch 5854fee23f9Smrg __max_and_fetch 5864fee23f9Smrg __fetch_and_add 5874fee23f9Smrg __fetch_and_sub 5884fee23f9Smrg __fetch_and_or 5894fee23f9Smrg __fetch_and_xor 5904fee23f9Smrg __fetch_and_and 5914fee23f9Smrg __fetch_and_nand 5924fee23f9Smrg __fetch_and_mpy 5934fee23f9Smrg __fetch_and_min 5944fee23f9Smrg __fetch_and_max 5954fee23f9Smrg __lock_test_and_set 5964fee23f9Smrg __lock_release 5974fee23f9Smrg __lock_acquire 5984fee23f9Smrg __compare_and_swap 5994fee23f9Smrg __synchronize 6004fee23f9Smrg __high_multiply 6014fee23f9Smrg __unix 6024fee23f9Smrg __sgi 6034fee23f9Smrg __linux__ 6044fee23f9Smrg __i386__ 6054fee23f9Smrg __i486__ 6064fee23f9Smrg __cplusplus 6074fee23f9Smrg __embedded_cplusplus 6084fee23f9Smrg // long double conversion members mangled as __opr 6094fee23f9Smrg // http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html 61048fb7bfaSmrg __opr 6114fee23f9Smrg </literallayout> 61248fb7bfaSmrg </section> 6134fee23f9Smrg 61448fb7bfaSmrg <section xml:id="coding_style.example"><info><title>By Example</title></info> 61548fb7bfaSmrg 61648fb7bfaSmrg <literallayout class="normal"> 6174fee23f9Smrg This library is written to appropriate C++ coding standards. As such, 6184fee23f9Smrg it is intended to precede the recommendations of the GNU Coding 6194fee23f9Smrg Standard, which can be referenced in full here: 6204fee23f9Smrg 621*0a307195Smrg <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.gnu.org/prep/standards/standards.html#Formatting">https://www.gnu.org/prep/standards/standards.html#Formatting</link> 6224fee23f9Smrg 6234fee23f9Smrg The rest of this is also interesting reading, but skip the "Design 6244fee23f9Smrg Advice" part. 6254fee23f9Smrg 6264fee23f9Smrg The GCC coding conventions are here, and are also useful: 627*0a307195Smrg <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/codingconventions.html">https://gcc.gnu.org/codingconventions.html</link> 6284fee23f9Smrg 6294fee23f9Smrg In addition, because it doesn't seem to be stated explicitly anywhere 6304fee23f9Smrg else, there is an 80 column source limit. 6314fee23f9Smrg 63248fb7bfaSmrg <filename>ChangeLog</filename> entries for member functions should use the 6334fee23f9Smrg classname::member function name syntax as follows: 6344fee23f9Smrg 63548fb7bfaSmrg<code> 6364fee23f9Smrg1999-04-15 Dennis Ritchie <dr@att.com> 6374fee23f9Smrg 6384fee23f9Smrg * src/basic_file.cc (__basic_file::open): Fix thinko in 6394fee23f9Smrg _G_HAVE_IO_FILE_OPEN bits. 64048fb7bfaSmrg</code> 6414fee23f9Smrg 6424fee23f9Smrg Notable areas of divergence from what may be previous local practice 6434fee23f9Smrg (particularly for GNU C) include: 6444fee23f9Smrg 6454fee23f9Smrg 01. Pointers and references 64648fb7bfaSmrg <code> 6474fee23f9Smrg char* p = "flop"; 6484fee23f9Smrg char& c = *p; 6494fee23f9Smrg -NOT- 6504fee23f9Smrg char *p = "flop"; // wrong 6514fee23f9Smrg char &c = *p; // wrong 65248fb7bfaSmrg </code> 6534fee23f9Smrg 6544fee23f9Smrg Reason: In C++, definitions are mixed with executable code. Here, 65548fb7bfaSmrg <code>p</code> is being initialized, not <code>*p</code>. This is near-universal 6564fee23f9Smrg practice among C++ programmers; it is normal for C hackers 6574fee23f9Smrg to switch spontaneously as they gain experience. 6584fee23f9Smrg 6594fee23f9Smrg 02. Operator names and parentheses 66048fb7bfaSmrg <code> 6614fee23f9Smrg operator==(type) 6624fee23f9Smrg -NOT- 6634fee23f9Smrg operator == (type) // wrong 66448fb7bfaSmrg </code> 6654fee23f9Smrg 66648fb7bfaSmrg Reason: The <code>==</code> is part of the function name. Separating 6674fee23f9Smrg it makes the declaration look like an expression. 6684fee23f9Smrg 6694fee23f9Smrg 03. Function names and parentheses 67048fb7bfaSmrg <code> 6714fee23f9Smrg void mangle() 6724fee23f9Smrg -NOT- 6734fee23f9Smrg void mangle () // wrong 67448fb7bfaSmrg </code> 6754fee23f9Smrg 6764fee23f9Smrg Reason: no space before parentheses (except after a control-flow 6774fee23f9Smrg keyword) is near-universal practice for C++. It identifies the 6784fee23f9Smrg parentheses as the function-call operator or declarator, as 6794fee23f9Smrg opposed to an expression or other overloaded use of parentheses. 6804fee23f9Smrg 6814fee23f9Smrg 04. Template function indentation 68248fb7bfaSmrg <code> 6834fee23f9Smrg template<typename T> 6844fee23f9Smrg void 6854fee23f9Smrg template_function(args) 6864fee23f9Smrg { } 6874fee23f9Smrg -NOT- 6884fee23f9Smrg template<class T> 6894fee23f9Smrg void template_function(args) {}; 69048fb7bfaSmrg </code> 6914fee23f9Smrg 6924fee23f9Smrg Reason: In class definitions, without indentation whitespace is 6934fee23f9Smrg needed both above and below the declaration to distinguish 6944fee23f9Smrg it visually from other members. (Also, re: "typename" 69548fb7bfaSmrg rather than "class".) <code>T</code> often could be <code>int</code>, which is 6964fee23f9Smrg not a class. ("class", here, is an anachronism.) 6974fee23f9Smrg 6984fee23f9Smrg 05. Template class indentation 69948fb7bfaSmrg <code> 7004fee23f9Smrg template<typename _CharT, typename _Traits> 7014fee23f9Smrg class basic_ios : public ios_base 7024fee23f9Smrg { 7034fee23f9Smrg public: 7044fee23f9Smrg // Types: 7054fee23f9Smrg }; 7064fee23f9Smrg -NOT- 7074fee23f9Smrg template<class _CharT, class _Traits> 7084fee23f9Smrg class basic_ios : public ios_base 7094fee23f9Smrg { 7104fee23f9Smrg public: 7114fee23f9Smrg // Types: 7124fee23f9Smrg }; 7134fee23f9Smrg -NOT- 7144fee23f9Smrg template<class _CharT, class _Traits> 7154fee23f9Smrg class basic_ios : public ios_base 7164fee23f9Smrg { 7174fee23f9Smrg public: 7184fee23f9Smrg // Types: 7194fee23f9Smrg }; 72048fb7bfaSmrg </code> 7214fee23f9Smrg 7224fee23f9Smrg 06. Enumerators 72348fb7bfaSmrg <code> 7244fee23f9Smrg enum 7254fee23f9Smrg { 7264fee23f9Smrg space = _ISspace, 7274fee23f9Smrg print = _ISprint, 7284fee23f9Smrg cntrl = _IScntrl 7294fee23f9Smrg }; 7304fee23f9Smrg -NOT- 7314fee23f9Smrg enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl }; 73248fb7bfaSmrg </code> 7334fee23f9Smrg 7344fee23f9Smrg 07. Member initialization lists 7354fee23f9Smrg All one line, separate from class name. 7364fee23f9Smrg 73748fb7bfaSmrg <code> 7384fee23f9Smrg gribble::gribble() 73948fb7bfaSmrg : _M_private_data(0), _M_more_stuff(0), _M_helper(0) 7404fee23f9Smrg { } 7414fee23f9Smrg -NOT- 74248fb7bfaSmrg gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0) 7434fee23f9Smrg { } 74448fb7bfaSmrg </code> 7454fee23f9Smrg 7464fee23f9Smrg 08. Try/Catch blocks 74748fb7bfaSmrg <code> 7484fee23f9Smrg try 7494fee23f9Smrg { 7504fee23f9Smrg // 7514fee23f9Smrg } 7524fee23f9Smrg catch (...) 7534fee23f9Smrg { 7544fee23f9Smrg // 7554fee23f9Smrg } 7564fee23f9Smrg -NOT- 7574fee23f9Smrg try { 7584fee23f9Smrg // 7594fee23f9Smrg } catch(...) { 7604fee23f9Smrg // 7614fee23f9Smrg } 76248fb7bfaSmrg </code> 7634fee23f9Smrg 7644fee23f9Smrg 09. Member functions declarations and definitions 7654fee23f9Smrg Keywords such as extern, static, export, explicit, inline, etc 7664fee23f9Smrg go on the line above the function name. Thus 7674fee23f9Smrg 76848fb7bfaSmrg <code> 7694fee23f9Smrg virtual int 7704fee23f9Smrg foo() 7714fee23f9Smrg -NOT- 7724fee23f9Smrg virtual int foo() 77348fb7bfaSmrg </code> 7744fee23f9Smrg 7754fee23f9Smrg Reason: GNU coding conventions dictate return types for functions 7764fee23f9Smrg are on a separate line than the function name and parameter list 7774fee23f9Smrg for definitions. For C++, where we have member functions that can 7784fee23f9Smrg be either inline definitions or declarations, keeping to this 7794fee23f9Smrg standard allows all member function names for a given class to be 7804fee23f9Smrg aligned to the same margin, increasing readability. 7814fee23f9Smrg 7824fee23f9Smrg 7834fee23f9Smrg 10. Invocation of member functions with "this->" 78448fb7bfaSmrg For non-uglified names, use <code>this->name</code> to call the function. 7854fee23f9Smrg 78648fb7bfaSmrg <code> 7874fee23f9Smrg this->sync() 7884fee23f9Smrg -NOT- 7894fee23f9Smrg sync() 79048fb7bfaSmrg </code> 7914fee23f9Smrg 7924fee23f9Smrg Reason: Koenig lookup. 7934fee23f9Smrg 7944fee23f9Smrg 11. Namespaces 79548fb7bfaSmrg <code> 7964fee23f9Smrg namespace std 7974fee23f9Smrg { 7984fee23f9Smrg blah blah blah; 7994fee23f9Smrg } // namespace std 8004fee23f9Smrg 8014fee23f9Smrg -NOT- 8024fee23f9Smrg 8034fee23f9Smrg namespace std { 8044fee23f9Smrg blah blah blah; 8054fee23f9Smrg } // namespace std 80648fb7bfaSmrg </code> 8074fee23f9Smrg 8084fee23f9Smrg 12. Spacing under protected and private in class declarations: 8094fee23f9Smrg space above, none below 8104fee23f9Smrg i.e. 8114fee23f9Smrg 81248fb7bfaSmrg <code> 8134fee23f9Smrg public: 8144fee23f9Smrg int foo; 8154fee23f9Smrg 8164fee23f9Smrg -NOT- 8174fee23f9Smrg public: 8184fee23f9Smrg 8194fee23f9Smrg int foo; 82048fb7bfaSmrg </code> 8214fee23f9Smrg 8224fee23f9Smrg 13. Spacing WRT return statements. 8234fee23f9Smrg no extra spacing before returns, no parenthesis 8244fee23f9Smrg i.e. 8254fee23f9Smrg 82648fb7bfaSmrg <code> 8274fee23f9Smrg } 8284fee23f9Smrg return __ret; 8294fee23f9Smrg 8304fee23f9Smrg -NOT- 8314fee23f9Smrg } 8324fee23f9Smrg 8334fee23f9Smrg return __ret; 8344fee23f9Smrg 8354fee23f9Smrg -NOT- 8364fee23f9Smrg 8374fee23f9Smrg } 8384fee23f9Smrg return (__ret); 83948fb7bfaSmrg </code> 8404fee23f9Smrg 8414fee23f9Smrg 8424fee23f9Smrg 14. Location of global variables. 8434fee23f9Smrg All global variables of class type, whether in the "user visible" 84448fb7bfaSmrg space (e.g., <code>cin</code>) or the implementation namespace, must be defined 8454fee23f9Smrg as a character array with the appropriate alignment and then later 8464fee23f9Smrg re-initialized to the correct value. 8474fee23f9Smrg 8484fee23f9Smrg This is due to startup issues on certain platforms, such as AIX. 84948fb7bfaSmrg For more explanation and examples, see <filename>src/globals.cc</filename>. All such 8504fee23f9Smrg variables should be contained in that file, for simplicity. 8514fee23f9Smrg 8524fee23f9Smrg 15. Exception abstractions 85348fb7bfaSmrg Use the exception abstractions found in <filename class="headerfile">functexcept.h</filename>, which allow 85448fb7bfaSmrg C++ programmers to use this library with <literal>-fno-exceptions</literal>. (Even if 8554fee23f9Smrg that is rarely advisable, it's a necessary evil for backwards 8564fee23f9Smrg compatibility.) 8574fee23f9Smrg 8584fee23f9Smrg 16. Exception error messages 8594fee23f9Smrg All start with the name of the function where the exception is 8604fee23f9Smrg thrown, and then (optional) descriptive text is added. Example: 8614fee23f9Smrg 86248fb7bfaSmrg <code> 8634fee23f9Smrg __throw_logic_error(__N("basic_string::_S_construct NULL not valid")); 86448fb7bfaSmrg </code> 8654fee23f9Smrg 86648fb7bfaSmrg Reason: The verbose terminate handler prints out <code>exception::what()</code>, 8674fee23f9Smrg as well as the typeinfo for the thrown exception. As this is the 8684fee23f9Smrg default terminate handler, by putting location info into the 8694fee23f9Smrg exception string, a very useful error message is printed out for 8704fee23f9Smrg uncaught exceptions. So useful, in fact, that non-programmers can 8714fee23f9Smrg give useful error messages, and programmers can intelligently 8724fee23f9Smrg speculate what went wrong without even using a debugger. 8734fee23f9Smrg 8744fee23f9Smrg 17. The doxygen style guide to comments is a separate document, 8754fee23f9Smrg see index. 8764fee23f9Smrg 8774fee23f9Smrg The library currently has a mixture of GNU-C and modern C++ coding 8784fee23f9Smrg styles. The GNU C usages will be combed out gradually. 8794fee23f9Smrg 8804fee23f9Smrg Name patterns: 8814fee23f9Smrg 8824fee23f9Smrg For nonstandard names appearing in Standard headers, we are constrained 8834fee23f9Smrg to use names that begin with underscores. This is called "uglification". 8844fee23f9Smrg The convention is: 8854fee23f9Smrg 88648fb7bfaSmrg Local and argument names: <literal>__[a-z].*</literal> 8874fee23f9Smrg 88848fb7bfaSmrg Examples: <code>__count __ix __s1</code> 8894fee23f9Smrg 89048fb7bfaSmrg Type names and template formal-argument names: <literal>_[A-Z][^_].*</literal> 8914fee23f9Smrg 89248fb7bfaSmrg Examples: <code>_Helper _CharT _N</code> 8934fee23f9Smrg 89448fb7bfaSmrg Member data and function names: <literal>_M_.*</literal> 8954fee23f9Smrg 89648fb7bfaSmrg Examples: <code>_M_num_elements _M_initialize ()</code> 8974fee23f9Smrg 89848fb7bfaSmrg Static data members, constants, and enumerations: <literal>_S_.*</literal> 8994fee23f9Smrg 90048fb7bfaSmrg Examples: <code>_S_max_elements _S_default_value</code> 9014fee23f9Smrg 9024fee23f9Smrg Don't use names in the same scope that differ only in the prefix, 9033f4ceed9Smrg e.g. _S_top and _M_top. See <link linkend="coding_style.bad_identifiers">BADNAMES</link> for a list of forbidden names. 9044fee23f9Smrg (The most tempting of these seem to be and "_T" and "__sz".) 9054fee23f9Smrg 9064fee23f9Smrg Names must never have "__" internally; it would confuse name 9074fee23f9Smrg unmanglers on some targets. Also, never use "__[0-9]", same reason. 9084fee23f9Smrg 9094fee23f9Smrg -------------------------- 9104fee23f9Smrg 9114fee23f9Smrg [BY EXAMPLE] 91248fb7bfaSmrg <code> 9134fee23f9Smrg 9144fee23f9Smrg #ifndef _HEADER_ 9154fee23f9Smrg #define _HEADER_ 1 9164fee23f9Smrg 9174fee23f9Smrg namespace std 9184fee23f9Smrg { 9194fee23f9Smrg class gribble 9204fee23f9Smrg { 9214fee23f9Smrg public: 9224fee23f9Smrg gribble() throw(); 9234fee23f9Smrg 9244fee23f9Smrg gribble(const gribble&); 9254fee23f9Smrg 9264fee23f9Smrg explicit 9274fee23f9Smrg gribble(int __howmany); 9284fee23f9Smrg 9294fee23f9Smrg gribble& 9304fee23f9Smrg operator=(const gribble&); 9314fee23f9Smrg 9324fee23f9Smrg virtual 9334fee23f9Smrg ~gribble() throw (); 9344fee23f9Smrg 9354fee23f9Smrg // Start with a capital letter, end with a period. 9364fee23f9Smrg inline void 9374fee23f9Smrg public_member(const char* __arg) const; 9384fee23f9Smrg 9394fee23f9Smrg // In-class function definitions should be restricted to one-liners. 9404fee23f9Smrg int 9414fee23f9Smrg one_line() { return 0 } 9424fee23f9Smrg 9434fee23f9Smrg int 9444fee23f9Smrg two_lines(const char* arg) 9454fee23f9Smrg { return strchr(arg, 'a'); } 9464fee23f9Smrg 9474fee23f9Smrg inline int 9484fee23f9Smrg three_lines(); // inline, but defined below. 9494fee23f9Smrg 9504fee23f9Smrg // Note indentation. 9514fee23f9Smrg template<typename _Formal_argument> 9524fee23f9Smrg void 9534fee23f9Smrg public_template() const throw(); 9544fee23f9Smrg 9554fee23f9Smrg template<typename _Iterator> 9564fee23f9Smrg void 9574fee23f9Smrg other_template(); 9584fee23f9Smrg 9594fee23f9Smrg private: 9604fee23f9Smrg class _Helper; 9614fee23f9Smrg 9624fee23f9Smrg int _M_private_data; 9634fee23f9Smrg int _M_more_stuff; 9644fee23f9Smrg _Helper* _M_helper; 9654fee23f9Smrg int _M_private_function(); 9664fee23f9Smrg 9674fee23f9Smrg enum _Enum 9684fee23f9Smrg { 9694fee23f9Smrg _S_one, 9704fee23f9Smrg _S_two 9714fee23f9Smrg }; 9724fee23f9Smrg 9734fee23f9Smrg static void 9744fee23f9Smrg _S_initialize_library(); 9754fee23f9Smrg }; 9764fee23f9Smrg 9774fee23f9Smrg // More-or-less-standard language features described by lack, not presence. 9784fee23f9Smrg # ifndef _G_NO_LONGLONG 9794fee23f9Smrg extern long long _G_global_with_a_good_long_name; // avoid globals! 9804fee23f9Smrg # endif 9814fee23f9Smrg 9824fee23f9Smrg // Avoid in-class inline definitions, define separately; 9834fee23f9Smrg // likewise for member class definitions: 9844fee23f9Smrg inline int 9854fee23f9Smrg gribble::public_member() const 9864fee23f9Smrg { int __local = 0; return __local; } 9874fee23f9Smrg 9884fee23f9Smrg class gribble::_Helper 9894fee23f9Smrg { 9904fee23f9Smrg int _M_stuff; 9914fee23f9Smrg 9924fee23f9Smrg friend class gribble; 9934fee23f9Smrg }; 9944fee23f9Smrg } 9954fee23f9Smrg 9964fee23f9Smrg // Names beginning with "__": only for arguments and 9974fee23f9Smrg // local variables; never use "__" in a type name, or 9984fee23f9Smrg // within any name; never use "__[0-9]". 9994fee23f9Smrg 10004fee23f9Smrg #endif /* _HEADER_ */ 10014fee23f9Smrg 10024fee23f9Smrg 10034fee23f9Smrg namespace std 10044fee23f9Smrg { 10054fee23f9Smrg template<typename T> // notice: "typename", not "class", no space 10064fee23f9Smrg long_return_value_type<with_many, args> 10074fee23f9Smrg function_name(char* pointer, // "char *pointer" is wrong. 10084fee23f9Smrg char* argument, 10094fee23f9Smrg const Reference& ref) 10104fee23f9Smrg { 10114fee23f9Smrg // int a_local; /* wrong; see below. */ 10124fee23f9Smrg if (test) 10134fee23f9Smrg { 10144fee23f9Smrg nested code 10154fee23f9Smrg } 10164fee23f9Smrg 10174fee23f9Smrg int a_local = 0; // declare variable at first use. 10184fee23f9Smrg 10194fee23f9Smrg // char a, b, *p; /* wrong */ 10204fee23f9Smrg char a = 'a'; 10214fee23f9Smrg char b = a + 1; 10224fee23f9Smrg char* c = "abc"; // each variable goes on its own line, always. 10234fee23f9Smrg 10244fee23f9Smrg // except maybe here... 10254fee23f9Smrg for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) { 10264fee23f9Smrg // ... 10274fee23f9Smrg } 10284fee23f9Smrg } 10294fee23f9Smrg 10304fee23f9Smrg gribble::gribble() 103148fb7bfaSmrg : _M_private_data(0), _M_more_stuff(0), _M_helper(0) 10324fee23f9Smrg { } 10334fee23f9Smrg 103448fb7bfaSmrg int 10354fee23f9Smrg gribble::three_lines() 10364fee23f9Smrg { 10374fee23f9Smrg // doesn't fit in one line. 10384fee23f9Smrg } 10394fee23f9Smrg } // namespace std 104048fb7bfaSmrg </code> 10414fee23f9Smrg </literallayout> 104248fb7bfaSmrg </section> 104348fb7bfaSmrg</section> 10444fee23f9Smrg 104548fb7bfaSmrg<section xml:id="contrib.design_notes" xreflabel="Design Notes"><info><title>Design Notes</title></info> 10464fee23f9Smrg <?dbhtml filename="source_design_notes.html"?> 104748fb7bfaSmrg 10484fee23f9Smrg <para> 10494fee23f9Smrg </para> 10504fee23f9Smrg 105148fb7bfaSmrg <literallayout class="normal"> 10524fee23f9Smrg 10534fee23f9Smrg The Library 10544fee23f9Smrg ----------- 10554fee23f9Smrg 10564fee23f9Smrg This paper is covers two major areas: 10574fee23f9Smrg 10584fee23f9Smrg - Features and policies not mentioned in the standard that 10594fee23f9Smrg the quality of the library implementation depends on, including 10604fee23f9Smrg extensions and "implementation-defined" features; 10614fee23f9Smrg 10624fee23f9Smrg - Plans for required but unimplemented library features and 10634fee23f9Smrg optimizations to them. 10644fee23f9Smrg 10654fee23f9Smrg Overhead 10664fee23f9Smrg -------- 10674fee23f9Smrg 10684fee23f9Smrg The standard defines a large library, much larger than the standard 10694fee23f9Smrg C library. A naive implementation would suffer substantial overhead 10704fee23f9Smrg in compile time, executable size, and speed, rendering it unusable 10714fee23f9Smrg in many (particularly embedded) applications. The alternative demands 10724fee23f9Smrg care in construction, and some compiler support, but there is no 10734fee23f9Smrg need for library subsets. 10744fee23f9Smrg 10754fee23f9Smrg What are the sources of this overhead? There are four main causes: 10764fee23f9Smrg 10774fee23f9Smrg - The library is specified almost entirely as templates, which 10784fee23f9Smrg with current compilers must be included in-line, resulting in 10794fee23f9Smrg very slow builds as tens or hundreds of thousands of lines 10804fee23f9Smrg of function definitions are read for each user source file. 10814fee23f9Smrg Indeed, the entire SGI STL, as well as the dos Reis valarray, 10824fee23f9Smrg are provided purely as header files, largely for simplicity in 10834fee23f9Smrg porting. Iostream/locale is (or will be) as large again. 10844fee23f9Smrg 10854fee23f9Smrg - The library is very flexible, specifying a multitude of hooks 10864fee23f9Smrg where users can insert their own code in place of defaults. 10874fee23f9Smrg When these hooks are not used, any time and code expended to 10884fee23f9Smrg support that flexibility is wasted. 10894fee23f9Smrg 10904fee23f9Smrg - Templates are often described as causing to "code bloat". In 10914fee23f9Smrg practice, this refers (when it refers to anything real) to several 10924fee23f9Smrg independent processes. First, when a class template is manually 10934fee23f9Smrg instantiated in its entirely, current compilers place the definitions 10944fee23f9Smrg for all members in a single object file, so that a program linking 10954fee23f9Smrg to one member gets definitions of all. Second, template functions 10964fee23f9Smrg which do not actually depend on the template argument are, under 10974fee23f9Smrg current compilers, generated anew for each instantiation, rather 10984fee23f9Smrg than being shared with other instantiations. Third, some of the 10994fee23f9Smrg flexibility mentioned above comes from virtual functions (both in 11004fee23f9Smrg regular classes and template classes) which current linkers add 11014fee23f9Smrg to the executable file even when they manifestly cannot be called. 11024fee23f9Smrg 11034fee23f9Smrg - The library is specified to use a language feature, exceptions, 11044fee23f9Smrg which in the current gcc compiler ABI imposes a run time and 11054fee23f9Smrg code space cost to handle the possibility of exceptions even when 11064fee23f9Smrg they are not used. Under the new ABI (accessed with -fnew-abi), 11074fee23f9Smrg there is a space overhead and a small reduction in code efficiency 11084fee23f9Smrg resulting from lost optimization opportunities associated with 11094fee23f9Smrg non-local branches associated with exceptions. 11104fee23f9Smrg 11114fee23f9Smrg What can be done to eliminate this overhead? A variety of coding 11124fee23f9Smrg techniques, and compiler, linker and library improvements and 11134fee23f9Smrg extensions may be used, as covered below. Most are not difficult, 11144fee23f9Smrg and some are already implemented in varying degrees. 11154fee23f9Smrg 11164fee23f9Smrg Overhead: Compilation Time 11174fee23f9Smrg -------------------------- 11184fee23f9Smrg 11194fee23f9Smrg Providing "ready-instantiated" template code in object code archives 11204fee23f9Smrg allows us to avoid generating and optimizing template instantiations 11214fee23f9Smrg in each compilation unit which uses them. However, the number of such 11224fee23f9Smrg instantiations that are useful to provide is limited, and anyway this 11234fee23f9Smrg is not enough, by itself, to minimize compilation time. In particular, 11244fee23f9Smrg it does not reduce time spent parsing conforming headers. 11254fee23f9Smrg 11264fee23f9Smrg Quicker header parsing will depend on library extensions and compiler 11274fee23f9Smrg improvements. One approach is some variation on the techniques 11284fee23f9Smrg previously marketed as "pre-compiled headers", now standardized as 11294fee23f9Smrg support for the "export" keyword. "Exported" template definitions 11304fee23f9Smrg can be placed (once) in a "repository" -- really just a library, but 11314fee23f9Smrg of template definitions rather than object code -- to be drawn upon 11324fee23f9Smrg at link time when an instantiation is needed, rather than placed in 11334fee23f9Smrg header files to be parsed along with every compilation unit. 11344fee23f9Smrg 11354fee23f9Smrg Until "export" is implemented we can put some of the lengthy template 11364fee23f9Smrg definitions in #if guards or alternative headers so that users can skip 11374fee23f9Smrg over the full definitions when they need only the ready-instantiated 11384fee23f9Smrg specializations. 11394fee23f9Smrg 11404fee23f9Smrg To be precise, this means that certain headers which define 11414fee23f9Smrg templates which users normally use only for certain arguments 11424fee23f9Smrg can be instrumented to avoid exposing the template definitions 11434fee23f9Smrg to the compiler unless a macro is defined. For example, in 11444fee23f9Smrg <string>, we might have: 11454fee23f9Smrg 11464fee23f9Smrg template <class _CharT, ... > class basic_string { 11474fee23f9Smrg ... // member declarations 11484fee23f9Smrg }; 11494fee23f9Smrg ... // operator declarations 11504fee23f9Smrg 11514fee23f9Smrg #ifdef _STRICT_ISO_ 11524fee23f9Smrg # if _G_NO_TEMPLATE_EXPORT 11534fee23f9Smrg # include <bits/std_locale.h> // headers needed by definitions 11544fee23f9Smrg # ... 11554fee23f9Smrg # include <bits/string.tcc> // member and global template definitions. 11564fee23f9Smrg # endif 11574fee23f9Smrg #endif 11584fee23f9Smrg 11594fee23f9Smrg Users who compile without specifying a strict-ISO-conforming flag 11604fee23f9Smrg would not see many of the template definitions they now see, and rely 11614fee23f9Smrg instead on ready-instantiated specializations in the library. This 11624fee23f9Smrg technique would be useful for the following substantial components: 11634fee23f9Smrg string, locale/iostreams, valarray. It would *not* be useful or 11644fee23f9Smrg usable with the following: containers, algorithms, iterators, 11654fee23f9Smrg allocator. Since these constitute a large (though decreasing) 11664fee23f9Smrg fraction of the library, the benefit the technique offers is 11674fee23f9Smrg limited. 11684fee23f9Smrg 11694fee23f9Smrg The language specifies the semantics of the "export" keyword, but 11704fee23f9Smrg the gcc compiler does not yet support it. When it does, problems 11714fee23f9Smrg with large template inclusions can largely disappear, given some 11724fee23f9Smrg minor library reorganization, along with the need for the apparatus 11734fee23f9Smrg described above. 11744fee23f9Smrg 11754fee23f9Smrg Overhead: Flexibility Cost 11764fee23f9Smrg -------------------------- 11774fee23f9Smrg 11784fee23f9Smrg The library offers many places where users can specify operations 11794fee23f9Smrg to be performed by the library in place of defaults. Sometimes 11804fee23f9Smrg this seems to require that the library use a more-roundabout, and 11814fee23f9Smrg possibly slower, way to accomplish the default requirements than 11824fee23f9Smrg would be used otherwise. 11834fee23f9Smrg 11844fee23f9Smrg The primary protection against this overhead is thorough compiler 11854fee23f9Smrg optimization, to crush out layers of inline function interfaces. 11864fee23f9Smrg Kuck & Associates has demonstrated the practicality of this kind 11874fee23f9Smrg of optimization. 11884fee23f9Smrg 11894fee23f9Smrg The second line of defense against this overhead is explicit 11904fee23f9Smrg specialization. By defining helper function templates, and writing 11914fee23f9Smrg specialized code for the default case, overhead can be eliminated 11924fee23f9Smrg for that case without sacrificing flexibility. This takes full 11934fee23f9Smrg advantage of any ability of the optimizer to crush out degenerate 11944fee23f9Smrg code. 11954fee23f9Smrg 11964fee23f9Smrg The library specifies many virtual functions which current linkers 11974fee23f9Smrg load even when they cannot be called. Some minor improvements to the 11984fee23f9Smrg compiler and to ld would eliminate any such overhead by simply 11994fee23f9Smrg omitting virtual functions that the complete program does not call. 12004fee23f9Smrg A prototype of this work has already been done. For targets where 12014fee23f9Smrg GNU ld is not used, a "pre-linker" could do the same job. 12024fee23f9Smrg 12034fee23f9Smrg The main areas in the standard interface where user flexibility 12044fee23f9Smrg can result in overhead are: 12054fee23f9Smrg 12064fee23f9Smrg - Allocators: Containers are specified to use user-definable 12074fee23f9Smrg allocator types and objects, making tuning for the container 12084fee23f9Smrg characteristics tricky. 12094fee23f9Smrg 12104fee23f9Smrg - Locales: the standard specifies locale objects used to implement 12114fee23f9Smrg iostream operations, involving many virtual functions which use 12124fee23f9Smrg streambuf iterators. 12134fee23f9Smrg 12144fee23f9Smrg - Algorithms and containers: these may be instantiated on any type, 12154fee23f9Smrg frequently duplicating code for identical operations. 12164fee23f9Smrg 12174fee23f9Smrg - Iostreams and strings: users are permitted to use these on their 12184fee23f9Smrg own types, and specify the operations the stream must use on these 12194fee23f9Smrg types. 12204fee23f9Smrg 12214fee23f9Smrg Note that these sources of overhead are _avoidable_. The techniques 12224fee23f9Smrg to avoid them are covered below. 12234fee23f9Smrg 12244fee23f9Smrg Code Bloat 12254fee23f9Smrg ---------- 12264fee23f9Smrg 12274fee23f9Smrg In the SGI STL, and in some other headers, many of the templates 12284fee23f9Smrg are defined "inline" -- either explicitly or by their placement 12294fee23f9Smrg in class definitions -- which should not be inline. This is a 12304fee23f9Smrg source of code bloat. Matt had remarked that he was relying on 12314fee23f9Smrg the compiler to recognize what was too big to benefit from inlining, 12324fee23f9Smrg and generate it out-of-line automatically. However, this also can 12334fee23f9Smrg result in code bloat except where the linker can eliminate the extra 12344fee23f9Smrg copies. 12354fee23f9Smrg 12364fee23f9Smrg Fixing these cases will require an audit of all inline functions 12374fee23f9Smrg defined in the library to determine which merit inlining, and moving 12384d5abbe8Smrg the rest out of line. This is an issue mainly in clauses 23, 25, and 12394fee23f9Smrg 27. Of course it can be done incrementally, and we should generally 12404fee23f9Smrg accept patches that move large functions out of line and into ".tcc" 12414fee23f9Smrg files, which can later be pulled into a repository. Compiler/linker 12424fee23f9Smrg improvements to recognize very large inline functions and move them 12434fee23f9Smrg out-of-line, but shared among compilation units, could make this 12444fee23f9Smrg work unnecessary. 12454fee23f9Smrg 12464fee23f9Smrg Pre-instantiating template specializations currently produces large 12474fee23f9Smrg amounts of dead code which bloats statically linked programs. The 12484fee23f9Smrg current state of the static library, libstdc++.a, is intolerable on 12494fee23f9Smrg this account, and will fuel further confused speculation about a need 12504fee23f9Smrg for a library "subset". A compiler improvement that treats each 12514fee23f9Smrg instantiated function as a separate object file, for linking purposes, 12524fee23f9Smrg would be one solution to this problem. An alternative would be to 12534fee23f9Smrg split up the manual instantiation files into dozens upon dozens of 12544fee23f9Smrg little files, each compiled separately, but an abortive attempt at 12554fee23f9Smrg this was done for <string> and, though it is far from complete, it 12564fee23f9Smrg is already a nuisance. A better interim solution (just until we have 12574fee23f9Smrg "export") is badly needed. 12584fee23f9Smrg 12594fee23f9Smrg When building a shared library, the current compiler/linker cannot 12604fee23f9Smrg automatically generate the instantiations needed. This creates a 12614fee23f9Smrg miserable situation; it means any time something is changed in the 12624fee23f9Smrg library, before a shared library can be built someone must manually 12634fee23f9Smrg copy the declarations of all templates that are needed by other parts 12644fee23f9Smrg of the library to an "instantiation" file, and add it to the build 12654fee23f9Smrg system to be compiled and linked to the library. This process is 12664fee23f9Smrg readily automated, and should be automated as soon as possible. 12674fee23f9Smrg Users building their own shared libraries experience identical 12684fee23f9Smrg frustrations. 12694fee23f9Smrg 12704fee23f9Smrg Sharing common aspects of template definitions among instantiations 12714fee23f9Smrg can radically reduce code bloat. The compiler could help a great 12724fee23f9Smrg deal here by recognizing when a function depends on nothing about 12734fee23f9Smrg a template parameter, or only on its size, and giving the resulting 12744fee23f9Smrg function a link-name "equate" that allows it to be shared with other 12754fee23f9Smrg instantiations. Implementation code could take advantage of the 12764fee23f9Smrg capability by factoring out code that does not depend on the template 12774fee23f9Smrg argument into separate functions to be merged by the compiler. 12784fee23f9Smrg 12794fee23f9Smrg Until such a compiler optimization is implemented, much can be done 12804fee23f9Smrg manually (if tediously) in this direction. One such optimization is 12814fee23f9Smrg to derive class templates from non-template classes, and move as much 12824fee23f9Smrg implementation as possible into the base class. Another is to partial- 12834fee23f9Smrg specialize certain common instantiations, such as vector<T*>, to share 12844fee23f9Smrg code for instantiations on all types T. While these techniques work, 12854fee23f9Smrg they are far from the complete solution that a compiler improvement 12864fee23f9Smrg would afford. 12874fee23f9Smrg 12884fee23f9Smrg Overhead: Expensive Language Features 12894fee23f9Smrg ------------------------------------- 12904fee23f9Smrg 12914fee23f9Smrg The main "expensive" language feature used in the standard library 12924fee23f9Smrg is exception support, which requires compiling in cleanup code with 12934fee23f9Smrg static table data to locate it, and linking in library code to use 12944fee23f9Smrg the table. For small embedded programs the amount of such library 12954fee23f9Smrg code and table data is assumed by some to be excessive. Under the 12964fee23f9Smrg "new" ABI this perception is generally exaggerated, although in some 12974fee23f9Smrg cases it may actually be excessive. 12984fee23f9Smrg 12994fee23f9Smrg To implement a library which does not use exceptions directly is 13004fee23f9Smrg not difficult given minor compiler support (to "turn off" exceptions 13014fee23f9Smrg and ignore exception constructs), and results in no great library 13024fee23f9Smrg maintenance difficulties. To be precise, given "-fno-exceptions", 13034fee23f9Smrg the compiler should treat "try" blocks as ordinary blocks, and 13044fee23f9Smrg "catch" blocks as dead code to ignore or eliminate. Compiler 13054fee23f9Smrg support is not strictly necessary, except in the case of "function 13064fee23f9Smrg try blocks"; otherwise the following macros almost suffice: 13074fee23f9Smrg 13084fee23f9Smrg #define throw(X) 13094fee23f9Smrg #define try if (true) 13104fee23f9Smrg #define catch(X) else if (false) 13114fee23f9Smrg 13124fee23f9Smrg However, there may be a need to use function try blocks in the 13134fee23f9Smrg library implementation, and use of macros in this way can make 13144fee23f9Smrg correct diagnostics impossible. Furthermore, use of this scheme 13154fee23f9Smrg would require the library to call a function to re-throw exceptions 13164fee23f9Smrg from a try block. Implementing the above semantics in the compiler 13174fee23f9Smrg is preferable. 13184fee23f9Smrg 13194fee23f9Smrg Given the support above (however implemented) it only remains to 13204fee23f9Smrg replace code that "throws" with a call to a well-documented "handler" 13214fee23f9Smrg function in a separate compilation unit which may be replaced by 13224fee23f9Smrg the user. The main source of exceptions that would be difficult 13234fee23f9Smrg for users to avoid is memory allocation failures, but users can 13244fee23f9Smrg define their own memory allocation primitives that never throw. 13254fee23f9Smrg Otherwise, the complete list of such handlers, and which library 13264fee23f9Smrg functions may call them, would be needed for users to be able to 13274fee23f9Smrg implement the necessary substitutes. (Fortunately, they have the 13284fee23f9Smrg source code.) 13294fee23f9Smrg 13304fee23f9Smrg Opportunities 13314fee23f9Smrg ------------- 13324fee23f9Smrg 13334fee23f9Smrg The template capabilities of C++ offer enormous opportunities for 13344fee23f9Smrg optimizing common library operations, well beyond what would be 13354fee23f9Smrg considered "eliminating overhead". In particular, many operations 13364fee23f9Smrg done in Glibc with macros that depend on proprietary language 13374fee23f9Smrg extensions can be implemented in pristine Standard C++. For example, 13384fee23f9Smrg the chapter 25 algorithms, and even C library functions such as strchr, 13394fee23f9Smrg can be specialized for the case of static arrays of known (small) size. 13404fee23f9Smrg 13414fee23f9Smrg Detailed optimization opportunities are identified below where 13424fee23f9Smrg the component where they would appear is discussed. Of course new 13434fee23f9Smrg opportunities will be identified during implementation. 13444fee23f9Smrg 13454fee23f9Smrg Unimplemented Required Library Features 13464fee23f9Smrg --------------------------------------- 13474fee23f9Smrg 13484fee23f9Smrg The standard specifies hundreds of components, grouped broadly by 13494fee23f9Smrg chapter. These are listed in excruciating detail in the CHECKLIST 13504fee23f9Smrg file. 13514fee23f9Smrg 13524fee23f9Smrg 17 general 13534fee23f9Smrg 18 support 13544fee23f9Smrg 19 diagnostics 13554fee23f9Smrg 20 utilities 13564fee23f9Smrg 21 string 13574fee23f9Smrg 22 locale 13584fee23f9Smrg 23 containers 13594fee23f9Smrg 24 iterators 13604fee23f9Smrg 25 algorithms 13614fee23f9Smrg 26 numerics 13624fee23f9Smrg 27 iostreams 13634fee23f9Smrg Annex D backward compatibility 13644fee23f9Smrg 13654fee23f9Smrg Anyone participating in implementation of the library should obtain 13664fee23f9Smrg a copy of the standard, ISO 14882. People in the U.S. can obtain an 13674fee23f9Smrg electronic copy for US$18 from ANSI's web site. Those from other 13684fee23f9Smrg countries should visit http://www.iso.org/ to find out the location 13694fee23f9Smrg of their country's representation in ISO, in order to know who can 13704fee23f9Smrg sell them a copy. 13714fee23f9Smrg 13724fee23f9Smrg The emphasis in the following sections is on unimplemented features 13734fee23f9Smrg and optimization opportunities. 13744fee23f9Smrg 13754fee23f9Smrg Chapter 17 General 13764fee23f9Smrg ------------------- 13774fee23f9Smrg 13784fee23f9Smrg Chapter 17 concerns overall library requirements. 13794fee23f9Smrg 13804fee23f9Smrg The standard doesn't mention threads. A multi-thread (MT) extension 13814fee23f9Smrg primarily affects operators new and delete (18), allocator (20), 13824fee23f9Smrg string (21), locale (22), and iostreams (27). The common underlying 13834fee23f9Smrg support needed for this is discussed under chapter 20. 13844fee23f9Smrg 13854fee23f9Smrg The standard requirements on names from the C headers create a 13864fee23f9Smrg lot of work, mostly done. Names in the C headers must be visible 13874fee23f9Smrg in the std:: and sometimes the global namespace; the names in the 13884fee23f9Smrg two scopes must refer to the same object. More stringent is that 13894fee23f9Smrg Koenig lookup implies that any types specified as defined in std:: 13904fee23f9Smrg really are defined in std::. Names optionally implemented as 13914fee23f9Smrg macros in C cannot be macros in C++. (An overview may be read at 13924fee23f9Smrg <http://www.cantrip.org/cheaders.html>). The scripts "inclosure" 13934fee23f9Smrg and "mkcshadow", and the directories shadow/ and cshadow/, are the 13944fee23f9Smrg beginning of an effort to conform in this area. 13954fee23f9Smrg 13964fee23f9Smrg A correct conforming definition of C header names based on underlying 13974fee23f9Smrg C library headers, and practical linking of conforming namespaced 13984fee23f9Smrg customer code with third-party C libraries depends ultimately on 13994fee23f9Smrg an ABI change, allowing namespaced C type names to be mangled into 14004fee23f9Smrg type names as if they were global, somewhat as C function names in a 14014fee23f9Smrg namespace, or C++ global variable names, are left unmangled. Perhaps 14024fee23f9Smrg another "extern" mode, such as 'extern "C-global"' would be an 14034fee23f9Smrg appropriate place for such type definitions. Such a type would 14044fee23f9Smrg affect mangling as follows: 14054fee23f9Smrg 14064fee23f9Smrg namespace A { 14074fee23f9Smrg struct X {}; 14084fee23f9Smrg extern "C-global" { // or maybe just 'extern "C"' 14094fee23f9Smrg struct Y {}; 14104fee23f9Smrg }; 14114fee23f9Smrg } 14124fee23f9Smrg void f(A::X*); // mangles to f__FPQ21A1X 14134fee23f9Smrg void f(A::Y*); // mangles to f__FP1Y 14144fee23f9Smrg 14154fee23f9Smrg (It may be that this is really the appropriate semantics for regular 14164fee23f9Smrg 'extern "C"', and 'extern "C-global"', as an extension, would not be 14174fee23f9Smrg necessary.) This would allow functions declared in non-standard C headers 14184fee23f9Smrg (and thus fixable by neither us nor users) to link properly with functions 14194fee23f9Smrg declared using C types defined in properly-namespaced headers. The 14204fee23f9Smrg problem this solves is that C headers (which C++ programmers do persist 14214fee23f9Smrg in using) frequently forward-declare C struct tags without including 14224fee23f9Smrg the header where the type is defined, as in 14234fee23f9Smrg 14244fee23f9Smrg struct tm; 14254fee23f9Smrg void munge(tm*); 14264fee23f9Smrg 14274fee23f9Smrg Without some compiler accommodation, munge cannot be called by correct 14284fee23f9Smrg C++ code using a pointer to a correctly-scoped tm* value. 14294fee23f9Smrg 14304fee23f9Smrg The current C headers use the preprocessor extension "#include_next", 14314fee23f9Smrg which the compiler complains about when run "-pedantic". 14324fee23f9Smrg (Incidentally, it appears that "-fpedantic" is currently ignored, 14334fee23f9Smrg probably a bug.) The solution in the C compiler is to use 14344fee23f9Smrg "-isystem" rather than "-I", but unfortunately in g++ this seems 14354fee23f9Smrg also to wrap the whole header in an 'extern "C"' block, so it's 14364fee23f9Smrg unusable for C++ headers. The correct solution appears to be to 14374fee23f9Smrg allow the various special include-directory options, if not given 14384fee23f9Smrg an argument, to affect subsequent include-directory options additively, 14394fee23f9Smrg so that if one said 14404fee23f9Smrg 14414fee23f9Smrg -pedantic -iprefix $(prefix) \ 14424fee23f9Smrg -idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \ 14434fee23f9Smrg -iwithprefix -I g++-v3/ext 14444fee23f9Smrg 14454fee23f9Smrg the compiler would search $(prefix)/g++-v3 and not report 14464fee23f9Smrg pedantic warnings for files found there, but treat files in 14474fee23f9Smrg $(prefix)/g++-v3/ext pedantically. (The undocumented semantics 14484fee23f9Smrg of "-isystem" in g++ stink. Can they be rescinded? If not it 14494fee23f9Smrg must be replaced with something more rationally behaved.) 14504fee23f9Smrg 14514fee23f9Smrg All the C headers need the treatment above; in the standard these 14524d5abbe8Smrg headers are mentioned in various clauses. Below, I have only 14534fee23f9Smrg mentioned those that present interesting implementation issues. 14544fee23f9Smrg 14554fee23f9Smrg The components identified as "mostly complete", below, have not been 14564fee23f9Smrg audited for conformance. In many cases where the library passes 14574fee23f9Smrg conformance tests we have non-conforming extensions that must be 14584fee23f9Smrg wrapped in #if guards for "pedantic" use, and in some cases renamed 14594fee23f9Smrg in a conforming way for continued use in the implementation regardless 14604fee23f9Smrg of conformance flags. 14614fee23f9Smrg 14624fee23f9Smrg The STL portion of the library still depends on a header 14634fee23f9Smrg stl/bits/stl_config.h full of #ifdef clauses. This apparatus 14644fee23f9Smrg should be replaced with autoconf/automake machinery. 14654fee23f9Smrg 14664fee23f9Smrg The SGI STL defines a type_traits<> template, specialized for 14674fee23f9Smrg many types in their code including the built-in numeric and 14684fee23f9Smrg pointer types and some library types, to direct optimizations of 14694fee23f9Smrg standard functions. The SGI compiler has been extended to generate 14704fee23f9Smrg specializations of this template automatically for user types, 14714fee23f9Smrg so that use of STL templates on user types can take advantage of 14724fee23f9Smrg these optimizations. Specializations for other, non-STL, types 14734fee23f9Smrg would make more optimizations possible, but extending the gcc 14744fee23f9Smrg compiler in the same way would be much better. Probably the next 14754fee23f9Smrg round of standardization will ratify this, but probably with 14764fee23f9Smrg changes, so it probably should be renamed to place it in the 14774fee23f9Smrg implementation namespace. 14784fee23f9Smrg 14794fee23f9Smrg The SGI STL also defines a large number of extensions visible in 14804fee23f9Smrg standard headers. (Other extensions that appear in separate headers 14814fee23f9Smrg have been sequestered in subdirectories ext/ and backward/.) All 14824fee23f9Smrg these extensions should be moved to other headers where possible, 14834fee23f9Smrg and in any case wrapped in a namespace (not std!), and (where kept 14844fee23f9Smrg in a standard header) girded about with macro guards. Some cannot be 14854fee23f9Smrg moved out of standard headers because they are used to implement 14864fee23f9Smrg standard features. The canonical method for accommodating these 14874fee23f9Smrg is to use a protected name, aliased in macro guards to a user-space 14884fee23f9Smrg name. Unfortunately C++ offers no satisfactory template typedef 14894fee23f9Smrg mechanism, so very ad-hoc and unsatisfactory aliasing must be used 14904fee23f9Smrg instead. 14914fee23f9Smrg 14924fee23f9Smrg Implementation of a template typedef mechanism should have the highest 14934fee23f9Smrg priority among possible extensions, on the same level as implementation 14944fee23f9Smrg of the template "export" feature. 14954fee23f9Smrg 14964fee23f9Smrg Chapter 18 Language support 14974fee23f9Smrg ---------------------------- 14984fee23f9Smrg 14994fee23f9Smrg Headers: <limits> <new> <typeinfo> <exception> 15004fee23f9Smrg C headers: <cstddef> <climits> <cfloat> <cstdarg> <csetjmp> 15014fee23f9Smrg <ctime> <csignal> <cstdlib> (also 21, 25, 26) 15024fee23f9Smrg 15034fee23f9Smrg This defines the built-in exceptions, rtti, numeric_limits<>, 15044fee23f9Smrg operator new and delete. Much of this is provided by the 15054fee23f9Smrg compiler in its static runtime library. 15064fee23f9Smrg 15074fee23f9Smrg Work to do includes defining numeric_limits<> specializations in 15084fee23f9Smrg separate files for all target architectures. Values for integer types 15094fee23f9Smrg except for bool and wchar_t are readily obtained from the C header 15104fee23f9Smrg <limits.h>, but values for the remaining numeric types (bool, wchar_t, 15114fee23f9Smrg float, double, long double) must be entered manually. This is 15124fee23f9Smrg largely dog work except for those members whose values are not 15134fee23f9Smrg easily deduced from available documentation. Also, this involves 15144fee23f9Smrg some work in target configuration to identify the correct choice of 15154fee23f9Smrg file to build against and to install. 15164fee23f9Smrg 15174fee23f9Smrg The definitions of the various operators new and delete must be 15184fee23f9Smrg made thread-safe, which depends on a portable exclusion mechanism, 15194fee23f9Smrg discussed under chapter 20. Of course there is always plenty of 15204fee23f9Smrg room for improvements to the speed of operators new and delete. 15214fee23f9Smrg 15224fee23f9Smrg <cstdarg>, in Glibc, defines some macros that gcc does not allow to 15234fee23f9Smrg be wrapped into an inline function. Probably this header will demand 15244fee23f9Smrg attention whenever a new target is chosen. The functions atexit(), 15254fee23f9Smrg exit(), and abort() in cstdlib have different semantics in C++, so 15264fee23f9Smrg must be re-implemented for C++. 15274fee23f9Smrg 15284fee23f9Smrg Chapter 19 Diagnostics 15294fee23f9Smrg ----------------------- 15304fee23f9Smrg 15314fee23f9Smrg Headers: <stdexcept> 15324fee23f9Smrg C headers: <cassert> <cerrno> 15334fee23f9Smrg 15344fee23f9Smrg This defines the standard exception objects, which are "mostly complete". 15354fee23f9Smrg Cygnus has a version, and now SGI provides a slightly different one. 15364fee23f9Smrg It makes little difference which we use. 15374fee23f9Smrg 15384fee23f9Smrg The C global name "errno", which C allows to be a variable or a macro, 15394fee23f9Smrg is required in C++ to be a macro. For MT it must typically result in 15404fee23f9Smrg a function call. 15414fee23f9Smrg 15424fee23f9Smrg Chapter 20 Utilities 15434fee23f9Smrg --------------------- 15444fee23f9Smrg Headers: <utility> <functional> <memory> 15454fee23f9Smrg C header: <ctime> (also in 18) 15464fee23f9Smrg 15474fee23f9Smrg SGI STL provides "mostly complete" versions of all the components 15484fee23f9Smrg defined in this chapter. However, the auto_ptr<> implementation 15494fee23f9Smrg is known to be wrong. Furthermore, the standard definition of it 15504fee23f9Smrg is known to be unimplementable as written. A minor change to the 15514fee23f9Smrg standard would fix it, and auto_ptr<> should be adjusted to match. 15524fee23f9Smrg 15534fee23f9Smrg Multi-threading affects the allocator implementation, and there must 15544fee23f9Smrg be configuration/installation choices for different users' MT 15554fee23f9Smrg requirements. Anyway, users will want to tune allocator options 15564fee23f9Smrg to support different target conditions, MT or no. 15574fee23f9Smrg 15584fee23f9Smrg The primitives used for MT implementation should be exposed, as an 15594fee23f9Smrg extension, for users' own work. We need cross-CPU "mutex" support, 15604fee23f9Smrg multi-processor shared-memory atomic integer operations, and single- 15614fee23f9Smrg processor uninterruptible integer operations, and all three configurable 15624fee23f9Smrg to be stubbed out for non-MT use, or to use an appropriately-loaded 15634fee23f9Smrg dynamic library for the actual runtime environment, or statically 15644fee23f9Smrg compiled in for cases where the target architecture is known. 15654fee23f9Smrg 15664fee23f9Smrg Chapter 21 String 15674fee23f9Smrg ------------------ 15684fee23f9Smrg Headers: <string> 15694fee23f9Smrg C headers: <cctype> <cwctype> <cstring> <cwchar> (also in 27) 15704fee23f9Smrg <cstdlib> (also in 18, 25, 26) 15714fee23f9Smrg 15724fee23f9Smrg We have "mostly-complete" char_traits<> implementations. Many of the 15734fee23f9Smrg char_traits<char> operations might be optimized further using existing 15744fee23f9Smrg proprietary language extensions. 15754fee23f9Smrg 15764fee23f9Smrg We have a "mostly-complete" basic_string<> implementation. The work 15774fee23f9Smrg to manually instantiate char and wchar_t specializations in object 15784fee23f9Smrg files to improve link-time behavior is extremely unsatisfactory, 15794fee23f9Smrg literally tripling library-build time with no commensurate improvement 15804fee23f9Smrg in static program link sizes. It must be redone. (Similar work is 15814d5abbe8Smrg needed for some components in clauses 22 and 27.) 15824fee23f9Smrg 15834fee23f9Smrg Other work needed for strings is MT-safety, as discussed under the 15844fee23f9Smrg chapter 20 heading. 15854fee23f9Smrg 15864fee23f9Smrg The standard C type mbstate_t from <cwchar> and used in char_traits<> 15874fee23f9Smrg must be different in C++ than in C, because in C++ the default constructor 15884fee23f9Smrg value mbstate_t() must be the "base" or "ground" sequence state. 15894fee23f9Smrg (According to the likely resolution of a recently raised Core issue, 15904fee23f9Smrg this may become unnecessary. However, there are other reasons to 15914fee23f9Smrg use a state type not as limited as whatever the C library provides.) 15924fee23f9Smrg If we might want to provide conversions from (e.g.) internally- 15934fee23f9Smrg represented EUC-wide to externally-represented Unicode, or vice- 15944fee23f9Smrg versa, the mbstate_t we choose will need to be more accommodating 15954fee23f9Smrg than what might be provided by an underlying C library. 15964fee23f9Smrg 15974fee23f9Smrg There remain some basic_string template-member functions which do 15984fee23f9Smrg not overload properly with their non-template brethren. The infamous 15994fee23f9Smrg hack akin to what was done in vector<> is needed, to conform to 16004fee23f9Smrg 23.1.1 para 10. The CHECKLIST items for basic_string marked 'X', 16014fee23f9Smrg or incomplete, are so marked for this reason. 16024fee23f9Smrg 16034fee23f9Smrg Replacing the string iterators, which currently are simple character 16044fee23f9Smrg pointers, with class objects would greatly increase the safety of the 16054fee23f9Smrg client interface, and also permit a "debug" mode in which range, 16064fee23f9Smrg ownership, and validity are rigorously checked. The current use of 16074fee23f9Smrg raw pointers as string iterators is evil. vector<> iterators need the 16084fee23f9Smrg same treatment. Note that the current implementation freely mixes 16094fee23f9Smrg pointers and iterators, and that must be fixed before safer iterators 16104fee23f9Smrg can be introduced. 16114fee23f9Smrg 16124fee23f9Smrg Some of the functions in <cstring> are different from the C version. 16134fee23f9Smrg generally overloaded on const and non-const argument pointers. For 16144fee23f9Smrg example, in <cstring> strchr is overloaded. The functions isupper 16154fee23f9Smrg etc. in <cctype> typically implemented as macros in C are functions 16164fee23f9Smrg in C++, because they are overloaded with others of the same name 16174fee23f9Smrg defined in <locale>. 16184fee23f9Smrg 16194fee23f9Smrg Many of the functions required in <cwctype> and <cwchar> cannot be 16204fee23f9Smrg implemented using underlying C facilities on intended targets because 16214fee23f9Smrg such facilities only partly exist. 16224fee23f9Smrg 16234fee23f9Smrg Chapter 22 Locale 16244fee23f9Smrg ------------------ 16254fee23f9Smrg Headers: <locale> 16264fee23f9Smrg C headers: <clocale> 16274fee23f9Smrg 16284fee23f9Smrg We have a "mostly complete" class locale, with the exception of 16294fee23f9Smrg code for constructing, and handling the names of, named locales. 16304fee23f9Smrg The ways that locales are named (particularly when categories 16314fee23f9Smrg (e.g. LC_TIME, LC_COLLATE) are different) varies among all target 16324fee23f9Smrg environments. This code must be written in various versions and 16334fee23f9Smrg chosen by configuration parameters. 16344fee23f9Smrg 16354fee23f9Smrg Members of many of the facets defined in <locale> are stubs. Generally, 16364fee23f9Smrg there are two sets of facets: the base class facets (which are supposed 16374fee23f9Smrg to implement the "C" locale) and the "byname" facets, which are supposed 16384fee23f9Smrg to read files to determine their behavior. The base ctype<>, collate<>, 16394fee23f9Smrg and numpunct<> facets are "mostly complete", except that the table of 16404fee23f9Smrg bitmask values used for "is" operations, and corresponding mask values, 16414fee23f9Smrg are still defined in libio and just included/linked. (We will need to 16424fee23f9Smrg implement these tables independently, soon, but should take advantage 16434fee23f9Smrg of libio where possible.) The num_put<>::put members for integer types 16444fee23f9Smrg are "mostly complete". 16454fee23f9Smrg 16464fee23f9Smrg A complete list of what has and has not been implemented may be 16474fee23f9Smrg found in CHECKLIST. However, note that the current definition of 16484fee23f9Smrg codecvt<wchar_t,char,mbstate_t> is wrong. It should simply write 16494fee23f9Smrg out the raw bytes representing the wide characters, rather than 16504fee23f9Smrg trying to convert each to a corresponding single "char" value. 16514fee23f9Smrg 16524fee23f9Smrg Some of the facets are more important than others. Specifically, 16534fee23f9Smrg the members of ctype<>, numpunct<>, num_put<>, and num_get<> facets 16544fee23f9Smrg are used by other library facilities defined in <string>, <istream>, 16554fee23f9Smrg and <ostream>, and the codecvt<> facet is used by basic_filebuf<> 16564fee23f9Smrg in <fstream>, so a conforming iostream implementation depends on 16574fee23f9Smrg these. 16584fee23f9Smrg 16594fee23f9Smrg The "long long" type eventually must be supported, but code mentioning 16604fee23f9Smrg it should be wrapped in #if guards to allow pedantic-mode compiling. 16614fee23f9Smrg 16624fee23f9Smrg Performance of num_put<> and num_get<> depend critically on 16634fee23f9Smrg caching computed values in ios_base objects, and on extensions 16644fee23f9Smrg to the interface with streambufs. 16654fee23f9Smrg 16664fee23f9Smrg Specifically: retrieving a copy of the locale object, extracting 16674fee23f9Smrg the needed facets, and gathering data from them, for each call to 16684fee23f9Smrg (e.g.) operator<< would be prohibitively slow. To cache format 16694fee23f9Smrg data for use by num_put<> and num_get<> we have a _Format_cache<> 16704fee23f9Smrg object stored in the ios_base::pword() array. This is constructed 16714fee23f9Smrg and initialized lazily, and is organized purely for utility. It 16724fee23f9Smrg is discarded when a new locale with different facets is imbued. 16734fee23f9Smrg 16744fee23f9Smrg Using only the public interfaces of the iterator arguments to the 16754fee23f9Smrg facet functions would limit performance by forbidding "vector-style" 16764fee23f9Smrg character operations. The streambuf iterator optimizations are 16774fee23f9Smrg described under chapter 24, but facets can also bypass the streambuf 16784fee23f9Smrg iterators via explicit specializations and operate directly on the 16794fee23f9Smrg streambufs, and use extended interfaces to get direct access to the 16804fee23f9Smrg streambuf internal buffer arrays. These extensions are mentioned 16814fee23f9Smrg under chapter 27. These optimizations are particularly important 16824fee23f9Smrg for input parsing. 16834fee23f9Smrg 16844fee23f9Smrg Unused virtual members of locale facets can be omitted, as mentioned 16854fee23f9Smrg above, by a smart linker. 16864fee23f9Smrg 16874fee23f9Smrg Chapter 23 Containers 16884fee23f9Smrg ---------------------- 16894fee23f9Smrg Headers: <deque> <list> <queue> <stack> <vector> <map> <set> <bitset> 16904fee23f9Smrg 16914fee23f9Smrg All the components in chapter 23 are implemented in the SGI STL. 16924fee23f9Smrg They are "mostly complete"; they include a large number of 16934fee23f9Smrg nonconforming extensions which must be wrapped. Some of these 16944fee23f9Smrg are used internally and must be renamed or duplicated. 16954fee23f9Smrg 16964fee23f9Smrg The SGI components are optimized for large-memory environments. For 16974fee23f9Smrg embedded targets, different criteria might be more appropriate. Users 16984fee23f9Smrg will want to be able to tune this behavior. We should provide 16994fee23f9Smrg ways for users to compile the library with different memory usage 17004fee23f9Smrg characteristics. 17014fee23f9Smrg 17024fee23f9Smrg A lot more work is needed on factoring out common code from different 17034fee23f9Smrg specializations to reduce code size here and in chapter 25. The 17044fee23f9Smrg easiest fix for this would be a compiler/ABI improvement that allows 17054fee23f9Smrg the compiler to recognize when a specialization depends only on the 17064fee23f9Smrg size (or other gross quality) of a template argument, and allow the 17074fee23f9Smrg linker to share the code with similar specializations. In its 17084fee23f9Smrg absence, many of the algorithms and containers can be partial- 17094fee23f9Smrg specialized, at least for the case of pointers, but this only solves 17104fee23f9Smrg a small part of the problem. Use of a type_traits-style template 17114fee23f9Smrg allows a few more optimization opportunities, more if the compiler 17124fee23f9Smrg can generate the specializations automatically. 17134fee23f9Smrg 17144fee23f9Smrg As an optimization, containers can specialize on the default allocator 17154fee23f9Smrg and bypass it, or take advantage of details of its implementation 17164fee23f9Smrg after it has been improved upon. 17174fee23f9Smrg 17184fee23f9Smrg Replacing the vector iterators, which currently are simple element 17194fee23f9Smrg pointers, with class objects would greatly increase the safety of the 17204fee23f9Smrg client interface, and also permit a "debug" mode in which range, 17214fee23f9Smrg ownership, and validity are rigorously checked. The current use of 17224fee23f9Smrg pointers for iterators is evil. 17234fee23f9Smrg 17244fee23f9Smrg As mentioned for chapter 24, the deque iterator is a good example of 17254fee23f9Smrg an opportunity to implement a "staged" iterator that would benefit 17264fee23f9Smrg from specializations of some algorithms. 17274fee23f9Smrg 17284fee23f9Smrg Chapter 24 Iterators 17294fee23f9Smrg --------------------- 17304fee23f9Smrg Headers: <iterator> 17314fee23f9Smrg 17324fee23f9Smrg Standard iterators are "mostly complete", with the exception of 17334fee23f9Smrg the stream iterators, which are not yet templatized on the 17344fee23f9Smrg stream type. Also, the base class template iterator<> appears 17354fee23f9Smrg to be wrong, so everything derived from it must also be wrong, 17364fee23f9Smrg currently. 17374fee23f9Smrg 17384fee23f9Smrg The streambuf iterators (currently located in stl/bits/std_iterator.h, 17394fee23f9Smrg but should be under bits/) can be rewritten to take advantage of 17404fee23f9Smrg friendship with the streambuf implementation. 17414fee23f9Smrg 17424fee23f9Smrg Matt Austern has identified opportunities where certain iterator 17434fee23f9Smrg types, particularly including streambuf iterators and deque 17444fee23f9Smrg iterators, have a "two-stage" quality, such that an intermediate 17454fee23f9Smrg limit can be checked much more quickly than the true limit on 17464fee23f9Smrg range operations. If identified with a member of iterator_traits, 17474fee23f9Smrg algorithms may be specialized for this case. Of course the 17484fee23f9Smrg iterators that have this quality can be identified by specializing 17494fee23f9Smrg a traits class. 17504fee23f9Smrg 17514fee23f9Smrg Many of the algorithms must be specialized for the streambuf 17524fee23f9Smrg iterators, to take advantage of block-mode operations, in order 17534fee23f9Smrg to allow iostream/locale operations' performance not to suffer. 17544fee23f9Smrg It may be that they could be treated as staged iterators and 17554fee23f9Smrg take advantage of those optimizations. 17564fee23f9Smrg 17574fee23f9Smrg Chapter 25 Algorithms 17584fee23f9Smrg ---------------------- 17594fee23f9Smrg Headers: <algorithm> 17604fee23f9Smrg C headers: <cstdlib> (also in 18, 21, 26)) 17614fee23f9Smrg 17624fee23f9Smrg The algorithms are "mostly complete". As mentioned above, they 17634fee23f9Smrg are optimized for speed at the expense of code and data size. 17644fee23f9Smrg 17654fee23f9Smrg Specializations of many of the algorithms for non-STL types would 17664fee23f9Smrg give performance improvements, but we must use great care not to 17674fee23f9Smrg interfere with fragile template overloading semantics for the 17684fee23f9Smrg standard interfaces. Conventionally the standard function template 17694fee23f9Smrg interface is an inline which delegates to a non-standard function 17704fee23f9Smrg which is then overloaded (this is already done in many places in 17714fee23f9Smrg the library). Particularly appealing opportunities for the sake of 17724fee23f9Smrg iostream performance are for copy and find applied to streambuf 17734fee23f9Smrg iterators or (as noted elsewhere) for staged iterators, of which 17744fee23f9Smrg the streambuf iterators are a good example. 17754fee23f9Smrg 17764fee23f9Smrg The bsearch and qsort functions cannot be overloaded properly as 17774fee23f9Smrg required by the standard because gcc does not yet allow overloading 17784fee23f9Smrg on the extern-"C"-ness of a function pointer. 17794fee23f9Smrg 17804fee23f9Smrg Chapter 26 Numerics 17814fee23f9Smrg -------------------- 17824fee23f9Smrg Headers: <complex> <valarray> <numeric> 17834fee23f9Smrg C headers: <cmath>, <cstdlib> (also 18, 21, 25) 17844fee23f9Smrg 17854fee23f9Smrg Numeric components: Gabriel dos Reis's valarray, Drepper's complex, 17864fee23f9Smrg and the few algorithms from the STL are "mostly done". Of course 17874fee23f9Smrg optimization opportunities abound for the numerically literate. It 17884fee23f9Smrg is not clear whether the valarray implementation really conforms 17894fee23f9Smrg fully, in the assumptions it makes about aliasing (and lack thereof) 17904fee23f9Smrg in its arguments. 17914fee23f9Smrg 17924fee23f9Smrg The C div() and ldiv() functions are interesting, because they are the 17934fee23f9Smrg only case where a C library function returns a class object by value. 17944fee23f9Smrg Since the C++ type div_t must be different from the underlying C type 17954fee23f9Smrg (which is in the wrong namespace) the underlying functions div() and 17964fee23f9Smrg ldiv() cannot be re-used efficiently. Fortunately they are trivial to 17974fee23f9Smrg re-implement. 17984fee23f9Smrg 17994fee23f9Smrg Chapter 27 Iostreams 18004fee23f9Smrg --------------------- 18014fee23f9Smrg Headers: <iosfwd> <streambuf> <ios> <ostream> <istream> <iostream> 18024fee23f9Smrg <iomanip> <sstream> <fstream> 18034fee23f9Smrg C headers: <cstdio> <cwchar> (also in 21) 18044fee23f9Smrg 18054fee23f9Smrg Iostream is currently in a very incomplete state. <iosfwd>, <iomanip>, 18064fee23f9Smrg ios_base, and basic_ios<> are "mostly complete". basic_streambuf<> and 18074fee23f9Smrg basic_ostream<> are well along, but basic_istream<> has had little work 18084fee23f9Smrg done. The standard stream objects, <sstream> and <fstream> have been 18094fee23f9Smrg started; basic_filebuf<> "write" functions have been implemented just 18104fee23f9Smrg enough to do "hello, world". 18114fee23f9Smrg 18124fee23f9Smrg Most of the istream and ostream operators << and >> (with the exception 18134fee23f9Smrg of the op<<(integer) ones) have not been changed to use locale primitives, 18144fee23f9Smrg sentry objects, or char_traits members. 18154fee23f9Smrg 18164fee23f9Smrg All these templates should be manually instantiated for char and 18174fee23f9Smrg wchar_t in a way that links only used members into user programs. 18184fee23f9Smrg 18194fee23f9Smrg Streambuf is fertile ground for optimization extensions. An extended 18204fee23f9Smrg interface giving iterator access to its internal buffer would be very 18214fee23f9Smrg useful for other library components. 18224fee23f9Smrg 18234fee23f9Smrg Iostream operations (primarily operators << and >>) can take advantage 18244fee23f9Smrg of the case where user code has not specified a locale, and bypass locale 18254fee23f9Smrg operations entirely. The current implementation of op<</num_put<>::put, 18264fee23f9Smrg for the integer types, demonstrates how they can cache encoding details 18274fee23f9Smrg from the locale on each operation. There is lots more room for 18284fee23f9Smrg optimization in this area. 18294fee23f9Smrg 18304fee23f9Smrg The definition of the relationship between the standard streams 18314fee23f9Smrg cout et al. and stdout et al. requires something like a "stdiobuf". 18324fee23f9Smrg The SGI solution of using double-indirection to actually use a 18334fee23f9Smrg stdio FILE object for buffering is unsatisfactory, because it 18344fee23f9Smrg interferes with peephole loop optimizations. 18354fee23f9Smrg 18364fee23f9Smrg The <sstream> header work has begun. stringbuf can benefit from 18374fee23f9Smrg friendship with basic_string<> and basic_string<>::_Rep to use 18384fee23f9Smrg those objects directly as buffers, and avoid allocating and making 18394fee23f9Smrg copies. 18404fee23f9Smrg 18414fee23f9Smrg The basic_filebuf<> template is a complex beast. It is specified to 18424fee23f9Smrg use the locale facet codecvt<> to translate characters between native 18434fee23f9Smrg files and the locale character encoding. In general this involves 18444fee23f9Smrg two buffers, one of "char" representing the file and another of 18454fee23f9Smrg "char_type", for the stream, with codecvt<> translating. The process 18464fee23f9Smrg is complicated by the variable-length nature of the translation, and 18474fee23f9Smrg the need to seek to corresponding places in the two representations. 18484fee23f9Smrg For the case of basic_filebuf<char>, when no translation is needed, 18494fee23f9Smrg a single buffer suffices. A specialized filebuf can be used to reduce 18504fee23f9Smrg code space overhead when no locale has been imbued. Matt Austern's 18514fee23f9Smrg work at SGI will be useful, perhaps directly as a source of code, or 18524fee23f9Smrg at least as an example to draw on. 18534fee23f9Smrg 18544fee23f9Smrg Filebuf, almost uniquely (cf. operator new), depends heavily on 18554fee23f9Smrg underlying environmental facilities. In current releases iostream 18564fee23f9Smrg depends fairly heavily on libio constant definitions, but it should 18574fee23f9Smrg be made independent. It also depends on operating system primitives 18584fee23f9Smrg for file operations. There is immense room for optimizations using 18594fee23f9Smrg (e.g.) mmap for reading. The shadow/ directory wraps, besides the 18604fee23f9Smrg standard C headers, the libio.h and unistd.h headers, for use mainly 18614fee23f9Smrg by filebuf. These wrappings have not been completed, though there 18624fee23f9Smrg is scaffolding in place. 18634fee23f9Smrg 18644fee23f9Smrg The encapsulation of certain C header <cstdio> names presents an 18654fee23f9Smrg interesting problem. It is possible to define an inline std::fprintf() 18664fee23f9Smrg implemented in terms of the 'extern "C"' vfprintf(), but there is no 18674fee23f9Smrg standard vfscanf() to use to implement std::fscanf(). It appears that 18684fee23f9Smrg vfscanf but be re-implemented in C++ for targets where no vfscanf 18694fee23f9Smrg extension has been defined. This is interesting in that it seems 18704fee23f9Smrg to be the only significant case in the C library where this kind of 18714fee23f9Smrg rewriting is necessary. (Of course Glibc provides the vfscanf() 18724fee23f9Smrg extension.) (The functions related to exit() must be rewritten 18734fee23f9Smrg for other reasons.) 18744fee23f9Smrg 18754fee23f9Smrg 18764fee23f9Smrg Annex D 18774fee23f9Smrg ------- 18784fee23f9Smrg Headers: <strstream> 18794fee23f9Smrg 18804fee23f9Smrg Annex D defines many non-library features, and many minor 18814fee23f9Smrg modifications to various headers, and a complete header. 18824fee23f9Smrg It is "mostly done", except that the libstdc++-2 <strstream> 18834fee23f9Smrg header has not been adopted into the library, or checked to 18844fee23f9Smrg verify that it matches the draft in those details that were 18854fee23f9Smrg clarified by the committee. Certainly it must at least be 18864fee23f9Smrg moved into the std namespace. 18874fee23f9Smrg 18884fee23f9Smrg We still need to wrap all the deprecated features in #if guards 18894fee23f9Smrg so that pedantic compile modes can detect their use. 18904fee23f9Smrg 18914fee23f9Smrg Nonstandard Extensions 18924fee23f9Smrg ---------------------- 18934fee23f9Smrg Headers: <iostream.h> <strstream.h> <hash> <rbtree> 18944fee23f9Smrg <pthread_alloc> <stdiobuf> (etc.) 18954fee23f9Smrg 18964fee23f9Smrg User code has come to depend on a variety of nonstandard components 18974fee23f9Smrg that we must not omit. Much of this code can be adopted from 18984fee23f9Smrg libstdc++-v2 or from the SGI STL. This particularly includes 18994fee23f9Smrg <iostream.h>, <strstream.h>, and various SGI extensions such 19004fee23f9Smrg as <hash_map.h>. Many of these are already placed in the 19014fee23f9Smrg subdirectories ext/ and backward/. (Note that it is better to 19024fee23f9Smrg include them via "<backward/hash_map.h>" or "<ext/hash_map>" than 19034fee23f9Smrg to search the subdirectory itself via a "-I" directive. 19044fee23f9Smrg </literallayout> 190548fb7bfaSmrg</section> 19064fee23f9Smrg 19074fee23f9Smrg</appendix> 1908