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