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