2 <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
6 <appendix id="appendix.contrib" xreflabel="Contributing">
7 <?dbhtml filename="appendix_contributing.html"?>
23 <primary>Appendix</primary>
24 <secondary>Contributing</secondary>
29 The GNU C++ Library follows an open development model. Active
30 contributors are assigned maintainer-ship responsibility, and given
31 write access to the source repository. First time contributors
32 should follow this procedure:
35 <sect1 id="contrib.list" xreflabel="Contributor Checklist">
36 <title>Contributor Checklist</title>
38 <sect2 id="list.reading" xreflabel="list.reading">
39 <title>Reading</title>
44 Get and read the relevant sections of the C++ language
45 specification. Copies of the full ISO 14882 standard are
46 available on line via the ISO mirror site for committee
47 members. Non-members, or those who have not paid for the
48 privilege of sitting on the committee and sustained their
49 two meeting commitment for voting rights, may get a copy of
50 the standard from their respective national standards
51 organization. In the USA, this national standards
52 organization is ANSI and their web-site is right
53 <ulink url="http://www.ansi.org">here.</ulink>
54 (And if you've already registered with them, clicking this link will take you to directly to the place where you can
55 <ulink url="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%3A2003">buy the standard on-line.)</ulink>
61 The library working group bugs, and known defects, can
63 <ulink url="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21 </ulink>
69 The newsgroup dedicated to standardization issues is
70 comp.std.c++: this FAQ for this group is quite useful and
72 found <ulink url="http://www.jamesd.demon.co.uk/csc/faq.html">
80 the <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU
81 Coding Standards</ulink>, and chuckle when you hit the part
82 about <quote>Using Languages Other Than C</quote>.
88 Be familiar with the extensions that preceded these
89 general GNU rules. These style issues for libstdc++ can be
90 found <link linkend="contrib.coding_style">here</link>.
96 And last but certainly not least, read the
97 library-specific information
98 found <link linkend="appendix.porting"> here</link>.
104 <sect2 id="list.copyright" xreflabel="list.copyright">
105 <title>Assignment</title>
107 Small changes can be accepted without a copyright assignment form on
108 file. New code and additions to the library need completed copyright
109 assignment form on file at the FSF. Note: your employer may be required
110 to fill out appropriate disclaimer forms as well.
114 Historically, the libstdc++ assignment form added the following
120 Which Belgian comic book character is better, Tintin or Asterix, and
126 While not strictly necessary, humoring the maintainers and answering
127 this question would be appreciated.
131 For more information about getting a copyright assignment, please see
132 <ulink url="http://www.gnu.org/prep/maintain/html_node/Legal-Matters.html">Legal
137 Please contact Benjamin Kosnik at
138 <email>bkoz+assign@redhat.com</email> if you are confused
139 about the assignment or have general licensing questions. When
140 requesting an assignment form from
141 <email>mailto:assign@gnu.org</email>, please cc the libstdc++
142 maintainer above so that progress can be monitored.
146 <sect2 id="list.getting" xreflabel="list.getting">
147 <title>Getting Sources</title>
149 <ulink url="http://gcc.gnu.org/svnwrite.html">Getting write access
150 (look for "Write after approval")</ulink>
154 <sect2 id="list.patches" xreflabel="list.patches">
155 <title>Submitting Patches</title>
158 Every patch must have several pieces of information before it can be
159 properly evaluated. Ideally (and to ensure the fastest possible
160 response from the maintainers) it would have all of these pieces:
166 A description of the bug and how your patch fixes this
167 bug. For new features a description of the feature and your
174 A ChangeLog entry as plain text; see the various
175 ChangeLog files for format and content. If using you are
176 using emacs as your editor, simply position the insertion
177 point at the beginning of your change and hit CX-4a to bring
178 up the appropriate ChangeLog entry. See--magic! Similar
179 functionality also exists for vi.
185 A testsuite submission or sample program that will
186 easily and simply show the existing error or test new
193 The patch itself. If you are accessing the SVN
194 repository use <command>svn update; svn diff NEW</command>;
195 else, use <command>diff -cp OLD NEW</command> ... If your
196 version of diff does not support these options, then get the
197 latest version of GNU
198 diff. The <ulink url="http://gcc.gnu.org/wiki/SvnTricks">SVN
199 Tricks</ulink> wiki page has information on customising the
200 output of <code>svn diff</code>.
206 When you have all these pieces, bundle them up in a
207 mail message and send it to libstdc++@gcc.gnu.org. All
208 patches and related discussion should be sent to the
209 libstdc++ mailing list.
218 <sect1 id="contrib.organization" xreflabel="Source Organization">
219 <?dbhtml filename="source_organization.html"?>
220 <title>Directory Layout and Source Conventions</title>
223 The unpacked source directory of libstdc++ contains the files
224 needed to create the GNU C++ Library.
228 It has subdirectories:
231 Files in HTML and text format that document usage, quirks of the
232 implementation, and contributor checklists.
235 All header files for the C++ library are within this directory,
236 modulo specific runtime-related files that are in the libsupc++
240 Files meant to be found by #include <name> directives in
241 standard-conforming user programs.
244 Headers intended to directly include standard C headers.
245 [NB: this can be enabled via --enable-cheaders=c]
248 Headers intended to include standard C headers in
249 the global namespace, and put select names into the std::
250 namespace. [NB: this is the default, and is the same as
251 --enable-cheaders=c_global]
254 Headers intended to include standard C headers
255 already in namespace std, and put select names into the std::
256 namespace. [NB: this is the same as --enable-cheaders=c_std]
259 Files included by standard headers and by other files in
263 Headers provided for backward compatibility, such as <iostream.h>.
264 They are not used in this library.
267 Headers that define extensions to the standard library. No
268 standard header refers to any of them.
271 Scripts that are used during the configure, build, make, or test
275 Files that are used in constructing the library, but are not
278 testsuites/[backward, demangle, ext, performance, thread, 17_* to 27_*]
279 Test programs are here, and may be used to begin to exercise the
280 library. Support for "make check" and "make check-install" is
281 complete, and runs through all the subdirectories here when this
282 command is issued from the build directory. Please note that
283 "make check" requires DejaGNU 1.4 or later to be installed. Please
284 note that "make check-script" calls the script mkcheck, which
285 requires bash, and which may need the paths to bash adjusted to
286 work properly, as /bin/bash is assumed.
288 Other subdirectories contain variant versions of certain files
289 that are meant to be copied or linked by the configure script.
298 In addition, a subdirectory holds the convenience library libsupc++.
301 Contains the runtime library for C++, including exception
302 handling and memory allocation and deallocation, RTTI, terminate
305 Note that glibc also has a bits/ subdirectory. We will either
306 need to be careful not to collide with names in its bits/
307 directory; or rename bits to (e.g.) cppbits/.
309 In files throughout the system, lines marked with an "XXX" indicate
310 a bug or incompletely-implemented feature. Lines marked "XXX MT"
311 indicate a place that may require attention for multi-thread safety.
316 <sect1 id="contrib.coding_style" xreflabel="Coding Style">
317 <?dbhtml filename="source_code_style.html"?>
318 <title>Coding Style</title>
321 <sect2 id="coding_style.bad_identifiers" xreflabel="coding_style.bad">
322 <title>Bad Identifiers</title>
324 Identifiers that conflict and should be avoided.
328 This is the list of names <quote>reserved to the
329 implementation</quote> that have been claimed by certain
330 compilers and system headers of interest, and should not be used
331 in the library. It will grow, of course. We generally are
332 interested in names that are not all-caps, except for those like
375 [Note that this list is out of date. It applies to the old
376 name-mangling; in G++ 3.0 and higher a different name-mangling is
377 used. In addition, many of the bugs relating to G++ interpreting
378 these names as operators have been fixed.]
380 The full set of __* identifiers (combined from gcc/cp/lex.c and
381 gcc/cplus-dem.c) that are either old or new, but are definitely
382 recognized by the demangler, is:
510 // long double conversion members mangled as __opr
511 // http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html
516 <sect2 id="coding_style.example" xreflabel="coding_style.example">
517 <title>By Example</title>
519 This library is written to appropriate C++ coding standards. As such,
520 it is intended to precede the recommendations of the GNU Coding
521 Standard, which can be referenced in full here:
523 http://www.gnu.org/prep/standards/standards.html#Formatting
525 The rest of this is also interesting reading, but skip the "Design
528 The GCC coding conventions are here, and are also useful:
529 http://gcc.gnu.org/codingconventions.html
531 In addition, because it doesn't seem to be stated explicitly anywhere
532 else, there is an 80 column source limit.
534 ChangeLog entries for member functions should use the
535 classname::member function name syntax as follows:
537 1999-04-15 Dennis Ritchie <dr@att.com>
539 * src/basic_file.cc (__basic_file::open): Fix thinko in
540 _G_HAVE_IO_FILE_OPEN bits.
542 Notable areas of divergence from what may be previous local practice
543 (particularly for GNU C) include:
545 01. Pointers and references
549 char *p = "flop"; // wrong
550 char &c = *p; // wrong
552 Reason: In C++, definitions are mixed with executable code. Here,
553 p is being initialized, not *p. This is near-universal
554 practice among C++ programmers; it is normal for C hackers
555 to switch spontaneously as they gain experience.
557 02. Operator names and parentheses
560 operator == (type) // wrong
562 Reason: The == is part of the function name. Separating
563 it makes the declaration look like an expression.
565 03. Function names and parentheses
568 void mangle () // wrong
570 Reason: no space before parentheses (except after a control-flow
571 keyword) is near-universal practice for C++. It identifies the
572 parentheses as the function-call operator or declarator, as
573 opposed to an expression or other overloaded use of parentheses.
575 04. Template function indentation
576 template<typename T>
578 template_function(args)
581 template<class T>
582 void template_function(args) {};
584 Reason: In class definitions, without indentation whitespace is
585 needed both above and below the declaration to distinguish
586 it visually from other members. (Also, re: "typename"
587 rather than "class".) T often could be int, which is
588 not a class. ("class", here, is an anachronism.)
590 05. Template class indentation
591 template<typename _CharT, typename _Traits>
592 class basic_ios : public ios_base
598 template<class _CharT, class _Traits>
599 class basic_ios : public ios_base
605 template<class _CharT, class _Traits>
606 class basic_ios : public ios_base
620 enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };
622 07. Member initialization lists
623 All one line, separate from class name.
626 : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
629 gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
648 09. Member functions declarations and definitions
649 Keywords such as extern, static, export, explicit, inline, etc
650 go on the line above the function name. Thus
657 Reason: GNU coding conventions dictate return types for functions
658 are on a separate line than the function name and parameter list
659 for definitions. For C++, where we have member functions that can
660 be either inline definitions or declarations, keeping to this
661 standard allows all member function names for a given class to be
662 aligned to the same margin, increasing readability.
665 10. Invocation of member functions with "this->"
666 For non-uglified names, use this->name to call the function.
672 Reason: Koenig lookup.
686 12. Spacing under protected and private in class declarations:
687 space above, none below
698 13. Spacing WRT return statements.
699 no extra spacing before returns, no parenthesis
716 14. Location of global variables.
717 All global variables of class type, whether in the "user visible"
718 space (e.g., cin) or the implementation namespace, must be defined
719 as a character array with the appropriate alignment and then later
720 re-initialized to the correct value.
722 This is due to startup issues on certain platforms, such as AIX.
723 For more explanation and examples, see src/globals.cc. All such
724 variables should be contained in that file, for simplicity.
726 15. Exception abstractions
727 Use the exception abstractions found in functexcept.h, which allow
728 C++ programmers to use this library with -fno-exceptions. (Even if
729 that is rarely advisable, it's a necessary evil for backwards
732 16. Exception error messages
733 All start with the name of the function where the exception is
734 thrown, and then (optional) descriptive text is added. Example:
736 __throw_logic_error(__N("basic_string::_S_construct NULL not valid"));
738 Reason: The verbose terminate handler prints out exception::what(),
739 as well as the typeinfo for the thrown exception. As this is the
740 default terminate handler, by putting location info into the
741 exception string, a very useful error message is printed out for
742 uncaught exceptions. So useful, in fact, that non-programmers can
743 give useful error messages, and programmers can intelligently
744 speculate what went wrong without even using a debugger.
746 17. The doxygen style guide to comments is a separate document,
749 The library currently has a mixture of GNU-C and modern C++ coding
750 styles. The GNU C usages will be combed out gradually.
754 For nonstandard names appearing in Standard headers, we are constrained
755 to use names that begin with underscores. This is called "uglification".
758 Local and argument names: __[a-z].*
760 Examples: __count __ix __s1
762 Type names and template formal-argument names: _[A-Z][^_].*
764 Examples: _Helper _CharT _N
766 Member data and function names: _M_.*
768 Examples: _M_num_elements _M_initialize ()
770 Static data members, constants, and enumerations: _S_.*
772 Examples: _S_max_elements _S_default_value
774 Don't use names in the same scope that differ only in the prefix,
775 e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names.
776 (The most tempting of these seem to be and "_T" and "__sz".)
778 Names must never have "__" internally; it would confuse name
779 unmanglers on some targets. Also, never use "__[0-9]", same reason.
781 --------------------------
795 gribble(const gribble&);
798 gribble(int __howmany);
801 operator=(const gribble&);
806 // Start with a capital letter, end with a period.
808 public_member(const char* __arg) const;
810 // In-class function definitions should be restricted to one-liners.
812 one_line() { return 0 }
815 two_lines(const char* arg)
816 { return strchr(arg, 'a'); }
819 three_lines(); // inline, but defined below.
822 template<typename _Formal_argument>
824 public_template() const throw();
826 template<typename _Iterator>
836 int _M_private_function();
845 _S_initialize_library();
848 // More-or-less-standard language features described by lack, not presence.
849 # ifndef _G_NO_LONGLONG
850 extern long long _G_global_with_a_good_long_name; // avoid globals!
853 // Avoid in-class inline definitions, define separately;
854 // likewise for member class definitions:
856 gribble::public_member() const
857 { int __local = 0; return __local; }
859 class gribble::_Helper
863 friend class gribble;
867 // Names beginning with "__": only for arguments and
868 // local variables; never use "__" in a type name, or
869 // within any name; never use "__[0-9]".
871 #endif /* _HEADER_ */
876 template<typename T> // notice: "typename", not "class", no space
877 long_return_value_type<with_many, args>
878 function_name(char* pointer, // "char *pointer" is wrong.
880 const Reference& ref)
882 // int a_local; /* wrong; see below. */
888 int a_local = 0; // declare variable at first use.
890 // char a, b, *p; /* wrong */
893 char* c = "abc"; // each variable goes on its own line, always.
895 // except maybe here...
896 for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) {
902 : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
906 gribble::three_lines()
908 // doesn't fit in one line.
915 <sect1 id="contrib.doc_style" xreflabel="Documentation Style">
916 <?dbhtml filename="documentation_style.html"?>
917 <title>Documentation Style</title>
918 <sect2 id="doc_style.doxygen" xreflabel="doc_style.doxygen">
919 <title>Doxygen</title>
920 <sect3 id="doxygen.prereq" xreflabel="doxygen.prereq">
921 <title>Prerequisites</title>
923 Prerequisite tools are Bash 2.x,
924 <ulink url="http://www.doxygen.org/">Doxygen</ulink>, and
925 the <ulink url="http://www.gnu.org/software/coreutils/">GNU
926 coreutils</ulink>. (GNU versions of find, xargs, and possibly
927 sed and grep are used, just because the GNU versions make
932 To generate the pretty pictures and hierarchy
934 <ulink url="http://www.research.att.com/sw/tools/graphviz/download.html">Graphviz</ulink>
935 package will need to be installed.
939 <sect3 id="doxygen.rules" xreflabel="doxygen.rules">
940 <title>Generating the Doxygen Files</title>
942 The following Makefile rules run Doxygen to generate HTML
943 docs, XML docs, and the man pages.
947 <screen><userinput>make doc-html-doxygen</userinput></screen>
951 <screen><userinput>make doc-xml-doxygen</userinput></screen>
955 <screen><userinput>make doc-man-doxygen</userinput></screen>
959 Careful observers will see that the Makefile rules simply call
960 a script from the source tree, <filename>run_doxygen</filename>, which
961 does the actual work of running Doxygen and then (most
962 importantly) massaging the output files. If for some reason
963 you prefer to not go through the Makefile, you can call this
964 script directly. (Start by passing <literal>--help</literal>.)
968 If you wish to tweak the Doxygen settings, do so by editing
969 <filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow
970 library hackers are written in triple-# comments.
975 <sect3 id="doxygen.markup" xreflabel="doxygen.markup">
976 <title>Markup</title>
979 In general, libstdc++ files should be formatted according to
980 the rules found in the
981 <link linkend="contrib.coding_style">Coding Standard</link>. Before
982 any doxygen-specific formatting tweaks are made, please try to
983 make sure that the initial formatting is sound.
987 Adding Doxygen markup to a file (informally called
988 <quote>doxygenating</quote>) is very simple. The Doxygen manual can be
990 <ulink url="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</ulink>.
991 We try to use a very-recent version of Doxygen.
996 <classname>deque</classname>/<classname>vector</classname>/<classname>list</classname>
997 and <classname>std::pair</classname> as examples. For
998 functions, see their member functions, and the free functions
999 in <filename>stl_algobase.h</filename>. Member functions of
1000 other container-like types should read similarly to these
1005 These points accompany the first list in section 3.1 of the
1010 <listitem><para>Use the Javadoc style...</para></listitem>
1013 ...not the Qt style. The intermediate *'s are preferred.
1018 Use the triple-slash style only for one-line comments (the
1019 <quote>brief</quote> mode). Very recent versions of Doxygen permit
1020 full-mode comments in triple-slash blocks, but the
1021 formatting still comes out wonky.
1026 This is disgusting. Don't do this.
1032 Use the @-style of commands, not the !-style. Please be
1033 careful about whitespace in your markup comments. Most of the
1034 time it doesn't matter; doxygen absorbs most whitespace, and
1035 both HTML and *roff are agnostic about whitespace. However,
1036 in <pre> blocks and @code/@endcode sections, spacing can
1037 have <quote>interesting</quote> effects.
1041 Use either kind of grouping, as
1042 appropriate. <filename>doxygroups.cc</filename> exists for this
1043 purpose. See <filename>stl_iterator.h</filename> for a good example
1044 of the <quote>other</quote> kind of grouping.
1048 Please use markup tags like @p and @a when referring to things
1049 such as the names of function parameters. Use @e for emphasis
1050 when necessary. Use @c to refer to other standard names.
1051 (Examples of all these abound in the present code.)
1058 <sect2 id="doc_style.docbook" xreflabel="doc_style.docbook">
1059 <title>Docbook</title>
1061 <sect3 id="docbook.prereq" xreflabel="docbook.prereq">
1062 <title>Prerequisites</title>
1064 Editing the DocBook sources requires an XML editor. Many
1065 exist: some notable options
1066 include <command>emacs</command>, <application>Kate</application>,
1067 or <application>Conglomerate</application>.
1071 Some editors support special <quote>XML Validation</quote>
1072 modes that can validate the file as it is
1073 produced. Recommended is the <command>nXML Mode</command>
1074 for <command>emacs</command>.
1078 Besides an editor, additional DocBook files and XML tools are
1083 Access to the DocBook stylesheets and DTD is required. The
1084 stylesheets are usually packaged by vendor, in something
1085 like <filename>docbook-style-xsl</filename>. To exactly match
1086 generated output, please use a version of the stylesheets
1088 to <filename>docbook-style-xsl-1.74.0-5</filename>. The
1089 installation directory for this package corresponds to
1090 the <literal>XSL_STYLE_DIR</literal>
1091 in <filename>doc/Makefile.am</filename> and defaults
1092 to <filename class="directory">/usr/share/sgml/docbook/xsl-stylesheets</filename>.
1096 For processing XML, an XML processor and some style
1097 sheets are necessary. Defaults are <command>xsltproc</command>
1098 provided by <filename>libxslt</filename>.
1102 For validating the XML document, you'll need
1103 something like <command>xmllint</command> and access to the
1104 DocBook DTD. These are provided
1105 by a vendor package like <filename>libxml2</filename>.
1109 For PDF output, something that transforms valid XML to PDF is
1110 required. Possible solutions include <command>xmlto</command>,
1111 <ulink url="http://xmlgraphics.apache.org/fop/">Apache
1112 FOP</ulink>, or <command>prince</command>. Other options are
1113 listed on the DocBook web <ulink
1114 url="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</ulink>. Please
1115 consult the <email>libstdc++@gcc.gnu.org</email> list when
1116 preparing printed manuals for current best practice and suggestions.
1120 Make sure that the XML documentation and markup is valid for
1121 any change. This can be done easily, with the validation rules
1122 in the <filename>Makefile</filename>, which is equivalent to doing:
1127 xmllint --noout --valid <filename>xml/index.xml</filename>
1132 <sect3 id="docbook.rules" xreflabel="docbook.rules">
1133 <title>Generating the DocBook Files</title>
1136 The following Makefile rules generate (in order): an HTML
1137 version of all the documentation, a PDF version of the same, a
1138 single XML document, and the result of validating the entire XML
1143 <screen><userinput>make doc-html</userinput></screen>
1147 <screen><userinput>make doc-pdf</userinput></screen>
1151 <screen><userinput>make doc-xml-single</userinput></screen>
1155 <screen><userinput>make doc-xml-validate</userinput></screen>
1160 <sect3 id="docbook.examples" xreflabel="docbook.examples">
1161 <title>File Organization and Basics</title>
1164 <emphasis>Which files are important</emphasis>
1166 All Docbook files are in the directory
1167 libstdc++-v3/doc/xml
1169 Inside this directory, the files of importance:
1170 spine.xml - index to documentation set
1171 manual/spine.xml - index to manual
1172 manual/*.xml - individual chapters and sections of the manual
1173 faq.xml - index to FAQ
1174 api.xml - index to source level / API
1176 All *.txml files are template xml files, i.e., otherwise empty files with
1177 the correct structure, suitable for filling in with new information.
1179 <emphasis>Canonical Writing Style</emphasis>
1183 member function template
1184 (via C++ Templates, Vandevoorde)
1186 class in namespace std: allocator, not std::allocator
1188 header file: iostream, not <iostream>
1191 <emphasis>General structure</emphasis>
1226 <sect3 id="docbook.markup" xreflabel="docbook.markup">
1227 <title>Markup By Example</title>
1230 Complete details on Docbook markup can be found in the DocBook Element
1231 Reference, <ulink url="http://www.docbook.org/tdg/en/html/part2.html">online</ulink>. An
1232 incomplete reference for HTML to Docbook conversion is detailed in the
1237 <title>HTML to Docbook XML markup comparison</title>
1238 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
1239 <colspec colname='c1'></colspec>
1240 <colspec colname='c2'></colspec>
1251 <entry><p></entry>
1252 <entry><para></entry>
1255 <entry><pre></entry>
1256 <entry><computeroutput>, <programlisting>,
1257 <literallayout></entry>
1260 <entry><ul></entry>
1261 <entry><itemizedlist></entry>
1264 <entry><ol></entry>
1265 <entry><orderedlist></entry>
1268 <entry><il></entry>
1269 <entry><listitem></entry>
1272 <entry><dl></entry>
1273 <entry><variablelist></entry>
1276 <entry><dt></entry>
1277 <entry><term></entry>
1280 <entry><dd></entry>
1281 <entry><listitem></entry>
1285 <entry><a href=""></entry>
1286 <entry><ulink url=""></entry>
1289 <entry><code></entry>
1290 <entry><literal>, <programlisting></entry>
1293 <entry><strong></entry>
1294 <entry><emphasis></entry>
1297 <entry><em></entry>
1298 <entry><emphasis></entry>
1301 <entry>"</entry>
1302 <entry><quote></entry>
1309 And examples of detailed markup for which there are no real HTML
1310 equivalents are listed in the table below.
1314 <title>Docbook XML Element Use</title>
1315 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
1316 <colspec colname='c1'></colspec>
1317 <colspec colname='c2'></colspec>
1321 <entry>Element</entry>
1328 <entry><structname></entry>
1329 <entry><structname>char_traits</structname></entry>
1332 <entry><classname></entry>
1333 <entry><classname>string</classname></entry>
1336 <entry><function></entry>
1338 <para><function>clear()</function></para>
1339 <para><function>fs.clear()</function></para>
1343 <entry><type></entry>
1344 <entry><type>long long</type></entry>
1347 <entry><varname></entry>
1348 <entry><varname>fs</varname></entry>
1351 <entry><literal></entry>
1353 <para><literal>-Weffc++</literal></para>
1354 <para><literal>rel_ops</literal></para>
1358 <entry><constant></entry>
1360 <para><constant>_GNU_SOURCE</constant></para>
1361 <para><constant>3.0</constant></para>
1365 <entry><command></entry>
1366 <entry><command>g++</command></entry>
1369 <entry><errortext></entry>
1370 <entry><errortext>In instantiation of</errortext></entry>
1373 <entry><filename></entry>
1375 <para><filename class="headerfile">ctype.h</filename></para>
1376 <para><filename class="directory">/home/gcc/build</filename></para>
1388 <sect1 id="contrib.design_notes" xreflabel="Design Notes">
1389 <?dbhtml filename="source_design_notes.html"?>
1390 <title>Design Notes</title>
1399 This paper is covers two major areas:
1401 - Features and policies not mentioned in the standard that
1402 the quality of the library implementation depends on, including
1403 extensions and "implementation-defined" features;
1405 - Plans for required but unimplemented library features and
1406 optimizations to them.
1411 The standard defines a large library, much larger than the standard
1412 C library. A naive implementation would suffer substantial overhead
1413 in compile time, executable size, and speed, rendering it unusable
1414 in many (particularly embedded) applications. The alternative demands
1415 care in construction, and some compiler support, but there is no
1416 need for library subsets.
1418 What are the sources of this overhead? There are four main causes:
1420 - The library is specified almost entirely as templates, which
1421 with current compilers must be included in-line, resulting in
1422 very slow builds as tens or hundreds of thousands of lines
1423 of function definitions are read for each user source file.
1424 Indeed, the entire SGI STL, as well as the dos Reis valarray,
1425 are provided purely as header files, largely for simplicity in
1426 porting. Iostream/locale is (or will be) as large again.
1428 - The library is very flexible, specifying a multitude of hooks
1429 where users can insert their own code in place of defaults.
1430 When these hooks are not used, any time and code expended to
1431 support that flexibility is wasted.
1433 - Templates are often described as causing to "code bloat". In
1434 practice, this refers (when it refers to anything real) to several
1435 independent processes. First, when a class template is manually
1436 instantiated in its entirely, current compilers place the definitions
1437 for all members in a single object file, so that a program linking
1438 to one member gets definitions of all. Second, template functions
1439 which do not actually depend on the template argument are, under
1440 current compilers, generated anew for each instantiation, rather
1441 than being shared with other instantiations. Third, some of the
1442 flexibility mentioned above comes from virtual functions (both in
1443 regular classes and template classes) which current linkers add
1444 to the executable file even when they manifestly cannot be called.
1446 - The library is specified to use a language feature, exceptions,
1447 which in the current gcc compiler ABI imposes a run time and
1448 code space cost to handle the possibility of exceptions even when
1449 they are not used. Under the new ABI (accessed with -fnew-abi),
1450 there is a space overhead and a small reduction in code efficiency
1451 resulting from lost optimization opportunities associated with
1452 non-local branches associated with exceptions.
1454 What can be done to eliminate this overhead? A variety of coding
1455 techniques, and compiler, linker and library improvements and
1456 extensions may be used, as covered below. Most are not difficult,
1457 and some are already implemented in varying degrees.
1459 Overhead: Compilation Time
1460 --------------------------
1462 Providing "ready-instantiated" template code in object code archives
1463 allows us to avoid generating and optimizing template instantiations
1464 in each compilation unit which uses them. However, the number of such
1465 instantiations that are useful to provide is limited, and anyway this
1466 is not enough, by itself, to minimize compilation time. In particular,
1467 it does not reduce time spent parsing conforming headers.
1469 Quicker header parsing will depend on library extensions and compiler
1470 improvements. One approach is some variation on the techniques
1471 previously marketed as "pre-compiled headers", now standardized as
1472 support for the "export" keyword. "Exported" template definitions
1473 can be placed (once) in a "repository" -- really just a library, but
1474 of template definitions rather than object code -- to be drawn upon
1475 at link time when an instantiation is needed, rather than placed in
1476 header files to be parsed along with every compilation unit.
1478 Until "export" is implemented we can put some of the lengthy template
1479 definitions in #if guards or alternative headers so that users can skip
1480 over the full definitions when they need only the ready-instantiated
1483 To be precise, this means that certain headers which define
1484 templates which users normally use only for certain arguments
1485 can be instrumented to avoid exposing the template definitions
1486 to the compiler unless a macro is defined. For example, in
1487 <string>, we might have:
1489 template <class _CharT, ... > class basic_string {
1490 ... // member declarations
1492 ... // operator declarations
1495 # if _G_NO_TEMPLATE_EXPORT
1496 # include <bits/std_locale.h> // headers needed by definitions
1498 # include <bits/string.tcc> // member and global template definitions.
1502 Users who compile without specifying a strict-ISO-conforming flag
1503 would not see many of the template definitions they now see, and rely
1504 instead on ready-instantiated specializations in the library. This
1505 technique would be useful for the following substantial components:
1506 string, locale/iostreams, valarray. It would *not* be useful or
1507 usable with the following: containers, algorithms, iterators,
1508 allocator. Since these constitute a large (though decreasing)
1509 fraction of the library, the benefit the technique offers is
1512 The language specifies the semantics of the "export" keyword, but
1513 the gcc compiler does not yet support it. When it does, problems
1514 with large template inclusions can largely disappear, given some
1515 minor library reorganization, along with the need for the apparatus
1518 Overhead: Flexibility Cost
1519 --------------------------
1521 The library offers many places where users can specify operations
1522 to be performed by the library in place of defaults. Sometimes
1523 this seems to require that the library use a more-roundabout, and
1524 possibly slower, way to accomplish the default requirements than
1525 would be used otherwise.
1527 The primary protection against this overhead is thorough compiler
1528 optimization, to crush out layers of inline function interfaces.
1529 Kuck & Associates has demonstrated the practicality of this kind
1532 The second line of defense against this overhead is explicit
1533 specialization. By defining helper function templates, and writing
1534 specialized code for the default case, overhead can be eliminated
1535 for that case without sacrificing flexibility. This takes full
1536 advantage of any ability of the optimizer to crush out degenerate
1539 The library specifies many virtual functions which current linkers
1540 load even when they cannot be called. Some minor improvements to the
1541 compiler and to ld would eliminate any such overhead by simply
1542 omitting virtual functions that the complete program does not call.
1543 A prototype of this work has already been done. For targets where
1544 GNU ld is not used, a "pre-linker" could do the same job.
1546 The main areas in the standard interface where user flexibility
1547 can result in overhead are:
1549 - Allocators: Containers are specified to use user-definable
1550 allocator types and objects, making tuning for the container
1551 characteristics tricky.
1553 - Locales: the standard specifies locale objects used to implement
1554 iostream operations, involving many virtual functions which use
1555 streambuf iterators.
1557 - Algorithms and containers: these may be instantiated on any type,
1558 frequently duplicating code for identical operations.
1560 - Iostreams and strings: users are permitted to use these on their
1561 own types, and specify the operations the stream must use on these
1564 Note that these sources of overhead are _avoidable_. The techniques
1565 to avoid them are covered below.
1570 In the SGI STL, and in some other headers, many of the templates
1571 are defined "inline" -- either explicitly or by their placement
1572 in class definitions -- which should not be inline. This is a
1573 source of code bloat. Matt had remarked that he was relying on
1574 the compiler to recognize what was too big to benefit from inlining,
1575 and generate it out-of-line automatically. However, this also can
1576 result in code bloat except where the linker can eliminate the extra
1579 Fixing these cases will require an audit of all inline functions
1580 defined in the library to determine which merit inlining, and moving
1581 the rest out of line. This is an issue mainly in chapters 23, 25, and
1582 27. Of course it can be done incrementally, and we should generally
1583 accept patches that move large functions out of line and into ".tcc"
1584 files, which can later be pulled into a repository. Compiler/linker
1585 improvements to recognize very large inline functions and move them
1586 out-of-line, but shared among compilation units, could make this
1589 Pre-instantiating template specializations currently produces large
1590 amounts of dead code which bloats statically linked programs. The
1591 current state of the static library, libstdc++.a, is intolerable on
1592 this account, and will fuel further confused speculation about a need
1593 for a library "subset". A compiler improvement that treats each
1594 instantiated function as a separate object file, for linking purposes,
1595 would be one solution to this problem. An alternative would be to
1596 split up the manual instantiation files into dozens upon dozens of
1597 little files, each compiled separately, but an abortive attempt at
1598 this was done for <string> and, though it is far from complete, it
1599 is already a nuisance. A better interim solution (just until we have
1600 "export") is badly needed.
1602 When building a shared library, the current compiler/linker cannot
1603 automatically generate the instantiations needed. This creates a
1604 miserable situation; it means any time something is changed in the
1605 library, before a shared library can be built someone must manually
1606 copy the declarations of all templates that are needed by other parts
1607 of the library to an "instantiation" file, and add it to the build
1608 system to be compiled and linked to the library. This process is
1609 readily automated, and should be automated as soon as possible.
1610 Users building their own shared libraries experience identical
1613 Sharing common aspects of template definitions among instantiations
1614 can radically reduce code bloat. The compiler could help a great
1615 deal here by recognizing when a function depends on nothing about
1616 a template parameter, or only on its size, and giving the resulting
1617 function a link-name "equate" that allows it to be shared with other
1618 instantiations. Implementation code could take advantage of the
1619 capability by factoring out code that does not depend on the template
1620 argument into separate functions to be merged by the compiler.
1622 Until such a compiler optimization is implemented, much can be done
1623 manually (if tediously) in this direction. One such optimization is
1624 to derive class templates from non-template classes, and move as much
1625 implementation as possible into the base class. Another is to partial-
1626 specialize certain common instantiations, such as vector<T*>, to share
1627 code for instantiations on all types T. While these techniques work,
1628 they are far from the complete solution that a compiler improvement
1631 Overhead: Expensive Language Features
1632 -------------------------------------
1634 The main "expensive" language feature used in the standard library
1635 is exception support, which requires compiling in cleanup code with
1636 static table data to locate it, and linking in library code to use
1637 the table. For small embedded programs the amount of such library
1638 code and table data is assumed by some to be excessive. Under the
1639 "new" ABI this perception is generally exaggerated, although in some
1640 cases it may actually be excessive.
1642 To implement a library which does not use exceptions directly is
1643 not difficult given minor compiler support (to "turn off" exceptions
1644 and ignore exception constructs), and results in no great library
1645 maintenance difficulties. To be precise, given "-fno-exceptions",
1646 the compiler should treat "try" blocks as ordinary blocks, and
1647 "catch" blocks as dead code to ignore or eliminate. Compiler
1648 support is not strictly necessary, except in the case of "function
1649 try blocks"; otherwise the following macros almost suffice:
1652 #define try if (true)
1653 #define catch(X) else if (false)
1655 However, there may be a need to use function try blocks in the
1656 library implementation, and use of macros in this way can make
1657 correct diagnostics impossible. Furthermore, use of this scheme
1658 would require the library to call a function to re-throw exceptions
1659 from a try block. Implementing the above semantics in the compiler
1662 Given the support above (however implemented) it only remains to
1663 replace code that "throws" with a call to a well-documented "handler"
1664 function in a separate compilation unit which may be replaced by
1665 the user. The main source of exceptions that would be difficult
1666 for users to avoid is memory allocation failures, but users can
1667 define their own memory allocation primitives that never throw.
1668 Otherwise, the complete list of such handlers, and which library
1669 functions may call them, would be needed for users to be able to
1670 implement the necessary substitutes. (Fortunately, they have the
1676 The template capabilities of C++ offer enormous opportunities for
1677 optimizing common library operations, well beyond what would be
1678 considered "eliminating overhead". In particular, many operations
1679 done in Glibc with macros that depend on proprietary language
1680 extensions can be implemented in pristine Standard C++. For example,
1681 the chapter 25 algorithms, and even C library functions such as strchr,
1682 can be specialized for the case of static arrays of known (small) size.
1684 Detailed optimization opportunities are identified below where
1685 the component where they would appear is discussed. Of course new
1686 opportunities will be identified during implementation.
1688 Unimplemented Required Library Features
1689 ---------------------------------------
1691 The standard specifies hundreds of components, grouped broadly by
1692 chapter. These are listed in excruciating detail in the CHECKLIST
1706 Annex D backward compatibility
1708 Anyone participating in implementation of the library should obtain
1709 a copy of the standard, ISO 14882. People in the U.S. can obtain an
1710 electronic copy for US$18 from ANSI's web site. Those from other
1711 countries should visit http://www.iso.ch/ to find out the location
1712 of their country's representation in ISO, in order to know who can
1715 The emphasis in the following sections is on unimplemented features
1716 and optimization opportunities.
1721 Chapter 17 concerns overall library requirements.
1723 The standard doesn't mention threads. A multi-thread (MT) extension
1724 primarily affects operators new and delete (18), allocator (20),
1725 string (21), locale (22), and iostreams (27). The common underlying
1726 support needed for this is discussed under chapter 20.
1728 The standard requirements on names from the C headers create a
1729 lot of work, mostly done. Names in the C headers must be visible
1730 in the std:: and sometimes the global namespace; the names in the
1731 two scopes must refer to the same object. More stringent is that
1732 Koenig lookup implies that any types specified as defined in std::
1733 really are defined in std::. Names optionally implemented as
1734 macros in C cannot be macros in C++. (An overview may be read at
1735 <http://www.cantrip.org/cheaders.html>). The scripts "inclosure"
1736 and "mkcshadow", and the directories shadow/ and cshadow/, are the
1737 beginning of an effort to conform in this area.
1739 A correct conforming definition of C header names based on underlying
1740 C library headers, and practical linking of conforming namespaced
1741 customer code with third-party C libraries depends ultimately on
1742 an ABI change, allowing namespaced C type names to be mangled into
1743 type names as if they were global, somewhat as C function names in a
1744 namespace, or C++ global variable names, are left unmangled. Perhaps
1745 another "extern" mode, such as 'extern "C-global"' would be an
1746 appropriate place for such type definitions. Such a type would
1747 affect mangling as follows:
1751 extern "C-global" { // or maybe just 'extern "C"'
1755 void f(A::X*); // mangles to f__FPQ21A1X
1756 void f(A::Y*); // mangles to f__FP1Y
1758 (It may be that this is really the appropriate semantics for regular
1759 'extern "C"', and 'extern "C-global"', as an extension, would not be
1760 necessary.) This would allow functions declared in non-standard C headers
1761 (and thus fixable by neither us nor users) to link properly with functions
1762 declared using C types defined in properly-namespaced headers. The
1763 problem this solves is that C headers (which C++ programmers do persist
1764 in using) frequently forward-declare C struct tags without including
1765 the header where the type is defined, as in
1770 Without some compiler accommodation, munge cannot be called by correct
1771 C++ code using a pointer to a correctly-scoped tm* value.
1773 The current C headers use the preprocessor extension "#include_next",
1774 which the compiler complains about when run "-pedantic".
1775 (Incidentally, it appears that "-fpedantic" is currently ignored,
1776 probably a bug.) The solution in the C compiler is to use
1777 "-isystem" rather than "-I", but unfortunately in g++ this seems
1778 also to wrap the whole header in an 'extern "C"' block, so it's
1779 unusable for C++ headers. The correct solution appears to be to
1780 allow the various special include-directory options, if not given
1781 an argument, to affect subsequent include-directory options additively,
1784 -pedantic -iprefix $(prefix) \
1785 -idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \
1786 -iwithprefix -I g++-v3/ext
1788 the compiler would search $(prefix)/g++-v3 and not report
1789 pedantic warnings for files found there, but treat files in
1790 $(prefix)/g++-v3/ext pedantically. (The undocumented semantics
1791 of "-isystem" in g++ stink. Can they be rescinded? If not it
1792 must be replaced with something more rationally behaved.)
1794 All the C headers need the treatment above; in the standard these
1795 headers are mentioned in various chapters. Below, I have only
1796 mentioned those that present interesting implementation issues.
1798 The components identified as "mostly complete", below, have not been
1799 audited for conformance. In many cases where the library passes
1800 conformance tests we have non-conforming extensions that must be
1801 wrapped in #if guards for "pedantic" use, and in some cases renamed
1802 in a conforming way for continued use in the implementation regardless
1803 of conformance flags.
1805 The STL portion of the library still depends on a header
1806 stl/bits/stl_config.h full of #ifdef clauses. This apparatus
1807 should be replaced with autoconf/automake machinery.
1809 The SGI STL defines a type_traits<> template, specialized for
1810 many types in their code including the built-in numeric and
1811 pointer types and some library types, to direct optimizations of
1812 standard functions. The SGI compiler has been extended to generate
1813 specializations of this template automatically for user types,
1814 so that use of STL templates on user types can take advantage of
1815 these optimizations. Specializations for other, non-STL, types
1816 would make more optimizations possible, but extending the gcc
1817 compiler in the same way would be much better. Probably the next
1818 round of standardization will ratify this, but probably with
1819 changes, so it probably should be renamed to place it in the
1820 implementation namespace.
1822 The SGI STL also defines a large number of extensions visible in
1823 standard headers. (Other extensions that appear in separate headers
1824 have been sequestered in subdirectories ext/ and backward/.) All
1825 these extensions should be moved to other headers where possible,
1826 and in any case wrapped in a namespace (not std!), and (where kept
1827 in a standard header) girded about with macro guards. Some cannot be
1828 moved out of standard headers because they are used to implement
1829 standard features. The canonical method for accommodating these
1830 is to use a protected name, aliased in macro guards to a user-space
1831 name. Unfortunately C++ offers no satisfactory template typedef
1832 mechanism, so very ad-hoc and unsatisfactory aliasing must be used
1835 Implementation of a template typedef mechanism should have the highest
1836 priority among possible extensions, on the same level as implementation
1837 of the template "export" feature.
1839 Chapter 18 Language support
1840 ----------------------------
1842 Headers: <limits> <new> <typeinfo> <exception>
1843 C headers: <cstddef> <climits> <cfloat> <cstdarg> <csetjmp>
1844 <ctime> <csignal> <cstdlib> (also 21, 25, 26)
1846 This defines the built-in exceptions, rtti, numeric_limits<>,
1847 operator new and delete. Much of this is provided by the
1848 compiler in its static runtime library.
1850 Work to do includes defining numeric_limits<> specializations in
1851 separate files for all target architectures. Values for integer types
1852 except for bool and wchar_t are readily obtained from the C header
1853 <limits.h>, but values for the remaining numeric types (bool, wchar_t,
1854 float, double, long double) must be entered manually. This is
1855 largely dog work except for those members whose values are not
1856 easily deduced from available documentation. Also, this involves
1857 some work in target configuration to identify the correct choice of
1858 file to build against and to install.
1860 The definitions of the various operators new and delete must be
1861 made thread-safe, which depends on a portable exclusion mechanism,
1862 discussed under chapter 20. Of course there is always plenty of
1863 room for improvements to the speed of operators new and delete.
1865 <cstdarg>, in Glibc, defines some macros that gcc does not allow to
1866 be wrapped into an inline function. Probably this header will demand
1867 attention whenever a new target is chosen. The functions atexit(),
1868 exit(), and abort() in cstdlib have different semantics in C++, so
1869 must be re-implemented for C++.
1871 Chapter 19 Diagnostics
1872 -----------------------
1874 Headers: <stdexcept>
1875 C headers: <cassert> <cerrno>
1877 This defines the standard exception objects, which are "mostly complete".
1878 Cygnus has a version, and now SGI provides a slightly different one.
1879 It makes little difference which we use.
1881 The C global name "errno", which C allows to be a variable or a macro,
1882 is required in C++ to be a macro. For MT it must typically result in
1885 Chapter 20 Utilities
1886 ---------------------
1887 Headers: <utility> <functional> <memory>
1888 C header: <ctime> (also in 18)
1890 SGI STL provides "mostly complete" versions of all the components
1891 defined in this chapter. However, the auto_ptr<> implementation
1892 is known to be wrong. Furthermore, the standard definition of it
1893 is known to be unimplementable as written. A minor change to the
1894 standard would fix it, and auto_ptr<> should be adjusted to match.
1896 Multi-threading affects the allocator implementation, and there must
1897 be configuration/installation choices for different users' MT
1898 requirements. Anyway, users will want to tune allocator options
1899 to support different target conditions, MT or no.
1901 The primitives used for MT implementation should be exposed, as an
1902 extension, for users' own work. We need cross-CPU "mutex" support,
1903 multi-processor shared-memory atomic integer operations, and single-
1904 processor uninterruptible integer operations, and all three configurable
1905 to be stubbed out for non-MT use, or to use an appropriately-loaded
1906 dynamic library for the actual runtime environment, or statically
1907 compiled in for cases where the target architecture is known.
1911 Headers: <string>
1912 C headers: <cctype> <cwctype> <cstring> <cwchar> (also in 27)
1913 <cstdlib> (also in 18, 25, 26)
1915 We have "mostly-complete" char_traits<> implementations. Many of the
1916 char_traits<char> operations might be optimized further using existing
1917 proprietary language extensions.
1919 We have a "mostly-complete" basic_string<> implementation. The work
1920 to manually instantiate char and wchar_t specializations in object
1921 files to improve link-time behavior is extremely unsatisfactory,
1922 literally tripling library-build time with no commensurate improvement
1923 in static program link sizes. It must be redone. (Similar work is
1924 needed for some components in chapters 22 and 27.)
1926 Other work needed for strings is MT-safety, as discussed under the
1929 The standard C type mbstate_t from <cwchar> and used in char_traits<>
1930 must be different in C++ than in C, because in C++ the default constructor
1931 value mbstate_t() must be the "base" or "ground" sequence state.
1932 (According to the likely resolution of a recently raised Core issue,
1933 this may become unnecessary. However, there are other reasons to
1934 use a state type not as limited as whatever the C library provides.)
1935 If we might want to provide conversions from (e.g.) internally-
1936 represented EUC-wide to externally-represented Unicode, or vice-
1937 versa, the mbstate_t we choose will need to be more accommodating
1938 than what might be provided by an underlying C library.
1940 There remain some basic_string template-member functions which do
1941 not overload properly with their non-template brethren. The infamous
1942 hack akin to what was done in vector<> is needed, to conform to
1943 23.1.1 para 10. The CHECKLIST items for basic_string marked 'X',
1944 or incomplete, are so marked for this reason.
1946 Replacing the string iterators, which currently are simple character
1947 pointers, with class objects would greatly increase the safety of the
1948 client interface, and also permit a "debug" mode in which range,
1949 ownership, and validity are rigorously checked. The current use of
1950 raw pointers as string iterators is evil. vector<> iterators need the
1951 same treatment. Note that the current implementation freely mixes
1952 pointers and iterators, and that must be fixed before safer iterators
1955 Some of the functions in <cstring> are different from the C version.
1956 generally overloaded on const and non-const argument pointers. For
1957 example, in <cstring> strchr is overloaded. The functions isupper
1958 etc. in <cctype> typically implemented as macros in C are functions
1959 in C++, because they are overloaded with others of the same name
1960 defined in <locale>.
1962 Many of the functions required in <cwctype> and <cwchar> cannot be
1963 implemented using underlying C facilities on intended targets because
1964 such facilities only partly exist.
1968 Headers: <locale>
1969 C headers: <clocale>
1971 We have a "mostly complete" class locale, with the exception of
1972 code for constructing, and handling the names of, named locales.
1973 The ways that locales are named (particularly when categories
1974 (e.g. LC_TIME, LC_COLLATE) are different) varies among all target
1975 environments. This code must be written in various versions and
1976 chosen by configuration parameters.
1978 Members of many of the facets defined in <locale> are stubs. Generally,
1979 there are two sets of facets: the base class facets (which are supposed
1980 to implement the "C" locale) and the "byname" facets, which are supposed
1981 to read files to determine their behavior. The base ctype<>, collate<>,
1982 and numpunct<> facets are "mostly complete", except that the table of
1983 bitmask values used for "is" operations, and corresponding mask values,
1984 are still defined in libio and just included/linked. (We will need to
1985 implement these tables independently, soon, but should take advantage
1986 of libio where possible.) The num_put<>::put members for integer types
1987 are "mostly complete".
1989 A complete list of what has and has not been implemented may be
1990 found in CHECKLIST. However, note that the current definition of
1991 codecvt<wchar_t,char,mbstate_t> is wrong. It should simply write
1992 out the raw bytes representing the wide characters, rather than
1993 trying to convert each to a corresponding single "char" value.
1995 Some of the facets are more important than others. Specifically,
1996 the members of ctype<>, numpunct<>, num_put<>, and num_get<> facets
1997 are used by other library facilities defined in <string>, <istream>,
1998 and <ostream>, and the codecvt<> facet is used by basic_filebuf<>
1999 in <fstream>, so a conforming iostream implementation depends on
2002 The "long long" type eventually must be supported, but code mentioning
2003 it should be wrapped in #if guards to allow pedantic-mode compiling.
2005 Performance of num_put<> and num_get<> depend critically on
2006 caching computed values in ios_base objects, and on extensions
2007 to the interface with streambufs.
2009 Specifically: retrieving a copy of the locale object, extracting
2010 the needed facets, and gathering data from them, for each call to
2011 (e.g.) operator<< would be prohibitively slow. To cache format
2012 data for use by num_put<> and num_get<> we have a _Format_cache<>
2013 object stored in the ios_base::pword() array. This is constructed
2014 and initialized lazily, and is organized purely for utility. It
2015 is discarded when a new locale with different facets is imbued.
2017 Using only the public interfaces of the iterator arguments to the
2018 facet functions would limit performance by forbidding "vector-style"
2019 character operations. The streambuf iterator optimizations are
2020 described under chapter 24, but facets can also bypass the streambuf
2021 iterators via explicit specializations and operate directly on the
2022 streambufs, and use extended interfaces to get direct access to the
2023 streambuf internal buffer arrays. These extensions are mentioned
2024 under chapter 27. These optimizations are particularly important
2027 Unused virtual members of locale facets can be omitted, as mentioned
2028 above, by a smart linker.
2030 Chapter 23 Containers
2031 ----------------------
2032 Headers: <deque> <list> <queue> <stack> <vector> <map> <set> <bitset>
2034 All the components in chapter 23 are implemented in the SGI STL.
2035 They are "mostly complete"; they include a large number of
2036 nonconforming extensions which must be wrapped. Some of these
2037 are used internally and must be renamed or duplicated.
2039 The SGI components are optimized for large-memory environments. For
2040 embedded targets, different criteria might be more appropriate. Users
2041 will want to be able to tune this behavior. We should provide
2042 ways for users to compile the library with different memory usage
2045 A lot more work is needed on factoring out common code from different
2046 specializations to reduce code size here and in chapter 25. The
2047 easiest fix for this would be a compiler/ABI improvement that allows
2048 the compiler to recognize when a specialization depends only on the
2049 size (or other gross quality) of a template argument, and allow the
2050 linker to share the code with similar specializations. In its
2051 absence, many of the algorithms and containers can be partial-
2052 specialized, at least for the case of pointers, but this only solves
2053 a small part of the problem. Use of a type_traits-style template
2054 allows a few more optimization opportunities, more if the compiler
2055 can generate the specializations automatically.
2057 As an optimization, containers can specialize on the default allocator
2058 and bypass it, or take advantage of details of its implementation
2059 after it has been improved upon.
2061 Replacing the vector iterators, which currently are simple element
2062 pointers, with class objects would greatly increase the safety of the
2063 client interface, and also permit a "debug" mode in which range,
2064 ownership, and validity are rigorously checked. The current use of
2065 pointers for iterators is evil.
2067 As mentioned for chapter 24, the deque iterator is a good example of
2068 an opportunity to implement a "staged" iterator that would benefit
2069 from specializations of some algorithms.
2071 Chapter 24 Iterators
2072 ---------------------
2073 Headers: <iterator>
2075 Standard iterators are "mostly complete", with the exception of
2076 the stream iterators, which are not yet templatized on the
2077 stream type. Also, the base class template iterator<> appears
2078 to be wrong, so everything derived from it must also be wrong,
2081 The streambuf iterators (currently located in stl/bits/std_iterator.h,
2082 but should be under bits/) can be rewritten to take advantage of
2083 friendship with the streambuf implementation.
2085 Matt Austern has identified opportunities where certain iterator
2086 types, particularly including streambuf iterators and deque
2087 iterators, have a "two-stage" quality, such that an intermediate
2088 limit can be checked much more quickly than the true limit on
2089 range operations. If identified with a member of iterator_traits,
2090 algorithms may be specialized for this case. Of course the
2091 iterators that have this quality can be identified by specializing
2094 Many of the algorithms must be specialized for the streambuf
2095 iterators, to take advantage of block-mode operations, in order
2096 to allow iostream/locale operations' performance not to suffer.
2097 It may be that they could be treated as staged iterators and
2098 take advantage of those optimizations.
2100 Chapter 25 Algorithms
2101 ----------------------
2102 Headers: <algorithm>
2103 C headers: <cstdlib> (also in 18, 21, 26))
2105 The algorithms are "mostly complete". As mentioned above, they
2106 are optimized for speed at the expense of code and data size.
2108 Specializations of many of the algorithms for non-STL types would
2109 give performance improvements, but we must use great care not to
2110 interfere with fragile template overloading semantics for the
2111 standard interfaces. Conventionally the standard function template
2112 interface is an inline which delegates to a non-standard function
2113 which is then overloaded (this is already done in many places in
2114 the library). Particularly appealing opportunities for the sake of
2115 iostream performance are for copy and find applied to streambuf
2116 iterators or (as noted elsewhere) for staged iterators, of which
2117 the streambuf iterators are a good example.
2119 The bsearch and qsort functions cannot be overloaded properly as
2120 required by the standard because gcc does not yet allow overloading
2121 on the extern-"C"-ness of a function pointer.
2124 --------------------
2125 Headers: <complex> <valarray> <numeric>
2126 C headers: <cmath>, <cstdlib> (also 18, 21, 25)
2128 Numeric components: Gabriel dos Reis's valarray, Drepper's complex,
2129 and the few algorithms from the STL are "mostly done". Of course
2130 optimization opportunities abound for the numerically literate. It
2131 is not clear whether the valarray implementation really conforms
2132 fully, in the assumptions it makes about aliasing (and lack thereof)
2135 The C div() and ldiv() functions are interesting, because they are the
2136 only case where a C library function returns a class object by value.
2137 Since the C++ type div_t must be different from the underlying C type
2138 (which is in the wrong namespace) the underlying functions div() and
2139 ldiv() cannot be re-used efficiently. Fortunately they are trivial to
2142 Chapter 27 Iostreams
2143 ---------------------
2144 Headers: <iosfwd> <streambuf> <ios> <ostream> <istream> <iostream>
2145 <iomanip> <sstream> <fstream>
2146 C headers: <cstdio> <cwchar> (also in 21)
2148 Iostream is currently in a very incomplete state. <iosfwd>, <iomanip>,
2149 ios_base, and basic_ios<> are "mostly complete". basic_streambuf<> and
2150 basic_ostream<> are well along, but basic_istream<> has had little work
2151 done. The standard stream objects, <sstream> and <fstream> have been
2152 started; basic_filebuf<> "write" functions have been implemented just
2153 enough to do "hello, world".
2155 Most of the istream and ostream operators << and >> (with the exception
2156 of the op<<(integer) ones) have not been changed to use locale primitives,
2157 sentry objects, or char_traits members.
2159 All these templates should be manually instantiated for char and
2160 wchar_t in a way that links only used members into user programs.
2162 Streambuf is fertile ground for optimization extensions. An extended
2163 interface giving iterator access to its internal buffer would be very
2164 useful for other library components.
2166 Iostream operations (primarily operators << and >>) can take advantage
2167 of the case where user code has not specified a locale, and bypass locale
2168 operations entirely. The current implementation of op<</num_put<>::put,
2169 for the integer types, demonstrates how they can cache encoding details
2170 from the locale on each operation. There is lots more room for
2171 optimization in this area.
2173 The definition of the relationship between the standard streams
2174 cout et al. and stdout et al. requires something like a "stdiobuf".
2175 The SGI solution of using double-indirection to actually use a
2176 stdio FILE object for buffering is unsatisfactory, because it
2177 interferes with peephole loop optimizations.
2179 The <sstream> header work has begun. stringbuf can benefit from
2180 friendship with basic_string<> and basic_string<>::_Rep to use
2181 those objects directly as buffers, and avoid allocating and making
2184 The basic_filebuf<> template is a complex beast. It is specified to
2185 use the locale facet codecvt<> to translate characters between native
2186 files and the locale character encoding. In general this involves
2187 two buffers, one of "char" representing the file and another of
2188 "char_type", for the stream, with codecvt<> translating. The process
2189 is complicated by the variable-length nature of the translation, and
2190 the need to seek to corresponding places in the two representations.
2191 For the case of basic_filebuf<char>, when no translation is needed,
2192 a single buffer suffices. A specialized filebuf can be used to reduce
2193 code space overhead when no locale has been imbued. Matt Austern's
2194 work at SGI will be useful, perhaps directly as a source of code, or
2195 at least as an example to draw on.
2197 Filebuf, almost uniquely (cf. operator new), depends heavily on
2198 underlying environmental facilities. In current releases iostream
2199 depends fairly heavily on libio constant definitions, but it should
2200 be made independent. It also depends on operating system primitives
2201 for file operations. There is immense room for optimizations using
2202 (e.g.) mmap for reading. The shadow/ directory wraps, besides the
2203 standard C headers, the libio.h and unistd.h headers, for use mainly
2204 by filebuf. These wrappings have not been completed, though there
2205 is scaffolding in place.
2207 The encapsulation of certain C header <cstdio> names presents an
2208 interesting problem. It is possible to define an inline std::fprintf()
2209 implemented in terms of the 'extern "C"' vfprintf(), but there is no
2210 standard vfscanf() to use to implement std::fscanf(). It appears that
2211 vfscanf but be re-implemented in C++ for targets where no vfscanf
2212 extension has been defined. This is interesting in that it seems
2213 to be the only significant case in the C library where this kind of
2214 rewriting is necessary. (Of course Glibc provides the vfscanf()
2215 extension.) (The functions related to exit() must be rewritten
2221 Headers: <strstream>
2223 Annex D defines many non-library features, and many minor
2224 modifications to various headers, and a complete header.
2225 It is "mostly done", except that the libstdc++-2 <strstream>
2226 header has not been adopted into the library, or checked to
2227 verify that it matches the draft in those details that were
2228 clarified by the committee. Certainly it must at least be
2229 moved into the std namespace.
2231 We still need to wrap all the deprecated features in #if guards
2232 so that pedantic compile modes can detect their use.
2234 Nonstandard Extensions
2235 ----------------------
2236 Headers: <iostream.h> <strstream.h> <hash> <rbtree>
2237 <pthread_alloc> <stdiobuf> (etc.)
2239 User code has come to depend on a variety of nonstandard components
2240 that we must not omit. Much of this code can be adopted from
2241 libstdc++-v2 or from the SGI STL. This particularly includes
2242 <iostream.h>, <strstream.h>, and various SGI extensions such
2243 as <hash_map.h>. Many of these are already placed in the
2244 subdirectories ext/ and backward/. (Note that it is better to
2245 include them via "<backward/hash_map.h>" or "<ext/hash_map>" than
2246 to search the subdirectory itself via a "-I" directive.
projects / l4.git / blob