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