mirror of git://gcc.gnu.org/git/gcc.git
html: Regenerate, remove un-needed.
2009-04-15 Benjamin Kosnik <bkoz@redhat.com> * doc/html: Regenerate, remove un-needed. From-SVN: r146145
This commit is contained in:
Benjamin Kosnik
parent
26113de4fc
commit
9434ad5384
|
|
@ -1,91 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Directory Layout and Source Conventions</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing" /><link rel="prev" href="appendix_contributing.html" title="Appendix A. Contributing" /><link rel="next" href="bk01apas03.html" title="Coding Style" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Directory Layout and Source Conventions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_contributing.html">Prev</a> </td><th width="60%" align="center">Appendix A. Contributing</th><td width="20%" align="right"> <a accesskey="n" href="bk01apas03.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contrib.organization"></a>Directory Layout and Source Conventions</h2></div></div></div><p>
|
|
||||||
The unpacked source directory of libstdc++ contains the files
|
|
||||||
needed to create the GNU C++ Library.
|
|
||||||
</p><div class="literallayout"><p><br />
|
|
||||||
It has subdirectories:<br />
|
|
||||||
<br />
|
|
||||||
doc<br />
|
|
||||||
Files in HTML and text format that document usage, quirks of the<br />
|
|
||||||
implementation, and contributor checklists.<br />
|
|
||||||
<br />
|
|
||||||
include<br />
|
|
||||||
All header files for the C++ library are within this directory,<br />
|
|
||||||
modulo specific runtime-related files that are in the libsupc++<br />
|
|
||||||
directory.<br />
|
|
||||||
<br />
|
|
||||||
include/std<br />
|
|
||||||
Files meant to be found by #include <name> directives in<br />
|
|
||||||
standard-conforming user programs. <br />
|
|
||||||
<br />
|
|
||||||
include/c<br />
|
|
||||||
Headers intended to directly include standard C headers. <br />
|
|
||||||
[NB: this can be enabled via --enable-cheaders=c]<br />
|
|
||||||
<br />
|
|
||||||
include/c_global <br />
|
|
||||||
Headers intended to include standard C headers in<br />
|
|
||||||
the global namespace, and put select names into the std::<br />
|
|
||||||
namespace. [NB: this is the default, and is the same as<br />
|
|
||||||
--enable-cheaders=c_global]<br />
|
|
||||||
<br />
|
|
||||||
include/c_std <br />
|
|
||||||
Headers intended to include standard C headers<br />
|
|
||||||
already in namespace std, and put select names into the std::<br />
|
|
||||||
namespace. [NB: this is the same as --enable-cheaders=c_std]<br />
|
|
||||||
<br />
|
|
||||||
include/bits<br />
|
|
||||||
Files included by standard headers and by other files in<br />
|
|
||||||
the bits directory. <br />
|
|
||||||
<br />
|
|
||||||
include/backward<br />
|
|
||||||
Headers provided for backward compatibility, such as <iostream.h>.<br />
|
|
||||||
They are not used in this library.<br />
|
|
||||||
<br />
|
|
||||||
include/ext<br />
|
|
||||||
Headers that define extensions to the standard library. No<br />
|
|
||||||
standard header refers to any of them.<br />
|
|
||||||
<br />
|
|
||||||
scripts<br />
|
|
||||||
Scripts that are used during the configure, build, make, or test<br />
|
|
||||||
process.<br />
|
|
||||||
<br />
|
|
||||||
src<br />
|
|
||||||
Files that are used in constructing the library, but are not<br />
|
|
||||||
installed.<br />
|
|
||||||
<br />
|
|
||||||
testsuites/[backward, demangle, ext, performance, thread, 17_* to 27_*]<br />
|
|
||||||
Test programs are here, and may be used to begin to exercise the <br />
|
|
||||||
library. Support for "make check" and "make check-install" is<br />
|
|
||||||
complete, and runs through all the subdirectories here when this<br />
|
|
||||||
command is issued from the build directory. Please note that<br />
|
|
||||||
"make check" requires DejaGNU 1.4 or later to be installed. Please<br />
|
|
||||||
note that "make check-script" calls the script mkcheck, which<br />
|
|
||||||
requires bash, and which may need the paths to bash adjusted to<br />
|
|
||||||
work properly, as /bin/bash is assumed.<br />
|
|
||||||
<br />
|
|
||||||
Other subdirectories contain variant versions of certain files<br />
|
|
||||||
that are meant to be copied or linked by the configure script.<br />
|
|
||||||
Currently these are:<br />
|
|
||||||
<br />
|
|
||||||
config/abi<br />
|
|
||||||
config/cpu<br />
|
|
||||||
config/io<br />
|
|
||||||
config/locale<br />
|
|
||||||
config/os<br />
|
|
||||||
<br />
|
|
||||||
In addition, a subdirectory holds the convenience library libsupc++.<br />
|
|
||||||
<br />
|
|
||||||
libsupc++<br />
|
|
||||||
Contains the runtime library for C++, including exception<br />
|
|
||||||
handling and memory allocation and deallocation, RTTI, terminate<br />
|
|
||||||
handlers, etc.<br />
|
|
||||||
<br />
|
|
||||||
Note that glibc also has a bits/ subdirectory. We will either<br />
|
|
||||||
need to be careful not to collide with names in its bits/<br />
|
|
||||||
directory; or rename bits to (e.g.) cppbits/.<br />
|
|
||||||
<br />
|
|
||||||
In files throughout the system, lines marked with an "XXX" indicate<br />
|
|
||||||
a bug or incompletely-implemented feature. Lines marked "XXX MT"<br />
|
|
||||||
indicate a place that may require attention for multi-thread safety.<br />
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendix_contributing.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01apas03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix A. Contributing </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Coding Style</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,585 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Coding Style</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing" /><link rel="prev" href="bk01apas02.html" title="Directory Layout and Source Conventions" /><link rel="next" href="bk01apas04.html" title="Documentation Style" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Coding Style</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01apas02.html">Prev</a> </td><th width="60%" align="center">Appendix A. Contributing</th><td width="20%" align="right"> <a accesskey="n" href="bk01apas04.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contrib.coding_style"></a>Coding Style</h2></div></div></div><p>
|
|
||||||
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="coding_style.bad_identifiers"></a>Bad Identifiers</h3></div></div></div><p>
|
|
||||||
Identifiers that conflict and should be avoided.
|
|
||||||
</p><div class="literallayout"><p><br />
|
|
||||||
This is the list of names “<span class="quote">reserved to the<br />
|
|
||||||
implementation</span>” that have been claimed by certain<br />
|
|
||||||
compilers and system headers of interest, and should not be used<br />
|
|
||||||
in the library. It will grow, of course. We generally are<br />
|
|
||||||
interested in names that are not all-caps, except for those like<br />
|
|
||||||
"_T"<br />
|
|
||||||
<br />
|
|
||||||
For Solaris:<br />
|
|
||||||
_B<br />
|
|
||||||
_C<br />
|
|
||||||
_L<br />
|
|
||||||
_N<br />
|
|
||||||
_P<br />
|
|
||||||
_S<br />
|
|
||||||
_U<br />
|
|
||||||
_X<br />
|
|
||||||
_E1<br />
|
|
||||||
..<br />
|
|
||||||
_E24<br />
|
|
||||||
<br />
|
|
||||||
Irix adds:<br />
|
|
||||||
_A<br />
|
|
||||||
_G<br />
|
|
||||||
<br />
|
|
||||||
MS adds:<br />
|
|
||||||
_T<br />
|
|
||||||
<br />
|
|
||||||
BSD adds:<br />
|
|
||||||
__used<br />
|
|
||||||
__unused<br />
|
|
||||||
__inline<br />
|
|
||||||
_Complex<br />
|
|
||||||
__istype<br />
|
|
||||||
__maskrune<br />
|
|
||||||
__tolower<br />
|
|
||||||
__toupper<br />
|
|
||||||
__wchar_t<br />
|
|
||||||
__wint_t<br />
|
|
||||||
_res<br />
|
|
||||||
_res_ext<br />
|
|
||||||
__tg_*<br />
|
|
||||||
<br />
|
|
||||||
SPU adds:<br />
|
|
||||||
__ea<br />
|
|
||||||
<br />
|
|
||||||
For GCC:<br />
|
|
||||||
<br />
|
|
||||||
[Note that this list is out of date. It applies to the old<br />
|
|
||||||
name-mangling; in G++ 3.0 and higher a different name-mangling is<br />
|
|
||||||
used. In addition, many of the bugs relating to G++ interpreting<br />
|
|
||||||
these names as operators have been fixed.]<br />
|
|
||||||
<br />
|
|
||||||
The full set of __* identifiers (combined from gcc/cp/lex.c and<br />
|
|
||||||
gcc/cplus-dem.c) that are either old or new, but are definitely <br />
|
|
||||||
recognized by the demangler, is:<br />
|
|
||||||
<br />
|
|
||||||
__aa<br />
|
|
||||||
__aad<br />
|
|
||||||
__ad<br />
|
|
||||||
__addr<br />
|
|
||||||
__adv<br />
|
|
||||||
__aer<br />
|
|
||||||
__als<br />
|
|
||||||
__alshift<br />
|
|
||||||
__amd<br />
|
|
||||||
__ami<br />
|
|
||||||
__aml<br />
|
|
||||||
__amu<br />
|
|
||||||
__aor<br />
|
|
||||||
__apl<br />
|
|
||||||
__array<br />
|
|
||||||
__ars<br />
|
|
||||||
__arshift<br />
|
|
||||||
__as<br />
|
|
||||||
__bit_and<br />
|
|
||||||
__bit_ior<br />
|
|
||||||
__bit_not<br />
|
|
||||||
__bit_xor<br />
|
|
||||||
__call<br />
|
|
||||||
__cl<br />
|
|
||||||
__cm<br />
|
|
||||||
__cn<br />
|
|
||||||
__co<br />
|
|
||||||
__component<br />
|
|
||||||
__compound<br />
|
|
||||||
__cond<br />
|
|
||||||
__convert<br />
|
|
||||||
__delete<br />
|
|
||||||
__dl<br />
|
|
||||||
__dv<br />
|
|
||||||
__eq<br />
|
|
||||||
__er<br />
|
|
||||||
__ge<br />
|
|
||||||
__gt<br />
|
|
||||||
__indirect<br />
|
|
||||||
__le<br />
|
|
||||||
__ls<br />
|
|
||||||
__lt<br />
|
|
||||||
__max<br />
|
|
||||||
__md<br />
|
|
||||||
__method_call<br />
|
|
||||||
__mi<br />
|
|
||||||
__min<br />
|
|
||||||
__minus<br />
|
|
||||||
__ml<br />
|
|
||||||
__mm<br />
|
|
||||||
__mn<br />
|
|
||||||
__mult<br />
|
|
||||||
__mx<br />
|
|
||||||
__ne<br />
|
|
||||||
__negate<br />
|
|
||||||
__new<br />
|
|
||||||
__nop<br />
|
|
||||||
__nt<br />
|
|
||||||
__nw<br />
|
|
||||||
__oo<br />
|
|
||||||
__op<br />
|
|
||||||
__or<br />
|
|
||||||
__pl<br />
|
|
||||||
__plus<br />
|
|
||||||
__postdecrement<br />
|
|
||||||
__postincrement<br />
|
|
||||||
__pp<br />
|
|
||||||
__pt<br />
|
|
||||||
__rf<br />
|
|
||||||
__rm<br />
|
|
||||||
__rs<br />
|
|
||||||
__sz<br />
|
|
||||||
__trunc_div<br />
|
|
||||||
__trunc_mod<br />
|
|
||||||
__truth_andif<br />
|
|
||||||
__truth_not<br />
|
|
||||||
__truth_orif<br />
|
|
||||||
__vc<br />
|
|
||||||
__vd<br />
|
|
||||||
__vn<br />
|
|
||||||
<br />
|
|
||||||
SGI badnames:<br />
|
|
||||||
__builtin_alloca<br />
|
|
||||||
__builtin_fsqrt<br />
|
|
||||||
__builtin_sqrt<br />
|
|
||||||
__builtin_fabs<br />
|
|
||||||
__builtin_dabs<br />
|
|
||||||
__builtin_cast_f2i<br />
|
|
||||||
__builtin_cast_i2f<br />
|
|
||||||
__builtin_cast_d2ll<br />
|
|
||||||
__builtin_cast_ll2d<br />
|
|
||||||
__builtin_copy_dhi2i<br />
|
|
||||||
__builtin_copy_i2dhi<br />
|
|
||||||
__builtin_copy_dlo2i<br />
|
|
||||||
__builtin_copy_i2dlo<br />
|
|
||||||
__add_and_fetch<br />
|
|
||||||
__sub_and_fetch<br />
|
|
||||||
__or_and_fetch<br />
|
|
||||||
__xor_and_fetch<br />
|
|
||||||
__and_and_fetch<br />
|
|
||||||
__nand_and_fetch<br />
|
|
||||||
__mpy_and_fetch<br />
|
|
||||||
__min_and_fetch<br />
|
|
||||||
__max_and_fetch<br />
|
|
||||||
__fetch_and_add<br />
|
|
||||||
__fetch_and_sub<br />
|
|
||||||
__fetch_and_or<br />
|
|
||||||
__fetch_and_xor<br />
|
|
||||||
__fetch_and_and<br />
|
|
||||||
__fetch_and_nand<br />
|
|
||||||
__fetch_and_mpy<br />
|
|
||||||
__fetch_and_min<br />
|
|
||||||
__fetch_and_max<br />
|
|
||||||
__lock_test_and_set<br />
|
|
||||||
__lock_release<br />
|
|
||||||
__lock_acquire<br />
|
|
||||||
__compare_and_swap<br />
|
|
||||||
__synchronize<br />
|
|
||||||
__high_multiply<br />
|
|
||||||
__unix<br />
|
|
||||||
__sgi<br />
|
|
||||||
__linux__<br />
|
|
||||||
__i386__<br />
|
|
||||||
__i486__<br />
|
|
||||||
__cplusplus<br />
|
|
||||||
__embedded_cplusplus<br />
|
|
||||||
// long double conversion members mangled as __opr<br />
|
|
||||||
// http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html<br />
|
|
||||||
_opr<br />
|
|
||||||
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="coding_style.example"></a>By Example</h3></div></div></div><div class="literallayout"><p><br />
|
|
||||||
This library is written to appropriate C++ coding standards. As such,<br />
|
|
||||||
it is intended to precede the recommendations of the GNU Coding<br />
|
|
||||||
Standard, which can be referenced in full here:<br />
|
|
||||||
<br />
|
|
||||||
http://www.gnu.org/prep/standards/standards.html#Formatting<br />
|
|
||||||
<br />
|
|
||||||
The rest of this is also interesting reading, but skip the "Design<br />
|
|
||||||
Advice" part.<br />
|
|
||||||
<br />
|
|
||||||
The GCC coding conventions are here, and are also useful:<br />
|
|
||||||
http://gcc.gnu.org/codingconventions.html<br />
|
|
||||||
<br />
|
|
||||||
In addition, because it doesn't seem to be stated explicitly anywhere<br />
|
|
||||||
else, there is an 80 column source limit.<br />
|
|
||||||
<br />
|
|
||||||
ChangeLog entries for member functions should use the<br />
|
|
||||||
classname::member function name syntax as follows:<br />
|
|
||||||
<br />
|
|
||||||
1999-04-15 Dennis Ritchie <dr@att.com><br />
|
|
||||||
<br />
|
|
||||||
* src/basic_file.cc (__basic_file::open): Fix thinko in<br />
|
|
||||||
_G_HAVE_IO_FILE_OPEN bits.<br />
|
|
||||||
<br />
|
|
||||||
Notable areas of divergence from what may be previous local practice<br />
|
|
||||||
(particularly for GNU C) include:<br />
|
|
||||||
<br />
|
|
||||||
01. Pointers and references<br />
|
|
||||||
char* p = "flop";<br />
|
|
||||||
char& c = *p;<br />
|
|
||||||
-NOT-<br />
|
|
||||||
char *p = "flop"; // wrong<br />
|
|
||||||
char &c = *p; // wrong<br />
|
|
||||||
<br />
|
|
||||||
Reason: In C++, definitions are mixed with executable code. Here, <br />
|
|
||||||
p is being initialized, not *p. This is near-universal<br />
|
|
||||||
practice among C++ programmers; it is normal for C hackers<br />
|
|
||||||
to switch spontaneously as they gain experience.<br />
|
|
||||||
<br />
|
|
||||||
02. Operator names and parentheses<br />
|
|
||||||
operator==(type)<br />
|
|
||||||
-NOT-<br />
|
|
||||||
operator == (type) // wrong<br />
|
|
||||||
<br />
|
|
||||||
Reason: The == is part of the function name. Separating<br />
|
|
||||||
it makes the declaration look like an expression. <br />
|
|
||||||
<br />
|
|
||||||
03. Function names and parentheses<br />
|
|
||||||
void mangle()<br />
|
|
||||||
-NOT-<br />
|
|
||||||
void mangle () // wrong<br />
|
|
||||||
<br />
|
|
||||||
Reason: no space before parentheses (except after a control-flow<br />
|
|
||||||
keyword) is near-universal practice for C++. It identifies the<br />
|
|
||||||
parentheses as the function-call operator or declarator, as <br />
|
|
||||||
opposed to an expression or other overloaded use of parentheses.<br />
|
|
||||||
<br />
|
|
||||||
04. Template function indentation<br />
|
|
||||||
template<typename T><br />
|
|
||||||
void <br />
|
|
||||||
template_function(args)<br />
|
|
||||||
{ }<br />
|
|
||||||
-NOT-<br />
|
|
||||||
template<class T><br />
|
|
||||||
void template_function(args) {};<br />
|
|
||||||
<br />
|
|
||||||
Reason: In class definitions, without indentation whitespace is<br />
|
|
||||||
needed both above and below the declaration to distinguish<br />
|
|
||||||
it visually from other members. (Also, re: "typename"<br />
|
|
||||||
rather than "class".) T often could be int, which is <br />
|
|
||||||
not a class. ("class", here, is an anachronism.)<br />
|
|
||||||
<br />
|
|
||||||
05. Template class indentation<br />
|
|
||||||
template<typename _CharT, typename _Traits><br />
|
|
||||||
class basic_ios : public ios_base<br />
|
|
||||||
{<br />
|
|
||||||
public:<br />
|
|
||||||
// Types:<br />
|
|
||||||
};<br />
|
|
||||||
-NOT-<br />
|
|
||||||
template<class _CharT, class _Traits><br />
|
|
||||||
class basic_ios : public ios_base<br />
|
|
||||||
{<br />
|
|
||||||
public:<br />
|
|
||||||
// Types:<br />
|
|
||||||
};<br />
|
|
||||||
-NOT-<br />
|
|
||||||
template<class _CharT, class _Traits><br />
|
|
||||||
class basic_ios : public ios_base<br />
|
|
||||||
{<br />
|
|
||||||
public:<br />
|
|
||||||
// Types:<br />
|
|
||||||
};<br />
|
|
||||||
<br />
|
|
||||||
06. Enumerators<br />
|
|
||||||
enum<br />
|
|
||||||
{<br />
|
|
||||||
space = _ISspace,<br />
|
|
||||||
print = _ISprint,<br />
|
|
||||||
cntrl = _IScntrl<br />
|
|
||||||
};<br />
|
|
||||||
-NOT-<br />
|
|
||||||
enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };<br />
|
|
||||||
<br />
|
|
||||||
07. Member initialization lists<br />
|
|
||||||
All one line, separate from class name.<br />
|
|
||||||
<br />
|
|
||||||
gribble::gribble() <br />
|
|
||||||
: _M_private_data(0), _M_more_stuff(0), _M_helper(0);<br />
|
|
||||||
{ }<br />
|
|
||||||
-NOT-<br />
|
|
||||||
gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0);<br />
|
|
||||||
{ }<br />
|
|
||||||
<br />
|
|
||||||
08. Try/Catch blocks<br />
|
|
||||||
try <br />
|
|
||||||
{<br />
|
|
||||||
//<br />
|
|
||||||
} <br />
|
|
||||||
catch (...)<br />
|
|
||||||
{<br />
|
|
||||||
//<br />
|
|
||||||
} <br />
|
|
||||||
-NOT-<br />
|
|
||||||
try {<br />
|
|
||||||
// <br />
|
|
||||||
} catch(...) { <br />
|
|
||||||
//<br />
|
|
||||||
}<br />
|
|
||||||
<br />
|
|
||||||
09. Member functions declarations and definitions<br />
|
|
||||||
Keywords such as extern, static, export, explicit, inline, etc<br />
|
|
||||||
go on the line above the function name. Thus<br />
|
|
||||||
<br />
|
|
||||||
virtual int <br />
|
|
||||||
foo()<br />
|
|
||||||
-NOT-<br />
|
|
||||||
virtual int foo()<br />
|
|
||||||
<br />
|
|
||||||
Reason: GNU coding conventions dictate return types for functions<br />
|
|
||||||
are on a separate line than the function name and parameter list<br />
|
|
||||||
for definitions. For C++, where we have member functions that can<br />
|
|
||||||
be either inline definitions or declarations, keeping to this<br />
|
|
||||||
standard allows all member function names for a given class to be<br />
|
|
||||||
aligned to the same margin, increasing readability.<br />
|
|
||||||
<br />
|
|
||||||
<br />
|
|
||||||
10. Invocation of member functions with "this->"<br />
|
|
||||||
For non-uglified names, use this->name to call the function.<br />
|
|
||||||
<br />
|
|
||||||
this->sync()<br />
|
|
||||||
-NOT-<br />
|
|
||||||
sync()<br />
|
|
||||||
<br />
|
|
||||||
Reason: Koenig lookup.<br />
|
|
||||||
<br />
|
|
||||||
11. Namespaces<br />
|
|
||||||
namespace std<br />
|
|
||||||
{<br />
|
|
||||||
blah blah blah;<br />
|
|
||||||
} // namespace std<br />
|
|
||||||
<br />
|
|
||||||
-NOT-<br />
|
|
||||||
<br />
|
|
||||||
namespace std {<br />
|
|
||||||
blah blah blah;<br />
|
|
||||||
} // namespace std<br />
|
|
||||||
<br />
|
|
||||||
12. Spacing under protected and private in class declarations:<br />
|
|
||||||
space above, none below<br />
|
|
||||||
i.e.<br />
|
|
||||||
<br />
|
|
||||||
public:<br />
|
|
||||||
int foo;<br />
|
|
||||||
<br />
|
|
||||||
-NOT-<br />
|
|
||||||
public:<br />
|
|
||||||
<br />
|
|
||||||
int foo;<br />
|
|
||||||
<br />
|
|
||||||
13. Spacing WRT return statements.<br />
|
|
||||||
no extra spacing before returns, no parenthesis<br />
|
|
||||||
i.e.<br />
|
|
||||||
<br />
|
|
||||||
}<br />
|
|
||||||
return __ret;<br />
|
|
||||||
<br />
|
|
||||||
-NOT-<br />
|
|
||||||
}<br />
|
|
||||||
<br />
|
|
||||||
return __ret;<br />
|
|
||||||
<br />
|
|
||||||
-NOT-<br />
|
|
||||||
<br />
|
|
||||||
}<br />
|
|
||||||
return (__ret);<br />
|
|
||||||
<br />
|
|
||||||
<br />
|
|
||||||
14. Location of global variables.<br />
|
|
||||||
All global variables of class type, whether in the "user visible"<br />
|
|
||||||
space (e.g., cin) or the implementation namespace, must be defined<br />
|
|
||||||
as a character array with the appropriate alignment and then later<br />
|
|
||||||
re-initialized to the correct value.<br />
|
|
||||||
<br />
|
|
||||||
This is due to startup issues on certain platforms, such as AIX.<br />
|
|
||||||
For more explanation and examples, see src/globals.cc. All such<br />
|
|
||||||
variables should be contained in that file, for simplicity.<br />
|
|
||||||
<br />
|
|
||||||
15. Exception abstractions<br />
|
|
||||||
Use the exception abstractions found in functexcept.h, which allow<br />
|
|
||||||
C++ programmers to use this library with -fno-exceptions. (Even if<br />
|
|
||||||
that is rarely advisable, it's a necessary evil for backwards<br />
|
|
||||||
compatibility.)<br />
|
|
||||||
<br />
|
|
||||||
16. Exception error messages<br />
|
|
||||||
All start with the name of the function where the exception is<br />
|
|
||||||
thrown, and then (optional) descriptive text is added. Example:<br />
|
|
||||||
<br />
|
|
||||||
__throw_logic_error(__N("basic_string::_S_construct NULL not valid"));<br />
|
|
||||||
<br />
|
|
||||||
Reason: The verbose terminate handler prints out exception::what(),<br />
|
|
||||||
as well as the typeinfo for the thrown exception. As this is the<br />
|
|
||||||
default terminate handler, by putting location info into the<br />
|
|
||||||
exception string, a very useful error message is printed out for<br />
|
|
||||||
uncaught exceptions. So useful, in fact, that non-programmers can<br />
|
|
||||||
give useful error messages, and programmers can intelligently<br />
|
|
||||||
speculate what went wrong without even using a debugger.<br />
|
|
||||||
<br />
|
|
||||||
17. The doxygen style guide to comments is a separate document,<br />
|
|
||||||
see index.<br />
|
|
||||||
<br />
|
|
||||||
The library currently has a mixture of GNU-C and modern C++ coding<br />
|
|
||||||
styles. The GNU C usages will be combed out gradually.<br />
|
|
||||||
<br />
|
|
||||||
Name patterns:<br />
|
|
||||||
<br />
|
|
||||||
For nonstandard names appearing in Standard headers, we are constrained <br />
|
|
||||||
to use names that begin with underscores. This is called "uglification".<br />
|
|
||||||
The convention is:<br />
|
|
||||||
<br />
|
|
||||||
Local and argument names: __[a-z].*<br />
|
|
||||||
<br />
|
|
||||||
Examples: __count __ix __s1 <br />
|
|
||||||
<br />
|
|
||||||
Type names and template formal-argument names: _[A-Z][^_].*<br />
|
|
||||||
<br />
|
|
||||||
Examples: _Helper _CharT _N <br />
|
|
||||||
<br />
|
|
||||||
Member data and function names: _M_.*<br />
|
|
||||||
<br />
|
|
||||||
Examples: _M_num_elements _M_initialize ()<br />
|
|
||||||
<br />
|
|
||||||
Static data members, constants, and enumerations: _S_.*<br />
|
|
||||||
<br />
|
|
||||||
Examples: _S_max_elements _S_default_value<br />
|
|
||||||
<br />
|
|
||||||
Don't use names in the same scope that differ only in the prefix, <br />
|
|
||||||
e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names.<br />
|
|
||||||
(The most tempting of these seem to be and "_T" and "__sz".)<br />
|
|
||||||
<br />
|
|
||||||
Names must never have "__" internally; it would confuse name<br />
|
|
||||||
unmanglers on some targets. Also, never use "__[0-9]", same reason.<br />
|
|
||||||
<br />
|
|
||||||
--------------------------<br />
|
|
||||||
<br />
|
|
||||||
[BY EXAMPLE]<br />
|
|
||||||
<br />
|
|
||||||
#ifndef _HEADER_<br />
|
|
||||||
#define _HEADER_ 1<br />
|
|
||||||
<br />
|
|
||||||
namespace std<br />
|
|
||||||
{<br />
|
|
||||||
class gribble<br />
|
|
||||||
{<br />
|
|
||||||
public:<br />
|
|
||||||
gribble() throw();<br />
|
|
||||||
<br />
|
|
||||||
gribble(const gribble&);<br />
|
|
||||||
<br />
|
|
||||||
explicit <br />
|
|
||||||
gribble(int __howmany);<br />
|
|
||||||
<br />
|
|
||||||
gribble& <br />
|
|
||||||
operator=(const gribble&);<br />
|
|
||||||
<br />
|
|
||||||
virtual <br />
|
|
||||||
~gribble() throw ();<br />
|
|
||||||
<br />
|
|
||||||
// Start with a capital letter, end with a period.<br />
|
|
||||||
inline void <br />
|
|
||||||
public_member(const char* __arg) const;<br />
|
|
||||||
<br />
|
|
||||||
// In-class function definitions should be restricted to one-liners.<br />
|
|
||||||
int <br />
|
|
||||||
one_line() { return 0 }<br />
|
|
||||||
<br />
|
|
||||||
int <br />
|
|
||||||
two_lines(const char* arg) <br />
|
|
||||||
{ return strchr(arg, 'a'); }<br />
|
|
||||||
<br />
|
|
||||||
inline int <br />
|
|
||||||
three_lines(); // inline, but defined below.<br />
|
|
||||||
<br />
|
|
||||||
// Note indentation.<br />
|
|
||||||
template<typename _Formal_argument><br />
|
|
||||||
void <br />
|
|
||||||
public_template() const throw();<br />
|
|
||||||
<br />
|
|
||||||
template<typename _Iterator><br />
|
|
||||||
void <br />
|
|
||||||
other_template();<br />
|
|
||||||
<br />
|
|
||||||
private:<br />
|
|
||||||
class _Helper;<br />
|
|
||||||
<br />
|
|
||||||
int _M_private_data;<br />
|
|
||||||
int _M_more_stuff;<br />
|
|
||||||
_Helper* _M_helper;<br />
|
|
||||||
int _M_private_function();<br />
|
|
||||||
<br />
|
|
||||||
enum _Enum <br />
|
|
||||||
{ <br />
|
|
||||||
_S_one, <br />
|
|
||||||
_S_two <br />
|
|
||||||
};<br />
|
|
||||||
<br />
|
|
||||||
static void <br />
|
|
||||||
_S_initialize_library();<br />
|
|
||||||
};<br />
|
|
||||||
<br />
|
|
||||||
// More-or-less-standard language features described by lack, not presence.<br />
|
|
||||||
# ifndef _G_NO_LONGLONG<br />
|
|
||||||
extern long long _G_global_with_a_good_long_name; // avoid globals!<br />
|
|
||||||
# endif<br />
|
|
||||||
<br />
|
|
||||||
// Avoid in-class inline definitions, define separately;<br />
|
|
||||||
// likewise for member class definitions:<br />
|
|
||||||
inline int<br />
|
|
||||||
gribble::public_member() const<br />
|
|
||||||
{ int __local = 0; return __local; }<br />
|
|
||||||
<br />
|
|
||||||
class gribble::_Helper<br />
|
|
||||||
{<br />
|
|
||||||
int _M_stuff;<br />
|
|
||||||
<br />
|
|
||||||
friend class gribble;<br />
|
|
||||||
};<br />
|
|
||||||
}<br />
|
|
||||||
<br />
|
|
||||||
// Names beginning with "__": only for arguments and<br />
|
|
||||||
// local variables; never use "__" in a type name, or<br />
|
|
||||||
// within any name; never use "__[0-9]".<br />
|
|
||||||
<br />
|
|
||||||
#endif /* _HEADER_ */<br />
|
|
||||||
<br />
|
|
||||||
<br />
|
|
||||||
namespace std <br />
|
|
||||||
{<br />
|
|
||||||
template<typename T> // notice: "typename", not "class", no space<br />
|
|
||||||
long_return_value_type<with_many, args> <br />
|
|
||||||
function_name(char* pointer, // "char *pointer" is wrong.<br />
|
|
||||||
char* argument, <br />
|
|
||||||
const Reference& ref)<br />
|
|
||||||
{<br />
|
|
||||||
// int a_local; /* wrong; see below. */<br />
|
|
||||||
if (test) <br />
|
|
||||||
{ <br />
|
|
||||||
nested code <br />
|
|
||||||
}<br />
|
|
||||||
<br />
|
|
||||||
int a_local = 0; // declare variable at first use.<br />
|
|
||||||
<br />
|
|
||||||
// char a, b, *p; /* wrong */<br />
|
|
||||||
char a = 'a';<br />
|
|
||||||
char b = a + 1;<br />
|
|
||||||
char* c = "abc"; // each variable goes on its own line, always.<br />
|
|
||||||
<br />
|
|
||||||
// except maybe here...<br />
|
|
||||||
for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) {<br />
|
|
||||||
// ...<br />
|
|
||||||
}<br />
|
|
||||||
}<br />
|
|
||||||
<br />
|
|
||||||
gribble::gribble()<br />
|
|
||||||
: _M_private_data(0), _M_more_stuff(0), _M_helper(0);<br />
|
|
||||||
{ }<br />
|
|
||||||
<br />
|
|
||||||
inline int <br />
|
|
||||||
gribble::three_lines()<br />
|
|
||||||
{<br />
|
|
||||||
// doesn't fit in one line.<br />
|
|
||||||
}<br />
|
|
||||||
} // namespace std<br />
|
|
||||||
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01apas02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01apas04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Directory Layout and Source Conventions </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Documentation Style</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,227 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Documentation Style</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing" /><link rel="prev" href="bk01apas03.html" title="Coding Style" /><link rel="next" href="bk01apas05.html" title="Design Notes" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Documentation Style</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01apas03.html">Prev</a> </td><th width="60%" align="center">Appendix A. Contributing</th><td width="20%" align="right"> <a accesskey="n" href="bk01apas05.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contrib.doc_style"></a>Documentation Style</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.doxygen"></a>Doxygen</h3></div></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.prereq"></a>Prerequisites</h4></div></div></div><p>
|
|
||||||
Prerequisite tools are Bash 2.x,
|
|
||||||
<a class="ulink" href="http://www.doxygen.org/" target="_top">Doxygen</a>, and
|
|
||||||
the <a class="ulink" href="http://www.gnu.org/software/coreutils/" target="_top">GNU
|
|
||||||
coreutils</a>. (GNU versions of find, xargs, and possibly
|
|
||||||
sed and grep are used, just because the GNU versions make
|
|
||||||
things very easy.)
|
|
||||||
</p><p>
|
|
||||||
To generate the pretty pictures and hierarchy
|
|
||||||
graphs, the
|
|
||||||
<a class="ulink" href="http://www.research.att.com/sw/tools/graphviz/download.html" target="_top">Graphviz</a>
|
|
||||||
package will need to be installed.
|
|
||||||
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.rules"></a>Generating the Doxygen Files</h4></div></div></div><p>
|
|
||||||
The following Makefile rules run Doxygen to generate HTML
|
|
||||||
docs, XML docs, and the man pages.
|
|
||||||
</p><p>
|
|
||||||
</p><pre class="screen"><strong class="userinput"><code>make doc-html-doxygen</code></strong></pre><p>
|
|
||||||
</p><p>
|
|
||||||
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-doxygen</code></strong></pre><p>
|
|
||||||
</p><p>
|
|
||||||
</p><pre class="screen"><strong class="userinput"><code>make doc-man-doxygen</code></strong></pre><p>
|
|
||||||
</p><p>
|
|
||||||
Careful observers will see that the Makefile rules simply call
|
|
||||||
a script from the source tree, <code class="filename">run_doxygen</code>, which
|
|
||||||
does the actual work of running Doxygen and then (most
|
|
||||||
importantly) massaging the output files. If for some reason
|
|
||||||
you prefer to not go through the Makefile, you can call this
|
|
||||||
script directly. (Start by passing <code class="literal">--help</code>.)
|
|
||||||
</p><p>
|
|
||||||
If you wish to tweak the Doxygen settings, do so by editing
|
|
||||||
<code class="filename">doc/doxygen/user.cfg.in</code>. Notes to fellow
|
|
||||||
library hackers are written in triple-# comments.
|
|
||||||
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="doxygen.markup"></a>Markup</h4></div></div></div><p>
|
|
||||||
In general, libstdc++ files should be formatted according to
|
|
||||||
the rules found in the
|
|
||||||
<a class="link" href="bk01apas03.html" title="Coding Style">Coding Standard</a>. Before
|
|
||||||
any doxygen-specific formatting tweaks are made, please try to
|
|
||||||
make sure that the initial formatting is sound.
|
|
||||||
</p><p>
|
|
||||||
Adding Doxygen markup to a file (informally called
|
|
||||||
“<span class="quote">doxygenating</span>”) is very simple. The Doxygen manual can be
|
|
||||||
found
|
|
||||||
<a class="ulink" href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman" target="_top">here</a>.
|
|
||||||
We try to use a very-recent version of Doxygen.
|
|
||||||
</p><p>
|
|
||||||
For classes, use
|
|
||||||
<code class="classname">deque</code>/<code class="classname">vector</code>/<code class="classname">list</code>
|
|
||||||
and <code class="classname">std::pair</code> as examples. For
|
|
||||||
functions, see their member functions, and the free functions
|
|
||||||
in <code class="filename">stl_algobase.h</code>. Member functions of
|
|
||||||
other container-like types should read similarly to these
|
|
||||||
member functions.
|
|
||||||
</p><p>
|
|
||||||
These points accompany the first list in section 3.1 of the
|
|
||||||
Doxygen manual:
|
|
||||||
</p><div class="orderedlist"><ol type="1"><li><p>Use the Javadoc style...</p></li><li><p>
|
|
||||||
...not the Qt style. The intermediate *'s are preferred.
|
|
||||||
</p></li><li><p>
|
|
||||||
Use the triple-slash style only for one-line comments (the
|
|
||||||
“<span class="quote">brief</span>” mode). Very recent versions of Doxygen permit
|
|
||||||
full-mode comments in triple-slash blocks, but the
|
|
||||||
formatting still comes out wonky.
|
|
||||||
</p></li><li><p>
|
|
||||||
This is disgusting. Don't do this.
|
|
||||||
</p></li></ol></div><p>
|
|
||||||
Use the @-style of commands, not the !-style. Please be
|
|
||||||
careful about whitespace in your markup comments. Most of the
|
|
||||||
time it doesn't matter; doxygen absorbs most whitespace, and
|
|
||||||
both HTML and *roff are agnostic about whitespace. However,
|
|
||||||
in <pre> blocks and @code/@endcode sections, spacing can
|
|
||||||
have “<span class="quote">interesting</span>” effects.
|
|
||||||
</p><p>
|
|
||||||
Use either kind of grouping, as
|
|
||||||
appropriate. <code class="filename">doxygroups.cc</code> exists for this
|
|
||||||
purpose. See <code class="filename">stl_iterator.h</code> for a good example
|
|
||||||
of the “<span class="quote">other</span>” kind of grouping.
|
|
||||||
</p><p>
|
|
||||||
Please use markup tags like @p and @a when referring to things
|
|
||||||
such as the names of function parameters. Use @e for emphasis
|
|
||||||
when necessary. Use @c to refer to other standard names.
|
|
||||||
(Examples of all these abound in the present code.)
|
|
||||||
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="doc_style.docbook"></a>Docbook</h3></div></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.prereq"></a>Prerequisites</h4></div></div></div><p>
|
|
||||||
Editing the DocBook sources requires an XML editor. Many
|
|
||||||
exist: some notable options
|
|
||||||
include <span class="command"><strong>emacs</strong></span>, <span class="application">Kate</span>,
|
|
||||||
or <span class="application">Conglomerate</span>.
|
|
||||||
</p><p>
|
|
||||||
Some editors support special “<span class="quote">XML Validation</span>”
|
|
||||||
modes that can validate the file as it is
|
|
||||||
produced. Recommended is the <span class="command"><strong>nXML Mode</strong></span>
|
|
||||||
for <span class="command"><strong>emacs</strong></span>.
|
|
||||||
</p><p>
|
|
||||||
Besides an editor, additional DocBook files and XML tools are
|
|
||||||
also required.
|
|
||||||
</p><p>
|
|
||||||
Access to the DocBook stylesheets and DTD is required. The
|
|
||||||
stylesheets are usually packaged by vendor, in something
|
|
||||||
like <code class="filename">docbook-style-xsl</code>. To exactly match
|
|
||||||
generated output, please use a version of the stylesheets
|
|
||||||
equivalent
|
|
||||||
to <code class="filename">docbook-style-xsl-1.74.0-5</code>. The
|
|
||||||
installation directory for this package corresponds to
|
|
||||||
the <code class="literal">XSL_STYLE_DIR</code>
|
|
||||||
in <code class="filename">doc/Makefile.am</code> and defaults
|
|
||||||
to <code class="filename">/usr/share/sgml/docbook/xsl-stylesheets</code>.
|
|
||||||
</p><p>
|
|
||||||
For processing XML, an XML processor and some style
|
|
||||||
sheets are necessary. Defaults are <span class="command"><strong>xsltproc</strong></span>
|
|
||||||
provided by <code class="filename">libxslt</code>.
|
|
||||||
</p><p>
|
|
||||||
For validating the XML document, you'll need
|
|
||||||
something like <span class="command"><strong>xmllint</strong></span> and access to the
|
|
||||||
DocBook DTD. These are provided
|
|
||||||
by a vendor package like <code class="filename">lixml2</code>.
|
|
||||||
</p><p>
|
|
||||||
For PDF output, something that transforms valid XML to PDF is
|
|
||||||
required. Possible solutions include <span class="command"><strong>xmlto</strong></span>,
|
|
||||||
<a class="ulink" href="http://xmlgraphics.apache.org/fop/" target="_top">Apache
|
|
||||||
FOP</a>, or <span class="command"><strong>prince</strong></span>. Other options are
|
|
||||||
listed on the DocBook web <a class="ulink" href="http://wiki.docbook.org/topic/DocBookPublishingTools" target="_top">pages</a>. Please
|
|
||||||
consult the <code class="email"><<a class="email" href="mailto:libstdc++@gcc.gnu.org">libstdc++@gcc.gnu.org</a>></code> list when
|
|
||||||
preparing printed manuals for current best practice and suggestions.
|
|
||||||
</p><p>
|
|
||||||
Make sure that the XML documentation and markup is valid for
|
|
||||||
any change. This can be done easily, with the validation rules
|
|
||||||
in the <code class="filename">Makefile</code>, which is equivalent to doing:
|
|
||||||
</p><pre class="screen">
|
|
||||||
<strong class="userinput"><code>
|
|
||||||
xmllint --noout --valid <code class="filename">xml/index.xml</code>
|
|
||||||
</code></strong>
|
|
||||||
</pre></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.rules"></a>Generating the DocBook Files</h4></div></div></div><p>
|
|
||||||
The following Makefile rules generate (in order): an HTML
|
|
||||||
version of all the documentation, a PDF version of the same, a
|
|
||||||
single XML document, and the result of validating the entire XML
|
|
||||||
document.
|
|
||||||
</p><p>
|
|
||||||
</p><pre class="screen"><strong class="userinput"><code>make doc-html</code></strong></pre><p>
|
|
||||||
</p><p>
|
|
||||||
</p><pre class="screen"><strong class="userinput"><code>make doc-pdf</code></strong></pre><p>
|
|
||||||
</p><p>
|
|
||||||
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-single</code></strong></pre><p>
|
|
||||||
</p><p>
|
|
||||||
</p><pre class="screen"><strong class="userinput"><code>make doc-xml-validate</code></strong></pre><p>
|
|
||||||
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.examples"></a>File Organization and Basics</h4></div></div></div><div class="literallayout"><p><br />
|
|
||||||
<span class="emphasis"><em>Which files are important</em></span><br />
|
|
||||||
<br />
|
|
||||||
All Docbook files are in the directory<br />
|
|
||||||
libstdc++-v3/doc/xml<br />
|
|
||||||
<br />
|
|
||||||
Inside this directory, the files of importance:<br />
|
|
||||||
spine.xml - index to documentation set<br />
|
|
||||||
manual/spine.xml - index to manual<br />
|
|
||||||
manual/*.xml - individual chapters and sections of the manual<br />
|
|
||||||
faq.xml - index to FAQ<br />
|
|
||||||
api.xml - index to source level / API <br />
|
|
||||||
<br />
|
|
||||||
All *.txml files are template xml files, i.e., otherwise empty files with<br />
|
|
||||||
the correct structure, suitable for filling in with new information.<br />
|
|
||||||
<br />
|
|
||||||
<span class="emphasis"><em>Canonical Writing Style</em></span><br />
|
|
||||||
<br />
|
|
||||||
class template<br />
|
|
||||||
function template<br />
|
|
||||||
member function template<br />
|
|
||||||
(via C++ Templates, Vandevoorde)<br />
|
|
||||||
<br />
|
|
||||||
class in namespace std: allocator, not std::allocator<br />
|
|
||||||
<br />
|
|
||||||
header file: iostream, not <iostream><br />
|
|
||||||
<br />
|
|
||||||
<br />
|
|
||||||
<span class="emphasis"><em>General structure</em></span><br />
|
|
||||||
<br />
|
|
||||||
<set><br />
|
|
||||||
<book><br />
|
|
||||||
</book><br />
|
|
||||||
<br />
|
|
||||||
<book><br />
|
|
||||||
<chapter><br />
|
|
||||||
</chapter><br />
|
|
||||||
</book><br />
|
|
||||||
<br />
|
|
||||||
<book> <br />
|
|
||||||
<part><br />
|
|
||||||
<chapter><br />
|
|
||||||
<section><br />
|
|
||||||
</section><br />
|
|
||||||
<br />
|
|
||||||
<sect1><br />
|
|
||||||
</sect1><br />
|
|
||||||
<br />
|
|
||||||
<sect1><br />
|
|
||||||
<sect2><br />
|
|
||||||
</sect2><br />
|
|
||||||
</sect1><br />
|
|
||||||
</chapter><br />
|
|
||||||
<br />
|
|
||||||
<chapter><br />
|
|
||||||
</chapter><br />
|
|
||||||
</part> <br />
|
|
||||||
</book><br />
|
|
||||||
<br />
|
|
||||||
</set><br />
|
|
||||||
</p></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="docbook.markup"></a>Markup By Example</h4></div></div></div><p>
|
|
||||||
Complete details on Docbook markup can be found in the DocBook Element
|
|
||||||
Reference, <a class="ulink" href="http://www.docbook.org/tdg/en/html/part2.html" target="_top">online</a>. An
|
|
||||||
incomplete reference for HTML to Docbook conversion is detailed in the
|
|
||||||
table below.
|
|
||||||
</p><div class="table"><a id="id552441"></a><p class="title"><b>Table A.1. HTML to Docbook XML markup comparison</b></p><div class="table-contents"><table summary="HTML to Docbook XML markup comparison" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">HTML</th><th align="left">XML</th></tr></thead><tbody><tr><td align="left"><p></td><td align="left"><para></td></tr><tr><td align="left"><pre></td><td align="left"><computeroutput>, <programlisting>,
|
|
||||||
<literallayout></td></tr><tr><td align="left"><ul></td><td align="left"><itemizedlist></td></tr><tr><td align="left"><ol></td><td align="left"><orderedlist></td></tr><tr><td align="left"><il></td><td align="left"><listitem></td></tr><tr><td align="left"><dl></td><td align="left"><variablelist></td></tr><tr><td align="left"><dt></td><td align="left"><term></td></tr><tr><td align="left"><dd></td><td align="left"><listitem></td></tr><tr><td align="left"><a href=""></td><td align="left"><ulink url=""></td></tr><tr><td align="left"><code></td><td align="left"><literal>, <programlisting></td></tr><tr><td align="left"><strong></td><td align="left"><emphasis></td></tr><tr><td align="left"><em></td><td align="left"><emphasis></td></tr><tr><td align="left">"</td><td align="left"><quote></td></tr></tbody></table></div></div><br class="table-break" /><p>
|
|
||||||
And examples of detailed markup for which there are no real HTML
|
|
||||||
equivalents are listed in the table below.
|
|
||||||
</p><div class="table"><a id="id554436"></a><p class="title"><b>Table A.2. Docbook XML Element Use</b></p><div class="table-contents"><table summary="Docbook XML Element Use" border="1"><colgroup><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Element</th><th align="left">Use</th></tr></thead><tbody><tr><td align="left"><structname></td><td align="left"><structname>char_traits</structname></td></tr><tr><td align="left"><classname></td><td align="left"><classname>string</classname></td></tr><tr><td align="left"><function></td><td align="left">
|
|
||||||
<p><function>clear()</function></p>
|
|
||||||
<p><function>fs.clear()</function></p>
|
|
||||||
</td></tr><tr><td align="left"><type></td><td align="left"><type>long long</type></td></tr><tr><td align="left"><varname></td><td align="left"><varname>fs</varname></td></tr><tr><td align="left"><literal></td><td align="left">
|
|
||||||
<p><literal>-Weffc++</literal></p>
|
|
||||||
<p><literal>rel_ops</literal></p>
|
|
||||||
</td></tr><tr><td align="left"><constant></td><td align="left">
|
|
||||||
<p><constant>_GNU_SOURCE</constant></p>
|
|
||||||
<p><constant>3.0</constant></p>
|
|
||||||
</td></tr><tr><td align="left"><command></td><td align="left"><command>g++</command></td></tr><tr><td align="left"><errortext></td><td align="left"><errortext>In instantiation of</errortext></td></tr><tr><td align="left"><filename></td><td align="left">
|
|
||||||
<p><filename class="headerfile">ctype.h</filename></p>
|
|
||||||
<p><filename class="directory">/home/gcc/build</filename></p>
|
|
||||||
</td></tr></tbody></table></div></div><br class="table-break" /></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01apas03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01apas05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Coding Style </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Design Notes</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,857 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Design Notes</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="appendix_contributing.html" title="Appendix A. Contributing" /><link rel="prev" href="bk01apas04.html" title="Documentation Style" /><link rel="next" href="appendix_porting.html" title="Appendix B. Porting and Maintenance" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Design Notes</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01apas04.html">Prev</a> </td><th width="60%" align="center">Appendix A. Contributing</th><td width="20%" align="right"> <a accesskey="n" href="appendix_porting.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contrib.design_notes"></a>Design Notes</h2></div></div></div><p>
|
|
||||||
</p><div class="literallayout"><p><br />
|
|
||||||
<br />
|
|
||||||
The Library<br />
|
|
||||||
-----------<br />
|
|
||||||
<br />
|
|
||||||
This paper is covers two major areas:<br />
|
|
||||||
<br />
|
|
||||||
- Features and policies not mentioned in the standard that<br />
|
|
||||||
the quality of the library implementation depends on, including<br />
|
|
||||||
extensions and "implementation-defined" features;<br />
|
|
||||||
<br />
|
|
||||||
- Plans for required but unimplemented library features and<br />
|
|
||||||
optimizations to them.<br />
|
|
||||||
<br />
|
|
||||||
Overhead<br />
|
|
||||||
--------<br />
|
|
||||||
<br />
|
|
||||||
The standard defines a large library, much larger than the standard<br />
|
|
||||||
C library. A naive implementation would suffer substantial overhead<br />
|
|
||||||
in compile time, executable size, and speed, rendering it unusable<br />
|
|
||||||
in many (particularly embedded) applications. The alternative demands<br />
|
|
||||||
care in construction, and some compiler support, but there is no<br />
|
|
||||||
need for library subsets.<br />
|
|
||||||
<br />
|
|
||||||
What are the sources of this overhead? There are four main causes:<br />
|
|
||||||
<br />
|
|
||||||
- The library is specified almost entirely as templates, which<br />
|
|
||||||
with current compilers must be included in-line, resulting in<br />
|
|
||||||
very slow builds as tens or hundreds of thousands of lines<br />
|
|
||||||
of function definitions are read for each user source file.<br />
|
|
||||||
Indeed, the entire SGI STL, as well as the dos Reis valarray,<br />
|
|
||||||
are provided purely as header files, largely for simplicity in<br />
|
|
||||||
porting. Iostream/locale is (or will be) as large again.<br />
|
|
||||||
<br />
|
|
||||||
- The library is very flexible, specifying a multitude of hooks<br />
|
|
||||||
where users can insert their own code in place of defaults.<br />
|
|
||||||
When these hooks are not used, any time and code expended to<br />
|
|
||||||
support that flexibility is wasted.<br />
|
|
||||||
<br />
|
|
||||||
- Templates are often described as causing to "code bloat". In<br />
|
|
||||||
practice, this refers (when it refers to anything real) to several<br />
|
|
||||||
independent processes. First, when a class template is manually<br />
|
|
||||||
instantiated in its entirely, current compilers place the definitions<br />
|
|
||||||
for all members in a single object file, so that a program linking<br />
|
|
||||||
to one member gets definitions of all. Second, template functions<br />
|
|
||||||
which do not actually depend on the template argument are, under<br />
|
|
||||||
current compilers, generated anew for each instantiation, rather<br />
|
|
||||||
than being shared with other instantiations. Third, some of the<br />
|
|
||||||
flexibility mentioned above comes from virtual functions (both in<br />
|
|
||||||
regular classes and template classes) which current linkers add<br />
|
|
||||||
to the executable file even when they manifestly cannot be called.<br />
|
|
||||||
<br />
|
|
||||||
- The library is specified to use a language feature, exceptions,<br />
|
|
||||||
which in the current gcc compiler ABI imposes a run time and<br />
|
|
||||||
code space cost to handle the possibility of exceptions even when<br />
|
|
||||||
they are not used. Under the new ABI (accessed with -fnew-abi),<br />
|
|
||||||
there is a space overhead and a small reduction in code efficiency<br />
|
|
||||||
resulting from lost optimization opportunities associated with<br />
|
|
||||||
non-local branches associated with exceptions.<br />
|
|
||||||
<br />
|
|
||||||
What can be done to eliminate this overhead? A variety of coding<br />
|
|
||||||
techniques, and compiler, linker and library improvements and<br />
|
|
||||||
extensions may be used, as covered below. Most are not difficult,<br />
|
|
||||||
and some are already implemented in varying degrees.<br />
|
|
||||||
<br />
|
|
||||||
Overhead: Compilation Time<br />
|
|
||||||
--------------------------<br />
|
|
||||||
<br />
|
|
||||||
Providing "ready-instantiated" template code in object code archives<br />
|
|
||||||
allows us to avoid generating and optimizing template instantiations<br />
|
|
||||||
in each compilation unit which uses them. However, the number of such<br />
|
|
||||||
instantiations that are useful to provide is limited, and anyway this<br />
|
|
||||||
is not enough, by itself, to minimize compilation time. In particular,<br />
|
|
||||||
it does not reduce time spent parsing conforming headers.<br />
|
|
||||||
<br />
|
|
||||||
Quicker header parsing will depend on library extensions and compiler<br />
|
|
||||||
improvements. One approach is some variation on the techniques<br />
|
|
||||||
previously marketed as "pre-compiled headers", now standardized as<br />
|
|
||||||
support for the "export" keyword. "Exported" template definitions<br />
|
|
||||||
can be placed (once) in a "repository" -- really just a library, but<br />
|
|
||||||
of template definitions rather than object code -- to be drawn upon<br />
|
|
||||||
at link time when an instantiation is needed, rather than placed in<br />
|
|
||||||
header files to be parsed along with every compilation unit.<br />
|
|
||||||
<br />
|
|
||||||
Until "export" is implemented we can put some of the lengthy template<br />
|
|
||||||
definitions in #if guards or alternative headers so that users can skip<br />
|
|
||||||
over the full definitions when they need only the ready-instantiated<br />
|
|
||||||
specializations.<br />
|
|
||||||
<br />
|
|
||||||
To be precise, this means that certain headers which define<br />
|
|
||||||
templates which users normally use only for certain arguments<br />
|
|
||||||
can be instrumented to avoid exposing the template definitions<br />
|
|
||||||
to the compiler unless a macro is defined. For example, in<br />
|
|
||||||
<string>, we might have:<br />
|
|
||||||
<br />
|
|
||||||
template <class _CharT, ... > class basic_string {<br />
|
|
||||||
... // member declarations<br />
|
|
||||||
};<br />
|
|
||||||
... // operator declarations<br />
|
|
||||||
<br />
|
|
||||||
#ifdef _STRICT_ISO_<br />
|
|
||||||
# if _G_NO_TEMPLATE_EXPORT<br />
|
|
||||||
# include <bits/std_locale.h> // headers needed by definitions<br />
|
|
||||||
# ...<br />
|
|
||||||
# include <bits/string.tcc> // member and global template definitions.<br />
|
|
||||||
# endif<br />
|
|
||||||
#endif<br />
|
|
||||||
<br />
|
|
||||||
Users who compile without specifying a strict-ISO-conforming flag<br />
|
|
||||||
would not see many of the template definitions they now see, and rely<br />
|
|
||||||
instead on ready-instantiated specializations in the library. This<br />
|
|
||||||
technique would be useful for the following substantial components:<br />
|
|
||||||
string, locale/iostreams, valarray. It would *not* be useful or<br />
|
|
||||||
usable with the following: containers, algorithms, iterators,<br />
|
|
||||||
allocator. Since these constitute a large (though decreasing)<br />
|
|
||||||
fraction of the library, the benefit the technique offers is<br />
|
|
||||||
limited.<br />
|
|
||||||
<br />
|
|
||||||
The language specifies the semantics of the "export" keyword, but<br />
|
|
||||||
the gcc compiler does not yet support it. When it does, problems<br />
|
|
||||||
with large template inclusions can largely disappear, given some<br />
|
|
||||||
minor library reorganization, along with the need for the apparatus<br />
|
|
||||||
described above.<br />
|
|
||||||
<br />
|
|
||||||
Overhead: Flexibility Cost<br />
|
|
||||||
--------------------------<br />
|
|
||||||
<br />
|
|
||||||
The library offers many places where users can specify operations<br />
|
|
||||||
to be performed by the library in place of defaults. Sometimes<br />
|
|
||||||
this seems to require that the library use a more-roundabout, and<br />
|
|
||||||
possibly slower, way to accomplish the default requirements than<br />
|
|
||||||
would be used otherwise.<br />
|
|
||||||
<br />
|
|
||||||
The primary protection against this overhead is thorough compiler<br />
|
|
||||||
optimization, to crush out layers of inline function interfaces.<br />
|
|
||||||
Kuck & Associates has demonstrated the practicality of this kind<br />
|
|
||||||
of optimization.<br />
|
|
||||||
<br />
|
|
||||||
The second line of defense against this overhead is explicit<br />
|
|
||||||
specialization. By defining helper function templates, and writing<br />
|
|
||||||
specialized code for the default case, overhead can be eliminated<br />
|
|
||||||
for that case without sacrificing flexibility. This takes full<br />
|
|
||||||
advantage of any ability of the optimizer to crush out degenerate<br />
|
|
||||||
code.<br />
|
|
||||||
<br />
|
|
||||||
The library specifies many virtual functions which current linkers<br />
|
|
||||||
load even when they cannot be called. Some minor improvements to the<br />
|
|
||||||
compiler and to ld would eliminate any such overhead by simply<br />
|
|
||||||
omitting virtual functions that the complete program does not call.<br />
|
|
||||||
A prototype of this work has already been done. For targets where<br />
|
|
||||||
GNU ld is not used, a "pre-linker" could do the same job.<br />
|
|
||||||
<br />
|
|
||||||
The main areas in the standard interface where user flexibility<br />
|
|
||||||
can result in overhead are:<br />
|
|
||||||
<br />
|
|
||||||
- Allocators: Containers are specified to use user-definable<br />
|
|
||||||
allocator types and objects, making tuning for the container<br />
|
|
||||||
characteristics tricky.<br />
|
|
||||||
<br />
|
|
||||||
- Locales: the standard specifies locale objects used to implement<br />
|
|
||||||
iostream operations, involving many virtual functions which use<br />
|
|
||||||
streambuf iterators.<br />
|
|
||||||
<br />
|
|
||||||
- Algorithms and containers: these may be instantiated on any type,<br />
|
|
||||||
frequently duplicating code for identical operations.<br />
|
|
||||||
<br />
|
|
||||||
- Iostreams and strings: users are permitted to use these on their<br />
|
|
||||||
own types, and specify the operations the stream must use on these<br />
|
|
||||||
types.<br />
|
|
||||||
<br />
|
|
||||||
Note that these sources of overhead are _avoidable_. The techniques<br />
|
|
||||||
to avoid them are covered below.<br />
|
|
||||||
<br />
|
|
||||||
Code Bloat<br />
|
|
||||||
----------<br />
|
|
||||||
<br />
|
|
||||||
In the SGI STL, and in some other headers, many of the templates<br />
|
|
||||||
are defined "inline" -- either explicitly or by their placement<br />
|
|
||||||
in class definitions -- which should not be inline. This is a<br />
|
|
||||||
source of code bloat. Matt had remarked that he was relying on<br />
|
|
||||||
the compiler to recognize what was too big to benefit from inlining,<br />
|
|
||||||
and generate it out-of-line automatically. However, this also can<br />
|
|
||||||
result in code bloat except where the linker can eliminate the extra<br />
|
|
||||||
copies.<br />
|
|
||||||
<br />
|
|
||||||
Fixing these cases will require an audit of all inline functions<br />
|
|
||||||
defined in the library to determine which merit inlining, and moving<br />
|
|
||||||
the rest out of line. This is an issue mainly in chapters 23, 25, and<br />
|
|
||||||
27. Of course it can be done incrementally, and we should generally<br />
|
|
||||||
accept patches that move large functions out of line and into ".tcc"<br />
|
|
||||||
files, which can later be pulled into a repository. Compiler/linker<br />
|
|
||||||
improvements to recognize very large inline functions and move them<br />
|
|
||||||
out-of-line, but shared among compilation units, could make this<br />
|
|
||||||
work unnecessary.<br />
|
|
||||||
<br />
|
|
||||||
Pre-instantiating template specializations currently produces large<br />
|
|
||||||
amounts of dead code which bloats statically linked programs. The<br />
|
|
||||||
current state of the static library, libstdc++.a, is intolerable on<br />
|
|
||||||
this account, and will fuel further confused speculation about a need<br />
|
|
||||||
for a library "subset". A compiler improvement that treats each<br />
|
|
||||||
instantiated function as a separate object file, for linking purposes,<br />
|
|
||||||
would be one solution to this problem. An alternative would be to<br />
|
|
||||||
split up the manual instantiation files into dozens upon dozens of<br />
|
|
||||||
little files, each compiled separately, but an abortive attempt at<br />
|
|
||||||
this was done for <string> and, though it is far from complete, it<br />
|
|
||||||
is already a nuisance. A better interim solution (just until we have<br />
|
|
||||||
"export") is badly needed.<br />
|
|
||||||
<br />
|
|
||||||
When building a shared library, the current compiler/linker cannot<br />
|
|
||||||
automatically generate the instantiations needed. This creates a<br />
|
|
||||||
miserable situation; it means any time something is changed in the<br />
|
|
||||||
library, before a shared library can be built someone must manually<br />
|
|
||||||
copy the declarations of all templates that are needed by other parts<br />
|
|
||||||
of the library to an "instantiation" file, and add it to the build<br />
|
|
||||||
system to be compiled and linked to the library. This process is<br />
|
|
||||||
readily automated, and should be automated as soon as possible.<br />
|
|
||||||
Users building their own shared libraries experience identical<br />
|
|
||||||
frustrations.<br />
|
|
||||||
<br />
|
|
||||||
Sharing common aspects of template definitions among instantiations<br />
|
|
||||||
can radically reduce code bloat. The compiler could help a great<br />
|
|
||||||
deal here by recognizing when a function depends on nothing about<br />
|
|
||||||
a template parameter, or only on its size, and giving the resulting<br />
|
|
||||||
function a link-name "equate" that allows it to be shared with other<br />
|
|
||||||
instantiations. Implementation code could take advantage of the<br />
|
|
||||||
capability by factoring out code that does not depend on the template<br />
|
|
||||||
argument into separate functions to be merged by the compiler.<br />
|
|
||||||
<br />
|
|
||||||
Until such a compiler optimization is implemented, much can be done<br />
|
|
||||||
manually (if tediously) in this direction. One such optimization is<br />
|
|
||||||
to derive class templates from non-template classes, and move as much<br />
|
|
||||||
implementation as possible into the base class. Another is to partial-<br />
|
|
||||||
specialize certain common instantiations, such as vector<T*>, to share<br />
|
|
||||||
code for instantiations on all types T. While these techniques work,<br />
|
|
||||||
they are far from the complete solution that a compiler improvement<br />
|
|
||||||
would afford.<br />
|
|
||||||
<br />
|
|
||||||
Overhead: Expensive Language Features<br />
|
|
||||||
-------------------------------------<br />
|
|
||||||
<br />
|
|
||||||
The main "expensive" language feature used in the standard library<br />
|
|
||||||
is exception support, which requires compiling in cleanup code with<br />
|
|
||||||
static table data to locate it, and linking in library code to use<br />
|
|
||||||
the table. For small embedded programs the amount of such library<br />
|
|
||||||
code and table data is assumed by some to be excessive. Under the<br />
|
|
||||||
"new" ABI this perception is generally exaggerated, although in some<br />
|
|
||||||
cases it may actually be excessive.<br />
|
|
||||||
<br />
|
|
||||||
To implement a library which does not use exceptions directly is<br />
|
|
||||||
not difficult given minor compiler support (to "turn off" exceptions<br />
|
|
||||||
and ignore exception constructs), and results in no great library<br />
|
|
||||||
maintenance difficulties. To be precise, given "-fno-exceptions",<br />
|
|
||||||
the compiler should treat "try" blocks as ordinary blocks, and<br />
|
|
||||||
"catch" blocks as dead code to ignore or eliminate. Compiler<br />
|
|
||||||
support is not strictly necessary, except in the case of "function<br />
|
|
||||||
try blocks"; otherwise the following macros almost suffice:<br />
|
|
||||||
<br />
|
|
||||||
#define throw(X)<br />
|
|
||||||
#define try if (true)<br />
|
|
||||||
#define catch(X) else if (false)<br />
|
|
||||||
<br />
|
|
||||||
However, there may be a need to use function try blocks in the<br />
|
|
||||||
library implementation, and use of macros in this way can make<br />
|
|
||||||
correct diagnostics impossible. Furthermore, use of this scheme<br />
|
|
||||||
would require the library to call a function to re-throw exceptions<br />
|
|
||||||
from a try block. Implementing the above semantics in the compiler<br />
|
|
||||||
is preferable.<br />
|
|
||||||
<br />
|
|
||||||
Given the support above (however implemented) it only remains to<br />
|
|
||||||
replace code that "throws" with a call to a well-documented "handler"<br />
|
|
||||||
function in a separate compilation unit which may be replaced by<br />
|
|
||||||
the user. The main source of exceptions that would be difficult<br />
|
|
||||||
for users to avoid is memory allocation failures, but users can<br />
|
|
||||||
define their own memory allocation primitives that never throw.<br />
|
|
||||||
Otherwise, the complete list of such handlers, and which library<br />
|
|
||||||
functions may call them, would be needed for users to be able to<br />
|
|
||||||
implement the necessary substitutes. (Fortunately, they have the<br />
|
|
||||||
source code.)<br />
|
|
||||||
<br />
|
|
||||||
Opportunities<br />
|
|
||||||
-------------<br />
|
|
||||||
<br />
|
|
||||||
The template capabilities of C++ offer enormous opportunities for<br />
|
|
||||||
optimizing common library operations, well beyond what would be<br />
|
|
||||||
considered "eliminating overhead". In particular, many operations<br />
|
|
||||||
done in Glibc with macros that depend on proprietary language<br />
|
|
||||||
extensions can be implemented in pristine Standard C++. For example,<br />
|
|
||||||
the chapter 25 algorithms, and even C library functions such as strchr,<br />
|
|
||||||
can be specialized for the case of static arrays of known (small) size.<br />
|
|
||||||
<br />
|
|
||||||
Detailed optimization opportunities are identified below where<br />
|
|
||||||
the component where they would appear is discussed. Of course new<br />
|
|
||||||
opportunities will be identified during implementation.<br />
|
|
||||||
<br />
|
|
||||||
Unimplemented Required Library Features<br />
|
|
||||||
---------------------------------------<br />
|
|
||||||
<br />
|
|
||||||
The standard specifies hundreds of components, grouped broadly by<br />
|
|
||||||
chapter. These are listed in excruciating detail in the CHECKLIST<br />
|
|
||||||
file.<br />
|
|
||||||
<br />
|
|
||||||
17 general<br />
|
|
||||||
18 support<br />
|
|
||||||
19 diagnostics<br />
|
|
||||||
20 utilities<br />
|
|
||||||
21 string<br />
|
|
||||||
22 locale<br />
|
|
||||||
23 containers<br />
|
|
||||||
24 iterators<br />
|
|
||||||
25 algorithms<br />
|
|
||||||
26 numerics<br />
|
|
||||||
27 iostreams<br />
|
|
||||||
Annex D backward compatibility<br />
|
|
||||||
<br />
|
|
||||||
Anyone participating in implementation of the library should obtain<br />
|
|
||||||
a copy of the standard, ISO 14882. People in the U.S. can obtain an<br />
|
|
||||||
electronic copy for US$18 from ANSI's web site. Those from other<br />
|
|
||||||
countries should visit http://www.iso.ch/ to find out the location<br />
|
|
||||||
of their country's representation in ISO, in order to know who can<br />
|
|
||||||
sell them a copy.<br />
|
|
||||||
<br />
|
|
||||||
The emphasis in the following sections is on unimplemented features<br />
|
|
||||||
and optimization opportunities.<br />
|
|
||||||
<br />
|
|
||||||
Chapter 17 General<br />
|
|
||||||
-------------------<br />
|
|
||||||
<br />
|
|
||||||
Chapter 17 concerns overall library requirements.<br />
|
|
||||||
<br />
|
|
||||||
The standard doesn't mention threads. A multi-thread (MT) extension<br />
|
|
||||||
primarily affects operators new and delete (18), allocator (20),<br />
|
|
||||||
string (21), locale (22), and iostreams (27). The common underlying<br />
|
|
||||||
support needed for this is discussed under chapter 20.<br />
|
|
||||||
<br />
|
|
||||||
The standard requirements on names from the C headers create a<br />
|
|
||||||
lot of work, mostly done. Names in the C headers must be visible<br />
|
|
||||||
in the std:: and sometimes the global namespace; the names in the<br />
|
|
||||||
two scopes must refer to the same object. More stringent is that<br />
|
|
||||||
Koenig lookup implies that any types specified as defined in std::<br />
|
|
||||||
really are defined in std::. Names optionally implemented as<br />
|
|
||||||
macros in C cannot be macros in C++. (An overview may be read at<br />
|
|
||||||
<http://www.cantrip.org/cheaders.html>). The scripts "inclosure"<br />
|
|
||||||
and "mkcshadow", and the directories shadow/ and cshadow/, are the<br />
|
|
||||||
beginning of an effort to conform in this area.<br />
|
|
||||||
<br />
|
|
||||||
A correct conforming definition of C header names based on underlying<br />
|
|
||||||
C library headers, and practical linking of conforming namespaced<br />
|
|
||||||
customer code with third-party C libraries depends ultimately on<br />
|
|
||||||
an ABI change, allowing namespaced C type names to be mangled into<br />
|
|
||||||
type names as if they were global, somewhat as C function names in a<br />
|
|
||||||
namespace, or C++ global variable names, are left unmangled. Perhaps<br />
|
|
||||||
another "extern" mode, such as 'extern "C-global"' would be an<br />
|
|
||||||
appropriate place for such type definitions. Such a type would<br />
|
|
||||||
affect mangling as follows:<br />
|
|
||||||
<br />
|
|
||||||
namespace A {<br />
|
|
||||||
struct X {};<br />
|
|
||||||
extern "C-global" { // or maybe just 'extern "C"'<br />
|
|
||||||
struct Y {};<br />
|
|
||||||
};<br />
|
|
||||||
}<br />
|
|
||||||
void f(A::X*); // mangles to f__FPQ21A1X<br />
|
|
||||||
void f(A::Y*); // mangles to f__FP1Y<br />
|
|
||||||
<br />
|
|
||||||
(It may be that this is really the appropriate semantics for regular<br />
|
|
||||||
'extern "C"', and 'extern "C-global"', as an extension, would not be<br />
|
|
||||||
necessary.) This would allow functions declared in non-standard C headers<br />
|
|
||||||
(and thus fixable by neither us nor users) to link properly with functions<br />
|
|
||||||
declared using C types defined in properly-namespaced headers. The<br />
|
|
||||||
problem this solves is that C headers (which C++ programmers do persist<br />
|
|
||||||
in using) frequently forward-declare C struct tags without including<br />
|
|
||||||
the header where the type is defined, as in<br />
|
|
||||||
<br />
|
|
||||||
struct tm;<br />
|
|
||||||
void munge(tm*);<br />
|
|
||||||
<br />
|
|
||||||
Without some compiler accommodation, munge cannot be called by correct<br />
|
|
||||||
C++ code using a pointer to a correctly-scoped tm* value.<br />
|
|
||||||
<br />
|
|
||||||
The current C headers use the preprocessor extension "#include_next",<br />
|
|
||||||
which the compiler complains about when run "-pedantic".<br />
|
|
||||||
(Incidentally, it appears that "-fpedantic" is currently ignored,<br />
|
|
||||||
probably a bug.) The solution in the C compiler is to use<br />
|
|
||||||
"-isystem" rather than "-I", but unfortunately in g++ this seems<br />
|
|
||||||
also to wrap the whole header in an 'extern "C"' block, so it's<br />
|
|
||||||
unusable for C++ headers. The correct solution appears to be to<br />
|
|
||||||
allow the various special include-directory options, if not given<br />
|
|
||||||
an argument, to affect subsequent include-directory options additively,<br />
|
|
||||||
so that if one said<br />
|
|
||||||
<br />
|
|
||||||
-pedantic -iprefix $(prefix) \<br />
|
|
||||||
-idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \<br />
|
|
||||||
-iwithprefix -I g++-v3/ext<br />
|
|
||||||
<br />
|
|
||||||
the compiler would search $(prefix)/g++-v3 and not report<br />
|
|
||||||
pedantic warnings for files found there, but treat files in<br />
|
|
||||||
$(prefix)/g++-v3/ext pedantically. (The undocumented semantics<br />
|
|
||||||
of "-isystem" in g++ stink. Can they be rescinded? If not it<br />
|
|
||||||
must be replaced with something more rationally behaved.)<br />
|
|
||||||
<br />
|
|
||||||
All the C headers need the treatment above; in the standard these<br />
|
|
||||||
headers are mentioned in various chapters. Below, I have only<br />
|
|
||||||
mentioned those that present interesting implementation issues.<br />
|
|
||||||
<br />
|
|
||||||
The components identified as "mostly complete", below, have not been<br />
|
|
||||||
audited for conformance. In many cases where the library passes<br />
|
|
||||||
conformance tests we have non-conforming extensions that must be<br />
|
|
||||||
wrapped in #if guards for "pedantic" use, and in some cases renamed<br />
|
|
||||||
in a conforming way for continued use in the implementation regardless<br />
|
|
||||||
of conformance flags.<br />
|
|
||||||
<br />
|
|
||||||
The STL portion of the library still depends on a header<br />
|
|
||||||
stl/bits/stl_config.h full of #ifdef clauses. This apparatus<br />
|
|
||||||
should be replaced with autoconf/automake machinery.<br />
|
|
||||||
<br />
|
|
||||||
The SGI STL defines a type_traits<> template, specialized for<br />
|
|
||||||
many types in their code including the built-in numeric and<br />
|
|
||||||
pointer types and some library types, to direct optimizations of<br />
|
|
||||||
standard functions. The SGI compiler has been extended to generate<br />
|
|
||||||
specializations of this template automatically for user types,<br />
|
|
||||||
so that use of STL templates on user types can take advantage of<br />
|
|
||||||
these optimizations. Specializations for other, non-STL, types<br />
|
|
||||||
would make more optimizations possible, but extending the gcc<br />
|
|
||||||
compiler in the same way would be much better. Probably the next<br />
|
|
||||||
round of standardization will ratify this, but probably with<br />
|
|
||||||
changes, so it probably should be renamed to place it in the<br />
|
|
||||||
implementation namespace.<br />
|
|
||||||
<br />
|
|
||||||
The SGI STL also defines a large number of extensions visible in<br />
|
|
||||||
standard headers. (Other extensions that appear in separate headers<br />
|
|
||||||
have been sequestered in subdirectories ext/ and backward/.) All<br />
|
|
||||||
these extensions should be moved to other headers where possible,<br />
|
|
||||||
and in any case wrapped in a namespace (not std!), and (where kept<br />
|
|
||||||
in a standard header) girded about with macro guards. Some cannot be<br />
|
|
||||||
moved out of standard headers because they are used to implement<br />
|
|
||||||
standard features. The canonical method for accommodating these<br />
|
|
||||||
is to use a protected name, aliased in macro guards to a user-space<br />
|
|
||||||
name. Unfortunately C++ offers no satisfactory template typedef<br />
|
|
||||||
mechanism, so very ad-hoc and unsatisfactory aliasing must be used<br />
|
|
||||||
instead.<br />
|
|
||||||
<br />
|
|
||||||
Implementation of a template typedef mechanism should have the highest<br />
|
|
||||||
priority among possible extensions, on the same level as implementation<br />
|
|
||||||
of the template "export" feature.<br />
|
|
||||||
<br />
|
|
||||||
Chapter 18 Language support<br />
|
|
||||||
----------------------------<br />
|
|
||||||
<br />
|
|
||||||
Headers: <limits> <new> <typeinfo> <exception><br />
|
|
||||||
C headers: <cstddef> <climits> <cfloat> <cstdarg> <csetjmp><br />
|
|
||||||
<ctime> <csignal> <cstdlib> (also 21, 25, 26)<br />
|
|
||||||
<br />
|
|
||||||
This defines the built-in exceptions, rtti, numeric_limits<>,<br />
|
|
||||||
operator new and delete. Much of this is provided by the<br />
|
|
||||||
compiler in its static runtime library.<br />
|
|
||||||
<br />
|
|
||||||
Work to do includes defining numeric_limits<> specializations in<br />
|
|
||||||
separate files for all target architectures. Values for integer types<br />
|
|
||||||
except for bool and wchar_t are readily obtained from the C header<br />
|
|
||||||
<limits.h>, but values for the remaining numeric types (bool, wchar_t,<br />
|
|
||||||
float, double, long double) must be entered manually. This is<br />
|
|
||||||
largely dog work except for those members whose values are not<br />
|
|
||||||
easily deduced from available documentation. Also, this involves<br />
|
|
||||||
some work in target configuration to identify the correct choice of<br />
|
|
||||||
file to build against and to install.<br />
|
|
||||||
<br />
|
|
||||||
The definitions of the various operators new and delete must be<br />
|
|
||||||
made thread-safe, which depends on a portable exclusion mechanism,<br />
|
|
||||||
discussed under chapter 20. Of course there is always plenty of<br />
|
|
||||||
room for improvements to the speed of operators new and delete.<br />
|
|
||||||
<br />
|
|
||||||
<cstdarg>, in Glibc, defines some macros that gcc does not allow to<br />
|
|
||||||
be wrapped into an inline function. Probably this header will demand<br />
|
|
||||||
attention whenever a new target is chosen. The functions atexit(),<br />
|
|
||||||
exit(), and abort() in cstdlib have different semantics in C++, so<br />
|
|
||||||
must be re-implemented for C++.<br />
|
|
||||||
<br />
|
|
||||||
Chapter 19 Diagnostics<br />
|
|
||||||
-----------------------<br />
|
|
||||||
<br />
|
|
||||||
Headers: <stdexcept><br />
|
|
||||||
C headers: <cassert> <cerrno><br />
|
|
||||||
<br />
|
|
||||||
This defines the standard exception objects, which are "mostly complete".<br />
|
|
||||||
Cygnus has a version, and now SGI provides a slightly different one.<br />
|
|
||||||
It makes little difference which we use.<br />
|
|
||||||
<br />
|
|
||||||
The C global name "errno", which C allows to be a variable or a macro,<br />
|
|
||||||
is required in C++ to be a macro. For MT it must typically result in<br />
|
|
||||||
a function call.<br />
|
|
||||||
<br />
|
|
||||||
Chapter 20 Utilities<br />
|
|
||||||
---------------------<br />
|
|
||||||
Headers: <utility> <functional> <memory><br />
|
|
||||||
C header: <ctime> (also in 18)<br />
|
|
||||||
<br />
|
|
||||||
SGI STL provides "mostly complete" versions of all the components<br />
|
|
||||||
defined in this chapter. However, the auto_ptr<> implementation<br />
|
|
||||||
is known to be wrong. Furthermore, the standard definition of it<br />
|
|
||||||
is known to be unimplementable as written. A minor change to the<br />
|
|
||||||
standard would fix it, and auto_ptr<> should be adjusted to match.<br />
|
|
||||||
<br />
|
|
||||||
Multi-threading affects the allocator implementation, and there must<br />
|
|
||||||
be configuration/installation choices for different users' MT<br />
|
|
||||||
requirements. Anyway, users will want to tune allocator options<br />
|
|
||||||
to support different target conditions, MT or no.<br />
|
|
||||||
<br />
|
|
||||||
The primitives used for MT implementation should be exposed, as an<br />
|
|
||||||
extension, for users' own work. We need cross-CPU "mutex" support,<br />
|
|
||||||
multi-processor shared-memory atomic integer operations, and single-<br />
|
|
||||||
processor uninterruptible integer operations, and all three configurable<br />
|
|
||||||
to be stubbed out for non-MT use, or to use an appropriately-loaded<br />
|
|
||||||
dynamic library for the actual runtime environment, or statically<br />
|
|
||||||
compiled in for cases where the target architecture is known.<br />
|
|
||||||
<br />
|
|
||||||
Chapter 21 String<br />
|
|
||||||
------------------<br />
|
|
||||||
Headers: <string><br />
|
|
||||||
C headers: <cctype> <cwctype> <cstring> <cwchar> (also in 27)<br />
|
|
||||||
<cstdlib> (also in 18, 25, 26)<br />
|
|
||||||
<br />
|
|
||||||
We have "mostly-complete" char_traits<> implementations. Many of the<br />
|
|
||||||
char_traits<char> operations might be optimized further using existing<br />
|
|
||||||
proprietary language extensions.<br />
|
|
||||||
<br />
|
|
||||||
We have a "mostly-complete" basic_string<> implementation. The work<br />
|
|
||||||
to manually instantiate char and wchar_t specializations in object<br />
|
|
||||||
files to improve link-time behavior is extremely unsatisfactory,<br />
|
|
||||||
literally tripling library-build time with no commensurate improvement<br />
|
|
||||||
in static program link sizes. It must be redone. (Similar work is<br />
|
|
||||||
needed for some components in chapters 22 and 27.)<br />
|
|
||||||
<br />
|
|
||||||
Other work needed for strings is MT-safety, as discussed under the<br />
|
|
||||||
chapter 20 heading.<br />
|
|
||||||
<br />
|
|
||||||
The standard C type mbstate_t from <cwchar> and used in char_traits<><br />
|
|
||||||
must be different in C++ than in C, because in C++ the default constructor<br />
|
|
||||||
value mbstate_t() must be the "base" or "ground" sequence state.<br />
|
|
||||||
(According to the likely resolution of a recently raised Core issue,<br />
|
|
||||||
this may become unnecessary. However, there are other reasons to<br />
|
|
||||||
use a state type not as limited as whatever the C library provides.)<br />
|
|
||||||
If we might want to provide conversions from (e.g.) internally-<br />
|
|
||||||
represented EUC-wide to externally-represented Unicode, or vice-<br />
|
|
||||||
versa, the mbstate_t we choose will need to be more accommodating<br />
|
|
||||||
than what might be provided by an underlying C library.<br />
|
|
||||||
<br />
|
|
||||||
There remain some basic_string template-member functions which do<br />
|
|
||||||
not overload properly with their non-template brethren. The infamous<br />
|
|
||||||
hack akin to what was done in vector<> is needed, to conform to<br />
|
|
||||||
23.1.1 para 10. The CHECKLIST items for basic_string marked 'X',<br />
|
|
||||||
or incomplete, are so marked for this reason.<br />
|
|
||||||
<br />
|
|
||||||
Replacing the string iterators, which currently are simple character<br />
|
|
||||||
pointers, with class objects would greatly increase the safety of the<br />
|
|
||||||
client interface, and also permit a "debug" mode in which range,<br />
|
|
||||||
ownership, and validity are rigorously checked. The current use of<br />
|
|
||||||
raw pointers as string iterators is evil. vector<> iterators need the<br />
|
|
||||||
same treatment. Note that the current implementation freely mixes<br />
|
|
||||||
pointers and iterators, and that must be fixed before safer iterators<br />
|
|
||||||
can be introduced.<br />
|
|
||||||
<br />
|
|
||||||
Some of the functions in <cstring> are different from the C version.<br />
|
|
||||||
generally overloaded on const and non-const argument pointers. For<br />
|
|
||||||
example, in <cstring> strchr is overloaded. The functions isupper<br />
|
|
||||||
etc. in <cctype> typically implemented as macros in C are functions<br />
|
|
||||||
in C++, because they are overloaded with others of the same name<br />
|
|
||||||
defined in <locale>.<br />
|
|
||||||
<br />
|
|
||||||
Many of the functions required in <cwctype> and <cwchar> cannot be<br />
|
|
||||||
implemented using underlying C facilities on intended targets because<br />
|
|
||||||
such facilities only partly exist.<br />
|
|
||||||
<br />
|
|
||||||
Chapter 22 Locale<br />
|
|
||||||
------------------<br />
|
|
||||||
Headers: <locale><br />
|
|
||||||
C headers: <clocale><br />
|
|
||||||
<br />
|
|
||||||
We have a "mostly complete" class locale, with the exception of<br />
|
|
||||||
code for constructing, and handling the names of, named locales.<br />
|
|
||||||
The ways that locales are named (particularly when categories<br />
|
|
||||||
(e.g. LC_TIME, LC_COLLATE) are different) varies among all target<br />
|
|
||||||
environments. This code must be written in various versions and<br />
|
|
||||||
chosen by configuration parameters.<br />
|
|
||||||
<br />
|
|
||||||
Members of many of the facets defined in <locale> are stubs. Generally,<br />
|
|
||||||
there are two sets of facets: the base class facets (which are supposed<br />
|
|
||||||
to implement the "C" locale) and the "byname" facets, which are supposed<br />
|
|
||||||
to read files to determine their behavior. The base ctype<>, collate<>,<br />
|
|
||||||
and numpunct<> facets are "mostly complete", except that the table of<br />
|
|
||||||
bitmask values used for "is" operations, and corresponding mask values,<br />
|
|
||||||
are still defined in libio and just included/linked. (We will need to<br />
|
|
||||||
implement these tables independently, soon, but should take advantage<br />
|
|
||||||
of libio where possible.) The num_put<>::put members for integer types<br />
|
|
||||||
are "mostly complete".<br />
|
|
||||||
<br />
|
|
||||||
A complete list of what has and has not been implemented may be<br />
|
|
||||||
found in CHECKLIST. However, note that the current definition of<br />
|
|
||||||
codecvt<wchar_t,char,mbstate_t> is wrong. It should simply write<br />
|
|
||||||
out the raw bytes representing the wide characters, rather than<br />
|
|
||||||
trying to convert each to a corresponding single "char" value.<br />
|
|
||||||
<br />
|
|
||||||
Some of the facets are more important than others. Specifically,<br />
|
|
||||||
the members of ctype<>, numpunct<>, num_put<>, and num_get<> facets<br />
|
|
||||||
are used by other library facilities defined in <string>, <istream>,<br />
|
|
||||||
and <ostream>, and the codecvt<> facet is used by basic_filebuf<><br />
|
|
||||||
in <fstream>, so a conforming iostream implementation depends on<br />
|
|
||||||
these.<br />
|
|
||||||
<br />
|
|
||||||
The "long long" type eventually must be supported, but code mentioning<br />
|
|
||||||
it should be wrapped in #if guards to allow pedantic-mode compiling.<br />
|
|
||||||
<br />
|
|
||||||
Performance of num_put<> and num_get<> depend critically on<br />
|
|
||||||
caching computed values in ios_base objects, and on extensions<br />
|
|
||||||
to the interface with streambufs.<br />
|
|
||||||
<br />
|
|
||||||
Specifically: retrieving a copy of the locale object, extracting<br />
|
|
||||||
the needed facets, and gathering data from them, for each call to<br />
|
|
||||||
(e.g.) operator<< would be prohibitively slow. To cache format<br />
|
|
||||||
data for use by num_put<> and num_get<> we have a _Format_cache<><br />
|
|
||||||
object stored in the ios_base::pword() array. This is constructed<br />
|
|
||||||
and initialized lazily, and is organized purely for utility. It<br />
|
|
||||||
is discarded when a new locale with different facets is imbued.<br />
|
|
||||||
<br />
|
|
||||||
Using only the public interfaces of the iterator arguments to the<br />
|
|
||||||
facet functions would limit performance by forbidding "vector-style"<br />
|
|
||||||
character operations. The streambuf iterator optimizations are<br />
|
|
||||||
described under chapter 24, but facets can also bypass the streambuf<br />
|
|
||||||
iterators via explicit specializations and operate directly on the<br />
|
|
||||||
streambufs, and use extended interfaces to get direct access to the<br />
|
|
||||||
streambuf internal buffer arrays. These extensions are mentioned<br />
|
|
||||||
under chapter 27. These optimizations are particularly important<br />
|
|
||||||
for input parsing.<br />
|
|
||||||
<br />
|
|
||||||
Unused virtual members of locale facets can be omitted, as mentioned<br />
|
|
||||||
above, by a smart linker.<br />
|
|
||||||
<br />
|
|
||||||
Chapter 23 Containers<br />
|
|
||||||
----------------------<br />
|
|
||||||
Headers: <deque> <list> <queue> <stack> <vector> <map> <set> <bitset><br />
|
|
||||||
<br />
|
|
||||||
All the components in chapter 23 are implemented in the SGI STL.<br />
|
|
||||||
They are "mostly complete"; they include a large number of<br />
|
|
||||||
nonconforming extensions which must be wrapped. Some of these<br />
|
|
||||||
are used internally and must be renamed or duplicated.<br />
|
|
||||||
<br />
|
|
||||||
The SGI components are optimized for large-memory environments. For<br />
|
|
||||||
embedded targets, different criteria might be more appropriate. Users<br />
|
|
||||||
will want to be able to tune this behavior. We should provide<br />
|
|
||||||
ways for users to compile the library with different memory usage<br />
|
|
||||||
characteristics.<br />
|
|
||||||
<br />
|
|
||||||
A lot more work is needed on factoring out common code from different<br />
|
|
||||||
specializations to reduce code size here and in chapter 25. The<br />
|
|
||||||
easiest fix for this would be a compiler/ABI improvement that allows<br />
|
|
||||||
the compiler to recognize when a specialization depends only on the<br />
|
|
||||||
size (or other gross quality) of a template argument, and allow the<br />
|
|
||||||
linker to share the code with similar specializations. In its<br />
|
|
||||||
absence, many of the algorithms and containers can be partial-<br />
|
|
||||||
specialized, at least for the case of pointers, but this only solves<br />
|
|
||||||
a small part of the problem. Use of a type_traits-style template<br />
|
|
||||||
allows a few more optimization opportunities, more if the compiler<br />
|
|
||||||
can generate the specializations automatically.<br />
|
|
||||||
<br />
|
|
||||||
As an optimization, containers can specialize on the default allocator<br />
|
|
||||||
and bypass it, or take advantage of details of its implementation<br />
|
|
||||||
after it has been improved upon.<br />
|
|
||||||
<br />
|
|
||||||
Replacing the vector iterators, which currently are simple element<br />
|
|
||||||
pointers, with class objects would greatly increase the safety of the<br />
|
|
||||||
client interface, and also permit a "debug" mode in which range,<br />
|
|
||||||
ownership, and validity are rigorously checked. The current use of<br />
|
|
||||||
pointers for iterators is evil.<br />
|
|
||||||
<br />
|
|
||||||
As mentioned for chapter 24, the deque iterator is a good example of<br />
|
|
||||||
an opportunity to implement a "staged" iterator that would benefit<br />
|
|
||||||
from specializations of some algorithms.<br />
|
|
||||||
<br />
|
|
||||||
Chapter 24 Iterators<br />
|
|
||||||
---------------------<br />
|
|
||||||
Headers: <iterator><br />
|
|
||||||
<br />
|
|
||||||
Standard iterators are "mostly complete", with the exception of<br />
|
|
||||||
the stream iterators, which are not yet templatized on the<br />
|
|
||||||
stream type. Also, the base class template iterator<> appears<br />
|
|
||||||
to be wrong, so everything derived from it must also be wrong,<br />
|
|
||||||
currently.<br />
|
|
||||||
<br />
|
|
||||||
The streambuf iterators (currently located in stl/bits/std_iterator.h,<br />
|
|
||||||
but should be under bits/) can be rewritten to take advantage of<br />
|
|
||||||
friendship with the streambuf implementation.<br />
|
|
||||||
<br />
|
|
||||||
Matt Austern has identified opportunities where certain iterator<br />
|
|
||||||
types, particularly including streambuf iterators and deque<br />
|
|
||||||
iterators, have a "two-stage" quality, such that an intermediate<br />
|
|
||||||
limit can be checked much more quickly than the true limit on<br />
|
|
||||||
range operations. If identified with a member of iterator_traits,<br />
|
|
||||||
algorithms may be specialized for this case. Of course the<br />
|
|
||||||
iterators that have this quality can be identified by specializing<br />
|
|
||||||
a traits class.<br />
|
|
||||||
<br />
|
|
||||||
Many of the algorithms must be specialized for the streambuf<br />
|
|
||||||
iterators, to take advantage of block-mode operations, in order<br />
|
|
||||||
to allow iostream/locale operations' performance not to suffer.<br />
|
|
||||||
It may be that they could be treated as staged iterators and<br />
|
|
||||||
take advantage of those optimizations.<br />
|
|
||||||
<br />
|
|
||||||
Chapter 25 Algorithms<br />
|
|
||||||
----------------------<br />
|
|
||||||
Headers: <algorithm><br />
|
|
||||||
C headers: <cstdlib> (also in 18, 21, 26))<br />
|
|
||||||
<br />
|
|
||||||
The algorithms are "mostly complete". As mentioned above, they<br />
|
|
||||||
are optimized for speed at the expense of code and data size.<br />
|
|
||||||
<br />
|
|
||||||
Specializations of many of the algorithms for non-STL types would<br />
|
|
||||||
give performance improvements, but we must use great care not to<br />
|
|
||||||
interfere with fragile template overloading semantics for the<br />
|
|
||||||
standard interfaces. Conventionally the standard function template<br />
|
|
||||||
interface is an inline which delegates to a non-standard function<br />
|
|
||||||
which is then overloaded (this is already done in many places in<br />
|
|
||||||
the library). Particularly appealing opportunities for the sake of<br />
|
|
||||||
iostream performance are for copy and find applied to streambuf<br />
|
|
||||||
iterators or (as noted elsewhere) for staged iterators, of which<br />
|
|
||||||
the streambuf iterators are a good example.<br />
|
|
||||||
<br />
|
|
||||||
The bsearch and qsort functions cannot be overloaded properly as<br />
|
|
||||||
required by the standard because gcc does not yet allow overloading<br />
|
|
||||||
on the extern-"C"-ness of a function pointer.<br />
|
|
||||||
<br />
|
|
||||||
Chapter 26 Numerics<br />
|
|
||||||
--------------------<br />
|
|
||||||
Headers: <complex> <valarray> <numeric><br />
|
|
||||||
C headers: <cmath>, <cstdlib> (also 18, 21, 25)<br />
|
|
||||||
<br />
|
|
||||||
Numeric components: Gabriel dos Reis's valarray, Drepper's complex,<br />
|
|
||||||
and the few algorithms from the STL are "mostly done". Of course<br />
|
|
||||||
optimization opportunities abound for the numerically literate. It<br />
|
|
||||||
is not clear whether the valarray implementation really conforms<br />
|
|
||||||
fully, in the assumptions it makes about aliasing (and lack thereof)<br />
|
|
||||||
in its arguments.<br />
|
|
||||||
<br />
|
|
||||||
The C div() and ldiv() functions are interesting, because they are the<br />
|
|
||||||
only case where a C library function returns a class object by value.<br />
|
|
||||||
Since the C++ type div_t must be different from the underlying C type<br />
|
|
||||||
(which is in the wrong namespace) the underlying functions div() and<br />
|
|
||||||
ldiv() cannot be re-used efficiently. Fortunately they are trivial to<br />
|
|
||||||
re-implement.<br />
|
|
||||||
<br />
|
|
||||||
Chapter 27 Iostreams<br />
|
|
||||||
---------------------<br />
|
|
||||||
Headers: <iosfwd> <streambuf> <ios> <ostream> <istream> <iostream><br />
|
|
||||||
<iomanip> <sstream> <fstream><br />
|
|
||||||
C headers: <cstdio> <cwchar> (also in 21)<br />
|
|
||||||
<br />
|
|
||||||
Iostream is currently in a very incomplete state. <iosfwd>, <iomanip>,<br />
|
|
||||||
ios_base, and basic_ios<> are "mostly complete". basic_streambuf<> and<br />
|
|
||||||
basic_ostream<> are well along, but basic_istream<> has had little work<br />
|
|
||||||
done. The standard stream objects, <sstream> and <fstream> have been<br />
|
|
||||||
started; basic_filebuf<> "write" functions have been implemented just<br />
|
|
||||||
enough to do "hello, world".<br />
|
|
||||||
<br />
|
|
||||||
Most of the istream and ostream operators << and >> (with the exception<br />
|
|
||||||
of the op<<(integer) ones) have not been changed to use locale primitives,<br />
|
|
||||||
sentry objects, or char_traits members.<br />
|
|
||||||
<br />
|
|
||||||
All these templates should be manually instantiated for char and<br />
|
|
||||||
wchar_t in a way that links only used members into user programs.<br />
|
|
||||||
<br />
|
|
||||||
Streambuf is fertile ground for optimization extensions. An extended<br />
|
|
||||||
interface giving iterator access to its internal buffer would be very<br />
|
|
||||||
useful for other library components.<br />
|
|
||||||
<br />
|
|
||||||
Iostream operations (primarily operators << and >>) can take advantage<br />
|
|
||||||
of the case where user code has not specified a locale, and bypass locale<br />
|
|
||||||
operations entirely. The current implementation of op<</num_put<>::put,<br />
|
|
||||||
for the integer types, demonstrates how they can cache encoding details<br />
|
|
||||||
from the locale on each operation. There is lots more room for<br />
|
|
||||||
optimization in this area.<br />
|
|
||||||
<br />
|
|
||||||
The definition of the relationship between the standard streams<br />
|
|
||||||
cout et al. and stdout et al. requires something like a "stdiobuf".<br />
|
|
||||||
The SGI solution of using double-indirection to actually use a<br />
|
|
||||||
stdio FILE object for buffering is unsatisfactory, because it<br />
|
|
||||||
interferes with peephole loop optimizations.<br />
|
|
||||||
<br />
|
|
||||||
The <sstream> header work has begun. stringbuf can benefit from<br />
|
|
||||||
friendship with basic_string<> and basic_string<>::_Rep to use<br />
|
|
||||||
those objects directly as buffers, and avoid allocating and making<br />
|
|
||||||
copies.<br />
|
|
||||||
<br />
|
|
||||||
The basic_filebuf<> template is a complex beast. It is specified to<br />
|
|
||||||
use the locale facet codecvt<> to translate characters between native<br />
|
|
||||||
files and the locale character encoding. In general this involves<br />
|
|
||||||
two buffers, one of "char" representing the file and another of<br />
|
|
||||||
"char_type", for the stream, with codecvt<> translating. The process<br />
|
|
||||||
is complicated by the variable-length nature of the translation, and<br />
|
|
||||||
the need to seek to corresponding places in the two representations.<br />
|
|
||||||
For the case of basic_filebuf<char>, when no translation is needed,<br />
|
|
||||||
a single buffer suffices. A specialized filebuf can be used to reduce<br />
|
|
||||||
code space overhead when no locale has been imbued. Matt Austern's<br />
|
|
||||||
work at SGI will be useful, perhaps directly as a source of code, or<br />
|
|
||||||
at least as an example to draw on.<br />
|
|
||||||
<br />
|
|
||||||
Filebuf, almost uniquely (cf. operator new), depends heavily on<br />
|
|
||||||
underlying environmental facilities. In current releases iostream<br />
|
|
||||||
depends fairly heavily on libio constant definitions, but it should<br />
|
|
||||||
be made independent. It also depends on operating system primitives<br />
|
|
||||||
for file operations. There is immense room for optimizations using<br />
|
|
||||||
(e.g.) mmap for reading. The shadow/ directory wraps, besides the<br />
|
|
||||||
standard C headers, the libio.h and unistd.h headers, for use mainly<br />
|
|
||||||
by filebuf. These wrappings have not been completed, though there<br />
|
|
||||||
is scaffolding in place.<br />
|
|
||||||
<br />
|
|
||||||
The encapsulation of certain C header <cstdio> names presents an<br />
|
|
||||||
interesting problem. It is possible to define an inline std::fprintf()<br />
|
|
||||||
implemented in terms of the 'extern "C"' vfprintf(), but there is no<br />
|
|
||||||
standard vfscanf() to use to implement std::fscanf(). It appears that<br />
|
|
||||||
vfscanf but be re-implemented in C++ for targets where no vfscanf<br />
|
|
||||||
extension has been defined. This is interesting in that it seems<br />
|
|
||||||
to be the only significant case in the C library where this kind of<br />
|
|
||||||
rewriting is necessary. (Of course Glibc provides the vfscanf()<br />
|
|
||||||
extension.) (The functions related to exit() must be rewritten<br />
|
|
||||||
for other reasons.)<br />
|
|
||||||
<br />
|
|
||||||
<br />
|
|
||||||
Annex D<br />
|
|
||||||
-------<br />
|
|
||||||
Headers: <strstream><br />
|
|
||||||
<br />
|
|
||||||
Annex D defines many non-library features, and many minor<br />
|
|
||||||
modifications to various headers, and a complete header.<br />
|
|
||||||
It is "mostly done", except that the libstdc++-2 <strstream><br />
|
|
||||||
header has not been adopted into the library, or checked to<br />
|
|
||||||
verify that it matches the draft in those details that were<br />
|
|
||||||
clarified by the committee. Certainly it must at least be<br />
|
|
||||||
moved into the std namespace.<br />
|
|
||||||
<br />
|
|
||||||
We still need to wrap all the deprecated features in #if guards<br />
|
|
||||||
so that pedantic compile modes can detect their use.<br />
|
|
||||||
<br />
|
|
||||||
Nonstandard Extensions<br />
|
|
||||||
----------------------<br />
|
|
||||||
Headers: <iostream.h> <strstream.h> <hash> <rbtree><br />
|
|
||||||
<pthread_alloc> <stdiobuf> (etc.)<br />
|
|
||||||
<br />
|
|
||||||
User code has come to depend on a variety of nonstandard components<br />
|
|
||||||
that we must not omit. Much of this code can be adopted from<br />
|
|
||||||
libstdc++-v2 or from the SGI STL. This particularly includes<br />
|
|
||||||
<iostream.h>, <strstream.h>, and various SGI extensions such<br />
|
|
||||||
as <hash_map.h>. Many of these are already placed in the<br />
|
|
||||||
subdirectories ext/ and backward/. (Note that it is better to<br />
|
|
||||||
include them via "<backward/hash_map.h>" or "<ext/hash_map>" than<br />
|
|
||||||
to search the subdirectory itself via a "-I" directive.<br />
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01apas04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="appendix_porting.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Documentation Style </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Appendix B. Porting and Maintenance</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,41 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix D. GNU General Public License</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="appendix_free.html" title="Appendix C. Free Software Needs Free Documentation" /><link rel="next" href="bk01apds02.html" title="TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix D. GNU General Public License</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_free.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="bk01apds02.html">Next</a></td></tr></table><hr /></div><div class="appendix" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.gpl-2.0"></a>Appendix D. GNU General Public License</h2></div><div><p class="releaseinfo">Version 2, June 1991</p></div><div><p class="copyright">Copyright © 1989, 1991 Free Software Foundation, Inc.</p></div><div><div class="legalnotice"><a id="gpl-legalnotice"></a><p>
|
|
||||||
</p><div class="address"><p>Free Software Foundation, Inc. <br />
|
|
||||||
<span class="street">51 Franklin Street, Fifth Floor</span>, <br />
|
|
||||||
<span class="city">Boston</span>, <span class="state">MA</span> <span class="postcode">02110-1301</span><br />
|
|
||||||
<span class="country">USA</span><br />
|
|
||||||
</p></div><p>
|
|
||||||
</p><p>Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.</p></div></div><div><p class="pubdate">Version 2, June 1991</p></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="bk01apd.html#gpl-1">Preamble</a></span></dt><dt><span class="section"><a href="bk01apds02.html">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</a></span></dt><dd><dl><dt><span class="section"><a href="bk01apds02.html#gpl-2-0">Section 0</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-1">Section 1</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-2">Section 2</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-3">Section 3</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-4">Section 4</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-5">Section 5</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-6">Section 6</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-7">Section 7</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-8">Section 8</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-9">Section 9</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-10">Section 10</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-11">NO WARRANTY Section 11</a></span></dt><dt><span class="section"><a href="bk01apds02.html#gpl-2-12">Section 12</a></span></dt></dl></dd><dt><span class="section"><a href="bk01apds03.html">How to Apply These Terms to Your New Programs</a></span></dt></dl></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="gpl-1"></a>Preamble</h2></div></div></div><p>The licenses for most software are designed to take away your
|
|
||||||
freedom to share and change it. By contrast, the GNU General Public License is
|
|
||||||
intended to guarantee your freedom to share and change
|
|
||||||
free software - to make sure the software is free for all its users.
|
|
||||||
This General Public License applies to most of the Free Software
|
|
||||||
Foundation's software and to any other program whose authors commit
|
|
||||||
to using it. (Some other Free Software Foundation software is covered
|
|
||||||
by the GNU Library General Public License instead.) You can apply it
|
|
||||||
to your programs, too.</p><p>When we speak of free software, we are referring to freedom, not price.
|
|
||||||
Our General Public Licenses are designed to make sure that you have the
|
|
||||||
freedom to distribute copies of free software (and charge for this
|
|
||||||
service if you wish), that you receive source code or can get it if you
|
|
||||||
want it, that you can change the software or use pieces of it in new free
|
|
||||||
programs; and that you know you can do these things.</p><p>To protect your rights, we need to make restrictions that forbid anyone
|
|
||||||
to deny you these rights or to ask you to surrender the rights. These
|
|
||||||
restrictions translate to certain responsibilities for you if you distribute
|
|
||||||
copies of the software, or if you modify it.</p><p>For example, if you distribute copies of such a program, whether gratis or
|
|
||||||
for a fee, you must give the recipients all the rights that you have. You
|
|
||||||
must make sure that they, too, receive or can get the source code. And you
|
|
||||||
must show them these terms so they know their rights.</p><p>We protect your rights with two steps:
|
|
||||||
</p><div class="orderedlist"><ol type="1"><li><p>copyright the software, and</p></li><li><p>offer you this license which gives you legal permission to copy,
|
|
||||||
distribute and/or modify the software.</p></li></ol></div><p>
|
|
||||||
</p><p>Also, for each author's protection and ours, we want to make certain that
|
|
||||||
everyone understands that there is no warranty for this free software. If
|
|
||||||
the software is modified by someone else and passed on, we want its
|
|
||||||
recipients to know that what they have is not the original, so that any
|
|
||||||
problems introduced by others will not reflect on the original authors'
|
|
||||||
reputations.</p><p>Finally, any free program is threatened constantly by software patents.
|
|
||||||
We wish to avoid the danger that redistributors of a free program will
|
|
||||||
individually obtain patent licenses, in effect making the program
|
|
||||||
proprietary. To prevent this, we have made it clear that any patent must be
|
|
||||||
licensed for everyone's free use or not licensed at all.</p><p>The precise terms and conditions for copying, distribution and modification
|
|
||||||
follow.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendix_free.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spine.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01apds02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix C. Free Software Needs Free Documentation </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,129 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01apd.html" title="Appendix D. GNU General Public License" /><link rel="prev" href="bk01apd.html" title="Appendix D. GNU General Public License" /><link rel="next" href="bk01apds03.html" title="How to Apply These Terms to Your New Programs" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01apd.html">Prev</a> </td><th width="60%" align="center">Appendix D. GNU General Public License</th><td width="20%" align="right"> <a accesskey="n" href="bk01apds03.html">Next</a></td></tr></table><hr /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="gpl-2"></a>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</h2></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="gpl-2-0"></a>Section 0</h3></div></div></div><p>This License applies to any program or other work which contains a notice
|
|
||||||
placed by the copyright holder saying it may be distributed under the terms
|
|
||||||
of this General Public License. The “<span class="quote">Program</span>”, below, refers to any such
|
|
||||||
program or work, and a
|
|
||||||
“<span class="quote">work based on the Program</span>” means either
|
|
||||||
the Program or any derivative work under copyright law: that is to say, a
|
|
||||||
work containing the Program or a portion of it, either verbatim or with
|
|
||||||
modifications and/or translated into another language. (Hereinafter, translation
|
|
||||||
is included without limitation in the term
|
|
||||||
“<span class="quote">modification</span>”.) Each licensee is addressed as “<span class="quote">you</span>”.</p><p>Activities other than copying, distribution and modification are not covered by
|
|
||||||
this License; they are outside its scope. The act of running the Program is not
|
|
||||||
restricted, and the output from the Program is covered only if its contents
|
|
||||||
constitute a work based on the Program (independent of having been made by running
|
|
||||||
the Program). Whether that is true depends on what the Program does.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="gpl-2-1"></a>Section 1</h3></div></div></div><p>You may copy and distribute verbatim copies of the Program's source code as you
|
|
||||||
receive it, in any medium, provided that you conspicuously and appropriately
|
|
||||||
publish on each copy an appropriate copyright notice and disclaimer of warranty;
|
|
||||||
keep intact all the notices that refer to this License and to the absence of any
|
|
||||||
warranty; and give any other recipients of the Program a copy of this License
|
|
||||||
along with the Program.</p><p>You may charge a fee for the physical act of transferring a copy, and you may at
|
|
||||||
your option offer warranty protection in exchange for a fee.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="gpl-2-2"></a>Section 2</h3></div></div></div><p>You may modify your copy or copies of the Program or any portion of it, thus
|
|
||||||
forming a work based on the Program, and copy and distribute such modifications
|
|
||||||
or work under the terms of
|
|
||||||
<a class="link" href="bk01apds02.html#gpl-2-1" title="Section 1">Section 1</a> above, provided
|
|
||||||
that you also meet all of these conditions:
|
|
||||||
</p><div class="orderedlist"><ol type="a"><li><p>You must cause the modified files to carry prominent notices stating that
|
|
||||||
you changed the files and the date of any change.</p></li><li><p>You must cause any work that you distribute or publish, that in whole or
|
|
||||||
in part contains or is derived from the Program or any part thereof, to be
|
|
||||||
licensed as a whole at no charge to all third parties under the terms of
|
|
||||||
this License.</p></li><li><p>If the modified program normally reads commands interactively when run, you
|
|
||||||
must cause it, when started running for such interactive use in the most
|
|
||||||
ordinary way, to print or display an announcement including an appropriate
|
|
||||||
copyright notice and a notice that there is no warranty (or else, saying
|
|
||||||
that you provide a warranty) and that users may redistribute the program
|
|
||||||
under these conditions, and telling the user how to view a copy of this
|
|
||||||
License. (Exception: If the Program itself is interactive but does not
|
|
||||||
normally print such an announcement, your work based on the Program is not
|
|
||||||
required to print an announcement.)</p></li></ol></div><p>
|
|
||||||
</p><p>These requirements apply to the modified work as a whole. If identifiable sections
|
|
||||||
of that work are not derived from the Program, and can be reasonably considered
|
|
||||||
independent and separate works in themselves, then this License, and its terms,
|
|
||||||
do not apply to those sections when you distribute them as separate works. But when
|
|
||||||
you distribute the same sections as part of a whole which is a work based on the
|
|
||||||
Program, the distribution of the whole must be on the terms of this License, whose
|
|
||||||
permissions for other licensees extend to the entire whole, and thus to each and
|
|
||||||
every part regardless of who wrote it.</p><p>Thus, it is not the intent of this section to claim rights or contest your rights
|
|
||||||
to work written entirely by you; rather, the intent is to exercise the right to control
|
|
||||||
the distribution of derivative or collective works based on the Program.</p><p>In addition, mere aggregation of another work not based on the Program with the Program
|
|
||||||
(or with a work based on the Program) on a volume of a storage or distribution medium
|
|
||||||
does not bring the other work under the scope of this License.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="gpl-2-3"></a>Section 3</h3></div></div></div><p>You may copy and distribute the Program (or a work based on it, under
|
|
||||||
<a class="link" href="bk01apds02.html#gpl-2-2" title="Section 2">Section 2</a> in object code or executable form under the terms of
|
|
||||||
<a class="link" href="bk01apds02.html#gpl-2-1" title="Section 1">Sections 1</a> and
|
|
||||||
<a class="link" href="bk01apds02.html#gpl-2-2" title="Section 2">2</a> above provided that you also do one of the following:
|
|
||||||
</p><div class="orderedlist"><ol type="a"><li><p>Accompany it with the complete corresponding machine-readable source code, which
|
|
||||||
must be distributed under the terms of Sections 1 and 2 above on a medium
|
|
||||||
customarily used for software interchange; or,</p></li><li><p>Accompany it with a written offer, valid for at least three years, to give any
|
|
||||||
third party, for a charge no more than your cost of physically performing source
|
|
||||||
distribution, a complete machine-readable copy of the corresponding source code,
|
|
||||||
to be distributed under the terms of Sections 1 and 2 above on a medium customarily
|
|
||||||
used for software interchange; or,</p></li><li><p>Accompany it with the information you received as to the offer to distribute
|
|
||||||
corresponding source code. (This alternative is allowed only for noncommercial
|
|
||||||
distribution and only if you received the program in object code or executable form
|
|
||||||
with such an offer, in accord with Subsection b above.)</p></li></ol></div><p>
|
|
||||||
</p><p>The source code for a work means the preferred form of the work for making modifications
|
|
||||||
to it. For an executable work, complete source code means all the source code for all modules
|
|
||||||
it contains, plus any associated interface definition files, plus the scripts used to control
|
|
||||||
compilation and installation of the executable. However, as a special exception, the source
|
|
||||||
code distributed need not include anything that is normally distributed (in either source or
|
|
||||||
binary form) with the major components (compiler, kernel, and so on) of the operating system
|
|
||||||
on which the executable runs, unless that component itself accompanies the executable.</p><p>If distribution of executable or object code is made by offering access to copy from a
|
|
||||||
designated place, then offering equivalent access to copy the source code from the same place
|
|
||||||
counts as distribution of the source code, even though third parties are not compelled to
|
|
||||||
copy the source along with the object code.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="gpl-2-4"></a>Section 4</h3></div></div></div><p>You may not copy, modify, sublicense, or distribute the Program except as expressly provided
|
|
||||||
under this License. Any attempt otherwise to copy, modify, sublicense or distribute the
|
|
||||||
Program is void, and will automatically terminate your rights under this License. However,
|
|
||||||
parties who have received copies, or rights, from you under this License will not have their
|
|
||||||
licenses terminated so long as such parties remain in full compliance.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="gpl-2-5"></a>Section 5</h3></div></div></div><p>You are not required to accept this License, since you have not signed it. However, nothing
|
|
||||||
else grants you permission to modify or distribute the Program or its derivative works.
|
|
||||||
These actions are prohibited by law if you do not accept this License. Therefore, by modifying
|
|
||||||
or distributing the Program (or any work based on the Program), you indicate your acceptance
|
|
||||||
of this License to do so, and all its terms and conditions for copying, distributing or
|
|
||||||
modifying the Program or works based on it.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="gpl-2-6"></a>Section 6</h3></div></div></div><p>Each time you redistribute the Program (or any work based on the Program), the recipient
|
|
||||||
automatically receives a license from the original licensor to copy, distribute or modify
|
|
||||||
the Program subject to these terms and conditions. You may not impose any further restrictions
|
|
||||||
on the recipients' exercise of the rights granted herein. You are not responsible for enforcing
|
|
||||||
compliance by third parties to this License.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="gpl-2-7"></a>Section 7</h3></div></div></div><p>If, as a consequence of a court judgment or allegation of patent infringement or for any other
|
|
||||||
reason (not limited to patent issues), conditions are imposed on you (whether by court order,
|
|
||||||
agreement or otherwise) that contradict the conditions of this License, they do not excuse you
|
|
||||||
from the conditions of this License. If you cannot distribute so as to satisfy simultaneously
|
|
||||||
your obligations under this License and any other pertinent obligations, then as a consequence
|
|
||||||
you may not distribute the Program at all. For example, if a patent license would not permit
|
|
||||||
royalty-free redistribution of the Program by all those who receive copies directly or
|
|
||||||
indirectly through you, then the only way you could satisfy both it and this License would be
|
|
||||||
to refrain entirely from distribution of the Program.</p><p>If any portion of this section is held invalid or unenforceable under any particular circumstance,
|
|
||||||
the balance of the section is intended to apply and the section as a whole is intended to apply
|
|
||||||
in other circumstances.</p><p>It is not the purpose of this section to induce you to infringe any patents or other property
|
|
||||||
right claims or to contest validity of any such claims; this section has the sole purpose of
|
|
||||||
protecting the integrity of the free software distribution system, which is implemented by public
|
|
||||||
license practices. Many people have made generous contributions to the wide range of software
|
|
||||||
distributed through that system in reliance on consistent application of that system; it is up
|
|
||||||
to the author/donor to decide if he or she is willing to distribute software through any other
|
|
||||||
system and a licensee cannot impose that choice.</p><p>This section is intended to make thoroughly clear what is believed to be a consequence of the
|
|
||||||
rest of this License.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="gpl-2-8"></a>Section 8</h3></div></div></div><p>If the distribution and/or use of the Program is restricted in certain countries either by patents
|
|
||||||
or by copyrighted interfaces, the original copyright holder who places the Program under this License
|
|
||||||
may add an explicit geographical distribution limitation excluding those countries, so that
|
|
||||||
distribution is permitted only in or among countries not thus excluded. In such case, this License
|
|
||||||
incorporates the limitation as if written in the body of this License.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="gpl-2-9"></a>Section 9</h3></div></div></div><p>The Free Software Foundation may publish revised and/or new versions of the General Public License
|
|
||||||
from time to time. Such new versions will be similar in spirit to the present version, but may differ
|
|
||||||
in detail to address new problems or concerns.</p><p>Each version is given a distinguishing version number. If the Program specifies a version number of
|
|
||||||
this License which applies to it and “<span class="quote">any later version</span>”, you have the option of following the terms
|
|
||||||
and conditions either of that version or of any later version published by the Free Software
|
|
||||||
Foundation. If the Program does not specify a version number of this License, you may choose any
|
|
||||||
version ever published by the Free Software Foundation.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="gpl-2-10"></a>Section 10</h3></div></div></div><p>If you wish to incorporate parts of the Program into other free programs whose distribution
|
|
||||||
conditions are different, write to the author to ask for permission. For software which is copyrighted
|
|
||||||
by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions
|
|
||||||
for this. Our decision will be guided by the two goals of preserving the free status of all
|
|
||||||
derivatives of our free software and of promoting the sharing and reuse of software generally.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="gpl-2-11"></a>NO WARRANTY Section 11</h3></div></div></div><p>BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT
|
|
||||||
PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
|
|
||||||
OTHER PARTIES PROVIDE THE PROGRAM “<span class="quote">AS IS</span>” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
|
|
||||||
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
||||||
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
|
|
||||||
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="gpl-2-12"></a>Section 12</h3></div></div></div><p>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR
|
|
||||||
ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
|
|
||||||
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
|
|
||||||
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
|
|
||||||
INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH
|
|
||||||
ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
|
|
||||||
DAMAGES.</p><p>END OF TERMS AND CONDITIONS</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01apd.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01apd.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01apds03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix D. GNU General Public License </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> How to Apply These Terms to Your New Programs</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,32 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>How to Apply These Terms to Your New Programs</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01apd.html" title="Appendix D. GNU General Public License" /><link rel="prev" href="bk01apds02.html" title="TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION" /><link rel="next" href="bk01ape.html" title="Appendix E. GNU Free Documentation License" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">How to Apply These Terms to Your New Programs</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01apds02.html">Prev</a> </td><th width="60%" align="center">Appendix D. GNU General Public License</th><td width="20%" align="right"> <a accesskey="n" href="bk01ape.html">Next</a></td></tr></table><hr /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="gpl-3"></a>How to Apply These Terms to Your New Programs</h2></div></div></div><p>If you develop a new program, and you want it to be of the greatest
|
|
||||||
possible use to the public, the best way to achieve this is to make it
|
|
||||||
free software which everyone can redistribute and change under these terms.</p><p>To do so, attach the following notices to the program. It is safest
|
|
||||||
to attach them to the start of each source file to most effectively
|
|
||||||
convey the exclusion of warranty; and each file should have at least
|
|
||||||
the “<span class="quote">copyright</span>” line and a pointer to where the full notice is found.</p><p><one line to give the program's name and a brief idea of what it does.>
|
|
||||||
Copyright (C) <year> <name of author></p><p>This program is free software; you can redistribute it and/or modify
|
|
||||||
it under the terms of the GNU General Public License as published by
|
|
||||||
the Free Software Foundation; either version 2 of the License, or
|
|
||||||
(at your option) any later version.</p><p>This program is distributed in the hope that it will be useful,
|
|
||||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
||||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
||||||
GNU General Public License for more details.</p><p>You should have received a copy of the GNU General Public License
|
|
||||||
along with this program; if not, write to the Free Software
|
|
||||||
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA</p><p>Also add information on how to contact you by electronic and paper mail.</p><p>If the program is interactive, make it output a short notice like this
|
|
||||||
when it starts in an interactive mode:</p><p>Gnomovision version 69, Copyright (C) year name of author
|
|
||||||
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type “<span class="quote">show w</span>”.
|
|
||||||
This is free software, and you are welcome to redistribute it
|
|
||||||
under certain conditions; type “<span class="quote">show c</span>” for details.</p><p>The hypothetical commands “<span class="quote">show w</span>” and “<span class="quote">show c</span>” should
|
|
||||||
show the appropriate parts of the General Public License. Of course, the commands you
|
|
||||||
use may be called something other than “<span class="quote">show w</span>” and “<span class="quote">show c</span>”;
|
|
||||||
they could even be mouse-clicks or menu items--whatever suits your program.</p><p>You should also get your employer (if you work as a programmer) or your
|
|
||||||
school, if any, to sign a “<span class="quote">copyright disclaimer</span>” for the program, if
|
|
||||||
necessary. Here is a sample; alter the names:</p><p>Yoyodyne, Inc., hereby disclaims all copyright interest in the program
|
|
||||||
“<span class="quote">Gnomovision</span>” (which makes passes at compilers) written by James Hacker.</p><p><signature of Ty Coon>, 1 April 1989
|
|
||||||
Ty Coon, President of Vice</p><p>This General Public License does not permit incorporating your program into
|
|
||||||
proprietary programs. If your program is a subroutine library, you may
|
|
||||||
consider it more useful to permit linking proprietary applications with the
|
|
||||||
library. If this is what you want to do, use the GNU Library General
|
|
||||||
Public License instead of this License.</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01apds02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01apd.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01ape.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Appendix E. GNU Free Documentation License</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,393 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix E. GNU Free Documentation License</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="spine.html" title="The GNU C++ Library" /><link rel="prev" href="bk01apds03.html" title="How to Apply These Terms to Your New Programs" /><link rel="next" href="../bk02.html" title="" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix E. GNU Free Documentation License</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01apds03.html">Prev</a> </td><th width="60%" align="center">The GNU C++ Library</th><td width="20%" align="right"> <a accesskey="n" href="../bk02.html">Next</a></td></tr></table><hr /></div><div class="appendix" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.gfdl-1.2"></a>Appendix E. GNU Free Documentation License</h2></div></div></div><p>
|
|
||||||
Copyright (C) 2000, 2001, 2002 Free Software Foundation,
|
|
||||||
<abbr class="abbrev">Inc.</abbr> 51 Franklin <abbr class="abbrev">St</abbr>, Fifth Floor,
|
|
||||||
Boston, <abbr class="abbrev">MA</abbr> 02110-1301 <abbr class="abbrev">USA</abbr>. Everyone is permitted to copy and
|
|
||||||
distribute verbatim copies of this license document, but changing it is
|
|
||||||
not allowed.
|
|
||||||
</p><h2><a id="Preamble"></a>
|
|
||||||
0. PREAMBLE
|
|
||||||
</h2><p>
|
|
||||||
The purpose of this License is to make a manual, textbook, or other
|
|
||||||
functional and useful document "free" in the sense of freedom: to assure
|
|
||||||
everyone the effective freedom to copy and redistribute it, with or
|
|
||||||
without modifying it, either commercially or noncommercially.
|
|
||||||
Secondarily, this License preserves for the author and publisher a way to
|
|
||||||
get credit for their work, while not being considered responsible for
|
|
||||||
modifications made by others.
|
|
||||||
</p><p>
|
|
||||||
This License is a kind of "copyleft", which means that derivative works of
|
|
||||||
the document must themselves be free in the same sense. It complements
|
|
||||||
the GNU General Public License, which is a copyleft license designed for
|
|
||||||
free software.
|
|
||||||
</p><p>
|
|
||||||
We have designed this License in order to use it for manuals for free
|
|
||||||
software, because free software needs free documentation: a free program
|
|
||||||
should come with manuals providing the same freedoms that the software
|
|
||||||
does. But this License is not limited to software manuals; it can be used
|
|
||||||
for any textual work, regardless of subject matter or whether it is
|
|
||||||
published as a printed book. We recommend this License principally for
|
|
||||||
works whose purpose is instruction or reference.</p><h2><a id="Definitions"></a>
|
|
||||||
1. APPLICABILITY AND DEFINITIONS
|
|
||||||
</h2><p>
|
|
||||||
This License applies to any manual or other work, in any medium, that
|
|
||||||
contains a notice placed by the copyright holder saying it can be
|
|
||||||
distributed under the terms of this License. Such a notice grants a
|
|
||||||
world-wide, royalty-free license, unlimited in duration, to use that work
|
|
||||||
under the conditions stated herein. The "Document", below, refers to any
|
|
||||||
such manual or work. Any member of the public is a licensee, and is
|
|
||||||
addressed as "you". You accept the license if you copy, modify or
|
|
||||||
distribute the work in a way requiring permission under copyright
|
|
||||||
law.
|
|
||||||
</p><p>
|
|
||||||
A "Modified Version" of the Document means any work containing the
|
|
||||||
Document or a portion of it, either copied verbatim, or with modifications
|
|
||||||
and/or translated into another language.
|
|
||||||
</p><p>
|
|
||||||
A "Secondary Section" is a named appendix or a front-matter section of the
|
|
||||||
Document that deals exclusively with the relationship of the publishers or
|
|
||||||
authors of the Document to the Document's overall subject (or to related
|
|
||||||
matters) and contains nothing that could fall directly within that overall
|
|
||||||
subject. (Thus, if the Document is in part a textbook of mathematics, a
|
|
||||||
Secondary Section may not explain any mathematics.) The relationship
|
|
||||||
could be a matter of historical connection with the subject or with
|
|
||||||
related matters, or of legal, commercial, philosophical, ethical or
|
|
||||||
political position regarding them.
|
|
||||||
</p><p>
|
|
||||||
The "Invariant Sections" are certain Secondary Sections whose titles are
|
|
||||||
designated, as being those of Invariant Sections, in the notice that says
|
|
||||||
that the Document is released under this License. If a section does not
|
|
||||||
fit the above definition of Secondary then it is not allowed to be
|
|
||||||
designated as Invariant. The Document may contain zero Invariant
|
|
||||||
Sections. If the Document does not identify any Invariant Sections then
|
|
||||||
there are none.
|
|
||||||
</p><p>
|
|
||||||
The "Cover Texts" are certain short passages of text that are listed, as
|
|
||||||
Front-Cover Texts or Back-Cover Texts, in the notice that says that the
|
|
||||||
Document is released under this License. A Front-Cover Text may be at
|
|
||||||
most 5 words, and a Back-Cover Text may be at most 25 words.
|
|
||||||
</p><p>
|
|
||||||
A "Transparent" copy of the Document means a machine-readable copy,
|
|
||||||
represented in a format whose specification is available to the general
|
|
||||||
public, that is suitable for revising the document straightforwardly with
|
|
||||||
generic text editors or (for images composed of pixels) generic paint
|
|
||||||
programs or (for drawings) some widely available drawing editor, and that
|
|
||||||
is suitable for input to text formatters or for automatic translation to a
|
|
||||||
variety of formats suitable for input to text formatters. A copy made in
|
|
||||||
an otherwise Transparent file format whose markup, or absence of markup,
|
|
||||||
has been arranged to thwart or discourage subsequent modification by
|
|
||||||
readers is not Transparent. An image format is not Transparent if used
|
|
||||||
for any substantial amount of text. A copy that is not "Transparent" is
|
|
||||||
called "Opaque".
|
|
||||||
</p><p>
|
|
||||||
Examples of suitable formats for Transparent copies include plain ASCII
|
|
||||||
without markup, Texinfo input format, LaTeX input format, SGML or XML
|
|
||||||
using a publicly available DTD, and standard-conforming simple HTML,
|
|
||||||
PostScript or PDF designed for human modification. Examples of
|
|
||||||
transparent image formats include PNG, XCF and JPG. Opaque formats
|
|
||||||
include proprietary formats that can be read and edited only by
|
|
||||||
proprietary word processors, SGML or XML for which the DTD and/or
|
|
||||||
processing tools are not generally available, and the machine-generated
|
|
||||||
HTML, PostScript or PDF produced by some word processors for output
|
|
||||||
purposes only.
|
|
||||||
</p><p>
|
|
||||||
The "Title Page" means, for a printed book, the title page itself, plus
|
|
||||||
such following pages as are needed to hold, legibly, the material this
|
|
||||||
License requires to appear in the title page. For works in formats which
|
|
||||||
do not have any title page as such, "Title Page" means the text near the
|
|
||||||
most prominent appearance of the work's title, preceding the beginning of
|
|
||||||
the body of the text.
|
|
||||||
</p><p>
|
|
||||||
A section "Entitled XYZ" means a named subunit of the Document whose title
|
|
||||||
either is precisely XYZ or contains XYZ in parentheses following text that
|
|
||||||
translates XYZ in another language. (Here XYZ stands for a specific
|
|
||||||
section name mentioned below, such as "Acknowledgements", "Dedications",
|
|
||||||
"Endorsements", or "History".) To "Preserve the Title" of such a section
|
|
||||||
when you modify the Document means that it remains a section "Entitled
|
|
||||||
XYZ" according to this definition.
|
|
||||||
</p><p>
|
|
||||||
The Document may include Warranty Disclaimers next to the notice which
|
|
||||||
states that this License applies to the Document. These Warranty
|
|
||||||
Disclaimers are considered to be included by reference in this License,
|
|
||||||
but only as regards disclaiming warranties: any other implication that
|
|
||||||
these Warranty Disclaimers may have is void and has no effect on the
|
|
||||||
meaning of this License.
|
|
||||||
</p><h2><a id="VerbatimCopying"></a>
|
|
||||||
2. VERBATIM COPYING
|
|
||||||
</h2><p>
|
|
||||||
You may copy and distribute the Document in any medium, either
|
|
||||||
commercially or noncommercially, provided that this License, the copyright
|
|
||||||
notices, and the license notice saying this License applies to the
|
|
||||||
Document are reproduced in all copies, and that you add no other
|
|
||||||
conditions whatsoever to those of this License. You may not use technical
|
|
||||||
measures to obstruct or control the reading or further copying of the
|
|
||||||
copies you make or distribute. However, you may accept compensation in
|
|
||||||
exchange for copies. If you distribute a large enough number of copies
|
|
||||||
you must also follow the conditions in section 3.
|
|
||||||
</p><p>
|
|
||||||
You may also lend copies, under the same conditions stated above, and you
|
|
||||||
may publicly display copies.
|
|
||||||
</p><h2><a id="QuantityCopying"></a>
|
|
||||||
3. COPYING IN QUANTITY
|
|
||||||
</h2><p>
|
|
||||||
If you publish printed copies (or copies in media that commonly have
|
|
||||||
printed covers) of the Document, numbering more than 100, and the
|
|
||||||
Document's license notice requires Cover Texts, you must enclose the
|
|
||||||
copies in covers that carry, clearly and legibly, all these Cover Texts:
|
|
||||||
Front-Cover Texts on the front cover, and Back-Cover Texts on the back
|
|
||||||
cover. Both covers must also clearly and legibly identify you as the
|
|
||||||
publisher of these copies. The front cover must present the full title
|
|
||||||
with all words of the title equally prominent and visible. You may add
|
|
||||||
other material on the covers in addition. Copying with changes limited to
|
|
||||||
the covers, as long as they preserve the title of the Document and satisfy
|
|
||||||
these conditions, can be treated as verbatim copying in other
|
|
||||||
respects.
|
|
||||||
</p><p>
|
|
||||||
If the required texts for either cover are too voluminous to fit legibly,
|
|
||||||
you should put the first ones listed (as many as fit reasonably) on the
|
|
||||||
actual cover, and continue the rest onto adjacent pages.
|
|
||||||
</p><p>
|
|
||||||
If you publish or distribute Opaque copies of the Document numbering more
|
|
||||||
than 100, you must either include a machine-readable Transparent copy
|
|
||||||
along with each Opaque copy, or state in or with each Opaque copy a
|
|
||||||
computer-network location from which the general network-using public has
|
|
||||||
access to download using public-standard network protocols a complete
|
|
||||||
Transparent copy of the Document, free of added material. If you use the
|
|
||||||
latter option, you must take reasonably prudent steps, when you begin
|
|
||||||
distribution of Opaque copies in quantity, to ensure that this Transparent
|
|
||||||
copy will remain thus accessible at the stated location until at least one
|
|
||||||
year after the last time you distribute an Opaque copy (directly or
|
|
||||||
through your agents or retailers) of that edition to the public.
|
|
||||||
</p><p>
|
|
||||||
It is requested, but not required, that you contact the authors of the
|
|
||||||
Document well before redistributing any large number of copies, to give
|
|
||||||
them a chance to provide you with an updated version of the
|
|
||||||
Document.
|
|
||||||
</p><h2><a id="Modifications"></a>
|
|
||||||
4. MODIFICATIONS
|
|
||||||
</h2><p>
|
|
||||||
You may copy and distribute a Modified Version of the Document under the
|
|
||||||
conditions of sections 2 and 3 above, provided that you release the
|
|
||||||
Modified Version under precisely this License, with the Modified Version
|
|
||||||
filling the role of the Document, thus licensing distribution and
|
|
||||||
modification of the Modified Version to whoever possesses a copy of it.
|
|
||||||
In addition, you must do these things in the Modified Version:
|
|
||||||
</p><div class="orderedlist"><ol type="A"><li>
|
|
||||||
Use in the Title Page (and on the covers, if any) a title distinct
|
|
||||||
from that of the Document, and from those of previous versions (which
|
|
||||||
should, if there were any, be listed in the History section of the
|
|
||||||
Document). You may use the same title as a previous version if the
|
|
||||||
original publisher of that version gives permission.
|
|
||||||
</li><li>
|
|
||||||
List on the Title Page, as authors, one or more persons or entities
|
|
||||||
responsible for authorship of the modifications in the Modified
|
|
||||||
Version, together with at least five of the principal authors of the
|
|
||||||
Document (all of its principal authors, if it has fewer than five),
|
|
||||||
unless they release you from this requirement.
|
|
||||||
</li><li>
|
|
||||||
State on the Title page the name of the publisher of the Modified
|
|
||||||
Version, as the publisher.
|
|
||||||
</li><li>
|
|
||||||
Preserve all the copyright notices of the Document.
|
|
||||||
</li><li>
|
|
||||||
Add an appropriate copyright notice for your modifications adjacent to
|
|
||||||
the other copyright notices.
|
|
||||||
</li><li>
|
|
||||||
Include, immediately after the copyright notices, a license notice
|
|
||||||
giving the public permission to use the Modified Version under the
|
|
||||||
terms of this License, in the form shown in the Addendum below.
|
|
||||||
</li><li>
|
|
||||||
Preserve in that license notice the full lists of Invariant Sections
|
|
||||||
and required Cover Texts given in the Document's license notice.
|
|
||||||
</li><li>
|
|
||||||
Include an unaltered copy of this License.
|
|
||||||
</li><li>
|
|
||||||
Preserve the section Entitled "History", Preserve its Title, and add
|
|
||||||
to it an item stating at least the title, year, new authors, and
|
|
||||||
publisher of the Modified Version as given on the Title Page. If
|
|
||||||
there is no section Entitled "History" in the Document, create one
|
|
||||||
stating the title, year, authors, and publisher of the Document as
|
|
||||||
given on its Title Page, then add an item describing the Modified
|
|
||||||
Version as stated in the previous sentence.
|
|
||||||
</li><li>
|
|
||||||
Preserve the network location, if any, given in the Document for
|
|
||||||
public access to a Transparent copy of the Document, and likewise the
|
|
||||||
network locations given in the Document for previous versions it was
|
|
||||||
based on. These may be placed in the "History" section. You may omit
|
|
||||||
a network location for a work that was published at least four years
|
|
||||||
before the Document itself, or if the original publisher of the
|
|
||||||
version it refers to gives permission.
|
|
||||||
</li><li>
|
|
||||||
For any section Entitled "Acknowledgements" or "Dedications", Preserve
|
|
||||||
the Title of the section, and preserve in the section all the
|
|
||||||
substance and tone of each of the contributor acknowledgements and/or
|
|
||||||
dedications given therein.
|
|
||||||
</li><li>
|
|
||||||
Preserve all the Invariant Sections of the Document, unaltered in
|
|
||||||
their text and in their titles. Section numbers or the equivalent are
|
|
||||||
not considered part of the section titles.
|
|
||||||
</li><li>
|
|
||||||
Delete any section Entitled "Endorsements". Such a section may not be
|
|
||||||
included in the Modified Version.
|
|
||||||
</li><li>
|
|
||||||
Do not retitle any existing section to be Entitled "Endorsements" or
|
|
||||||
to conflict in title with any Invariant Section.
|
|
||||||
</li><li>
|
|
||||||
Preserve any Warranty Disclaimers.
|
|
||||||
</li></ol></div><p>
|
|
||||||
If the Modified Version includes new front-matter sections or appendices
|
|
||||||
that qualify as Secondary Sections and contain no material copied from the
|
|
||||||
Document, you may at your option designate some or all of these sections
|
|
||||||
as invariant. To do this, add their titles to the list of Invariant
|
|
||||||
Sections in the Modified Version's license notice. These titles must be
|
|
||||||
distinct from any other section titles.
|
|
||||||
</p><p>
|
|
||||||
You may add a section Entitled "Endorsements", provided it contains
|
|
||||||
nothing but endorsements of your Modified Version by various parties--for
|
|
||||||
example, statements of peer review or that the text has been approved by
|
|
||||||
an organization as the authoritative definition of a standard.
|
|
||||||
</p><p>
|
|
||||||
You may add a passage of up to five words as a Front-Cover Text, and a
|
|
||||||
passage of up to 25 words as a Back-Cover Text, to the end of the list of
|
|
||||||
Cover Texts in the Modified Version. Only one passage of Front-Cover Text
|
|
||||||
and one of Back-Cover Text may be added by (or through arrangements made
|
|
||||||
by) any one entity. If the Document already includes a cover text for the
|
|
||||||
same cover, previously added by you or by arrangement made by the same
|
|
||||||
entity you are acting on behalf of, you may not add another; but you may
|
|
||||||
replace the old one, on explicit permission from the previous publisher
|
|
||||||
that added the old one.
|
|
||||||
</p><p>
|
|
||||||
The author(s) and publisher(s) of the Document do not by this License give
|
|
||||||
permission to use their names for publicity for or to assert or imply
|
|
||||||
endorsement of any Modified Version.
|
|
||||||
</p><h2><a id="Combining"></a>
|
|
||||||
5. COMBINING DOCUMENTS
|
|
||||||
</h2><p>
|
|
||||||
You may combine the Document with other documents released under this
|
|
||||||
License, under the terms defined in section 4 above for modified versions,
|
|
||||||
provided that you include in the combination all of the Invariant Sections
|
|
||||||
of all of the original documents, unmodified, and list them all as
|
|
||||||
Invariant Sections of your combined work in its license notice, and that
|
|
||||||
you preserve all their Warranty Disclaimers.
|
|
||||||
</p><p>
|
|
||||||
The combined work need only contain one copy of this License, and multiple
|
|
||||||
identical Invariant Sections may be replaced with a single copy. If there
|
|
||||||
are multiple Invariant Sections with the same name but different contents,
|
|
||||||
make the title of each such section unique by adding at the end of it, in
|
|
||||||
parentheses, the name of the original author or publisher of that section
|
|
||||||
if known, or else a unique number. Make the same adjustment to the
|
|
||||||
section titles in the list of Invariant Sections in the license notice of
|
|
||||||
the combined work.
|
|
||||||
</p><p>
|
|
||||||
In the combination, you must combine any sections Entitled "History" in
|
|
||||||
the various original documents, forming one section Entitled "History";
|
|
||||||
likewise combine any sections Entitled "Acknowledgements", and any
|
|
||||||
sections Entitled "Dedications". You must delete all sections Entitled
|
|
||||||
"Endorsements".
|
|
||||||
</p><h2><a id="Collections"></a>
|
|
||||||
6. COLLECTIONS OF DOCUMENTS
|
|
||||||
</h2><p>
|
|
||||||
You may make a collection consisting of the Document and other documents
|
|
||||||
released under this License, and replace the individual copies of this
|
|
||||||
License in the various documents with a single copy that is included in
|
|
||||||
the collection, provided that you follow the rules of this License for
|
|
||||||
verbatim copying of each of the documents in all other respects.
|
|
||||||
</p><p>
|
|
||||||
You may extract a single document from such a collection, and distribute
|
|
||||||
it individually under this License, provided you insert a copy of this
|
|
||||||
License into the extracted document, and follow this License in all other
|
|
||||||
respects regarding verbatim copying of that document.
|
|
||||||
</p><h2><a id="Aggregation"></a>
|
|
||||||
7. AGGREGATION WITH INDEPENDENT WORKS
|
|
||||||
</h2><p>
|
|
||||||
A compilation of the Document or its derivatives with other separate and
|
|
||||||
independent documents or works, in or on a volume of a storage or
|
|
||||||
distribution medium, is called an "aggregate" if the copyright resulting
|
|
||||||
from the compilation is not used to limit the legal rights of the
|
|
||||||
compilation's users beyond what the individual works permit. When the
|
|
||||||
Document is included in an aggregate, this License does not apply to the
|
|
||||||
other works in the aggregate which are not themselves derivative works of
|
|
||||||
the Document.
|
|
||||||
</p><p>
|
|
||||||
If the Cover Text requirement of section 3 is applicable to these copies
|
|
||||||
of the Document, then if the Document is less than one half of the entire
|
|
||||||
aggregate, the Document's Cover Texts may be placed on covers that bracket
|
|
||||||
the Document within the aggregate, or the electronic equivalent of covers
|
|
||||||
if the Document is in electronic form. Otherwise they must appear on
|
|
||||||
printed covers that bracket the whole aggregate.
|
|
||||||
</p><h2><a id="Translation"></a>
|
|
||||||
8. TRANSLATION
|
|
||||||
</h2><p>
|
|
||||||
Translation is considered a kind of modification, so you may distribute
|
|
||||||
translations of the Document under the terms of section 4. Replacing
|
|
||||||
Invariant Sections with translations requires special permission from
|
|
||||||
their copyright holders, but you may include translations of some or all
|
|
||||||
Invariant Sections in addition to the original versions of these Invariant
|
|
||||||
Sections. You may include a translation of this License, and all the
|
|
||||||
license notices in the Document, and any Warranty Disclaimers, provided
|
|
||||||
that you also include the original English version of this License and the
|
|
||||||
original versions of those notices and disclaimers. In case of a
|
|
||||||
disagreement between the translation and the original version of this
|
|
||||||
License or a notice or disclaimer, the original version will prevail.
|
|
||||||
</p><p>
|
|
||||||
If a section in the Document is Entitled "Acknowledgements",
|
|
||||||
"Dedications", or "History", the requirement (section 4) to Preserve its
|
|
||||||
Title (section 1) will typically require changing the actual title.
|
|
||||||
</p><h2><a id="Termination"></a>
|
|
||||||
9. TERMINATION
|
|
||||||
</h2><p>
|
|
||||||
You may not copy, modify, sublicense, or distribute the Document except as
|
|
||||||
expressly provided for under this License. Any other attempt to copy,
|
|
||||||
modify, sublicense or distribute the Document is void, and will
|
|
||||||
automatically terminate your rights under this License. However, parties
|
|
||||||
who have received copies, or rights, from you under this License will not
|
|
||||||
have their licenses terminated so long as such parties remain in full
|
|
||||||
compliance.
|
|
||||||
</p><h2><a id="FutureRevisions"></a>
|
|
||||||
10. FUTURE REVISIONS OF THIS LICENSE
|
|
||||||
</h2><p>
|
|
||||||
The Free Software Foundation may publish new, revised versions of the GNU
|
|
||||||
Free Documentation License from time to time. Such new versions will be
|
|
||||||
similar in spirit to the present version, but may differ in detail to
|
|
||||||
address new problems or concerns. See <a class="ulink" href="http://www.gnu.org/copyleft/" target="_top">http://www.gnu.org/copyleft/</a>.
|
|
||||||
</p><p>
|
|
||||||
Each version of the License is given a distinguishing version number. If
|
|
||||||
the Document specifies that a particular numbered version of this License
|
|
||||||
"or any later version" applies to it, you have the option of following the
|
|
||||||
terms and conditions either of that specified version or of any later
|
|
||||||
version that has been published (not as a draft) by the Free Software
|
|
||||||
Foundation. If the Document does not specify a version number of this
|
|
||||||
License, you may choose any version ever published (not as a draft) by the
|
|
||||||
Free Software Foundation.
|
|
||||||
</p><h2><a id="HowToUse"></a>
|
|
||||||
ADDENDUM: How to use this License for your documents
|
|
||||||
</h2><p>
|
|
||||||
To use this License in a document you have written, include a copy of the
|
|
||||||
License in the document and put the following copyright and license
|
|
||||||
notices just after the title page:
|
|
||||||
</p><div class="blockquote"><blockquote class="blockquote"><p>
|
|
||||||
Copyright (C) YEAR YOUR NAME.
|
|
||||||
</p><p>
|
|
||||||
Permission is granted to copy, distribute and/or modify this document
|
|
||||||
under the terms of the GNU Free Documentation License, Version 1.2 or
|
|
||||||
any later version published by the Free Software Foundation; with no
|
|
||||||
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
|
||||||
copy of the license is included in the section entitled "GNU Free
|
|
||||||
Documentation License".
|
|
||||||
</p></blockquote></div><p>
|
|
||||||
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
|
|
||||||
replace the "with...Texts." line with this:
|
|
||||||
</p><div class="blockquote"><blockquote class="blockquote"><p>
|
|
||||||
with the Invariant Sections being LIST THEIR TITLES, with the
|
|
||||||
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
|
|
||||||
</p></blockquote></div><p>
|
|
||||||
If you have Invariant Sections without Cover Texts, or some other
|
|
||||||
combination of the three, merge those two alternatives to suit the
|
|
||||||
situation.
|
|
||||||
</p><p>
|
|
||||||
If your document contains nontrivial examples of program code, we
|
|
||||||
recommend releasing these examples in parallel under your choice of free
|
|
||||||
software license, such as the GNU General Public License, to permit their
|
|
||||||
use in free software.
|
|
||||||
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01apds03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spine.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="../bk02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">How to Apply These Terms to Your New Programs </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>
|
|
||||||
File diff suppressed because one or more lines are too long
|
|
@ -1,40 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>License</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt01ch01.html" title="Chapter 1. Status" /><link rel="prev" href="bk01pt01ch01.html" title="Chapter 1. Status" /><link rel="next" href="bk01pt01ch01s03.html" title="Bugs" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">License</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt01ch01.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Status</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt01ch01s03.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.status.license"></a>License</h2></div></div></div><p>
|
|
||||||
There are two licenses affecting GNU libstdc++: one for the code,
|
|
||||||
and one for the documentation.
|
|
||||||
</p><p>
|
|
||||||
There is a license section in the FAQ regarding common <a class="link" href="../faq.html#faq.license" title="License">questions</a>. If you have more
|
|
||||||
questions, ask the FSF or the <a class="ulink" href="http://gcc.gnu.org/lists.html" target="_top">gcc mailing list</a>.
|
|
||||||
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.status.license.gpl"></a>The Code: GPL</h3></div></div></div><p>
|
|
||||||
The source code is distributed under the <a class="link" href="bk01apd.html" title="Appendix D. GNU General Public License">GNU General Public License version 2</a>,
|
|
||||||
with the so-called “<span class="quote">Runtime Exception</span>”
|
|
||||||
as follows (or see any header or implementation file):
|
|
||||||
</p><div class="literallayout"><p><br />
|
|
||||||
As a special exception, you may use this file as part of a free software<br />
|
|
||||||
library without restriction. Specifically, if other files instantiate<br />
|
|
||||||
templates or use macros or inline functions from this file, or you compile<br />
|
|
||||||
this file and link it with other files to produce an executable, this<br />
|
|
||||||
file does not by itself cause the resulting executable to be covered by<br />
|
|
||||||
the GNU General Public License. This exception does not however<br />
|
|
||||||
invalidate any other reasons why the executable file might be covered by<br />
|
|
||||||
the GNU General Public License.<br />
|
|
||||||
</p></div><p>
|
|
||||||
Hopefully that text is self-explanatory. If it isn't, you need to speak
|
|
||||||
to your lawyer, or the Free Software Foundation.
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.status.license.fdl"></a>The Documentation: GPL, FDL</h3></div></div></div><p>
|
|
||||||
The documentation shipped with the library and made available over
|
|
||||||
the web, excluding the pages generated from source comments, are
|
|
||||||
copyrighted by the Free Software Foundation, and placed under the
|
|
||||||
<a class="link" href="bk01ape.html" title="Appendix E. GNU Free Documentation License"> GNU Free Documentation
|
|
||||||
License version 1.2</a>. There are no Front-Cover Texts, no
|
|
||||||
Back-Cover Texts, and no Invariant Sections.
|
|
||||||
</p><p>
|
|
||||||
For documentation generated by doxygen or other automated tools
|
|
||||||
via processing source code comments and markup, the original source
|
|
||||||
code license applies to the generated files. Thus, the doxygen
|
|
||||||
documents are licensed <a class="link" href="bk01apd.html" title="Appendix D. GNU General Public License">GPL</a>.
|
|
||||||
</p><p>
|
|
||||||
If you plan on making copies of the documentation, please let us know.
|
|
||||||
We can probably offer suggestions.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch01.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt01ch01.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt01ch01s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Status </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Bugs</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,330 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Bugs</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt01ch01.html" title="Chapter 1. Status" /><link rel="prev" href="bk01pt01ch01s02.html" title="License" /><link rel="next" href="bk01pt01ch02.html" title="Chapter 2. Setup" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Bugs</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt01ch01s02.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Status</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt01ch02.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.status.bugs"></a>Bugs</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.status.bugs.impl"></a>Implementation Bugs</h3></div></div></div><p>
|
|
||||||
Information on known bugs, details on efforts to fix them, and
|
|
||||||
fixed bugs are all available as part of the GCC bug tracking
|
|
||||||
system, <a class="ulink" href="http://gcc.gnu.org/bugzilla" target="_top">bugzilla</a>, with the
|
|
||||||
category set to <code class="literal">libstdc++</code>.
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.status.bugs.iso"></a>Standard Bugs</h3></div></div></div><p>
|
|
||||||
Everybody's got issues. Even the C++ Standard Library.
|
|
||||||
</p><p>
|
|
||||||
The Library Working Group, or LWG, is the ISO subcommittee responsible
|
|
||||||
for making changes to the library. They periodically publish an
|
|
||||||
Issues List containing problems and possible solutions. As they reach
|
|
||||||
a consensus on proposed solutions, we often incorporate the solution.
|
|
||||||
</p><p>
|
|
||||||
Here are the issues which have resulted in code changes to the library.
|
|
||||||
The links are to the specific defect reports from a <span class="emphasis"><em>partial
|
|
||||||
copy</em></span> of the Issues List. You can read the full version online
|
|
||||||
at the <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/" target="_top">ISO C++
|
|
||||||
Committee homepage</a>, linked to on the
|
|
||||||
<a class="ulink" href="http://gcc.gnu.org/readings.html" target="_top">GCC "Readings"
|
|
||||||
page</a>. If
|
|
||||||
you spend a lot of time reading the issues, we recommend downloading
|
|
||||||
the ZIP file and reading them locally.
|
|
||||||
</p><p>
|
|
||||||
(NB: <span class="emphasis"><em>partial copy</em></span> means that not all
|
|
||||||
links within the lwg-*.html pages will work. Specifically,
|
|
||||||
links to defect reports that have not been accorded full DR
|
|
||||||
status will probably break. Rather than trying to mirror the
|
|
||||||
entire issues list on our overworked web server, we recommend
|
|
||||||
you go to the LWG homepage instead.)
|
|
||||||
</p><p>
|
|
||||||
If a DR is not listed here, we may simply not have gotten to
|
|
||||||
it yet; feel free to submit a patch. Search the include/bits
|
|
||||||
and src directories for appearances of
|
|
||||||
<code class="constant">_GLIBCXX_RESOLVE_LIB_DEFECTS</code> for examples
|
|
||||||
of style. Note that we usually do not make changes to the
|
|
||||||
code until an issue has reached <a class="ulink" href="lwg-active.html#DR" target="_top">DR</a> status.
|
|
||||||
</p><div class="variablelist"><dl><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#5" target="_top">5</a>:
|
|
||||||
<span class="emphasis"><em>string::compare specification questionable</em></span>
|
|
||||||
</span></dt><dd><p>This should be two overloaded functions rather than a single function.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#17" target="_top">17</a>:
|
|
||||||
<span class="emphasis"><em>Bad bool parsing</em></span>
|
|
||||||
</span></dt><dd><p>Apparently extracting Boolean values was messed up...
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#19" target="_top">19</a>:
|
|
||||||
<span class="emphasis"><em>"Noconv" definition too vague</em></span>
|
|
||||||
</span></dt><dd><p>If <code class="code">codecvt::do_in</code> returns <code class="code">noconv</code> there are
|
|
||||||
no changes to the values in <code class="code">[to, to_limit)</code>.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#22" target="_top">22</a>:
|
|
||||||
<span class="emphasis"><em>Member open vs flags</em></span>
|
|
||||||
</span></dt><dd><p>Re-opening a file stream does <span class="emphasis"><em>not</em></span> clear the state flags.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-active.html#23" target="_top">23</a>:
|
|
||||||
<span class="emphasis"><em>Num_get overflow result</em></span>
|
|
||||||
</span></dt><dd><p>Implement the proposed resolution.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#25" target="_top">25</a>:
|
|
||||||
<span class="emphasis"><em>String operator<< uses width() value wrong</em></span>
|
|
||||||
</span></dt><dd><p>Padding issues.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#48" target="_top">48</a>:
|
|
||||||
<span class="emphasis"><em>Use of non-existent exception constructor</em></span>
|
|
||||||
</span></dt><dd><p>An instance of <code class="code">ios_base::failure</code> is constructed instead.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#49" target="_top">49</a>:
|
|
||||||
<span class="emphasis"><em>Underspecification of ios_base::sync_with_stdio</em></span>
|
|
||||||
</span></dt><dd><p>The return type is the <span class="emphasis"><em>previous</em></span> state of synchronization.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#50" target="_top">50</a>:
|
|
||||||
<span class="emphasis"><em>Copy constructor and assignment operator of ios_base</em></span>
|
|
||||||
</span></dt><dd><p>These members functions are declared <code class="code">private</code> and are
|
|
||||||
thus inaccessible. Specifying the correct semantics of
|
|
||||||
"copying stream state" was deemed too complicated.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#60" target="_top">60</a>:
|
|
||||||
<span class="emphasis"><em>What is a formatted input function?</em></span>
|
|
||||||
</span></dt><dd><p>This DR made many widespread changes to <code class="code">basic_istream</code>
|
|
||||||
and <code class="code">basic_ostream</code> all of which have been implemented.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#63" target="_top">63</a>:
|
|
||||||
<span class="emphasis"><em>Exception-handling policy for unformatted output</em></span>
|
|
||||||
</span></dt><dd><p>Make the policy consistent with that of formatted input, unformatted
|
|
||||||
input, and formatted output.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#68" target="_top">68</a>:
|
|
||||||
<span class="emphasis"><em>Extractors for char* should store null at end</em></span>
|
|
||||||
</span></dt><dd><p>And they do now. An editing glitch in the last item in the list of
|
|
||||||
[27.6.1.2.3]/7.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#74" target="_top">74</a>:
|
|
||||||
<span class="emphasis"><em>Garbled text for codecvt::do_max_length</em></span>
|
|
||||||
</span></dt><dd><p>The text of the standard was gibberish. Typos gone rampant.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#75" target="_top">75</a>:
|
|
||||||
<span class="emphasis"><em>Contradiction in codecvt::length's argument types</em></span>
|
|
||||||
</span></dt><dd><p>Change the first parameter to <code class="code">stateT&</code> and implement
|
|
||||||
the new effects paragraph.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="lwg-defects.html#83" target="_top">83</a>:
|
|
||||||
<span class="emphasis"><em>string::npos vs. string::max_size()</em></span>
|
|
||||||
</span></dt><dd><p>Safety checks on the size of the string should test against
|
|
||||||
<code class="code">max_size()</code> rather than <code class="code">npos</code>.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#90" target="_top">90</a>:
|
|
||||||
<span class="emphasis"><em>Incorrect description of operator>> for strings</em></span>
|
|
||||||
</span></dt><dd><p>The effect contain <code class="code">isspace(c,getloc())</code> which must be
|
|
||||||
replaced by <code class="code">isspace(c,is.getloc())</code>.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#91" target="_top">91</a>:
|
|
||||||
<span class="emphasis"><em>Description of operator>> and getline() for string<>
|
|
||||||
might cause endless loop</em></span>
|
|
||||||
</span></dt><dd><p>They behave as a formatted input function and as an unformatted
|
|
||||||
input function, respectively (except that <code class="code">getline</code> is
|
|
||||||
not required to set <code class="code">gcount</code>).
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#103" target="_top">103</a>:
|
|
||||||
<span class="emphasis"><em>set::iterator is required to be modifiable, but this allows
|
|
||||||
modification of keys.</em></span>
|
|
||||||
</span></dt><dd><p>For associative containers where the value type is the same as
|
|
||||||
the key type, both <code class="code">iterator</code> and <code class="code">const_iterator
|
|
||||||
</code> are constant iterators.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#109" target="_top">109</a>:
|
|
||||||
<span class="emphasis"><em>Missing binders for non-const sequence elements</em></span>
|
|
||||||
</span></dt><dd><p>The <code class="code">binder1st</code> and <code class="code">binder2nd</code> didn't have an
|
|
||||||
<code class="code">operator()</code> taking a non-const parameter.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#110" target="_top">110</a>:
|
|
||||||
<span class="emphasis"><em>istreambuf_iterator::equal not const</em></span>
|
|
||||||
</span></dt><dd><p>This was not a const member function. Note that the DR says to
|
|
||||||
replace the function with a const one; we have instead provided an
|
|
||||||
overloaded version with identical contents.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#117" target="_top">117</a>:
|
|
||||||
<span class="emphasis"><em>basic_ostream uses nonexistent num_put member functions</em></span>
|
|
||||||
</span></dt><dd><p><code class="code">num_put::put()</code> was overloaded on the wrong types.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#118" target="_top">118</a>:
|
|
||||||
<span class="emphasis"><em>basic_istream uses nonexistent num_get member functions</em></span>
|
|
||||||
</span></dt><dd><p>Same as 117, but for <code class="code">num_get::get()</code>.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#129" target="_top">129</a>:
|
|
||||||
<span class="emphasis"><em>Need error indication from seekp() and seekg()</em></span>
|
|
||||||
</span></dt><dd><p>These functions set <code class="code">failbit</code> on error now.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#136" target="_top">136</a>:
|
|
||||||
<span class="emphasis"><em>seekp, seekg setting wrong streams?</em></span>
|
|
||||||
</span></dt><dd><p><code class="code">seekp</code> should only set the output stream, and
|
|
||||||
<code class="code">seekg</code> should only set the input stream.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#167" target="_top">167</a>:
|
|
||||||
<span class="emphasis"><em>Improper use of traits_type::length()</em></span>
|
|
||||||
</span></dt><dd><p><code class="code">op<<</code> with a <code class="code">const char*</code> was
|
|
||||||
calculating an incorrect number of characters to write.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#169" target="_top">169</a>:
|
|
||||||
<span class="emphasis"><em>Bad efficiency of overflow() mandated</em></span>
|
|
||||||
</span></dt><dd><p>Grow efficiently the internal array object.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#171" target="_top">171</a>:
|
|
||||||
<span class="emphasis"><em>Strange seekpos() semantics due to joint position</em></span>
|
|
||||||
</span></dt><dd><p>Quite complex to summarize...
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#181" target="_top">181</a>:
|
|
||||||
<span class="emphasis"><em>make_pair() unintended behavior</em></span>
|
|
||||||
</span></dt><dd><p>This function used to take its arguments as reference-to-const, now
|
|
||||||
it copies them (pass by value).
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#195" target="_top">195</a>:
|
|
||||||
<span class="emphasis"><em>Should basic_istream::sentry's constructor ever set eofbit?</em></span>
|
|
||||||
</span></dt><dd><p>Yes, it can, specifically if EOF is reached while skipping whitespace.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#211" target="_top">211</a>:
|
|
||||||
<span class="emphasis"><em>operator>>(istream&, string&) doesn't set failbit</em></span>
|
|
||||||
</span></dt><dd><p>If nothing is extracted into the string, <code class="code">op>></code> now
|
|
||||||
sets <code class="code">failbit</code> (which can cause an exception, etc., etc.).
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#214" target="_top">214</a>:
|
|
||||||
<span class="emphasis"><em>set::find() missing const overload</em></span>
|
|
||||||
</span></dt><dd><p>Both <code class="code">set</code> and <code class="code">multiset</code> were missing
|
|
||||||
overloaded find, lower_bound, upper_bound, and equal_range functions
|
|
||||||
for const instances.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#231" target="_top">231</a>:
|
|
||||||
<span class="emphasis"><em>Precision in iostream?</em></span>
|
|
||||||
</span></dt><dd><p>For conversion from a floating-point type, <code class="code">str.precision()</code>
|
|
||||||
is specified in the conversion specification.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-active.html#233" target="_top">233</a>:
|
|
||||||
<span class="emphasis"><em>Insertion hints in associative containers</em></span>
|
|
||||||
</span></dt><dd><p>Implement N1780, first check before then check after, insert as close
|
|
||||||
to hint as possible.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#235" target="_top">235</a>:
|
|
||||||
<span class="emphasis"><em>No specification of default ctor for reverse_iterator</em></span>
|
|
||||||
</span></dt><dd><p>The declaration of <code class="code">reverse_iterator</code> lists a default constructor.
|
|
||||||
However, no specification is given what this constructor should do.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#241" target="_top">241</a>:
|
|
||||||
<span class="emphasis"><em>Does unique_copy() require CopyConstructible and Assignable?</em></span>
|
|
||||||
</span></dt><dd><p>Add a helper for forward_iterator/output_iterator, fix the existing
|
|
||||||
one for input_iterator/output_iterator to not rely on Assignability.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#243" target="_top">243</a>:
|
|
||||||
<span class="emphasis"><em>get and getline when sentry reports failure</em></span>
|
|
||||||
</span></dt><dd><p>Store a null character only if the character array has a non-zero size.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#251" target="_top">251</a>:
|
|
||||||
<span class="emphasis"><em>basic_stringbuf missing allocator_type</em></span>
|
|
||||||
</span></dt><dd><p>This nested typedef was originally not specified.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#253" target="_top">253</a>:
|
|
||||||
<span class="emphasis"><em>valarray helper functions are almost entirely useless</em></span>
|
|
||||||
</span></dt><dd><p>Make the copy constructor and copy-assignment operator declarations
|
|
||||||
public in gslice_array, indirect_array, mask_array, slice_array; provide
|
|
||||||
definitions.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#265" target="_top">265</a>:
|
|
||||||
<span class="emphasis"><em>std::pair::pair() effects overly restrictive</em></span>
|
|
||||||
</span></dt><dd><p>The default ctor would build its members from copies of temporaries;
|
|
||||||
now it simply uses their respective default ctors.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#266" target="_top">266</a>:
|
|
||||||
<span class="emphasis"><em>bad_exception::~bad_exception() missing Effects clause</em></span>
|
|
||||||
</span></dt><dd><p>The <code class="code">bad_</code>* classes no longer have destructors (they
|
|
||||||
are trivial), since no description of them was ever given.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#271" target="_top">271</a>:
|
|
||||||
<span class="emphasis"><em>basic_iostream missing typedefs</em></span>
|
|
||||||
</span></dt><dd><p>The typedefs it inherits from its base classes can't be used, since
|
|
||||||
(for example) <code class="code">basic_iostream<T>::traits_type</code> is ambiguous.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#275" target="_top">275</a>:
|
|
||||||
<span class="emphasis"><em>Wrong type in num_get::get() overloads</em></span>
|
|
||||||
</span></dt><dd><p>Similar to 118.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#280" target="_top">280</a>:
|
|
||||||
<span class="emphasis"><em>Comparison of reverse_iterator to const reverse_iterator</em></span>
|
|
||||||
</span></dt><dd><p>Add global functions with two template parameters.
|
|
||||||
(NB: not added for now a templated assignment operator)
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#292" target="_top">292</a>:
|
|
||||||
<span class="emphasis"><em>Effects of a.copyfmt (a)</em></span>
|
|
||||||
</span></dt><dd><p>If <code class="code">(this == &rhs)</code> do nothing.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#300" target="_top">300</a>:
|
|
||||||
<span class="emphasis"><em>List::merge() specification incomplete</em></span>
|
|
||||||
</span></dt><dd><p>If <code class="code">(this == &x)</code> do nothing.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#303" target="_top">303</a>:
|
|
||||||
<span class="emphasis"><em>Bitset input operator underspecified</em></span>
|
|
||||||
</span></dt><dd><p>Basically, compare the input character to
|
|
||||||
<code class="code">is.widen(0)</code> and <code class="code">is.widen(1)</code>.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#305" target="_top">305</a>:
|
|
||||||
<span class="emphasis"><em>Default behavior of codecvt<wchar_t, char,
|
|
||||||
mbstate_t>::length()</em></span>
|
|
||||||
</span></dt><dd><p>Do not specify what <code class="code">codecvt<wchar_t, char,
|
|
||||||
mbstate_t>::do_length</code> must return.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#328" target="_top">328</a>:
|
|
||||||
<span class="emphasis"><em>Bad sprintf format modifier in
|
|
||||||
money_put<>::do_put()</em></span>
|
|
||||||
</span></dt><dd><p>Change the format string to "%.0Lf".
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#365" target="_top">365</a>:
|
|
||||||
<span class="emphasis"><em>Lack of const-qualification in clause 27</em></span>
|
|
||||||
</span></dt><dd><p>Add const overloads of <code class="code">is_open</code>.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-active.html#387" target="_top">387</a>:
|
|
||||||
<span class="emphasis"><em>std::complex over-encapsulated</em></span>
|
|
||||||
</span></dt><dd><p>Add the <code class="code">real(T)</code> and <code class="code">imag(T)</code>
|
|
||||||
members; in C++0x mode, also adjust the existing
|
|
||||||
<code class="code">real()</code> and <code class="code">imag()</code> members and
|
|
||||||
free functions.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#389" target="_top">389</a>:
|
|
||||||
<span class="emphasis"><em>Const overload of valarray::operator[] returns
|
|
||||||
by value</em></span>
|
|
||||||
</span></dt><dd><p>Change it to return a <code class="code">const T&</code>.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-active.html#396" target="_top">396</a>:
|
|
||||||
<span class="emphasis"><em>what are characters zero and one</em></span>
|
|
||||||
</span></dt><dd><p>Implement the proposed resolution.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#402" target="_top">402</a>:
|
|
||||||
<span class="emphasis"><em>Wrong new expression in [some_]allocator::construct</em></span>
|
|
||||||
</span></dt><dd><p>Replace "new" with "::new".
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#409" target="_top">409</a>:
|
|
||||||
<span class="emphasis"><em>Closing an fstream should clear the error state</em></span>
|
|
||||||
</span></dt><dd><p>Have <code class="code">open</code> clear the error flags.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-active.html#431" target="_top">431</a>:
|
|
||||||
<span class="emphasis"><em>Swapping containers with unequal allocators</em></span>
|
|
||||||
</span></dt><dd><p>Implement Option 3, as per N1599.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#432" target="_top">432</a>:
|
|
||||||
<span class="emphasis"><em>stringbuf::overflow() makes only one write position
|
|
||||||
available</em></span>
|
|
||||||
</span></dt><dd><p>Implement the resolution, beyond DR 169.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#434" target="_top">434</a>:
|
|
||||||
<span class="emphasis"><em>bitset::to_string() hard to use</em></span>
|
|
||||||
</span></dt><dd><p>Add three overloads, taking fewer template arguments.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#438" target="_top">438</a>:
|
|
||||||
<span class="emphasis"><em>Ambiguity in the "do the right thing" clause</em></span>
|
|
||||||
</span></dt><dd><p>Implement the resolution, basically cast less.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#453" target="_top">453</a>:
|
|
||||||
<span class="emphasis"><em>basic_stringbuf::seekoff need not always fail for an empty stream</em></span>
|
|
||||||
</span></dt><dd><p>Don't fail if the next pointer is null and newoff is zero.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#455" target="_top">455</a>:
|
|
||||||
<span class="emphasis"><em>cerr::tie() and wcerr::tie() are overspecified</em></span>
|
|
||||||
</span></dt><dd><p>Initialize cerr tied to cout and wcerr tied to wcout.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#464" target="_top">464</a>:
|
|
||||||
<span class="emphasis"><em>Suggestion for new member functions in standard containers</em></span>
|
|
||||||
</span></dt><dd><p>Add <code class="code">data()</code> to <code class="code">std::vector</code> and
|
|
||||||
<code class="code">at(const key_type&)</code> to <code class="code">std::map</code>.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#508" target="_top">508</a>:
|
|
||||||
<span class="emphasis"><em>Bad parameters for ranlux64_base_01</em></span>
|
|
||||||
</span></dt><dd><p>Fix the parameters.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-closed.html#512" target="_top">512</a>:
|
|
||||||
<span class="emphasis"><em>Seeding subtract_with_carry_01 from a single unsigned long</em></span>
|
|
||||||
</span></dt><dd><p>Construct a <code class="code">linear_congruential</code> engine and seed with it.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-closed.html#526" target="_top">526</a>:
|
|
||||||
<span class="emphasis"><em>Is it undefined if a function in the standard changes in
|
|
||||||
parameters?</em></span>
|
|
||||||
</span></dt><dd><p>Use &value.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#538" target="_top">538</a>:
|
|
||||||
<span class="emphasis"><em>241 again: Does unique_copy() require CopyConstructible
|
|
||||||
and Assignable?</em></span>
|
|
||||||
</span></dt><dd><p>In case of input_iterator/output_iterator rely on Assignability of
|
|
||||||
input_iterator' value_type.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#541" target="_top">541</a>:
|
|
||||||
<span class="emphasis"><em>shared_ptr template assignment and void</em></span>
|
|
||||||
</span></dt><dd><p>Add an auto_ptr<void> specialization.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#543" target="_top">543</a>:
|
|
||||||
<span class="emphasis"><em>valarray slice default constructor</em></span>
|
|
||||||
</span></dt><dd><p>Follow the straightforward proposed resolution.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#550" target="_top">550</a>:
|
|
||||||
<span class="emphasis"><em>What should the return type of pow(float,int) be?</em></span>
|
|
||||||
</span></dt><dd><p>In C++0x mode, remove the pow(float,int), etc., signatures.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#586" target="_top">586</a>:
|
|
||||||
<span class="emphasis"><em>string inserter not a formatted function</em></span>
|
|
||||||
</span></dt><dd><p>Change it to be a formatted output function (i.e. catch exceptions).
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#596" target="_top">596</a>:
|
|
||||||
<span class="emphasis"><em>27.8.1.3 Table 112 omits "a+" and "a+b" modes</em></span>
|
|
||||||
</span></dt><dd><p>Add the missing modes to fopen_mode.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#660" target="_top">660</a>:
|
|
||||||
<span class="emphasis"><em>Missing bitwise operations</em></span>
|
|
||||||
</span></dt><dd><p>Add the missing operations.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-active.html#691" target="_top">691</a>:
|
|
||||||
<span class="emphasis"><em>const_local_iterator cbegin, cend missing from TR1</em></span>
|
|
||||||
</span></dt><dd><p>In C++0x mode add cbegin(size_type) and cend(size_type)
|
|
||||||
to the unordered containers.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#693" target="_top">693</a>:
|
|
||||||
<span class="emphasis"><em>std::bitset::all() missing</em></span>
|
|
||||||
</span></dt><dd><p>Add it, consistently with the discussion.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#695" target="_top">695</a>:
|
|
||||||
<span class="emphasis"><em>ctype<char>::classic_table() not accessible</em></span>
|
|
||||||
</span></dt><dd><p>Make the member functions table and classic_table public.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#761" target="_top">761</a>:
|
|
||||||
<span class="emphasis"><em>unordered_map needs an at() member function</em></span>
|
|
||||||
</span></dt><dd><p>In C++0x mode, add at() and at() const.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#775" target="_top">775</a>:
|
|
||||||
<span class="emphasis"><em>Tuple indexing should be unsigned?</em></span>
|
|
||||||
</span></dt><dd><p>Implement the int -> size_t replacements.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-active.html#776" target="_top">776</a>:
|
|
||||||
<span class="emphasis"><em>Undescribed assign function of std::array</em></span>
|
|
||||||
</span></dt><dd><p>In C++0x mode, remove assign, add fill.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-defects.html#781" target="_top">781</a>:
|
|
||||||
<span class="emphasis"><em>std::complex should add missing C99 functions</em></span>
|
|
||||||
</span></dt><dd><p>In C++0x mode, add std::proj.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-active.html#809" target="_top">809</a>:
|
|
||||||
<span class="emphasis"><em>std::swap should be overloaded for array types</em></span>
|
|
||||||
</span></dt><dd><p>Add the overload.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-active.html#844" target="_top">844</a>:
|
|
||||||
<span class="emphasis"><em>complex pow return type is ambiguous</em></span>
|
|
||||||
</span></dt><dd><p>In C++0x mode, remove the pow(complex<T>, int) signature.
|
|
||||||
</p></dd><dt><span class="term"><a class="ulink" href="../ext/lwg-active.html#853" target="_top">853</a>:
|
|
||||||
<span class="emphasis"><em>to_string needs updating with zero and one</em></span>
|
|
||||||
</span></dt><dd><p>Update / add the signatures.
|
|
||||||
</p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch01s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt01ch01.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt01ch02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">License </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 2. Setup</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,98 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 2. Setup</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="intro.html" title="Part I. Introduction" /><link rel="prev" href="bk01pt01ch01s03.html" title="Bugs" /><link rel="next" href="configure.html" title="Configure" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. Setup</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt01ch01s03.html">Prev</a> </td><th width="60%" align="center">Part I. Introduction</th><td width="20%" align="right"> <a accesskey="n" href="configure.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.setup"></a>Chapter 2. Setup</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt01ch02.html#manual.intro.setup.prereq">Prerequisites</a></span></dt><dt><span class="sect1"><a href="configure.html">Configure</a></span></dt><dt><span class="sect1"><a href="bk01pt01ch02s03.html">Make</a></span></dt><dt><span class="sect1"><a href="test.html">Test</a></span></dt><dd><dl><dt><span class="sect2"><a href="test.html#test.organization">Organization</a></span></dt><dt><span class="sect2"><a href="test.html#test.run">Running the Testsuite</a></span></dt><dt><span class="sect2"><a href="test.html#test.new_tests">Writing a new test case</a></span></dt><dt><span class="sect2"><a href="test.html#test.harness">Test Harness and Utilities</a></span></dt></dl></dd></dl></div><p>To transform libstdc++ sources into installed include files
|
|
||||||
and properly built binaries useful for linking to other software is
|
|
||||||
a multi-step process. Steps include getting the sources,
|
|
||||||
configuring and building the sources, testing, and installation.
|
|
||||||
</p><p>The general outline of commands is something like:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
<span class="emphasis"><em>get gcc sources</em></span>
|
|
||||||
<span class="emphasis"><em>extract into gccsrcdir</em></span>
|
|
||||||
mkdir <span class="emphasis"><em>gccbuilddir</em></span>
|
|
||||||
cd <span class="emphasis"><em>gccbuilddir</em></span>
|
|
||||||
<span class="emphasis"><em>gccsrcdir</em></span>/configure --prefix=<span class="emphasis"><em>destdir</em></span> --other-opts...
|
|
||||||
make
|
|
||||||
make check
|
|
||||||
make install
|
|
||||||
</pre><p>
|
|
||||||
Each step is described in more detail in the following sections.
|
|
||||||
</p><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.setup.prereq"></a>Prerequisites</h2></div></div></div><p>
|
|
||||||
Because libstdc++ is part of GCC, the primary source for
|
|
||||||
installation instructions is
|
|
||||||
<a class="ulink" href="http://gcc.gnu.org/install/" target="_top">the GCC install page</a>.
|
|
||||||
In particular, list of prerequisite software needed to build the library
|
|
||||||
<a class="ulink" href="http://gcc.gnu.org/install/prerequisites.html" target="_top">
|
|
||||||
starts with those requirements.</a> The same pages also list
|
|
||||||
the tools you will need if you wish to modify the source.
|
|
||||||
</p><p>
|
|
||||||
Additional data is given here only where it applies to libstdc++.
|
|
||||||
</p><p>As of GCC 4.0.1 the minimum version of binutils required to build
|
|
||||||
libstdc++ is <code class="code">2.15.90.0.1.1</code>. You can get snapshots
|
|
||||||
(as well as releases) of binutils from
|
|
||||||
<a class="ulink" href="ftp://sources.redhat.com/pub/binutils" target="_top">
|
|
||||||
ftp://sources.redhat.com/pub/binutils</a>.
|
|
||||||
Older releases of libstdc++ do not require such a recent version,
|
|
||||||
but to take full advantage of useful space-saving features and
|
|
||||||
bug-fixes you should use a recent binutils whenever possible.
|
|
||||||
The configure process will automatically detect and use these
|
|
||||||
features if the underlying support is present.
|
|
||||||
</p><p>
|
|
||||||
Finally, a few system-specific requirements:
|
|
||||||
</p><div class="variablelist"><dl><dt><span class="term">linux</span></dt><dd><p>
|
|
||||||
If gcc 3.1.0 or later on is being used on linux, an attempt
|
|
||||||
will be made to use "C" library functionality necessary for
|
|
||||||
C++ named locale support. For gcc 3.2.1 and later, this
|
|
||||||
means that glibc 2.2.5 or later is required and the "C"
|
|
||||||
library de_DE locale information must be installed.
|
|
||||||
</p><p>
|
|
||||||
Note however that the sanity checks involving the de_DE
|
|
||||||
locale are skipped when an explicit --enable-clocale=gnu
|
|
||||||
configure option is used: only the basic checks are carried
|
|
||||||
out, defending against misconfigurations.
|
|
||||||
</p><p>
|
|
||||||
If the 'gnu' locale model is being used, the following
|
|
||||||
locales are used and tested in the libstdc++ testsuites.
|
|
||||||
The first column is the name of the locale, the second is
|
|
||||||
the character set it is expected to use.
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
de_DE ISO-8859-1
|
|
||||||
de_DE@euro ISO-8859-15
|
|
||||||
en_HK ISO-8859-1
|
|
||||||
en_PH ISO-8859-1
|
|
||||||
en_US ISO-8859-1
|
|
||||||
en_US.ISO-8859-1 ISO-8859-1
|
|
||||||
en_US.ISO-8859-15 ISO-8859-15
|
|
||||||
en_US.UTF-8 UTF-8
|
|
||||||
es_ES ISO-8859-1
|
|
||||||
es_MX ISO-8859-1
|
|
||||||
fr_FR ISO-8859-1
|
|
||||||
fr_FR@euro ISO-8859-15
|
|
||||||
is_IS UTF-8
|
|
||||||
it_IT ISO-8859-1
|
|
||||||
ja_JP.eucjp EUC-JP
|
|
||||||
se_NO.UTF-8 UTF-8
|
|
||||||
ta_IN UTF-8
|
|
||||||
zh_TW BIG5
|
|
||||||
</pre><p>Failure to have the underlying "C" library locale
|
|
||||||
information installed will mean that C++ named locales for the
|
|
||||||
above regions will not work: because of this, the libstdc++
|
|
||||||
testsuite will skip the named locale tests. If this isn't an
|
|
||||||
issue, don't worry about it. If named locales are needed, the
|
|
||||||
underlying locale information must be installed. Note that
|
|
||||||
rebuilding libstdc++ after the "C" locales are installed is not
|
|
||||||
necessary.
|
|
||||||
</p><p>
|
|
||||||
To install support for locales, do only one of the following:
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>install all locales</p><div class="itemizedlist"><ul type="circle"><li><p>with RedHat Linux:
|
|
||||||
</p><p> <code class="code"> export LC_ALL=C </code>
|
|
||||||
</p><p> <code class="code"> rpm -e glibc-common --nodeps </code>
|
|
||||||
</p><p>
|
|
||||||
<code class="code"> rpm -i --define "_install_langs all"
|
|
||||||
glibc-common-2.2.5-34.i386.rpm
|
|
||||||
</code>
|
|
||||||
</p></li><li><p>
|
|
||||||
Instructions for other operating systems solicited.
|
|
||||||
</p></li></ul></div></li><li><p>install just the necessary locales</p><div class="itemizedlist"><ul type="circle"><li><p>with Debian Linux:</p><p> Add the above list, as shown, to the file
|
|
||||||
<code class="code">/etc/locale.gen</code> </p><p> run <code class="code">/usr/sbin/locale-gen</code> </p></li><li><p>on most Unix-like operating systems:</p><p><code class="code"> localedef -i de_DE -f ISO-8859-1 de_DE </code></p><p>(repeat for each entry in the above list) </p></li><li><p>
|
|
||||||
Instructions for other operating systems solicited.
|
|
||||||
</p></li></ul></div></li></ul></div></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch01s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="intro.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="configure.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Bugs </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Configure</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,9 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Make</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt01ch02.html" title="Chapter 2. Setup" /><link rel="prev" href="configure.html" title="Configure" /><link rel="next" href="test.html" title="Test" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Make</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="configure.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Setup</th><td width="20%" align="right"> <a accesskey="n" href="test.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.setup.make"></a>Make</h2></div></div></div><p>If you have never done this before, you should read the basic
|
|
||||||
<a class="ulink" href="http://gcc.gnu.org/install/" target="_top">GCC Installation
|
|
||||||
Instructions</a> first. Read <span class="emphasis"><em>all of them</em></span>.
|
|
||||||
<span class="emphasis"><em>Twice.</em></span>
|
|
||||||
</p><p>Then type:<span class="command"><strong>make</strong></span>, and congratulations, you're
|
|
||||||
started to build.
|
|
||||||
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configure.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt01ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="test.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Configure </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Test</td></tr></table></div></body></html>
|
|
||||||
File diff suppressed because one or more lines are too long
|
|
@ -1,61 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Namespaces</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="bk01pt01ch03s02.html" title="Headers" /><link rel="next" href="bk01pt01ch03s04.html" title="Macros" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Namespaces</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt01ch03s02.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt01ch03s04.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.namespaces"></a>Namespaces</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.all"></a>Available Namespaces</h3></div></div></div><p> There are three main namespaces.
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>std</p><p>The ISO C++ standards specify that "all library entities are defined
|
|
||||||
within namespace std." This includes namespaces nested
|
|
||||||
within <code class="code">namespace std</code>, such as <code class="code">namespace
|
|
||||||
std::tr1</code>.
|
|
||||||
</p></li><li><p>abi</p><p>Specified by the C++ ABI. This ABI specifies a number of type and
|
|
||||||
function APIs supplemental to those required by the ISO C++ Standard,
|
|
||||||
but necessary for interoperability.
|
|
||||||
</p></li><li><p>__gnu_</p><p>Indicating one of several GNU extensions. Choices
|
|
||||||
include <code class="code">__gnu_cxx</code>, <code class="code">__gnu_debug</code>, <code class="code">__gnu_parallel</code>,
|
|
||||||
and <code class="code">__gnu_pbds</code>.
|
|
||||||
</p></li></ul></div><p> A complete list of implementation namespaces (including namespace contents) is available in the generated source <a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html" target="_top">documentation</a>.
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.std"></a>namespace std</h3></div></div></div><p>
|
|
||||||
One standard requirement is that the library components are defined
|
|
||||||
in <code class="code">namespace std::</code>. Thus, in order to use these types or
|
|
||||||
functions, one must do one of two things:
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>put a kind of <span class="emphasis"><em>using-declaration</em></span> in your source
|
|
||||||
(either <code class="code">using namespace std;</code> or i.e. <code class="code">using
|
|
||||||
std::string;</code>) This approach works well for individual source files, but
|
|
||||||
should not be used in a global context, like header files.
|
|
||||||
</p></li><li><p>use a <span class="emphasis"><em>fully
|
|
||||||
qualified name</em></span>for each library symbol
|
|
||||||
(i.e. <code class="code">std::string</code>, <code class="code">std::cout</code>) Always can be
|
|
||||||
used, and usually enhanced, by strategic use of typedefs. (In the
|
|
||||||
cases where the qualified verbiage becomes unwieldy.)
|
|
||||||
</p></li></ul></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.comp"></a>Using Namespace Composition</h3></div></div></div><p>
|
|
||||||
Best practice in programming suggests sequestering new data or
|
|
||||||
functionality in a sanely-named, unique namespace whenever
|
|
||||||
possible. This is considered an advantage over dumping everything in
|
|
||||||
the global namespace, as then name look-up can be explicitly enabled or
|
|
||||||
disabled as above, symbols are consistently mangled without repetitive
|
|
||||||
naming prefixes or macros, etc.
|
|
||||||
</p><p>For instance, consider a project that defines most of its classes in <code class="code">namespace gtk</code>. It is possible to
|
|
||||||
adapt <code class="code">namespace gtk</code> to <code class="code">namespace std</code> by using a C++-feature called
|
|
||||||
<span class="emphasis"><em>namespace composition</em></span>. This is what happens if
|
|
||||||
a <span class="emphasis"><em>using</em></span>-declaration is put into a
|
|
||||||
namespace-definition: the imported symbol(s) gets imported into the
|
|
||||||
currently active namespace(s). For example:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
namespace gtk
|
|
||||||
{
|
|
||||||
using std::string;
|
|
||||||
using std::tr1::array;
|
|
||||||
|
|
||||||
class Window { ... };
|
|
||||||
}
|
|
||||||
</pre><p>
|
|
||||||
In this example, <code class="code">std::string</code> gets imported into
|
|
||||||
<code class="code">namespace gtk</code>. The result is that use of
|
|
||||||
<code class="code">std::string</code> inside namespace gtk can just use <code class="code">string</code>, without the explicit qualification.
|
|
||||||
As an added bonus,
|
|
||||||
<code class="code">std::string</code> does not get imported into
|
|
||||||
the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the
|
|
||||||
<code class="code">using</code>-declarations can wrapped in macros that
|
|
||||||
are set based on autoconf-tests to either "" or i.e. <code class="code">using
|
|
||||||
std::string;</code> (depending on whether the system has
|
|
||||||
libstdc++ in <code class="code">std::</code> or not). (ideas from
|
|
||||||
<code class="email"><<a class="email" href="mailto:llewelly@dbritsch.dsl.xmission.com">llewelly@dbritsch.dsl.xmission.com</a>></code>, Karl Nelson <code class="email"><<a class="email" href="mailto:kenelson@ece.ucdavis.edu">kenelson@ece.ucdavis.edu</a>></code>)
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch03s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt01ch03s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Headers </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Macros</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,70 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Macros</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="bk01pt01ch03s03.html" title="Namespaces" /><link rel="next" href="bk01pt01ch03s05.html" title="Concurrency" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Macros</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt01ch03s03.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt01ch03s05.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.macros"></a>Macros</h2></div></div></div><p>All pre-processor switches and configurations are all gathered
|
|
||||||
in the file <code class="code">c++config.h</code>, which is generated during
|
|
||||||
the libstdc++ configuration and build process, and included by
|
|
||||||
files part of the public libstdc++ API. Most of these macros
|
|
||||||
should not be used by consumers of libstdc++, and are reserved
|
|
||||||
for internal implementation use. <span class="emphasis"><em>These macros cannot be
|
|
||||||
redefined</em></span>. However, a select handful of these macro
|
|
||||||
control libstdc++ extensions and extra features, or provide
|
|
||||||
versioning information for the API, and are able to be used.
|
|
||||||
</p><p>All library macros begin with <code class="code">_GLIBCXX_</code> (except for
|
|
||||||
versions 3.1.x to 3.3.x, which use <code class="code">_GLIBCPP_</code>).
|
|
||||||
</p><p>Below is the macro which users may check for library version
|
|
||||||
information. </p><div class="variablelist"><dl><dt><span class="term"><code class="code">__GLIBCXX__</code></span></dt><dd><p>The current version of
|
|
||||||
libstdc++ in compressed ISO date format, form of an unsigned
|
|
||||||
long. For details on the value of this particular macro for a
|
|
||||||
particular release, please consult this <a class="ulink" href="abi.html" target="_top">
|
|
||||||
document</a>.
|
|
||||||
</p></dd></dl></div><p>Below are the macros which users may change with #define/#undef or
|
|
||||||
with -D/-U compiler flags. The default state of the symbol is
|
|
||||||
listed.</p><p>“<span class="quote">Configurable</span>” (or “<span class="quote">Not configurable</span>”) means
|
|
||||||
that the symbol is initially chosen (or not) based on
|
|
||||||
--enable/--disable options at library build and configure time
|
|
||||||
(documented <a class="link" href="configure.html" title="Configure">here</a>), with the
|
|
||||||
various --enable/--disable choices being translated to
|
|
||||||
#define/#undef).
|
|
||||||
</p><p> <acronym class="acronym">ABI</acronym> means that changing from the default value may
|
|
||||||
mean changing the <acronym class="acronym">ABI</acronym> of compiled code. In other words, these
|
|
||||||
choices control code which has already been compiled (i.e., in a
|
|
||||||
binary such as libstdc++.a/.so). If you explicitly #define or
|
|
||||||
#undef these macros, the <span class="emphasis"><em>headers</em></span> may see different code
|
|
||||||
paths, but the <span class="emphasis"><em>libraries</em></span> which you link against will not.
|
|
||||||
Experimenting with different values with the expectation of
|
|
||||||
consistent linkage requires changing the config headers before
|
|
||||||
building/installing the library.
|
|
||||||
</p><div class="variablelist"><dl><dt><span class="term"><code class="code">_GLIBCXX_DEPRECATED</code></span></dt><dd><p>
|
|
||||||
Defined by default. Not configurable. ABI-changing. Turning this off
|
|
||||||
removes older ARM-style iostreams code, and other anachronisms
|
|
||||||
from the API. This macro is dependent on the version of the
|
|
||||||
standard being tracked, and as a result may give different results for
|
|
||||||
<code class="code">-std=c++98</code> and <code class="code">-std=c++0x</code>. This may
|
|
||||||
be useful in updating old C++ code which no longer meet the
|
|
||||||
requirements of the language, or for checking current code
|
|
||||||
against new language standards.
|
|
||||||
</p></dd><dt><span class="term"><code class="code">_GLIBCXX_FORCE_NEW</code></span></dt><dd><p>
|
|
||||||
Undefined by default. When defined, memory allocation and
|
|
||||||
allocators controlled by libstdc++ call operator new/delete
|
|
||||||
without caching and pooling. Configurable via
|
|
||||||
<code class="code">--enable-libstdcxx-allocator</code>. ABI-changing.
|
|
||||||
</p></dd><dt><span class="term"><code class="code">_GLIBCXX_CONCEPT_CHECKS</code></span></dt><dd><p>
|
|
||||||
Undefined by default. Configurable via
|
|
||||||
<code class="code">--enable-concept-checks</code>. When defined, performs
|
|
||||||
compile-time checking on certain template instantiations to
|
|
||||||
detect violations of the requirements of the standard. This
|
|
||||||
is described in more detail <a class="ulink" href="../19_diagnostics/howto.html#3" target="_top">here</a>.
|
|
||||||
</p></dd><dt><span class="term"><code class="code">_GLIBCXX_DEBUG</code></span></dt><dd><p>
|
|
||||||
Undefined by default. When defined, compiles
|
|
||||||
user code using the <a class="ulink" href="../ext/debug.html#safe" target="_top">libstdc++ debug
|
|
||||||
mode</a>.
|
|
||||||
</p></dd><dt><span class="term"><code class="code">_GLIBCXX_DEBUG_PEDANTIC</code></span></dt><dd><p>
|
|
||||||
Undefined by default. When defined while
|
|
||||||
compiling with the <a class="ulink" href="../ext/debug.html#safe" target="_top">libstdc++ debug
|
|
||||||
mode</a>, makes the debug mode extremely picky by making the use
|
|
||||||
of libstdc++ extensions and libstdc++-specific behavior into
|
|
||||||
errors.
|
|
||||||
</p></dd><dt><span class="term"><code class="code">_GLIBCXX_PARALLEL</code></span></dt><dd><p>Undefined by default. When defined, compiles
|
|
||||||
user code using the <a class="ulink" href="../ext/parallel_mode.html" target="_top">libstdc++ parallel
|
|
||||||
mode</a>.
|
|
||||||
</p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch03s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt01ch03s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Namespaces </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Concurrency</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,219 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Concurrency</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="bk01pt01ch03s04.html" title="Macros" /><link rel="next" href="bk01pt01ch03s06.html" title="Exceptions" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Concurrency</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt01ch03s04.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt01ch03s06.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.concurrency"></a>Concurrency</h2></div></div></div><p>This section discusses issues surrounding the proper compilation
|
|
||||||
of multithreaded applications which use the Standard C++
|
|
||||||
library. This information is GCC-specific since the C++
|
|
||||||
standard does not address matters of multithreaded applications.
|
|
||||||
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.prereq"></a>Prerequisites</h3></div></div></div><p>All normal disclaimers aside, multithreaded C++ application are
|
|
||||||
only supported when libstdc++ and all user code was built with
|
|
||||||
compilers which report (via <code class="code"> gcc/g++ -v </code>) the same thread
|
|
||||||
model and that model is not <span class="emphasis"><em>single</em></span>. As long as your
|
|
||||||
final application is actually single-threaded, then it should be
|
|
||||||
safe to mix user code built with a thread model of
|
|
||||||
<span class="emphasis"><em>single</em></span> with a libstdc++ and other C++ libraries built
|
|
||||||
with another thread model useful on the platform. Other mixes
|
|
||||||
may or may not work but are not considered supported. (Thus, if
|
|
||||||
you distribute a shared C++ library in binary form only, it may
|
|
||||||
be best to compile it with a GCC configured with
|
|
||||||
--enable-threads for maximal interchangeability and usefulness
|
|
||||||
with a user population that may have built GCC with either
|
|
||||||
--enable-threads or --disable-threads.)
|
|
||||||
</p><p>When you link a multithreaded application, you will probably
|
|
||||||
need to add a library or flag to g++. This is a very
|
|
||||||
non-standardized area of GCC across ports. Some ports support a
|
|
||||||
special flag (the spelling isn't even standardized yet) to add
|
|
||||||
all required macros to a compilation (if any such flags are
|
|
||||||
required then you must provide the flag for all compilations not
|
|
||||||
just linking) and link-library additions and/or replacements at
|
|
||||||
link time. The documentation is weak. Here is a quick summary
|
|
||||||
to display how ad hoc this is: On Solaris, both -pthreads and
|
|
||||||
-threads (with subtly different meanings) are honored. On OSF,
|
|
||||||
-pthread and -threads (with subtly different meanings) are
|
|
||||||
honored. On Linux/i386, -pthread is honored. On FreeBSD,
|
|
||||||
-pthread is honored. Some other ports use other switches.
|
|
||||||
AFAIK, none of this is properly documented anywhere other than
|
|
||||||
in ``gcc -dumpspecs'' (look at lib and cpp entries).
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.thread_safety"></a>Thread Safety</h3></div></div></div><p>
|
|
||||||
We currently use the <a class="ulink" href="http://www.sgi.com/tech/stl/thread_safety.html" target="_top">SGI STL</a> definition of thread safety.
|
|
||||||
</p><p>The library strives to be thread-safe when all of the following
|
|
||||||
conditions are met:
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>The system's libc is itself thread-safe,
|
|
||||||
</p></li><li><p>
|
|
||||||
The compiler in use reports a thread model other than
|
|
||||||
'single'. This can be tested via output from <code class="code">gcc
|
|
||||||
-v</code>. Multi-thread capable versions of gcc output
|
|
||||||
something like this:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
%gcc -v
|
|
||||||
Using built-in specs.
|
|
||||||
...
|
|
||||||
Thread model: posix
|
|
||||||
gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
|
|
||||||
</pre><p>Look for "Thread model" lines that aren't equal to "single."</p></li><li><p>
|
|
||||||
Requisite command-line flags are used for atomic operations
|
|
||||||
and threading. Examples of this include <code class="code">-pthread</code>
|
|
||||||
and <code class="code">-march=native</code>, although specifics vary
|
|
||||||
depending on the host environment. See <a class="ulink" href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html" target="_top">Machine
|
|
||||||
Dependent Options</a>.
|
|
||||||
</p></li><li><p>
|
|
||||||
An implementation of atomicity.h functions
|
|
||||||
exists for the architecture in question. See the internals documentation for more <a class="ulink" href="../ext/concurrence.html" target="_top">details</a>.
|
|
||||||
</p></li></ul></div><p>The user-code must guard against concurrent method calls which may
|
|
||||||
access any particular library object's state. Typically, the
|
|
||||||
application programmer may infer what object locks must be held
|
|
||||||
based on the objects referenced in a method call. Without getting
|
|
||||||
into great detail, here is an example which requires user-level
|
|
||||||
locks:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
library_class_a shared_object_a;
|
|
||||||
|
|
||||||
thread_main () {
|
|
||||||
library_class_b *object_b = new library_class_b;
|
|
||||||
shared_object_a.add_b (object_b); // must hold lock for shared_object_a
|
|
||||||
shared_object_a.mutate (); // must hold lock for shared_object_a
|
|
||||||
}
|
|
||||||
|
|
||||||
// Multiple copies of thread_main() are started in independent threads.</pre><p>Under the assumption that object_a and object_b are never exposed to
|
|
||||||
another thread, here is an example that should not require any
|
|
||||||
user-level locks:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
thread_main () {
|
|
||||||
library_class_a object_a;
|
|
||||||
library_class_b *object_b = new library_class_b;
|
|
||||||
object_a.add_b (object_b);
|
|
||||||
object_a.mutate ();
|
|
||||||
} </pre><p>All library objects are safe to use in a multithreaded program as
|
|
||||||
long as each thread carefully locks out access by any other
|
|
||||||
thread while it uses any object visible to another thread, i.e.,
|
|
||||||
treat library objects like any other shared resource. In general,
|
|
||||||
this requirement includes both read and write access to objects;
|
|
||||||
unless otherwise documented as safe, do not assume that two threads
|
|
||||||
may access a shared standard library object at the same time.
|
|
||||||
</p><p>See chapters <a class="ulink" href="../17_intro/howto.html#3" target="_top">17</a> (library
|
|
||||||
introduction), <a class="ulink" href="../23_containers/howto.html#3" target="_top">23</a>
|
|
||||||
(containers), and <a class="ulink" href="../27_io/howto.html#9" target="_top">27</a> (I/O) for
|
|
||||||
more information.
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.atomics"></a>Atomics</h3></div></div></div><p>
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.io"></a>IO</h3></div></div></div><p>I'll assume that you have already read the
|
|
||||||
<a class="ulink" href="../17_intro/howto.html#3" target="_top">general notes on library threads</a>,
|
|
||||||
and the
|
|
||||||
<a class="ulink" href="../23_containers/howto.html#3" target="_top">notes on threaded container
|
|
||||||
access</a> (you might not think of an I/O stream as a container, but
|
|
||||||
the points made there also hold here). If you have not read them,
|
|
||||||
please do so first.
|
|
||||||
</p><p>This gets a bit tricky. Please read carefully, and bear with me.
|
|
||||||
</p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.structure"></a>Structure</h4></div></div></div><p>A wrapper
|
|
||||||
type called <code class="code">__basic_file</code> provides our abstraction layer
|
|
||||||
for the <code class="code">std::filebuf</code> classes. Nearly all decisions dealing
|
|
||||||
with actual input and output must be made in <code class="code">__basic_file</code>.
|
|
||||||
</p><p>A generic locking mechanism is somewhat in place at the filebuf layer,
|
|
||||||
but is not used in the current code. Providing locking at any higher
|
|
||||||
level is akin to providing locking within containers, and is not done
|
|
||||||
for the same reasons (see the links above).
|
|
||||||
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.defaults"></a>Defaults</h4></div></div></div><p>The __basic_file type is simply a collection of small wrappers around
|
|
||||||
the C stdio layer (again, see the link under Structure). We do no
|
|
||||||
locking ourselves, but simply pass through to calls to <code class="code">fopen</code>,
|
|
||||||
<code class="code">fwrite</code>, and so forth.
|
|
||||||
</p><p>So, for 3.0, the question of "is multithreading safe for I/O"
|
|
||||||
must be answered with, "is your platform's C library threadsafe
|
|
||||||
for I/O?" Some are by default, some are not; many offer multiple
|
|
||||||
implementations of the C library with varying tradeoffs of threadsafety
|
|
||||||
and efficiency. You, the programmer, are always required to take care
|
|
||||||
with multiple threads.
|
|
||||||
</p><p>(As an example, the POSIX standard requires that C stdio FILE*
|
|
||||||
operations are atomic. POSIX-conforming C libraries (e.g, on Solaris
|
|
||||||
and GNU/Linux) have an internal mutex to serialize operations on
|
|
||||||
FILE*s. However, you still need to not do stupid things like calling
|
|
||||||
<code class="code">fclose(fs)</code> in one thread followed by an access of
|
|
||||||
<code class="code">fs</code> in another.)
|
|
||||||
</p><p>So, if your platform's C library is threadsafe, then your
|
|
||||||
<code class="code">fstream</code> I/O operations will be threadsafe at the lowest
|
|
||||||
level. For higher-level operations, such as manipulating the data
|
|
||||||
contained in the stream formatting classes (e.g., setting up callbacks
|
|
||||||
inside an <code class="code">std::ofstream</code>), you need to guard such accesses
|
|
||||||
like any other critical shared resource.
|
|
||||||
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.future"></a>Future</h4></div></div></div><p> A
|
|
||||||
second choice may be available for I/O implementations: libio. This is
|
|
||||||
disabled by default, and in fact will not currently work due to other
|
|
||||||
issues. It will be revisited, however.
|
|
||||||
</p><p>The libio code is a subset of the guts of the GNU libc (glibc) I/O
|
|
||||||
implementation. When libio is in use, the <code class="code">__basic_file</code>
|
|
||||||
type is basically derived from FILE. (The real situation is more
|
|
||||||
complex than that... it's derived from an internal type used to
|
|
||||||
implement FILE. See libio/libioP.h to see scary things done with
|
|
||||||
vtbls.) The result is that there is no "layer" of C stdio
|
|
||||||
to go through; the filebuf makes calls directly into the same
|
|
||||||
functions used to implement <code class="code">fread</code>, <code class="code">fwrite</code>,
|
|
||||||
and so forth, using internal data structures. (And when I say
|
|
||||||
"makes calls directly," I mean the function is literally
|
|
||||||
replaced by a jump into an internal function. Fast but frightening.
|
|
||||||
*grin*)
|
|
||||||
</p><p>Also, the libio internal locks are used. This requires pulling in
|
|
||||||
large chunks of glibc, such as a pthreads implementation, and is one
|
|
||||||
of the issues preventing widespread use of libio as the libstdc++
|
|
||||||
cstdio implementation.
|
|
||||||
</p><p>But we plan to make this work, at least as an option if not a future
|
|
||||||
default. Platforms running a copy of glibc with a recent-enough
|
|
||||||
version will see calls from libstdc++ directly into the glibc already
|
|
||||||
installed. For other platforms, a copy of the libio subsection will
|
|
||||||
be built and included in libstdc++.
|
|
||||||
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="concurrency.io.alt"></a>Alternatives</h4></div></div></div><p>Don't forget that other cstdio implementations are possible. You could
|
|
||||||
easily write one to perform your own forms of locking, to solve your
|
|
||||||
"interesting" problems.
|
|
||||||
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.concurrency.containers"></a>Containers</h3></div></div></div><p>This section discusses issues surrounding the design of
|
|
||||||
multithreaded applications which use Standard C++ containers.
|
|
||||||
All information in this section is current as of the gcc 3.0
|
|
||||||
release and all later point releases. Although earlier gcc
|
|
||||||
releases had a different approach to threading configuration and
|
|
||||||
proper compilation, the basic code design rules presented here
|
|
||||||
were similar. For information on all other aspects of
|
|
||||||
multithreading as it relates to libstdc++, including details on
|
|
||||||
the proper compilation of threaded code (and compatibility between
|
|
||||||
threaded and non-threaded code), see Chapter 17.
|
|
||||||
</p><p>Two excellent pages to read when working with the Standard C++
|
|
||||||
containers and threads are
|
|
||||||
<a class="ulink" href="http://www.sgi.com/tech/stl/thread_safety.html" target="_top">SGI's
|
|
||||||
http://www.sgi.com/tech/stl/thread_safety.html</a> and
|
|
||||||
<a class="ulink" href="http://www.sgi.com/tech/stl/Allocators.html" target="_top">SGI's
|
|
||||||
http://www.sgi.com/tech/stl/Allocators.html</a>.
|
|
||||||
</p><p><span class="emphasis"><em>However, please ignore all discussions about the user-level
|
|
||||||
configuration of the lock implementation inside the STL
|
|
||||||
container-memory allocator on those pages. For the sake of this
|
|
||||||
discussion, libstdc++ configures the SGI STL implementation,
|
|
||||||
not you. This is quite different from how gcc pre-3.0 worked.
|
|
||||||
In particular, past advice was for people using g++ to
|
|
||||||
explicitly define _PTHREADS or other macros or port-specific
|
|
||||||
compilation options on the command line to get a thread-safe
|
|
||||||
STL. This is no longer required for any port and should no
|
|
||||||
longer be done unless you really know what you are doing and
|
|
||||||
assume all responsibility.</em></span>
|
|
||||||
</p><p>Since the container implementation of libstdc++ uses the SGI
|
|
||||||
code, we use the same definition of thread safety as SGI when
|
|
||||||
discussing design. A key point that beginners may miss is the
|
|
||||||
fourth major paragraph of the first page mentioned above
|
|
||||||
("For most clients,"...), which points out that
|
|
||||||
locking must nearly always be done outside the container, by
|
|
||||||
client code (that'd be you, not us). There is a notable
|
|
||||||
exceptions to this rule. Allocators called while a container or
|
|
||||||
element is constructed uses an internal lock obtained and
|
|
||||||
released solely within libstdc++ code (in fact, this is the
|
|
||||||
reason STL requires any knowledge of the thread configuration).
|
|
||||||
</p><p>For implementing a container which does its own locking, it is
|
|
||||||
trivial to provide a wrapper class which obtains the lock (as
|
|
||||||
SGI suggests), performs the container operation, and then
|
|
||||||
releases the lock. This could be templatized <span class="emphasis"><em>to a certain
|
|
||||||
extent</em></span>, on the underlying container and/or a locking
|
|
||||||
mechanism. Trying to provide a catch-all general template
|
|
||||||
solution would probably be more trouble than it's worth.
|
|
||||||
</p><p>The STL implementation is currently configured to use the
|
|
||||||
high-speed caching memory allocator. Some people like to
|
|
||||||
test and/or normally run threaded programs with a different
|
|
||||||
default. For all details about how to globally override this
|
|
||||||
at application run-time see <a class="ulink" href="../ext/howto.html#3" target="_top">here</a>.
|
|
||||||
</p><p>There is a better way (not standardized yet): It is possible to
|
|
||||||
force the malloc-based allocator on a per-case-basis for some
|
|
||||||
application code. The library team generally believes that this
|
|
||||||
is a better way to tune an application for high-speed using this
|
|
||||||
implementation of the STL. There is
|
|
||||||
<a class="ulink" href="../ext/howto.html#3" target="_top">more information on allocators here</a>.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch03s04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt01ch03s06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Macros </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Exceptions</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,6 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Exceptions</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="bk01pt01ch03s05.html" title="Concurrency" /><link rel="next" href="debug.html" title="Debugging Support" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Exceptions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt01ch03s05.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="debug.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.exception"></a>Exceptions</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="intro.using.exception.propagating"></a>Propagating Exceptions aka Exception Neutrality</h3></div></div></div><p>
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="intro.using.exception.safety"></a>Exception Safety</h3></div></div></div><p>
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="intro.using.exception.no"></a>Support for <code class="literal">-fno-exceptions</code></h3></div></div></div><p>
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt01ch03s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="debug.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Concurrency </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Debugging Support</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,40 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 4. Types</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="support.html" title="Part II. Support" /><link rel="prev" href="bk01pt02pr01.html" title="" /><link rel="next" href="bk01pt02ch04s02.html" title="Numeric Properties" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 4. Types</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt02pr01.html">Prev</a> </td><th width="60%" align="center">Part II. Support</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt02ch04s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.support.types"></a>Chapter 4. Types</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt02ch04.html#manual.support.types.fundamental">Fundamental Types</a></span></dt><dt><span class="sect1"><a href="bk01pt02ch04s02.html">Numeric Properties</a></span></dt><dt><span class="sect1"><a href="bk01pt02ch04s03.html">NULL</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.support.types.fundamental"></a>Fundamental Types</h2></div></div></div><p>
|
|
||||||
C++ has the following builtin types:
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>
|
|
||||||
char
|
|
||||||
</p></li><li><p>
|
|
||||||
signed char
|
|
||||||
</p></li><li><p>
|
|
||||||
unsigned char
|
|
||||||
</p></li><li><p>
|
|
||||||
signed short
|
|
||||||
</p></li><li><p>
|
|
||||||
signed int
|
|
||||||
</p></li><li><p>
|
|
||||||
signed long
|
|
||||||
</p></li><li><p>
|
|
||||||
unsigned short
|
|
||||||
</p></li><li><p>
|
|
||||||
unsigned int
|
|
||||||
</p></li><li><p>
|
|
||||||
unsigned long
|
|
||||||
</p></li><li><p>
|
|
||||||
bool
|
|
||||||
</p></li><li><p>
|
|
||||||
wchar_t
|
|
||||||
</p></li><li><p>
|
|
||||||
float
|
|
||||||
</p></li><li><p>
|
|
||||||
double
|
|
||||||
</p></li><li><p>
|
|
||||||
long double
|
|
||||||
</p></li></ul></div><p>
|
|
||||||
These fundamental types are always available, without having to
|
|
||||||
include a header file. These types are exactly the same in
|
|
||||||
either C++ or in C.
|
|
||||||
</p><p>
|
|
||||||
Specializing parts of the library on these types is prohibited:
|
|
||||||
instead, use a POD.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt02pr01.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="support.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt02ch04s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Numeric Properties</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,66 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 5. Dynamic Memory</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="support.html" title="Part II. Support" /><link rel="prev" href="bk01pt02ch04s03.html" title="NULL" /><link rel="next" href="bk01pt02ch06.html" title="Chapter 6. Termination" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. Dynamic Memory</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt02ch04s03.html">Prev</a> </td><th width="60%" align="center">Part II. Support</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt02ch06.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.support.memory"></a>Chapter 5. Dynamic Memory</h2></div></div></div><p>
|
|
||||||
There are six flavors each of <code class="function">new</code> and
|
|
||||||
<code class="function">delete</code>, so make certain that you're using the right
|
|
||||||
ones. Here are quickie descriptions of <code class="function">new</code>:
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>
|
|
||||||
single object form, throwing a
|
|
||||||
<code class="classname">bad_alloc</code> on errors; this is what most
|
|
||||||
people are used to using
|
|
||||||
</p></li><li><p>
|
|
||||||
Single object "nothrow" form, returning NULL on errors
|
|
||||||
</p></li><li><p>
|
|
||||||
Array <code class="function">new</code>, throwing
|
|
||||||
<code class="classname">bad_alloc</code> on errors
|
|
||||||
</p></li><li><p>
|
|
||||||
Array nothrow <code class="function">new</code>, returning
|
|
||||||
<code class="constant">NULL</code> on errors
|
|
||||||
</p></li><li><p>
|
|
||||||
Placement <code class="function">new</code>, which does nothing (like
|
|
||||||
it's supposed to)
|
|
||||||
</p></li><li><p>
|
|
||||||
Placement array <code class="function">new</code>, which also does
|
|
||||||
nothing
|
|
||||||
</p></li></ul></div><p>
|
|
||||||
They are distinguished by the parameters that you pass to them, like
|
|
||||||
any other overloaded function. The six flavors of <code class="function">delete</code>
|
|
||||||
are distinguished the same way, but none of them are allowed to throw
|
|
||||||
an exception under any circumstances anyhow. (They match up for
|
|
||||||
completeness' sake.)
|
|
||||||
</p><p>
|
|
||||||
Remember that it is perfectly okay to call <code class="function">delete</code> on a
|
|
||||||
NULL pointer! Nothing happens, by definition. That is not the
|
|
||||||
same thing as deleting a pointer twice.
|
|
||||||
</p><p>
|
|
||||||
By default, if one of the “<span class="quote">throwing <code class="function">new</code>s</span>” can't
|
|
||||||
allocate the memory requested, it tosses an instance of a
|
|
||||||
<code class="classname">bad_alloc</code> exception (or, technically, some class derived
|
|
||||||
from it). You can change this by writing your own function (called a
|
|
||||||
new-handler) and then registering it with <code class="function">set_new_handler()</code>:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
typedef void (*PFV)(void);
|
|
||||||
|
|
||||||
static char* safety;
|
|
||||||
static PFV old_handler;
|
|
||||||
|
|
||||||
void my_new_handler ()
|
|
||||||
{
|
|
||||||
delete[] safety;
|
|
||||||
popup_window ("Dude, you are running low on heap memory. You
|
|
||||||
should, like, close some windows, or something.
|
|
||||||
The next time you run out, we're gonna burn!");
|
|
||||||
set_new_handler (old_handler);
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
int main ()
|
|
||||||
{
|
|
||||||
safety = new char[500000];
|
|
||||||
old_handler = set_new_handler (&my_new_handler);
|
|
||||||
...
|
|
||||||
}
|
|
||||||
</pre><p>
|
|
||||||
<code class="classname">bad_alloc</code> is derived from the base <code class="classname">exception</code>
|
|
||||||
class defined in Chapter 19.
|
|
||||||
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt02ch04s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="support.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt02ch06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">NULL </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 6. Termination</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,45 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 6. Termination</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="support.html" title="Part II. Support" /><link rel="prev" href="bk01pt02ch05.html" title="Chapter 5. Dynamic Memory" /><link rel="next" href="bk01pt02ch06s02.html" title="Verbose Terminate Handler" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. Termination</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt02ch05.html">Prev</a> </td><th width="60%" align="center">Part II. Support</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt02ch06s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.support.termination"></a>Chapter 6. Termination</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt02ch06.html#support.termination.handlers">Termination Handlers</a></span></dt><dt><span class="sect1"><a href="bk01pt02ch06s02.html">Verbose Terminate Handler</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="support.termination.handlers"></a>Termination Handlers</h2></div></div></div><p>
|
|
||||||
Not many changes here to <code class="filename">cstdlib</code>. You should note that the
|
|
||||||
<code class="function">abort()</code> function does not call the
|
|
||||||
destructors of automatic nor static objects, so if you're
|
|
||||||
depending on those to do cleanup, it isn't going to happen.
|
|
||||||
(The functions registered with <code class="function">atexit()</code>
|
|
||||||
don't get called either, so you can forget about that
|
|
||||||
possibility, too.)
|
|
||||||
</p><p>
|
|
||||||
The good old <code class="function">exit()</code> function can be a bit
|
|
||||||
funky, too, until you look closer. Basically, three points to
|
|
||||||
remember are:
|
|
||||||
</p><div class="orderedlist"><ol type="1"><li><p>
|
|
||||||
Static objects are destroyed in reverse order of their creation.
|
|
||||||
</p></li><li><p>
|
|
||||||
Functions registered with <code class="function">atexit()</code> are called in
|
|
||||||
reverse order of registration, once per registration call.
|
|
||||||
(This isn't actually new.)
|
|
||||||
</p></li><li><p>
|
|
||||||
The previous two actions are “<span class="quote">interleaved,</span>” that is,
|
|
||||||
given this pseudocode:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
extern "C or C++" void f1 (void);
|
|
||||||
extern "C or C++" void f2 (void);
|
|
||||||
|
|
||||||
static Thing obj1;
|
|
||||||
atexit(f1);
|
|
||||||
static Thing obj2;
|
|
||||||
atexit(f2);
|
|
||||||
</pre><p>
|
|
||||||
then at a call of <code class="function">exit()</code>,
|
|
||||||
<code class="varname">f2</code> will be called, then
|
|
||||||
<code class="varname">obj2</code> will be destroyed, then
|
|
||||||
<code class="varname">f1</code> will be called, and finally
|
|
||||||
<code class="varname">obj1</code> will be destroyed. If
|
|
||||||
<code class="varname">f1</code> or <code class="varname">f2</code> allow an
|
|
||||||
exception to propagate out of them, Bad Things happen.
|
|
||||||
</p></li></ol></div><p>
|
|
||||||
Note also that <code class="function">atexit()</code> is only required to store 32
|
|
||||||
functions, and the compiler/library might already be using some of
|
|
||||||
those slots. If you think you may run out, we recommend using
|
|
||||||
the <code class="function">xatexit</code>/<code class="function">xexit</code> combination from <code class="literal">libiberty</code>, which has no such limit.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt02ch05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="support.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt02ch06s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 5. Dynamic Memory </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Verbose Terminate Handler</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,76 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Verbose Terminate Handler</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt02ch06.html" title="Chapter 6. Termination" /><link rel="prev" href="bk01pt02ch06.html" title="Chapter 6. Termination" /><link rel="next" href="diagnostics.html" title="Part III. Diagnostics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Verbose Terminate Handler</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt02ch06.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Termination</th><td width="20%" align="right"> <a accesskey="n" href="diagnostics.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="support.termination.verbose"></a>Verbose Terminate Handler</h2></div></div></div><p>
|
|
||||||
If you are having difficulty with uncaught exceptions and want a
|
|
||||||
little bit of help debugging the causes of the core dumps, you can
|
|
||||||
make use of a GNU extension, the verbose terminate handler.
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
#include <exception>
|
|
||||||
|
|
||||||
int main()
|
|
||||||
{
|
|
||||||
std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
|
|
||||||
...
|
|
||||||
|
|
||||||
throw <em class="replaceable"><code>anything</code></em>;
|
|
||||||
}
|
|
||||||
</pre><p>
|
|
||||||
The <code class="function">__verbose_terminate_handler</code> function
|
|
||||||
obtains the name of the current exception, attempts to demangle
|
|
||||||
it, and prints it to stderr. If the exception is derived from
|
|
||||||
<code class="classname">exception</code> then the output from
|
|
||||||
<code class="function">what()</code> will be included.
|
|
||||||
</p><p>
|
|
||||||
Any replacement termination function is required to kill the
|
|
||||||
program without returning; this one calls abort.
|
|
||||||
</p><p>
|
|
||||||
For example:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
#include <exception>
|
|
||||||
#include <stdexcept>
|
|
||||||
|
|
||||||
struct argument_error : public std::runtime_error
|
|
||||||
{
|
|
||||||
argument_error(const std::string& s): std::runtime_error(s) { }
|
|
||||||
};
|
|
||||||
|
|
||||||
int main(int argc)
|
|
||||||
{
|
|
||||||
std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
|
|
||||||
if (argc > 5)
|
|
||||||
throw argument_error(“<span class="quote">argc is greater than 5!</span>”);
|
|
||||||
else
|
|
||||||
throw argc;
|
|
||||||
}
|
|
||||||
</pre><p>
|
|
||||||
With the verbose terminate handler active, this gives:
|
|
||||||
</p><pre class="screen">
|
|
||||||
<code class="computeroutput">
|
|
||||||
% ./a.out
|
|
||||||
terminate called after throwing a `int'
|
|
||||||
Aborted
|
|
||||||
% ./a.out f f f f f f f f f f f
|
|
||||||
terminate called after throwing an instance of `argument_error'
|
|
||||||
what(): argc is greater than 5!
|
|
||||||
Aborted
|
|
||||||
</code>
|
|
||||||
</pre><p>
|
|
||||||
The 'Aborted' line comes from the call to
|
|
||||||
<code class="function">abort()</code>, of course.
|
|
||||||
</p><p>
|
|
||||||
This is the default termination handler; nothing need be done to
|
|
||||||
use it. To go back to the previous “<span class="quote">silent death</span>”
|
|
||||||
method, simply include <code class="filename">exception</code> and
|
|
||||||
<code class="filename">cstdlib</code>, and call
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
std::set_terminate(std::abort);
|
|
||||||
</pre><p>
|
|
||||||
After this, all calls to <code class="function">terminate</code> will use
|
|
||||||
<code class="function">abort</code> as the terminate handler.
|
|
||||||
</p><p>
|
|
||||||
Note: the verbose terminate handler will attempt to write to
|
|
||||||
stderr. If your application closes stderr or redirects it to an
|
|
||||||
inappropriate location,
|
|
||||||
<code class="function">__verbose_terminate_handler</code> will behave in
|
|
||||||
an unspecified manner.
|
|
||||||
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt02ch06.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt02ch06.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="diagnostics.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6. Termination </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part III. Diagnostics</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,16 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 7. Exceptions</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="diagnostics.html" title="Part III. Diagnostics" /><link rel="prev" href="diagnostics.html" title="Part III. Diagnostics" /><link rel="next" href="bk01pt03ch07s02.html" title="Adding Data to Exceptions" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 7. Exceptions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="diagnostics.html">Prev</a> </td><th width="60%" align="center">Part III. Diagnostics</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch07s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.diagnostics.exceptions"></a>Chapter 7. Exceptions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt03ch07.html#manual.diagnostics.exceptions.hierarchy">Exception Classes</a></span></dt><dt><span class="sect1"><a href="bk01pt03ch07s02.html">Adding Data to Exceptions</a></span></dt><dt><span class="sect1"><a href="bk01pt03ch07s03.html">Cancellation</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.diagnostics.exceptions.hierarchy"></a>Exception Classes</h2></div></div></div><p>
|
|
||||||
All exception objects are defined in one of the standard header
|
|
||||||
files: <code class="filename">exception</code>,
|
|
||||||
<code class="filename">stdexcept</code>, <code class="filename">new</code>, and
|
|
||||||
<code class="filename">typeinfo</code>.
|
|
||||||
</p><p>
|
|
||||||
The base exception object is <code class="classname">exception</code>,
|
|
||||||
located in <code class="filename">exception</code>. This object has no
|
|
||||||
<code class="classname">string</code> member.
|
|
||||||
</p><p>
|
|
||||||
Derived from this are several classes that may have a
|
|
||||||
<code class="classname">string</code> member: a full hierarchy can be
|
|
||||||
found in the <a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00233.html" target="_top">source documentation</a>.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="diagnostics.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="diagnostics.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch07s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part III. Diagnostics </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Adding Data to Exceptions</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,9 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 9. Functors</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="utilities.html" title="Part IV. Utilities" /><link rel="prev" href="utilities.html" title="Part IV. Utilities" /><link rel="next" href="bk01pt04ch10.html" title="Chapter 10. Pairs" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 9. Functors</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="utilities.html">Prev</a> </td><th width="60%" align="center">Part IV. Utilities</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt04ch10.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.util.functors"></a>Chapter 9. Functors</h2></div></div></div><p>If you don't know what functors are, you're not alone. Many people
|
|
||||||
get slightly the wrong idea. In the interest of not reinventing
|
|
||||||
the wheel, we will refer you to the introduction to the functor
|
|
||||||
concept written by SGI as part of their STL, in
|
|
||||||
<a class="ulink" href="http://www.sgi.com/tech/stl/functors.html" target="_top">their
|
|
||||||
http://www.sgi.com/tech/stl/functors.html</a>.
|
|
||||||
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="utilities.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="utilities.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt04ch10.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part IV. Utilities </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 10. Pairs</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,39 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 10. Pairs</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="utilities.html" title="Part IV. Utilities" /><link rel="prev" href="bk01pt04ch09.html" title="Chapter 9. Functors" /><link rel="next" href="bk01pt04ch11.html" title="Chapter 11. Memory" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 10. Pairs</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt04ch09.html">Prev</a> </td><th width="60%" align="center">Part IV. Utilities</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt04ch11.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.util.pairs"></a>Chapter 10. Pairs</h2></div></div></div><p>The <code class="code">pair<T1,T2></code> is a simple and handy way to
|
|
||||||
carry around a pair of objects. One is of type T1, and another of
|
|
||||||
type T2; they may be the same type, but you don't get anything
|
|
||||||
extra if they are. The two members can be accessed directly, as
|
|
||||||
<code class="code">.first</code> and <code class="code">.second</code>.
|
|
||||||
</p><p>Construction is simple. The default ctor initializes each member
|
|
||||||
with its respective default ctor. The other simple ctor,
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
pair (const T1& x, const T2& y);
|
|
||||||
</pre><p>does what you think it does, <code class="code">first</code> getting <code class="code">x</code>
|
|
||||||
and <code class="code">second</code> getting <code class="code">y</code>.
|
|
||||||
</p><p>There is a copy constructor, but it requires that your compiler
|
|
||||||
handle member function templates:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
template <class U, class V> pair (const pair<U,V>& p);
|
|
||||||
</pre><p>The compiler will convert as necessary from U to T1 and from
|
|
||||||
V to T2 in order to perform the respective initializations.
|
|
||||||
</p><p>The comparison operators are done for you. Equality
|
|
||||||
of two <code class="code">pair<T1,T2></code>s is defined as both <code class="code">first</code>
|
|
||||||
members comparing equal and both <code class="code">second</code> members comparing
|
|
||||||
equal; this simply delegates responsibility to the respective
|
|
||||||
<code class="code">operator==</code> functions (for types like MyClass) or builtin
|
|
||||||
comparisons (for types like int, char, etc).
|
|
||||||
</p><p>
|
|
||||||
The less-than operator is a bit odd the first time you see it. It
|
|
||||||
is defined as evaluating to:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
x.first < y.first ||
|
|
||||||
( !(y.first < x.first) && x.second < y.second )
|
|
||||||
</pre><p>The other operators are not defined using the <code class="code">rel_ops</code>
|
|
||||||
functions above, but their semantics are the same.
|
|
||||||
</p><p>Finally, there is a template function called <code class="function">make_pair</code>
|
|
||||||
that takes two references-to-const objects and returns an
|
|
||||||
instance of a pair instantiated on their respective types:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
pair<int,MyClass> p = make_pair(4,myobject);
|
|
||||||
</pre></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt04ch09.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="utilities.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt04ch11.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. Functors </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 11. Memory</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,346 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 11. Memory</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="utilities.html" title="Part IV. Utilities" /><link rel="prev" href="bk01pt04ch10.html" title="Chapter 10. Pairs" /><link rel="next" href="auto_ptr.html" title="auto_ptr" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 11. Memory</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt04ch10.html">Prev</a> </td><th width="60%" align="center">Part IV. Utilities</th><td width="20%" align="right"> <a accesskey="n" href="auto_ptr.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.util.memory"></a>Chapter 11. Memory</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt04ch11.html#manual.util.memory.allocator">Allocators</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt04ch11.html#allocator.req">Requirements</a></span></dt><dt><span class="sect2"><a href="bk01pt04ch11.html#allocator.design_issues">Design Issues</a></span></dt><dt><span class="sect2"><a href="bk01pt04ch11.html#allocator.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="bk01pt04ch11.html#allocator.using">Using a Specific Allocator</a></span></dt><dt><span class="sect2"><a href="bk01pt04ch11.html#allocator.custom">Custom Allocators</a></span></dt><dt><span class="sect2"><a href="bk01pt04ch11.html#allocator.ext">Extension Allocators</a></span></dt></dl></dd><dt><span class="sect1"><a href="auto_ptr.html">auto_ptr</a></span></dt><dd><dl><dt><span class="sect2"><a href="auto_ptr.html#auto_ptr.limitations">Limitations</a></span></dt><dt><span class="sect2"><a href="auto_ptr.html#auto_ptr.using">Use in Containers</a></span></dt></dl></dd><dt><span class="sect1"><a href="shared_ptr.html">shared_ptr</a></span></dt><dd><dl><dt><span class="sect2"><a href="shared_ptr.html#shared_ptr.req">Requirements</a></span></dt><dt><span class="sect2"><a href="shared_ptr.html#shared_ptr.design_issues">Design Issues</a></span></dt><dt><span class="sect2"><a href="shared_ptr.html#shared_ptr.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="shared_ptr.html#shared_ptr.using">Use</a></span></dt><dt><span class="sect2"><a href="shared_ptr.html#shared_ptr.ack">Acknowledgments</a></span></dt></dl></dd></dl></div><p>
|
|
||||||
Memory contains three general areas. First, function and operator
|
|
||||||
calls via <code class="function">new</code> and <code class="function">delete</code>
|
|
||||||
operator or member function calls. Second, allocation via
|
|
||||||
<code class="classname">allocator</code>. And finally, smart pointer and
|
|
||||||
intelligent pointer abstractions.
|
|
||||||
</p><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.util.memory.allocator"></a>Allocators</h2></div></div></div><p>
|
|
||||||
Memory management for Standard Library entities is encapsulated in a
|
|
||||||
class template called <code class="classname">allocator</code>. The
|
|
||||||
<code class="classname">allocator</code> abstraction is used throughout the
|
|
||||||
library in <code class="classname">string</code>, container classes,
|
|
||||||
algorithms, and parts of iostreams. This class, and base classes of
|
|
||||||
it, are the superset of available free store (“<span class="quote">heap</span>”)
|
|
||||||
management classes.
|
|
||||||
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.req"></a>Requirements</h3></div></div></div><p>
|
|
||||||
The C++ standard only gives a few directives in this area:
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>
|
|
||||||
When you add elements to a container, and the container must
|
|
||||||
allocate more memory to hold them, the container makes the
|
|
||||||
request via its <span class="type">Allocator</span> template
|
|
||||||
parameter, which is usually aliased to
|
|
||||||
<span class="type">allocator_type</span>. This includes adding chars
|
|
||||||
to the string class, which acts as a regular STL container in
|
|
||||||
this respect.
|
|
||||||
</p></li><li><p>
|
|
||||||
The default <span class="type">Allocator</span> argument of every
|
|
||||||
container-of-T is <code class="classname">allocator<T></code>.
|
|
||||||
</p></li><li><p>
|
|
||||||
The interface of the <code class="classname">allocator<T></code> class is
|
|
||||||
extremely simple. It has about 20 public declarations (nested
|
|
||||||
typedefs, member functions, etc), but the two which concern us most
|
|
||||||
are:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
T* allocate (size_type n, const void* hint = 0);
|
|
||||||
void deallocate (T* p, size_type n);
|
|
||||||
</pre><p>
|
|
||||||
The <code class="varname">n</code> arguments in both those
|
|
||||||
functions is a <span class="emphasis"><em>count</em></span> of the number of
|
|
||||||
<span class="type">T</span>'s to allocate space for, <span class="emphasis"><em>not their
|
|
||||||
total size</em></span>.
|
|
||||||
(This is a simplification; the real signatures use nested typedefs.)
|
|
||||||
</p></li><li><p>
|
|
||||||
The storage is obtained by calling <code class="function">::operator
|
|
||||||
new</code>, but it is unspecified when or how
|
|
||||||
often this function is called. The use of the
|
|
||||||
<code class="varname">hint</code> is unspecified, but intended as an
|
|
||||||
aid to locality if an implementation so
|
|
||||||
desires. <code class="constant">[20.4.1.1]/6</code>
|
|
||||||
</p></li></ul></div><p>
|
|
||||||
Complete details cam be found in the C++ standard, look in
|
|
||||||
<code class="constant">[20.4 Memory]</code>.
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.design_issues"></a>Design Issues</h3></div></div></div><p>
|
|
||||||
The easiest way of fulfilling the requirements is to call
|
|
||||||
<code class="function">operator new</code> each time a container needs
|
|
||||||
memory, and to call <code class="function">operator delete</code> each time
|
|
||||||
the container releases memory. This method may be <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00105.html" target="_top">slower</a>
|
|
||||||
than caching the allocations and re-using previously-allocated
|
|
||||||
memory, but has the advantage of working correctly across a wide
|
|
||||||
variety of hardware and operating systems, including large
|
|
||||||
clusters. The <code class="classname">__gnu_cxx::new_allocator</code>
|
|
||||||
implements the simple operator new and operator delete semantics,
|
|
||||||
while <code class="classname">__gnu_cxx::malloc_allocator</code>
|
|
||||||
implements much the same thing, only with the C language functions
|
|
||||||
<code class="function">std::malloc</code> and <code class="function">free</code>.
|
|
||||||
</p><p>
|
|
||||||
Another approach is to use intelligence within the allocator
|
|
||||||
class to cache allocations. This extra machinery can take a variety
|
|
||||||
of forms: a bitmap index, an index into an exponentially increasing
|
|
||||||
power-of-two-sized buckets, or simpler fixed-size pooling cache.
|
|
||||||
The cache is shared among all the containers in the program: when
|
|
||||||
your program's <code class="classname">std::vector<int></code> gets
|
|
||||||
cut in half and frees a bunch of its storage, that memory can be
|
|
||||||
reused by the private
|
|
||||||
<code class="classname">std::list<WonkyWidget></code> brought in from
|
|
||||||
a KDE library that you linked against. And operators
|
|
||||||
<code class="function">new</code> and <code class="function">delete</code> are not
|
|
||||||
always called to pass the memory on, either, which is a speed
|
|
||||||
bonus. Examples of allocators that use these techniques are
|
|
||||||
<code class="classname">__gnu_cxx::bitmap_allocator</code>,
|
|
||||||
<code class="classname">__gnu_cxx::pool_allocator</code>, and
|
|
||||||
<code class="classname">__gnu_cxx::__mt_alloc</code>.
|
|
||||||
</p><p>
|
|
||||||
Depending on the implementation techniques used, the underlying
|
|
||||||
operating system, and compilation environment, scaling caching
|
|
||||||
allocators can be tricky. In particular, order-of-destruction and
|
|
||||||
order-of-creation for memory pools may be difficult to pin down
|
|
||||||
with certainty, which may create problems when used with plugins
|
|
||||||
or loading and unloading shared objects in memory. As such, using
|
|
||||||
caching allocators on systems that do not support
|
|
||||||
<code class="function">abi::__cxa_atexit</code> is not recommended.
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.impl"></a>Implementation</h3></div></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id495307"></a>Interface Design</h4></div></div></div><p>
|
|
||||||
The only allocator interface that
|
|
||||||
is support is the standard C++ interface. As such, all STL
|
|
||||||
containers have been adjusted, and all external allocators have
|
|
||||||
been modified to support this change.
|
|
||||||
</p><p>
|
|
||||||
The class <code class="classname">allocator</code> just has typedef,
|
|
||||||
constructor, and rebind members. It inherits from one of the
|
|
||||||
high-speed extension allocators, covered below. Thus, all
|
|
||||||
allocation and deallocation depends on the base class.
|
|
||||||
</p><p>
|
|
||||||
The base class that <code class="classname">allocator</code> is derived from
|
|
||||||
may not be user-configurable.
|
|
||||||
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id462480"></a>Selecting Default Allocation Policy</h4></div></div></div><p>
|
|
||||||
It's difficult to pick an allocation strategy that will provide
|
|
||||||
maximum utility, without excessively penalizing some behavior. In
|
|
||||||
fact, it's difficult just deciding which typical actions to measure
|
|
||||||
for speed.
|
|
||||||
</p><p>
|
|
||||||
Three synthetic benchmarks have been created that provide data
|
|
||||||
that is used to compare different C++ allocators. These tests are:
|
|
||||||
</p><div class="orderedlist"><ol type="1"><li><p>
|
|
||||||
Insertion.
|
|
||||||
</p><p>
|
|
||||||
Over multiple iterations, various STL container
|
|
||||||
objects have elements inserted to some maximum amount. A variety
|
|
||||||
of allocators are tested.
|
|
||||||
Test source for <a class="ulink" href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/sequence.cc?view=markup" target="_top">sequence</a>
|
|
||||||
and <a class="ulink" href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/associative.cc?view=markup" target="_top">associative</a>
|
|
||||||
containers.
|
|
||||||
</p></li><li><p>
|
|
||||||
Insertion and erasure in a multi-threaded environment.
|
|
||||||
</p><p>
|
|
||||||
This test shows the ability of the allocator to reclaim memory
|
|
||||||
on a pre-thread basis, as well as measuring thread contention
|
|
||||||
for memory resources.
|
|
||||||
Test source
|
|
||||||
<a class="ulink" href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert_erase/associative.cc?view=markup" target="_top">here</a>.
|
|
||||||
</p></li><li><p>
|
|
||||||
A threaded producer/consumer model.
|
|
||||||
</p><p>
|
|
||||||
Test source for
|
|
||||||
<a class="ulink" href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/producer_consumer/sequence.cc?view=markup" target="_top">sequence</a>
|
|
||||||
and
|
|
||||||
<a class="ulink" href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/producer_consumer/associative.cc?view=markup" target="_top">associative</a>
|
|
||||||
containers.
|
|
||||||
</p></li></ol></div><p>
|
|
||||||
The current default choice for
|
|
||||||
<code class="classname">allocator</code> is
|
|
||||||
<code class="classname">__gnu_cxx::new_allocator</code>.
|
|
||||||
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id531789"></a>Disabling Memory Caching</h4></div></div></div><p>
|
|
||||||
In use, <code class="classname">allocator</code> may allocate and
|
|
||||||
deallocate using implementation-specified strategies and
|
|
||||||
heuristics. Because of this, every call to an allocator object's
|
|
||||||
<code class="function">allocate</code> member function may not actually
|
|
||||||
call the global operator new. This situation is also duplicated
|
|
||||||
for calls to the <code class="function">deallocate</code> member
|
|
||||||
function.
|
|
||||||
</p><p>
|
|
||||||
This can be confusing.
|
|
||||||
</p><p>
|
|
||||||
In particular, this can make debugging memory errors more
|
|
||||||
difficult, especially when using third party tools like valgrind or
|
|
||||||
debug versions of <code class="function">new</code>.
|
|
||||||
</p><p>
|
|
||||||
There are various ways to solve this problem. One would be to use
|
|
||||||
a custom allocator that just called operators
|
|
||||||
<code class="function">new</code> and <code class="function">delete</code>
|
|
||||||
directly, for every allocation. (See
|
|
||||||
<code class="filename">include/ext/new_allocator.h</code>, for instance.)
|
|
||||||
However, that option would involve changing source code to use
|
|
||||||
a non-default allocator. Another option is to force the
|
|
||||||
default allocator to remove caching and pools, and to directly
|
|
||||||
allocate with every call of <code class="function">allocate</code> and
|
|
||||||
directly deallocate with every call of
|
|
||||||
<code class="function">deallocate</code>, regardless of efficiency. As it
|
|
||||||
turns out, this last option is also available.
|
|
||||||
</p><p>
|
|
||||||
To globally disable memory caching within the library for the
|
|
||||||
default allocator, merely set
|
|
||||||
<code class="constant">GLIBCXX_FORCE_NEW</code> (with any value) in the
|
|
||||||
system's environment before running the program. If your program
|
|
||||||
crashes with <code class="constant">GLIBCXX_FORCE_NEW</code> in the
|
|
||||||
environment, it likely means that you linked against objects
|
|
||||||
built against the older library (objects which might still using the
|
|
||||||
cached allocations...).
|
|
||||||
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.using"></a>Using a Specific Allocator</h3></div></div></div><p>
|
|
||||||
You can specify different memory management schemes on a
|
|
||||||
per-container basis, by overriding the default
|
|
||||||
<span class="type">Allocator</span> template parameter. For example, an easy
|
|
||||||
(but non-portable) method of specifying that only <code class="function">malloc</code> or <code class="function">free</code>
|
|
||||||
should be used instead of the default node allocator is:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
std::list <int, __gnu_cxx::malloc_allocator<int> > malloc_list;</pre><p>
|
|
||||||
Likewise, a debugging form of whichever allocator is currently in use:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
std::deque <int, __gnu_cxx::debug_allocator<std::allocator<int> > > debug_deque;
|
|
||||||
</pre></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.custom"></a>Custom Allocators</h3></div></div></div><p>
|
|
||||||
Writing a portable C++ allocator would dictate that the interface
|
|
||||||
would look much like the one specified for
|
|
||||||
<code class="classname">allocator</code>. Additional member functions, but
|
|
||||||
not subtractions, would be permissible.
|
|
||||||
</p><p>
|
|
||||||
Probably the best place to start would be to copy one of the
|
|
||||||
extension allocators: say a simple one like
|
|
||||||
<code class="classname">new_allocator</code>.
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.ext"></a>Extension Allocators</h3></div></div></div><p>
|
|
||||||
Several other allocators are provided as part of this
|
|
||||||
implementation. The location of the extension allocators and their
|
|
||||||
names have changed, but in all cases, functionality is
|
|
||||||
equivalent. Starting with gcc-3.4, all extension allocators are
|
|
||||||
standard style. Before this point, SGI style was the norm. Because of
|
|
||||||
this, the number of template arguments also changed. Here's a simple
|
|
||||||
chart to track the changes.
|
|
||||||
</p><p>
|
|
||||||
More details on each of these extension allocators follows.
|
|
||||||
</p><div class="orderedlist"><ol type="1"><li><p>
|
|
||||||
<code class="classname">new_allocator</code>
|
|
||||||
</p><p>
|
|
||||||
Simply wraps <code class="function">::operator new</code>
|
|
||||||
and <code class="function">::operator delete</code>.
|
|
||||||
</p></li><li><p>
|
|
||||||
<code class="classname">malloc_allocator</code>
|
|
||||||
</p><p>
|
|
||||||
Simply wraps <code class="function">malloc</code> and
|
|
||||||
<code class="function">free</code>. There is also a hook for an
|
|
||||||
out-of-memory handler (for
|
|
||||||
<code class="function">new</code>/<code class="function">delete</code> this is
|
|
||||||
taken care of elsewhere).
|
|
||||||
</p></li><li><p>
|
|
||||||
<code class="classname">array_allocator</code>
|
|
||||||
</p><p>
|
|
||||||
Allows allocations of known and fixed sizes using existing
|
|
||||||
global or external storage allocated via construction of
|
|
||||||
<code class="classname">std::tr1::array</code> objects. By using this
|
|
||||||
allocator, fixed size containers (including
|
|
||||||
<code class="classname">std::string</code>) can be used without
|
|
||||||
instances calling <code class="function">::operator new</code> and
|
|
||||||
<code class="function">::operator delete</code>. This capability
|
|
||||||
allows the use of STL abstractions without runtime
|
|
||||||
complications or overhead, even in situations such as program
|
|
||||||
startup. For usage examples, please consult the testsuite.
|
|
||||||
</p></li><li><p>
|
|
||||||
<code class="classname">debug_allocator</code>
|
|
||||||
</p><p>
|
|
||||||
A wrapper around an arbitrary allocator A. It passes on
|
|
||||||
slightly increased size requests to A, and uses the extra
|
|
||||||
memory to store size information. When a pointer is passed
|
|
||||||
to <code class="function">deallocate()</code>, the stored size is
|
|
||||||
checked, and <code class="function">assert()</code> is used to
|
|
||||||
guarantee they match.
|
|
||||||
</p></li><li><p>
|
|
||||||
<code class="classname">throw_allocator</code>
|
|
||||||
</p><p>
|
|
||||||
Includes memory tracking and marking abilities as well as hooks for
|
|
||||||
throwing exceptions at configurable intervals (including random,
|
|
||||||
all, none).
|
|
||||||
</p></li><li><p>
|
|
||||||
<code class="classname">__pool_alloc</code>
|
|
||||||
</p><p>
|
|
||||||
A high-performance, single pool allocator. The reusable
|
|
||||||
memory is shared among identical instantiations of this type.
|
|
||||||
It calls through <code class="function">::operator new</code> to
|
|
||||||
obtain new memory when its lists run out. If a client
|
|
||||||
container requests a block larger than a certain threshold
|
|
||||||
size, then the pool is bypassed, and the allocate/deallocate
|
|
||||||
request is passed to <code class="function">::operator new</code>
|
|
||||||
directly.
|
|
||||||
</p><p>
|
|
||||||
Older versions of this class take a boolean template
|
|
||||||
parameter, called <code class="varname">thr</code>, and an integer template
|
|
||||||
parameter, called <code class="varname">inst</code>.
|
|
||||||
</p><p>
|
|
||||||
The <code class="varname">inst</code> number is used to track additional memory
|
|
||||||
pools. The point of the number is to allow multiple
|
|
||||||
instantiations of the classes without changing the semantics at
|
|
||||||
all. All three of
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
typedef __pool_alloc<true,0> normal;
|
|
||||||
typedef __pool_alloc<true,1> private;
|
|
||||||
typedef __pool_alloc<true,42> also_private;
|
|
||||||
</pre><p>
|
|
||||||
behave exactly the same way. However, the memory pool for each type
|
|
||||||
(and remember that different instantiations result in different types)
|
|
||||||
remains separate.
|
|
||||||
</p><p>
|
|
||||||
The library uses <span class="emphasis"><em>0</em></span> in all its instantiations. If you
|
|
||||||
wish to keep separate free lists for a particular purpose, use a
|
|
||||||
different number.
|
|
||||||
</p><p>The <code class="varname">thr</code> boolean determines whether the
|
|
||||||
pool should be manipulated atomically or not. When
|
|
||||||
<code class="varname">thr</code> = <code class="constant">true</code>, the allocator
|
|
||||||
is is thread-safe, while <code class="varname">thr</code> =
|
|
||||||
<code class="constant">false</code>, and is slightly faster but unsafe for
|
|
||||||
multiple threads.
|
|
||||||
</p><p>
|
|
||||||
For thread-enabled configurations, the pool is locked with a
|
|
||||||
single big lock. In some situations, this implementation detail
|
|
||||||
may result in severe performance degradation.
|
|
||||||
</p><p>
|
|
||||||
(Note that the GCC thread abstraction layer allows us to provide
|
|
||||||
safe zero-overhead stubs for the threading routines, if threads
|
|
||||||
were disabled at configuration time.)
|
|
||||||
</p></li><li><p>
|
|
||||||
<code class="classname">__mt_alloc</code>
|
|
||||||
</p><p>
|
|
||||||
A high-performance fixed-size allocator with
|
|
||||||
exponentially-increasing allocations. It has its own
|
|
||||||
documentation, found <a class="link" href="bk01pt12ch32.html#manual.ext.allocator.mt" title="mt_allocator">here</a>.
|
|
||||||
</p></li><li><p>
|
|
||||||
<code class="classname">bitmap_allocator</code>
|
|
||||||
</p><p>
|
|
||||||
A high-performance allocator that uses a bit-map to keep track
|
|
||||||
of the used and unused memory locations. It has its own
|
|
||||||
documentation, found <a class="link" href="bitmap_allocator.html" title="bitmap_allocator">here</a>.
|
|
||||||
</p></li></ol></div></div><div class="bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id505299"></a><p><span class="title"><i>
|
|
||||||
ISO/IEC 14882:1998 Programming languages - C++
|
|
||||||
</i>. </span>
|
|
||||||
isoc++_1998
|
|
||||||
<span class="pagenums">20.4 Memory. </span></p></div><div class="biblioentry"><a id="id465950"></a><p><span class="title"><i>The Standard Librarian: What Are Allocators Good
|
|
||||||
</i>. </span>
|
|
||||||
austernm
|
|
||||||
<span class="author"><span class="firstname">Matt</span> <span class="surname">Austern</span>. </span><span class="publisher"><span class="publishername">
|
|
||||||
C/C++ Users Journal
|
|
||||||
. </span></span><span class="biblioid">
|
|
||||||
<a class="ulink" href="http://www.cuj.com/documents/s=8000/cujcexp1812austern/" target="_top">
|
|
||||||
</a>
|
|
||||||
. </span></p></div><div class="biblioentry"><a id="id515746"></a><p><span class="title"><i>The Hoard Memory Allocator</i>. </span>
|
|
||||||
emeryb
|
|
||||||
<span class="author"><span class="firstname">Emery</span> <span class="surname">Berger</span>. </span><span class="biblioid">
|
|
||||||
<a class="ulink" href="http://www.cs.umass.edu/~emery/hoard/" target="_top">
|
|
||||||
</a>
|
|
||||||
. </span></p></div><div class="biblioentry"><a id="id507784"></a><p><span class="title"><i>Reconsidering Custom Memory Allocation</i>. </span>
|
|
||||||
bergerzorn
|
|
||||||
<span class="author"><span class="firstname">Emery</span> <span class="surname">Berger</span>. </span><span class="author"><span class="firstname">Ben</span> <span class="surname">Zorn</span>. </span><span class="author"><span class="firstname">Kathryn</span> <span class="surname">McKinley</span>. </span><span class="copyright">Copyright © 2002 OOPSLA. </span><span class="biblioid">
|
|
||||||
<a class="ulink" href="http://www.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf" target="_top">
|
|
||||||
</a>
|
|
||||||
. </span></p></div><div class="biblioentry"><a id="id467782"></a><p><span class="title"><i>Allocator Types</i>. </span>
|
|
||||||
kreftlanger
|
|
||||||
<span class="author"><span class="firstname">Klaus</span> <span class="surname">Kreft</span>. </span><span class="author"><span class="firstname">Angelika</span> <span class="surname">Langer</span>. </span><span class="publisher"><span class="publishername">
|
|
||||||
C/C++ Users Journal
|
|
||||||
. </span></span><span class="biblioid">
|
|
||||||
<a class="ulink" href="http://www.langer.camelot.de/Articles/C++Report/Allocators/Allocators.html" target="_top">
|
|
||||||
</a>
|
|
||||||
. </span></p></div><div class="biblioentry"><a id="id470766"></a><p><span class="title"><i>The C++ Programming Language</i>. </span>
|
|
||||||
tcpl
|
|
||||||
<span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 . </span><span class="pagenums">19.4 Allocators. </span><span class="publisher"><span class="publishername">
|
|
||||||
Addison Wesley
|
|
||||||
. </span></span></p></div><div class="biblioentry"><a id="id468765"></a><p><span class="title"><i>Yalloc: A Recycling C++ Allocator</i>. </span>
|
|
||||||
yenf
|
|
||||||
<span class="author"><span class="firstname">Felix</span> <span class="surname">Yen</span>. </span><span class="copyright">Copyright © . </span><span class="biblioid">
|
|
||||||
<a class="ulink" href="http://home.earthlink.net/~brimar/yalloc/" target="_top">
|
|
||||||
</a>
|
|
||||||
. </span></p></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt04ch10.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="utilities.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auto_ptr.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 10. Pairs </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> auto_ptr</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,4 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 12. Traits</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="utilities.html" title="Part IV. Utilities" /><link rel="prev" href="shared_ptr.html" title="shared_ptr" /><link rel="next" href="strings.html" title="Part V. Strings" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 12. Traits</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="shared_ptr.html">Prev</a> </td><th width="60%" align="center">Part IV. Utilities</th><td width="20%" align="right"> <a accesskey="n" href="strings.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.util.traits"></a>Chapter 12. Traits</h2></div></div></div><p>
|
|
||||||
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="shared_ptr.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="utilities.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="strings.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">shared_ptr </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part V. Strings</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,422 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 14. Locales</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="localization.html" title="Part VI. Localization" /><link rel="prev" href="localization.html" title="Part VI. Localization" /><link rel="next" href="bk01pt06ch15.html" title="Chapter 15. Facets aka Categories" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 14. Locales</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="localization.html">Prev</a> </td><th width="60%" align="center">Part VI. Localization</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt06ch15.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.localization.locales"></a>Chapter 14. Locales</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt06ch14.html#manual.localization.locales.locale">locale</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt06ch14.html#locales.locale.req">Requirements</a></span></dt><dt><span class="sect2"><a href="bk01pt06ch14.html#locales.locale.design">Design</a></span></dt><dt><span class="sect2"><a href="bk01pt06ch14.html#locales.locale.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="bk01pt06ch14.html#locales.locale.future">Future</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.localization.locales.locale"></a>locale</h2></div></div></div><p>
|
|
||||||
Describes the basic locale object, including nested
|
|
||||||
classes id, facet, and the reference-counted implementation object,
|
|
||||||
class _Impl.
|
|
||||||
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="locales.locale.req"></a>Requirements</h3></div></div></div><p>
|
|
||||||
Class locale is non-templatized and has two distinct types nested
|
|
||||||
inside of it:
|
|
||||||
</p><div class="blockquote"><blockquote class="blockquote"><p>
|
|
||||||
<span class="emphasis"><em>
|
|
||||||
class facet
|
|
||||||
22.1.1.1.2 Class locale::facet
|
|
||||||
</em></span>
|
|
||||||
</p></blockquote></div><p>
|
|
||||||
Facets actually implement locale functionality. For instance, a facet
|
|
||||||
called numpunct is the data objects that can be used to query for the
|
|
||||||
thousands separator is in the German locale.
|
|
||||||
</p><p>
|
|
||||||
Literally, a facet is strictly defined:
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>
|
|
||||||
Containing the following public data member:
|
|
||||||
</p><p>
|
|
||||||
<code class="code">static locale::id id;</code>
|
|
||||||
</p></li><li><p>
|
|
||||||
Derived from another facet:
|
|
||||||
</p><p>
|
|
||||||
<code class="code">class gnu_codecvt: public std::ctype<user-defined-type></code>
|
|
||||||
</p></li></ul></div><p>
|
|
||||||
Of interest in this class are the memory management options explicitly
|
|
||||||
specified as an argument to facet's constructor. Each constructor of a
|
|
||||||
facet class takes a std::size_t __refs argument: if __refs == 0, the
|
|
||||||
facet is deleted when the locale containing it is destroyed. If __refs
|
|
||||||
== 1, the facet is not destroyed, even when it is no longer
|
|
||||||
referenced.
|
|
||||||
</p><div class="blockquote"><blockquote class="blockquote"><p>
|
|
||||||
<span class="emphasis"><em>
|
|
||||||
class id
|
|
||||||
22.1.1.1.3 - Class locale::id
|
|
||||||
</em></span>
|
|
||||||
</p></blockquote></div><p>
|
|
||||||
Provides an index for looking up specific facets.
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="locales.locale.design"></a>Design</h3></div></div></div><p>
|
|
||||||
The major design challenge is fitting an object-orientated and
|
|
||||||
non-global locale design on top of POSIX and other relevant standards,
|
|
||||||
which include the Single Unix (nee X/Open.)
|
|
||||||
</p><p>
|
|
||||||
Because C and earlier versions of POSIX fall down so completely,
|
|
||||||
portability is an issue.
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="locales.locale.impl"></a>Implementation</h3></div></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="locale.impl.c"></a>Interacting with "C" locales</h4></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
|
|
||||||
<code class="code">`locale -a`</code> displays available locales.
|
|
||||||
</p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting">
|
|
||||||
af_ZA
|
|
||||||
ar_AE
|
|
||||||
ar_AE.utf8
|
|
||||||
ar_BH
|
|
||||||
ar_BH.utf8
|
|
||||||
ar_DZ
|
|
||||||
ar_DZ.utf8
|
|
||||||
ar_EG
|
|
||||||
ar_EG.utf8
|
|
||||||
ar_IN
|
|
||||||
ar_IQ
|
|
||||||
ar_IQ.utf8
|
|
||||||
ar_JO
|
|
||||||
ar_JO.utf8
|
|
||||||
ar_KW
|
|
||||||
ar_KW.utf8
|
|
||||||
ar_LB
|
|
||||||
ar_LB.utf8
|
|
||||||
ar_LY
|
|
||||||
ar_LY.utf8
|
|
||||||
ar_MA
|
|
||||||
ar_MA.utf8
|
|
||||||
ar_OM
|
|
||||||
ar_OM.utf8
|
|
||||||
ar_QA
|
|
||||||
ar_QA.utf8
|
|
||||||
ar_SA
|
|
||||||
ar_SA.utf8
|
|
||||||
ar_SD
|
|
||||||
ar_SD.utf8
|
|
||||||
ar_SY
|
|
||||||
ar_SY.utf8
|
|
||||||
ar_TN
|
|
||||||
ar_TN.utf8
|
|
||||||
ar_YE
|
|
||||||
ar_YE.utf8
|
|
||||||
be_BY
|
|
||||||
be_BY.utf8
|
|
||||||
bg_BG
|
|
||||||
bg_BG.utf8
|
|
||||||
br_FR
|
|
||||||
bs_BA
|
|
||||||
C
|
|
||||||
ca_ES
|
|
||||||
ca_ES@euro
|
|
||||||
ca_ES.utf8
|
|
||||||
ca_ES.utf8@euro
|
|
||||||
cs_CZ
|
|
||||||
cs_CZ.utf8
|
|
||||||
cy_GB
|
|
||||||
da_DK
|
|
||||||
da_DK.iso885915
|
|
||||||
da_DK.utf8
|
|
||||||
de_AT
|
|
||||||
de_AT@euro
|
|
||||||
de_AT.utf8
|
|
||||||
de_AT.utf8@euro
|
|
||||||
de_BE
|
|
||||||
de_BE@euro
|
|
||||||
de_BE.utf8
|
|
||||||
de_BE.utf8@euro
|
|
||||||
de_CH
|
|
||||||
de_CH.utf8
|
|
||||||
de_DE
|
|
||||||
de_DE@euro
|
|
||||||
de_DE.utf8
|
|
||||||
de_DE.utf8@euro
|
|
||||||
de_LU
|
|
||||||
de_LU@euro
|
|
||||||
de_LU.utf8
|
|
||||||
de_LU.utf8@euro
|
|
||||||
el_GR
|
|
||||||
el_GR.utf8
|
|
||||||
en_AU
|
|
||||||
en_AU.utf8
|
|
||||||
en_BW
|
|
||||||
en_BW.utf8
|
|
||||||
en_CA
|
|
||||||
en_CA.utf8
|
|
||||||
en_DK
|
|
||||||
en_DK.utf8
|
|
||||||
en_GB
|
|
||||||
en_GB.iso885915
|
|
||||||
en_GB.utf8
|
|
||||||
en_HK
|
|
||||||
en_HK.utf8
|
|
||||||
en_IE
|
|
||||||
en_IE@euro
|
|
||||||
en_IE.utf8
|
|
||||||
en_IE.utf8@euro
|
|
||||||
en_IN
|
|
||||||
en_NZ
|
|
||||||
en_NZ.utf8
|
|
||||||
en_PH
|
|
||||||
en_PH.utf8
|
|
||||||
en_SG
|
|
||||||
en_SG.utf8
|
|
||||||
en_US
|
|
||||||
en_US.iso885915
|
|
||||||
en_US.utf8
|
|
||||||
en_ZA
|
|
||||||
en_ZA.utf8
|
|
||||||
en_ZW
|
|
||||||
en_ZW.utf8
|
|
||||||
es_AR
|
|
||||||
es_AR.utf8
|
|
||||||
es_BO
|
|
||||||
es_BO.utf8
|
|
||||||
es_CL
|
|
||||||
es_CL.utf8
|
|
||||||
es_CO
|
|
||||||
es_CO.utf8
|
|
||||||
es_CR
|
|
||||||
es_CR.utf8
|
|
||||||
es_DO
|
|
||||||
es_DO.utf8
|
|
||||||
es_EC
|
|
||||||
es_EC.utf8
|
|
||||||
es_ES
|
|
||||||
es_ES@euro
|
|
||||||
es_ES.utf8
|
|
||||||
es_ES.utf8@euro
|
|
||||||
es_GT
|
|
||||||
es_GT.utf8
|
|
||||||
es_HN
|
|
||||||
es_HN.utf8
|
|
||||||
es_MX
|
|
||||||
es_MX.utf8
|
|
||||||
es_NI
|
|
||||||
es_NI.utf8
|
|
||||||
es_PA
|
|
||||||
es_PA.utf8
|
|
||||||
es_PE
|
|
||||||
es_PE.utf8
|
|
||||||
es_PR
|
|
||||||
es_PR.utf8
|
|
||||||
es_PY
|
|
||||||
es_PY.utf8
|
|
||||||
es_SV
|
|
||||||
es_SV.utf8
|
|
||||||
es_US
|
|
||||||
es_US.utf8
|
|
||||||
es_UY
|
|
||||||
es_UY.utf8
|
|
||||||
es_VE
|
|
||||||
es_VE.utf8
|
|
||||||
et_EE
|
|
||||||
et_EE.utf8
|
|
||||||
eu_ES
|
|
||||||
eu_ES@euro
|
|
||||||
eu_ES.utf8
|
|
||||||
eu_ES.utf8@euro
|
|
||||||
fa_IR
|
|
||||||
fi_FI
|
|
||||||
fi_FI@euro
|
|
||||||
fi_FI.utf8
|
|
||||||
fi_FI.utf8@euro
|
|
||||||
fo_FO
|
|
||||||
fo_FO.utf8
|
|
||||||
fr_BE
|
|
||||||
fr_BE@euro
|
|
||||||
fr_BE.utf8
|
|
||||||
fr_BE.utf8@euro
|
|
||||||
fr_CA
|
|
||||||
fr_CA.utf8
|
|
||||||
fr_CH
|
|
||||||
fr_CH.utf8
|
|
||||||
fr_FR
|
|
||||||
fr_FR@euro
|
|
||||||
fr_FR.utf8
|
|
||||||
fr_FR.utf8@euro
|
|
||||||
fr_LU
|
|
||||||
fr_LU@euro
|
|
||||||
fr_LU.utf8
|
|
||||||
fr_LU.utf8@euro
|
|
||||||
ga_IE
|
|
||||||
ga_IE@euro
|
|
||||||
ga_IE.utf8
|
|
||||||
ga_IE.utf8@euro
|
|
||||||
gl_ES
|
|
||||||
gl_ES@euro
|
|
||||||
gl_ES.utf8
|
|
||||||
gl_ES.utf8@euro
|
|
||||||
gv_GB
|
|
||||||
gv_GB.utf8
|
|
||||||
he_IL
|
|
||||||
he_IL.utf8
|
|
||||||
hi_IN
|
|
||||||
hr_HR
|
|
||||||
hr_HR.utf8
|
|
||||||
hu_HU
|
|
||||||
hu_HU.utf8
|
|
||||||
id_ID
|
|
||||||
id_ID.utf8
|
|
||||||
is_IS
|
|
||||||
is_IS.utf8
|
|
||||||
it_CH
|
|
||||||
it_CH.utf8
|
|
||||||
it_IT
|
|
||||||
it_IT@euro
|
|
||||||
it_IT.utf8
|
|
||||||
it_IT.utf8@euro
|
|
||||||
iw_IL
|
|
||||||
iw_IL.utf8
|
|
||||||
ja_JP.eucjp
|
|
||||||
ja_JP.utf8
|
|
||||||
ka_GE
|
|
||||||
kl_GL
|
|
||||||
kl_GL.utf8
|
|
||||||
ko_KR.euckr
|
|
||||||
ko_KR.utf8
|
|
||||||
kw_GB
|
|
||||||
kw_GB.utf8
|
|
||||||
lt_LT
|
|
||||||
lt_LT.utf8
|
|
||||||
lv_LV
|
|
||||||
lv_LV.utf8
|
|
||||||
mi_NZ
|
|
||||||
mk_MK
|
|
||||||
mk_MK.utf8
|
|
||||||
mr_IN
|
|
||||||
ms_MY
|
|
||||||
ms_MY.utf8
|
|
||||||
mt_MT
|
|
||||||
mt_MT.utf8
|
|
||||||
nl_BE
|
|
||||||
nl_BE@euro
|
|
||||||
nl_BE.utf8
|
|
||||||
nl_BE.utf8@euro
|
|
||||||
nl_NL
|
|
||||||
nl_NL@euro
|
|
||||||
nl_NL.utf8
|
|
||||||
nl_NL.utf8@euro
|
|
||||||
nn_NO
|
|
||||||
nn_NO.utf8
|
|
||||||
no_NO
|
|
||||||
no_NO.utf8
|
|
||||||
oc_FR
|
|
||||||
pl_PL
|
|
||||||
pl_PL.utf8
|
|
||||||
POSIX
|
|
||||||
pt_BR
|
|
||||||
pt_BR.utf8
|
|
||||||
pt_PT
|
|
||||||
pt_PT@euro
|
|
||||||
pt_PT.utf8
|
|
||||||
pt_PT.utf8@euro
|
|
||||||
ro_RO
|
|
||||||
ro_RO.utf8
|
|
||||||
ru_RU
|
|
||||||
ru_RU.koi8r
|
|
||||||
ru_RU.utf8
|
|
||||||
ru_UA
|
|
||||||
ru_UA.utf8
|
|
||||||
se_NO
|
|
||||||
sk_SK
|
|
||||||
sk_SK.utf8
|
|
||||||
sl_SI
|
|
||||||
sl_SI.utf8
|
|
||||||
sq_AL
|
|
||||||
sq_AL.utf8
|
|
||||||
sr_YU
|
|
||||||
sr_YU@cyrillic
|
|
||||||
sr_YU.utf8
|
|
||||||
sr_YU.utf8@cyrillic
|
|
||||||
sv_FI
|
|
||||||
sv_FI@euro
|
|
||||||
sv_FI.utf8
|
|
||||||
sv_FI.utf8@euro
|
|
||||||
sv_SE
|
|
||||||
sv_SE.iso885915
|
|
||||||
sv_SE.utf8
|
|
||||||
ta_IN
|
|
||||||
te_IN
|
|
||||||
tg_TJ
|
|
||||||
th_TH
|
|
||||||
th_TH.utf8
|
|
||||||
tl_PH
|
|
||||||
tr_TR
|
|
||||||
tr_TR.utf8
|
|
||||||
uk_UA
|
|
||||||
uk_UA.utf8
|
|
||||||
ur_PK
|
|
||||||
uz_UZ
|
|
||||||
vi_VN
|
|
||||||
vi_VN.tcvn
|
|
||||||
wa_BE
|
|
||||||
wa_BE@euro
|
|
||||||
yi_US
|
|
||||||
zh_CN
|
|
||||||
zh_CN.gb18030
|
|
||||||
zh_CN.gbk
|
|
||||||
zh_CN.utf8
|
|
||||||
zh_HK
|
|
||||||
zh_HK.utf8
|
|
||||||
zh_TW
|
|
||||||
zh_TW.euctw
|
|
||||||
zh_TW.utf8
|
|
||||||
</pre></blockquote></div></li><li><p>
|
|
||||||
<code class="code">`locale`</code> displays environmental variables that
|
|
||||||
impact how locale("") will be deduced.
|
|
||||||
</p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting">
|
|
||||||
LANG=en_US
|
|
||||||
LC_CTYPE="en_US"
|
|
||||||
LC_NUMERIC="en_US"
|
|
||||||
LC_TIME="en_US"
|
|
||||||
LC_COLLATE="en_US"
|
|
||||||
LC_MONETARY="en_US"
|
|
||||||
LC_MESSAGES="en_US"
|
|
||||||
LC_PAPER="en_US"
|
|
||||||
LC_NAME="en_US"
|
|
||||||
LC_ADDRESS="en_US"
|
|
||||||
LC_TELEPHONE="en_US"
|
|
||||||
LC_MEASUREMENT="en_US"
|
|
||||||
LC_IDENTIFICATION="en_US"
|
|
||||||
LC_ALL=
|
|
||||||
</pre></blockquote></div></li></ul></div><p>
|
|
||||||
From Josuttis, p. 697-698, which says, that "there is only *one*
|
|
||||||
relation (of the C++ locale mechanism) to the C locale mechanism: the
|
|
||||||
global C locale is modified if a named C++ locale object is set as the
|
|
||||||
global locale" (emphasis Paolo), that is:
|
|
||||||
</p><pre class="programlisting">std::locale::global(std::locale(""));</pre><p>affects the C functions as if the following call was made:</p><pre class="programlisting">std::setlocale(LC_ALL, "");</pre><p>
|
|
||||||
On the other hand, there is *no* vice versa, that is, calling
|
|
||||||
setlocale has *no* whatsoever on the C++ locale mechanism, in
|
|
||||||
particular on the working of locale(""), which constructs the locale
|
|
||||||
object from the environment of the running program, that is, in
|
|
||||||
practice, the set of LC_ALL, LANG, etc. variable of the shell.
|
|
||||||
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="locales.locale.future"></a>Future</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
|
|
||||||
Locale initialization: at what point does _S_classic, _S_global
|
|
||||||
get initialized? Can named locales assume this initialization
|
|
||||||
has already taken place?
|
|
||||||
</p></li><li><p>
|
|
||||||
Document how named locales error check when filling data
|
|
||||||
members. I.e., a fr_FR locale that doesn't have
|
|
||||||
numpunct::truename(): does it use "true"? Or is it a blank
|
|
||||||
string? What's the convention?
|
|
||||||
</p></li><li><p>
|
|
||||||
Explain how locale aliasing happens. When does "de_DE" use "de"
|
|
||||||
information? What is the rule for locales composed of just an
|
|
||||||
ISO language code (say, "de") and locales with both an ISO
|
|
||||||
language code and ISO country code (say, "de_DE").
|
|
||||||
</p></li><li><p>
|
|
||||||
What should non-required facet instantiations do? If the
|
|
||||||
generic implementation is provided, then how to end-users
|
|
||||||
provide specializations?
|
|
||||||
</p></li></ul></div></div><div class="bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="locales.locale.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id459942"></a><p><span class="title"><i>
|
|
||||||
The GNU C Library
|
|
||||||
</i>. </span><span class="author"><span class="firstname">Roland</span> <span class="surname">McGrath</span>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2007 FSF. </span><span class="pagenums">Chapters 6 Character Set Handling and 7 Locales and Internationalization. </span></p></div><div class="biblioentry"><a id="id551010"></a><p><span class="title"><i>
|
|
||||||
Correspondence
|
|
||||||
</i>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2002 . </span></p></div><div class="biblioentry"><a id="id551039"></a><p><span class="title"><i>
|
|
||||||
ISO/IEC 14882:1998 Programming languages - C++
|
|
||||||
</i>. </span><span class="copyright">Copyright © 1998 ISO. </span></p></div><div class="biblioentry"><a id="id474312"></a><p><span class="title"><i>
|
|
||||||
ISO/IEC 9899:1999 Programming languages - C
|
|
||||||
</i>. </span><span class="copyright">Copyright © 1999 ISO. </span></p></div><div class="biblioentry"><a id="id474331"></a><p><span class="title"><i>
|
|
||||||
System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
|
|
||||||
</i>. </span><span class="copyright">Copyright © 1999
|
|
||||||
The Open Group/The Institute of Electrical and Electronics Engineers, Inc.. </span><span class="biblioid">
|
|
||||||
<a class="ulink" href="http://www.opennc.org/austin/docreg.html" target="_top">
|
|
||||||
</a>
|
|
||||||
. </span></p></div><div class="biblioentry"><a id="id516648"></a><p><span class="title"><i>
|
|
||||||
The C++ Programming Language, Special Edition
|
|
||||||
</i>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley, Inc.. </span><span class="pagenums">Appendix D. </span><span class="publisher"><span class="publishername">
|
|
||||||
Addison Wesley
|
|
||||||
. </span></span></p></div><div class="biblioentry"><a id="id481148"></a><p><span class="title"><i>
|
|
||||||
Standard C++ IOStreams and Locales
|
|
||||||
</i>. </span><span class="subtitle">
|
|
||||||
Advanced Programmer's Guide and Reference
|
|
||||||
. </span><span class="author"><span class="firstname">Angelika</span> <span class="surname">Langer</span>. </span><span class="author"><span class="firstname">Klaus</span> <span class="surname">Kreft</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley Longman, Inc.. </span><span class="publisher"><span class="publishername">
|
|
||||||
Addison Wesley Longman
|
|
||||||
. </span></span></p></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="localization.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="localization.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt06ch15.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part VI. Localization </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 15. Facets aka Categories</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,74 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 15. Facets aka Categories</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="localization.html" title="Part VI. Localization" /><link rel="prev" href="bk01pt06ch14.html" title="Chapter 14. Locales" /><link rel="next" href="codecvt.html" title="codecvt" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 15. Facets aka Categories</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt06ch14.html">Prev</a> </td><th width="60%" align="center">Part VI. Localization</th><td width="20%" align="right"> <a accesskey="n" href="codecvt.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.localization.facet"></a>Chapter 15. Facets aka Categories</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt06ch15.html#manual.localization.facet.ctype">ctype</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt06ch15.html#facet.ctype.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="bk01pt06ch15.html#facet.ctype.future">Future</a></span></dt></dl></dd><dt><span class="sect1"><a href="codecvt.html">codecvt</a></span></dt><dd><dl><dt><span class="sect2"><a href="codecvt.html#facet.codecvt.req">Requirements</a></span></dt><dt><span class="sect2"><a href="codecvt.html#facet.codecvt.design">Design</a></span></dt><dt><span class="sect2"><a href="codecvt.html#facet.codecvt.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="codecvt.html#facet.codecvt.use">Use</a></span></dt><dt><span class="sect2"><a href="codecvt.html#facet.codecvt.future">Future</a></span></dt></dl></dd><dt><span class="sect1"><a href="messages.html">messages</a></span></dt><dd><dl><dt><span class="sect2"><a href="messages.html#facet.messages.req">Requirements</a></span></dt><dt><span class="sect2"><a href="messages.html#facet.messages.design">Design</a></span></dt><dt><span class="sect2"><a href="messages.html#facet.messages.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="messages.html#facet.messages.use">Use</a></span></dt><dt><span class="sect2"><a href="messages.html#facet.messages.future">Future</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.localization.facet.ctype"></a>ctype</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="facet.ctype.impl"></a>Implementation</h3></div></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="id461922"></a>Specializations</h4></div></div></div><p>
|
|
||||||
For the required specialization codecvt<wchar_t, char, mbstate_t> ,
|
|
||||||
conversions are made between the internal character set (always UCS4
|
|
||||||
on GNU/Linux) and whatever the currently selected locale for the
|
|
||||||
LC_CTYPE category implements.
|
|
||||||
</p><p>
|
|
||||||
The two required specializations are implemented as follows:
|
|
||||||
</p><p>
|
|
||||||
<code class="code">
|
|
||||||
ctype<char>
|
|
||||||
</code>
|
|
||||||
</p><p>
|
|
||||||
This is simple specialization. Implementing this was a piece of cake.
|
|
||||||
</p><p>
|
|
||||||
<code class="code">
|
|
||||||
ctype<wchar_t>
|
|
||||||
</code>
|
|
||||||
</p><p>
|
|
||||||
This specialization, by specifying all the template parameters, pretty
|
|
||||||
much ties the hands of implementors. As such, the implementation is
|
|
||||||
straightforward, involving mcsrtombs for the conversions between char
|
|
||||||
to wchar_t and wcsrtombs for conversions between wchar_t and char.
|
|
||||||
</p><p>
|
|
||||||
Neither of these two required specializations deals with Unicode
|
|
||||||
characters.
|
|
||||||
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="facet.ctype.future"></a>Future</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
|
|
||||||
How to deal with the global locale issue?
|
|
||||||
</p></li><li><p>
|
|
||||||
How to deal with different types than char, wchar_t? </p></li><li><p>
|
|
||||||
Overlap between codecvt/ctype: narrow/widen
|
|
||||||
</p></li><li><p>
|
|
||||||
Mask typedef in codecvt_base, argument types in codecvt. what
|
|
||||||
is know about this type?
|
|
||||||
</p></li><li><p>
|
|
||||||
Why mask* argument in codecvt?
|
|
||||||
</p></li><li><p>
|
|
||||||
Can this be made (more) generic? is there a simple way to
|
|
||||||
straighten out the configure-time mess that is a by-product of
|
|
||||||
this class?
|
|
||||||
</p></li><li><p>
|
|
||||||
Get the ctype<wchar_t>::mask stuff under control. Need to
|
|
||||||
make some kind of static table, and not do lookup every time
|
|
||||||
somebody hits the do_is... functions. Too bad we can't just
|
|
||||||
redefine mask for ctype<wchar_t>
|
|
||||||
</p></li><li><p>
|
|
||||||
Rename abstract base class. See if just smash-overriding is a
|
|
||||||
better approach. Clarify, add sanity to naming.
|
|
||||||
</p></li></ul></div></div><div class="bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="facet.ctype.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id477855"></a><p><span class="title"><i>
|
|
||||||
The GNU C Library
|
|
||||||
</i>. </span><span class="author"><span class="firstname">Roland</span> <span class="surname">McGrath</span>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2007 FSF. </span><span class="pagenums">Chapters 6 Character Set Handling and 7 Locales and Internationalization. </span></p></div><div class="biblioentry"><a id="id462336"></a><p><span class="title"><i>
|
|
||||||
Correspondence
|
|
||||||
</i>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="copyright">Copyright © 2002 . </span></p></div><div class="biblioentry"><a id="id516995"></a><p><span class="title"><i>
|
|
||||||
ISO/IEC 14882:1998 Programming languages - C++
|
|
||||||
</i>. </span><span class="copyright">Copyright © 1998 ISO. </span></p></div><div class="biblioentry"><a id="id517013"></a><p><span class="title"><i>
|
|
||||||
ISO/IEC 9899:1999 Programming languages - C
|
|
||||||
</i>. </span><span class="copyright">Copyright © 1999 ISO. </span></p></div><div class="biblioentry"><a id="id535750"></a><p><span class="title"><i>
|
|
||||||
System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
|
|
||||||
</i>. </span><span class="copyright">Copyright © 1999
|
|
||||||
The Open Group/The Institute of Electrical and Electronics Engineers, Inc.. </span><span class="biblioid">
|
|
||||||
<a class="ulink" href="http://www.opennc.org/austin/docreg.html" target="_top">
|
|
||||||
</a>
|
|
||||||
. </span></p></div><div class="biblioentry"><a id="id535776"></a><p><span class="title"><i>
|
|
||||||
The C++ Programming Language, Special Edition
|
|
||||||
</i>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley, Inc.. </span><span class="pagenums">Appendix D. </span><span class="publisher"><span class="publishername">
|
|
||||||
Addison Wesley
|
|
||||||
. </span></span></p></div><div class="biblioentry"><a id="id477745"></a><p><span class="title"><i>
|
|
||||||
Standard C++ IOStreams and Locales
|
|
||||||
</i>. </span><span class="subtitle">
|
|
||||||
Advanced Programmer's Guide and Reference
|
|
||||||
. </span><span class="author"><span class="firstname">Angelika</span> <span class="surname">Langer</span>. </span><span class="author"><span class="firstname">Klaus</span> <span class="surname">Kreft</span>. </span><span class="copyright">Copyright © 2000 Addison Wesley Longman, Inc.. </span><span class="publisher"><span class="publishername">
|
|
||||||
Addison Wesley Longman
|
|
||||||
. </span></span></p></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt06ch14.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="localization.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="codecvt.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 14. Locales </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> codecvt</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,37 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 16. Sequences</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="containers.html" title="Part VII. Containers" /><link rel="prev" href="containers.html" title="Part VII. Containers" /><link rel="next" href="bk01pt07ch16s02.html" title="vector" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 16. Sequences</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="containers.html">Prev</a> </td><th width="60%" align="center">Part VII. Containers</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt07ch16s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.containers.sequences"></a>Chapter 16. Sequences</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt07ch16.html#containers.sequences.list">list</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt07ch16.html#sequences.list.size">list::size() is O(n)</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt07ch16s02.html">vector</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt07ch16s02.html#sequences.vector.management">Space Overhead Management</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="containers.sequences.list"></a>list</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sequences.list.size"></a>list::size() is O(n)</h3></div></div></div><p>
|
|
||||||
Yes it is, and that's okay. This is a decision that we preserved
|
|
||||||
when we imported SGI's STL implementation. The following is
|
|
||||||
quoted from <a class="ulink" href="http://www.sgi.com/tech/stl/FAQ.html" target="_top">their FAQ</a>:
|
|
||||||
</p><div class="blockquote"><blockquote class="blockquote"><p>
|
|
||||||
The size() member function, for list and slist, takes time
|
|
||||||
proportional to the number of elements in the list. This was a
|
|
||||||
deliberate tradeoff. The only way to get a constant-time
|
|
||||||
size() for linked lists would be to maintain an extra member
|
|
||||||
variable containing the list's size. This would require taking
|
|
||||||
extra time to update that variable (it would make splice() a
|
|
||||||
linear time operation, for example), and it would also make the
|
|
||||||
list larger. Many list algorithms don't require that extra
|
|
||||||
word (algorithms that do require it might do better with
|
|
||||||
vectors than with lists), and, when it is necessary to maintain
|
|
||||||
an explicit size count, it's something that users can do
|
|
||||||
themselves.
|
|
||||||
</p><p>
|
|
||||||
This choice is permitted by the C++ standard. The standard says
|
|
||||||
that size() “<span class="quote">should</span>” be constant time, and
|
|
||||||
“<span class="quote">should</span>” does not mean the same thing as
|
|
||||||
“<span class="quote">shall</span>”. This is the officially recommended ISO
|
|
||||||
wording for saying that an implementation is supposed to do
|
|
||||||
something unless there is a good reason not to.
|
|
||||||
</p><p>
|
|
||||||
One implication of linear time size(): you should never write
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
if (L.size() == 0)
|
|
||||||
...
|
|
||||||
</pre><p>
|
|
||||||
Instead, you should write
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
if (L.empty())
|
|
||||||
...
|
|
||||||
</pre></blockquote></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="containers.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="containers.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt07ch16s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part VII. Containers </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> vector</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,16 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>vector</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt07ch16.html" title="Chapter 16. Sequences" /><link rel="prev" href="bk01pt07ch16.html" title="Chapter 16. Sequences" /><link rel="next" href="bk01pt07ch17.html" title="Chapter 17. Associative" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">vector</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt07ch16.html">Prev</a> </td><th width="60%" align="center">Chapter 16. Sequences</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt07ch17.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="containers.sequences.vector"></a>vector</h2></div></div></div><p>
|
|
||||||
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sequences.vector.management"></a>Space Overhead Management</h3></div></div></div><p>
|
|
||||||
In <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-04/msg00105.html" target="_top">this
|
|
||||||
message to the list</a>, Daniel Kostecky announced work on an
|
|
||||||
alternate form of <code class="code">std::vector</code> that would support
|
|
||||||
hints on the number of elements to be over-allocated. The design
|
|
||||||
was also described, along with possible implementation choices.
|
|
||||||
</p><p>
|
|
||||||
The first two alpha releases were announced <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00048.html" target="_top">here</a>
|
|
||||||
and <a class="ulink" href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00111.html" target="_top">here</a>.
|
|
||||||
The releases themselves are available at
|
|
||||||
<a class="ulink" href="http://www.kotelna.sk/dk/sw/caphint/" target="_top">
|
|
||||||
http://www.kotelna.sk/dk/sw/caphint/</a>.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt07ch16.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt07ch16.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt07ch17.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 16. Sequences </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 17. Associative</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,84 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 17. Associative</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="containers.html" title="Part VII. Containers" /><link rel="prev" href="bk01pt07ch16s02.html" title="vector" /><link rel="next" href="bk01pt07ch17s02.html" title="bitset" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 17. Associative</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt07ch16s02.html">Prev</a> </td><th width="60%" align="center">Part VII. Containers</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt07ch17s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.containers.associative"></a>Chapter 17. Associative</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt07ch17.html#containers.associative.insert_hints">Insertion Hints</a></span></dt><dt><span class="sect1"><a href="bk01pt07ch17s02.html">bitset</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt07ch17s02.html#associative.bitset.size_variable">Size Variable</a></span></dt><dt><span class="sect2"><a href="bk01pt07ch17s02.html#associative.bitset.type_string">Type String</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="containers.associative.insert_hints"></a>Insertion Hints</h2></div></div></div><p>
|
|
||||||
Section [23.1.2], Table 69, of the C++ standard lists this
|
|
||||||
function for all of the associative containers (map, set, etc):
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
a.insert(p,t);
|
|
||||||
</pre><p>
|
|
||||||
where 'p' is an iterator into the container 'a', and 't' is the
|
|
||||||
item to insert. The standard says that “<span class="quote"><code class="code">t</code> is
|
|
||||||
inserted as close as possible to the position just prior to
|
|
||||||
<code class="code">p</code>.</span>” (Library DR #233 addresses this topic,
|
|
||||||
referring to <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1780.html" target="_top">N1780</a>.
|
|
||||||
Since version 4.2 GCC implements the resolution to DR 233, so
|
|
||||||
that insertions happen as close as possible to the hint. For
|
|
||||||
earlier releases the hint was only used as described below.
|
|
||||||
</p><p>
|
|
||||||
Here we'll describe how the hinting works in the libstdc++
|
|
||||||
implementation, and what you need to do in order to take
|
|
||||||
advantage of it. (Insertions can change from logarithmic
|
|
||||||
complexity to amortized constant time, if the hint is properly
|
|
||||||
used.) Also, since the current implementation is based on the
|
|
||||||
SGI STL one, these points may hold true for other library
|
|
||||||
implementations also, since the HP/SGI code is used in a lot of
|
|
||||||
places.
|
|
||||||
</p><p>
|
|
||||||
In the following text, the phrases <span class="emphasis"><em>greater
|
|
||||||
than</em></span> and <span class="emphasis"><em>less than</em></span> refer to the
|
|
||||||
results of the strict weak ordering imposed on the container by
|
|
||||||
its comparison object, which defaults to (basically)
|
|
||||||
“<span class="quote"><</span>”. Using those phrases is semantically sloppy,
|
|
||||||
but I didn't want to get bogged down in syntax. I assume that if
|
|
||||||
you are intelligent enough to use your own comparison objects,
|
|
||||||
you are also intelligent enough to assign “<span class="quote">greater</span>”
|
|
||||||
and “<span class="quote">lesser</span>” their new meanings in the next
|
|
||||||
paragraph. *grin*
|
|
||||||
</p><p>
|
|
||||||
If the <code class="code">hint</code> parameter ('p' above) is equivalent to:
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>
|
|
||||||
<code class="code">begin()</code>, then the item being inserted should
|
|
||||||
have a key less than all the other keys in the container.
|
|
||||||
The item will be inserted at the beginning of the container,
|
|
||||||
becoming the new entry at <code class="code">begin()</code>.
|
|
||||||
</p></li><li><p>
|
|
||||||
<code class="code">end()</code>, then the item being inserted should have
|
|
||||||
a key greater than all the other keys in the container. The
|
|
||||||
item will be inserted at the end of the container, becoming
|
|
||||||
the new entry at <code class="code">end()</code>.
|
|
||||||
</p></li><li><p>
|
|
||||||
neither <code class="code">begin()</code> nor <code class="code">end()</code>, then:
|
|
||||||
Let <code class="code">h</code> be the entry in the container pointed to
|
|
||||||
by <code class="code">hint</code>, that is, <code class="code">h = *hint</code>. Then
|
|
||||||
the item being inserted should have a key less than that of
|
|
||||||
<code class="code">h</code>, and greater than that of the item preceding
|
|
||||||
<code class="code">h</code>. The new item will be inserted between
|
|
||||||
<code class="code">h</code> and <code class="code">h</code>'s predecessor.
|
|
||||||
</p></li></ul></div><p>
|
|
||||||
For <code class="code">multimap</code> and <code class="code">multiset</code>, the
|
|
||||||
restrictions are slightly looser: “<span class="quote">greater than</span>”
|
|
||||||
should be replaced by “<span class="quote">not less than</span>”and “<span class="quote">less
|
|
||||||
than</span>” should be replaced by “<span class="quote">not greater
|
|
||||||
than.</span>” (Why not replace greater with
|
|
||||||
greater-than-or-equal-to? You probably could in your head, but
|
|
||||||
the mathematicians will tell you that it isn't the same thing.)
|
|
||||||
</p><p>
|
|
||||||
If the conditions are not met, then the hint is not used, and the
|
|
||||||
insertion proceeds as if you had called <code class="code"> a.insert(t)
|
|
||||||
</code> instead. (<span class="emphasis"><em>Note </em></span> that GCC releases
|
|
||||||
prior to 3.0.2 had a bug in the case with <code class="code">hint ==
|
|
||||||
begin()</code> for the <code class="code">map</code> and <code class="code">set</code>
|
|
||||||
classes. You should not use a hint argument in those releases.)
|
|
||||||
</p><p>
|
|
||||||
This behavior goes well with other containers'
|
|
||||||
<code class="code">insert()</code> functions which take an iterator: if used,
|
|
||||||
the new item will be inserted before the iterator passed as an
|
|
||||||
argument, same as the other containers.
|
|
||||||
</p><p>
|
|
||||||
<span class="emphasis"><em>Note </em></span> also that the hint in this
|
|
||||||
implementation is a one-shot. The older insertion-with-hint
|
|
||||||
routines check the immediately surrounding entries to ensure that
|
|
||||||
the new item would in fact belong there. If the hint does not
|
|
||||||
point to the correct place, then no further local searching is
|
|
||||||
done; the search begins from scratch in logarithmic time.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt07ch16s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="containers.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt07ch17s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">vector </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> bitset</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,105 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>bitset</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="bk01pt07ch17.html" title="Chapter 17. Associative" /><link rel="prev" href="bk01pt07ch17.html" title="Chapter 17. Associative" /><link rel="next" href="bk01pt07ch18.html" title="Chapter 18. Interacting with C" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">bitset</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt07ch17.html">Prev</a> </td><th width="60%" align="center">Chapter 17. Associative</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt07ch18.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="containers.associative.bitset"></a>bitset</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="associative.bitset.size_variable"></a>Size Variable</h3></div></div></div><p>
|
|
||||||
No, you cannot write code of the form
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
#include <bitset>
|
|
||||||
|
|
||||||
void foo (size_t n)
|
|
||||||
{
|
|
||||||
std::bitset<n> bits;
|
|
||||||
....
|
|
||||||
}
|
|
||||||
</pre><p>
|
|
||||||
because <code class="code">n</code> must be known at compile time. Your
|
|
||||||
compiler is correct; it is not a bug. That's the way templates
|
|
||||||
work. (Yes, it <span class="emphasis"><em>is</em></span> a feature.)
|
|
||||||
</p><p>
|
|
||||||
There are a couple of ways to handle this kind of thing. Please
|
|
||||||
consider all of them before passing judgement. They include, in
|
|
||||||
no particular order:
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>A very large N in <code class="code">bitset<N></code>.</p></li><li><p>A container<bool>.</p></li><li><p>Extremely weird solutions.</p></li></ul></div><p>
|
|
||||||
<span class="emphasis"><em>A very large N in
|
|
||||||
<code class="code">bitset<N></code>. </em></span> It has been
|
|
||||||
pointed out a few times in newsgroups that N bits only takes up
|
|
||||||
(N/8) bytes on most systems, and division by a factor of eight is
|
|
||||||
pretty impressive when speaking of memory. Half a megabyte given
|
|
||||||
over to a bitset (recall that there is zero space overhead for
|
|
||||||
housekeeping info; it is known at compile time exactly how large
|
|
||||||
the set is) will hold over four million bits. If you're using
|
|
||||||
those bits as status flags (e.g.,
|
|
||||||
“<span class="quote">changed</span>”/“<span class="quote">unchanged</span>” flags), that's a
|
|
||||||
<span class="emphasis"><em>lot</em></span> of state.
|
|
||||||
</p><p>
|
|
||||||
You can then keep track of the “<span class="quote">maximum bit used</span>”
|
|
||||||
during some testing runs on representative data, make note of how
|
|
||||||
many of those bits really need to be there, and then reduce N to
|
|
||||||
a smaller number. Leave some extra space, of course. (If you
|
|
||||||
plan to write code like the incorrect example above, where the
|
|
||||||
bitset is a local variable, then you may have to talk your
|
|
||||||
compiler into allowing that much stack space; there may be zero
|
|
||||||
space overhead, but it's all allocated inside the object.)
|
|
||||||
</p><p>
|
|
||||||
<span class="emphasis"><em>A container<bool>. </em></span> The
|
|
||||||
Committee made provision for the space savings possible with that
|
|
||||||
(N/8) usage previously mentioned, so that you don't have to do
|
|
||||||
wasteful things like <code class="code">Container<char></code> or
|
|
||||||
<code class="code">Container<short int></code>. Specifically,
|
|
||||||
<code class="code">vector<bool></code> is required to be specialized for
|
|
||||||
that space savings.
|
|
||||||
</p><p>
|
|
||||||
The problem is that <code class="code">vector<bool></code> doesn't
|
|
||||||
behave like a normal vector anymore. There have been recent
|
|
||||||
journal articles which discuss the problems (the ones by Herb
|
|
||||||
Sutter in the May and July/August 1999 issues of C++ Report cover
|
|
||||||
it well). Future revisions of the ISO C++ Standard will change
|
|
||||||
the requirement for <code class="code">vector<bool></code>
|
|
||||||
specialization. In the meantime, <code class="code">deque<bool></code>
|
|
||||||
is recommended (although its behavior is sane, you probably will
|
|
||||||
not get the space savings, but the allocation scheme is different
|
|
||||||
than that of vector).
|
|
||||||
</p><p>
|
|
||||||
<span class="emphasis"><em>Extremely weird solutions. </em></span> If
|
|
||||||
you have access to the compiler and linker at runtime, you can do
|
|
||||||
something insane, like figuring out just how many bits you need,
|
|
||||||
then writing a temporary source code file. That file contains an
|
|
||||||
instantiation of <code class="code">bitset</code> for the required number of
|
|
||||||
bits, inside some wrapper functions with unchanging signatures.
|
|
||||||
Have your program then call the compiler on that file using
|
|
||||||
Position Independent Code, then open the newly-created object
|
|
||||||
file and load those wrapper functions. You'll have an
|
|
||||||
instantiation of <code class="code">bitset<N></code> for the exact
|
|
||||||
<code class="code">N</code> that you need at the time. Don't forget to delete
|
|
||||||
the temporary files. (Yes, this <span class="emphasis"><em>can</em></span> be, and
|
|
||||||
<span class="emphasis"><em>has been</em></span>, done.)
|
|
||||||
</p><p>
|
|
||||||
This would be the approach of either a visionary genius or a
|
|
||||||
raving lunatic, depending on your programming and management
|
|
||||||
style. Probably the latter.
|
|
||||||
</p><p>
|
|
||||||
Which of the above techniques you use, if any, are up to you and
|
|
||||||
your intended application. Some time/space profiling is
|
|
||||||
indicated if it really matters (don't just guess). And, if you
|
|
||||||
manage to do anything along the lines of the third category, the
|
|
||||||
author would love to hear from you...
|
|
||||||
</p><p>
|
|
||||||
Also note that the implementation of bitset used in libstdc++ has
|
|
||||||
<a class="ulink" href="../ext/sgiexts.html#ch23" target="_top">some extensions</a>.
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="associative.bitset.type_string"></a>Type String</h3></div></div></div><p>
|
|
||||||
</p><p>
|
|
||||||
Bitmasks do not take char* nor const char* arguments in their
|
|
||||||
constructors. This is something of an accident, but you can read
|
|
||||||
about the problem: follow the library's “<span class="quote">Links</span>” from
|
|
||||||
the homepage, and from the C++ information “<span class="quote">defect
|
|
||||||
reflector</span>” link, select the library issues list. Issue
|
|
||||||
number 116 describes the problem.
|
|
||||||
</p><p>
|
|
||||||
For now you can simply make a temporary string object using the
|
|
||||||
constructor expression:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
std::bitset<5> b ( std::string(“<span class="quote">10110</span>”) );
|
|
||||||
</pre><p>
|
|
||||||
instead of
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
std::bitset<5> b ( “<span class="quote">10110</span>” ); // invalid
|
|
||||||
</pre></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt07ch17.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="bk01pt07ch17.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt07ch18.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 17. Associative </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 18. Interacting with C</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,60 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 18. Interacting with C</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="containers.html" title="Part VII. Containers" /><link rel="prev" href="bk01pt07ch17s02.html" title="bitset" /><link rel="next" href="iterators.html" title="Part VIII. Iterators" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 18. Interacting with C</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt07ch17s02.html">Prev</a> </td><th width="60%" align="center">Part VII. Containers</th><td width="20%" align="right"> <a accesskey="n" href="iterators.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.containers.c"></a>Chapter 18. Interacting with C</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt07ch18.html#containers.c.vs_array">Containers vs. Arrays</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="containers.c.vs_array"></a>Containers vs. Arrays</h2></div></div></div><p>
|
|
||||||
You're writing some code and can't decide whether to use builtin
|
|
||||||
arrays or some kind of container. There are compelling reasons
|
|
||||||
to use one of the container classes, but you're afraid that
|
|
||||||
you'll eventually run into difficulties, change everything back
|
|
||||||
to arrays, and then have to change all the code that uses those
|
|
||||||
data types to keep up with the change.
|
|
||||||
</p><p>
|
|
||||||
If your code makes use of the standard algorithms, this isn't as
|
|
||||||
scary as it sounds. The algorithms don't know, nor care, about
|
|
||||||
the kind of “<span class="quote">container</span>” on which they work, since
|
|
||||||
the algorithms are only given endpoints to work with. For the
|
|
||||||
container classes, these are iterators (usually
|
|
||||||
<code class="code">begin()</code> and <code class="code">end()</code>, but not always).
|
|
||||||
For builtin arrays, these are the address of the first element
|
|
||||||
and the <a class="ulink" href="../24_iterators/howto.html#2" target="_top">past-the-end</a> element.
|
|
||||||
</p><p>
|
|
||||||
Some very simple wrapper functions can hide all of that from the
|
|
||||||
rest of the code. For example, a pair of functions called
|
|
||||||
<code class="code">beginof</code> can be written, one that takes an array,
|
|
||||||
another that takes a vector. The first returns a pointer to the
|
|
||||||
first element, and the second returns the vector's
|
|
||||||
<code class="code">begin()</code> iterator.
|
|
||||||
</p><p>
|
|
||||||
The functions should be made template functions, and should also
|
|
||||||
be declared inline. As pointed out in the comments in the code
|
|
||||||
below, this can lead to <code class="code">beginof</code> being optimized out
|
|
||||||
of existence, so you pay absolutely nothing in terms of increased
|
|
||||||
code size or execution time.
|
|
||||||
</p><p>
|
|
||||||
The result is that if all your algorithm calls look like
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
std::transform(beginof(foo), endof(foo), beginof(foo), SomeFunction);
|
|
||||||
</pre><p>
|
|
||||||
then the type of foo can change from an array of ints to a vector
|
|
||||||
of ints to a deque of ints and back again, without ever changing
|
|
||||||
any client code.
|
|
||||||
</p><p>
|
|
||||||
This author has a collection of such functions, called
|
|
||||||
“<span class="quote">*of</span>” because they all extend the builtin
|
|
||||||
“<span class="quote">sizeof</span>”. It started with some Usenet discussions
|
|
||||||
on a transparent way to find the length of an array. A
|
|
||||||
simplified and much-reduced version for easier reading is <a class="ulink" href="wrappers_h.txt" target="_top">given here</a>.
|
|
||||||
</p><p>
|
|
||||||
Astute readers will notice two things at once: first, that the
|
|
||||||
container class is still a <code class="code">vector<T></code> instead
|
|
||||||
of a more general <code class="code">Container<T></code>. This would
|
|
||||||
mean that three functions for <code class="code">deque</code> would have to be
|
|
||||||
added, another three for <code class="code">list</code>, and so on. This is
|
|
||||||
due to problems with getting template resolution correct; I find
|
|
||||||
it easier just to give the extra three lines and avoid confusion.
|
|
||||||
</p><p>
|
|
||||||
Second, the line
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
inline unsigned int lengthof (T (&)[sz]) { return sz; }
|
|
||||||
</pre><p>
|
|
||||||
looks just weird! Hint: unused parameters can be left nameless.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt07ch17s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="containers.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="iterators.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">bitset </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Part VIII. Iterators</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,19 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 21. Complex</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="numerics.html" title="Part X. Numerics" /><link rel="prev" href="numerics.html" title="Part X. Numerics" /><link rel="next" href="bk01pt10ch22.html" title="Chapter 22. Generalized Operations" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 21. Complex</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="numerics.html">Prev</a> </td><th width="60%" align="center">Part X. Numerics</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt10ch22.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.numerics.complex"></a>Chapter 21. Complex</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt10ch21.html#numerics.complex.processing">complex Processing</a></span></dt></dl></div><p>
|
|
||||||
</p><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="numerics.complex.processing"></a>complex Processing</h2></div></div></div><p>
|
|
||||||
</p><p>Using <code class="code">complex<></code> becomes even more comple- er, sorry,
|
|
||||||
<span class="emphasis"><em>complicated</em></span>, with the not-quite-gratuitously-incompatible
|
|
||||||
addition of complex types to the C language. David Tribble has
|
|
||||||
compiled a list of C++98 and C99 conflict points; his description of
|
|
||||||
C's new type versus those of C++ and how to get them playing together
|
|
||||||
nicely is
|
|
||||||
<a class="ulink" href="http://david.tribble.com/text/cdiffs.htm#C99-complex" target="_top">here</a>.
|
|
||||||
</p><p><code class="code">complex<></code> is intended to be instantiated with a
|
|
||||||
floating-point type. As long as you meet that and some other basic
|
|
||||||
requirements, then the resulting instantiation has all of the usual
|
|
||||||
math operators defined, as well as definitions of <code class="code">op<<</code>
|
|
||||||
and <code class="code">op>></code> that work with iostreams: <code class="code">op<<</code>
|
|
||||||
prints <code class="code">(u,v)</code> and <code class="code">op>></code> can read <code class="code">u</code>,
|
|
||||||
<code class="code">(u)</code>, and <code class="code">(u,v)</code>.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="numerics.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="numerics.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt10ch22.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part X. Numerics </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 22. Generalized Operations</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,26 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 22. Generalized Operations</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="numerics.html" title="Part X. Numerics" /><link rel="prev" href="bk01pt10ch21.html" title="Chapter 21. Complex" /><link rel="next" href="bk01pt10ch23.html" title="Chapter 23. Interacting with C" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 22. Generalized Operations</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt10ch21.html">Prev</a> </td><th width="60%" align="center">Part X. Numerics</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt10ch23.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.numerics.generalized_ops"></a>Chapter 22. Generalized Operations</h2></div></div></div><p>
|
|
||||||
</p><p>There are four generalized functions in the <numeric> header
|
|
||||||
that follow the same conventions as those in <algorithm>. Each
|
|
||||||
of them is overloaded: one signature for common default operations,
|
|
||||||
and a second for fully general operations. Their names are
|
|
||||||
self-explanatory to anyone who works with numerics on a regular basis:
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p><code class="code">accumulate</code></p></li><li><p><code class="code">inner_product</code></p></li><li><p><code class="code">partial_sum</code></p></li><li><p><code class="code">adjacent_difference</code></p></li></ul></div><p>Here is a simple example of the two forms of <code class="code">accumulate</code>.
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
int ar[50];
|
|
||||||
int someval = somefunction();
|
|
||||||
|
|
||||||
// ...initialize members of ar to something...
|
|
||||||
|
|
||||||
int sum = std::accumulate(ar,ar+50,0);
|
|
||||||
int sum_stuff = std::accumulate(ar,ar+50,someval);
|
|
||||||
int product = std::accumulate(ar,ar+50,1,std::multiplies<int>());
|
|
||||||
</pre><p>The first call adds all the members of the array, using zero as an
|
|
||||||
initial value for <code class="code">sum</code>. The second does the same, but uses
|
|
||||||
<code class="code">someval</code> as the starting value (thus, <code class="code">sum_stuff == sum +
|
|
||||||
someval</code>). The final call uses the second of the two signatures,
|
|
||||||
and multiplies all the members of the array; here we must obviously
|
|
||||||
use 1 as a starting value instead of 0.
|
|
||||||
</p><p>The other three functions have similar dual-signature forms.
|
|
||||||
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt10ch21.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="numerics.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt10ch23.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 21. Complex </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 23. Interacting with C</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,18 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 23. Interacting with C</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="numerics.html" title="Part X. Numerics" /><link rel="prev" href="bk01pt10ch22.html" title="Chapter 22. Generalized Operations" /><link rel="next" href="bk01pt10ch23s02.html" title="C99" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 23. Interacting with C</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt10ch22.html">Prev</a> </td><th width="60%" align="center">Part X. Numerics</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt10ch23s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.numerics.c"></a>Chapter 23. Interacting with C</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt10ch23.html#numerics.c.array">Numerics vs. Arrays</a></span></dt><dt><span class="sect1"><a href="bk01pt10ch23s02.html">C99</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="numerics.c.array"></a>Numerics vs. Arrays</h2></div></div></div><p>One of the major reasons why FORTRAN can chew through numbers so well
|
|
||||||
is that it is defined to be free of pointer aliasing, an assumption
|
|
||||||
that C89 is not allowed to make, and neither is C++98. C99 adds a new
|
|
||||||
keyword, <code class="code">restrict</code>, to apply to individual pointers. The
|
|
||||||
C++ solution is contained in the library rather than the language
|
|
||||||
(although many vendors can be expected to add this to their compilers
|
|
||||||
as an extension).
|
|
||||||
</p><p>That library solution is a set of two classes, five template classes,
|
|
||||||
and "a whole bunch" of functions. The classes are required
|
|
||||||
to be free of pointer aliasing, so compilers can optimize the
|
|
||||||
daylights out of them the same way that they have been for FORTRAN.
|
|
||||||
They are collectively called <code class="code">valarray</code>, although strictly
|
|
||||||
speaking this is only one of the five template classes, and they are
|
|
||||||
designed to be familiar to people who have worked with the BLAS
|
|
||||||
libraries before.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt10ch22.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="numerics.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt10ch23s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 22. Generalized Operations </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> C99</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,113 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 24. Iostream Objects</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="io.html" title="Part XI. Input and Output" /><link rel="prev" href="io.html" title="Part XI. Input and Output" /><link rel="next" href="bk01pt11ch25.html" title="Chapter 25. Stream Buffers" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 24. Iostream Objects</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="io.html">Prev</a> </td><th width="60%" align="center">Part XI. Input and Output</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt11ch25.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.io.objects"></a>Chapter 24. Iostream Objects</h2></div></div></div><p>To minimize the time you have to wait on the compiler, it's good to
|
|
||||||
only include the headers you really need. Many people simply include
|
|
||||||
<iostream> when they don't need to -- and that can <span class="emphasis"><em>penalize
|
|
||||||
your runtime as well.</em></span> Here are some tips on which header to use
|
|
||||||
for which situations, starting with the simplest.
|
|
||||||
</p><p><span class="emphasis"><em><iosfwd></em></span> should be included whenever you simply
|
|
||||||
need the <span class="emphasis"><em>name</em></span> of an I/O-related class, such as
|
|
||||||
"ofstream" or "basic_streambuf". Like the name
|
|
||||||
implies, these are forward declarations. (A word to all you fellow
|
|
||||||
old school programmers: trying to forward declare classes like
|
|
||||||
"class istream;" won't work. Look in the iosfwd header if
|
|
||||||
you'd like to know why.) For example,
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
#include <iosfwd>
|
|
||||||
|
|
||||||
class MyClass
|
|
||||||
{
|
|
||||||
....
|
|
||||||
std::ifstream& input_file;
|
|
||||||
};
|
|
||||||
|
|
||||||
extern std::ostream& operator<< (std::ostream&, MyClass&);
|
|
||||||
</pre><p><span class="emphasis"><em><ios></em></span> declares the base classes for the entire
|
|
||||||
I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the
|
|
||||||
counting types std::streamoff and std::streamsize, the file
|
|
||||||
positioning type std::fpos, and the various manipulators like
|
|
||||||
std::hex, std::fixed, std::noshowbase, and so forth.
|
|
||||||
</p><p>The ios_base class is what holds the format flags, the state flags,
|
|
||||||
and the functions which change them (setf(), width(), precision(),
|
|
||||||
etc). You can also store extra data and register callback functions
|
|
||||||
through ios_base, but that has been historically underused. Anything
|
|
||||||
which doesn't depend on the type of characters stored is consolidated
|
|
||||||
here.
|
|
||||||
</p><p>The template class basic_ios is the highest template class in the
|
|
||||||
hierarchy; it is the first one depending on the character type, and
|
|
||||||
holds all general state associated with that type: the pointer to the
|
|
||||||
polymorphic stream buffer, the facet information, etc.
|
|
||||||
</p><p><span class="emphasis"><em><streambuf></em></span> declares the template class
|
|
||||||
basic_streambuf, and two standard instantiations, streambuf and
|
|
||||||
wstreambuf. If you need to work with the vastly useful and capable
|
|
||||||
stream buffer classes, e.g., to create a new form of storage
|
|
||||||
transport, this header is the one to include.
|
|
||||||
</p><p><span class="emphasis"><em><istream></em></span>/<span class="emphasis"><em><ostream></em></span> are
|
|
||||||
the headers to include when you are using the >>/<<
|
|
||||||
interface, or any of the other abstract stream formatting functions.
|
|
||||||
For example,
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
#include <istream>
|
|
||||||
|
|
||||||
std::ostream& operator<< (std::ostream& os, MyClass& c)
|
|
||||||
{
|
|
||||||
return os << c.data1() << c.data2();
|
|
||||||
}
|
|
||||||
</pre><p>The std::istream and std::ostream classes are the abstract parents of
|
|
||||||
the various concrete implementations. If you are only using the
|
|
||||||
interfaces, then you only need to use the appropriate interface header.
|
|
||||||
</p><p><span class="emphasis"><em><iomanip></em></span> provides "extractors and inserters
|
|
||||||
that alter information maintained by class ios_base and its derived
|
|
||||||
classes," such as std::setprecision and std::setw. If you need
|
|
||||||
to write expressions like <code class="code">os << setw(3);</code> or
|
|
||||||
<code class="code">is >> setbase(8);</code>, you must include <iomanip>.
|
|
||||||
</p><p><span class="emphasis"><em><sstream></em></span>/<span class="emphasis"><em><fstream></em></span>
|
|
||||||
declare the six stringstream and fstream classes. As they are the
|
|
||||||
standard concrete descendants of istream and ostream, you will already
|
|
||||||
know about them.
|
|
||||||
</p><p>Finally, <span class="emphasis"><em><iostream></em></span> provides the eight standard
|
|
||||||
global objects (cin, cout, etc). To do this correctly, this header
|
|
||||||
also provides the contents of the <istream> and <ostream>
|
|
||||||
headers, but nothing else. The contents of this header look like
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
#include <ostream>
|
|
||||||
#include <istream>
|
|
||||||
|
|
||||||
namespace std
|
|
||||||
{
|
|
||||||
extern istream cin;
|
|
||||||
extern ostream cout;
|
|
||||||
....
|
|
||||||
|
|
||||||
// this is explained below
|
|
||||||
<span class="emphasis"><em>static ios_base::Init __foo;</em></span> // not its real name
|
|
||||||
}
|
|
||||||
</pre><p>Now, the runtime penalty mentioned previously: the global objects
|
|
||||||
must be initialized before any of your own code uses them; this is
|
|
||||||
guaranteed by the standard. Like any other global object, they must
|
|
||||||
be initialized once and only once. This is typically done with a
|
|
||||||
construct like the one above, and the nested class ios_base::Init is
|
|
||||||
specified in the standard for just this reason.
|
|
||||||
</p><p>How does it work? Because the header is included before any of your
|
|
||||||
code, the <span class="emphasis"><em>__foo</em></span> object is constructed before any of
|
|
||||||
your objects. (Global objects are built in the order in which they
|
|
||||||
are declared, and destroyed in reverse order.) The first time the
|
|
||||||
constructor runs, the eight stream objects are set up.
|
|
||||||
</p><p>The <code class="code">static</code> keyword means that each object file compiled
|
|
||||||
from a source file containing <iostream> will have its own
|
|
||||||
private copy of <span class="emphasis"><em>__foo</em></span>. There is no specified order
|
|
||||||
of construction across object files (it's one of those pesky NP
|
|
||||||
problems that make life so interesting), so one copy in each object
|
|
||||||
file means that the stream objects are guaranteed to be set up before
|
|
||||||
any of your code which uses them could run, thereby meeting the
|
|
||||||
requirements of the standard.
|
|
||||||
</p><p>The penalty, of course, is that after the first copy of
|
|
||||||
<span class="emphasis"><em>__foo</em></span> is constructed, all the others are just wasted
|
|
||||||
processor time. The time spent is merely for an increment-and-test
|
|
||||||
inside a function call, but over several dozen or hundreds of object
|
|
||||||
files, that time can add up. (It's not in a tight loop, either.)
|
|
||||||
</p><p>The lesson? Only include <iostream> when you need to use one of
|
|
||||||
the standard objects in that source file; you'll pay less startup
|
|
||||||
time. Only include the header files you need to in general; your
|
|
||||||
compile times will go down when there's less parsing work to do.
|
|
||||||
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="io.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="io.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt11ch25.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part XI. Input and Output </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 25. Stream Buffers</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,57 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 25. Stream Buffers</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="io.html" title="Part XI. Input and Output" /><link rel="prev" href="bk01pt11ch24.html" title="Chapter 24. Iostream Objects" /><link rel="next" href="bk01pt11ch25s02.html" title="Buffering" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 25. Stream Buffers</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt11ch24.html">Prev</a> </td><th width="60%" align="center">Part XI. Input and Output</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt11ch25s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.io.streambufs"></a>Chapter 25. Stream Buffers</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt11ch25.html#io.streambuf.derived">Derived streambuf Classes</a></span></dt><dt><span class="sect1"><a href="bk01pt11ch25s02.html">Buffering</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="io.streambuf.derived"></a>Derived streambuf Classes</h2></div></div></div><p>
|
|
||||||
</p><p>Creating your own stream buffers for I/O can be remarkably easy.
|
|
||||||
If you are interested in doing so, we highly recommend two very
|
|
||||||
excellent books:
|
|
||||||
<a class="ulink" href="http://www.langer.camelot.de/iostreams.html" target="_top">Standard C++
|
|
||||||
IOStreams and Locales</a> by Langer and Kreft, ISBN 0-201-18395-1, and
|
|
||||||
<a class="ulink" href="http://www.josuttis.com/libbook/" target="_top">The C++ Standard Library</a>
|
|
||||||
by Nicolai Josuttis, ISBN 0-201-37926-0. Both are published by
|
|
||||||
Addison-Wesley, who isn't paying us a cent for saying that, honest.
|
|
||||||
</p><p>Here is a simple example, io/outbuf1, from the Josuttis text. It
|
|
||||||
transforms everything sent through it to uppercase. This version
|
|
||||||
assumes many things about the nature of the character type being
|
|
||||||
used (for more information, read the books or the newsgroups):
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
#include <iostream>
|
|
||||||
#include <streambuf>
|
|
||||||
#include <locale>
|
|
||||||
#include <cstdio>
|
|
||||||
|
|
||||||
class outbuf : public std::streambuf
|
|
||||||
{
|
|
||||||
protected:
|
|
||||||
/* central output function
|
|
||||||
* - print characters in uppercase mode
|
|
||||||
*/
|
|
||||||
virtual int_type overflow (int_type c) {
|
|
||||||
if (c != EOF) {
|
|
||||||
// convert lowercase to uppercase
|
|
||||||
c = std::toupper(static_cast<char>(c),getloc());
|
|
||||||
|
|
||||||
// and write the character to the standard output
|
|
||||||
if (putchar(c) == EOF) {
|
|
||||||
return EOF;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
return c;
|
|
||||||
}
|
|
||||||
};
|
|
||||||
|
|
||||||
int main()
|
|
||||||
{
|
|
||||||
// create special output buffer
|
|
||||||
outbuf ob;
|
|
||||||
// initialize output stream with that output buffer
|
|
||||||
std::ostream out(&ob);
|
|
||||||
|
|
||||||
out << "31 hexadecimal: "
|
|
||||||
<< std::hex << 31 << std::endl;
|
|
||||||
return 0;
|
|
||||||
}
|
|
||||||
</pre><p>Try it yourself! More examples can be found in 3.1.x code, in
|
|
||||||
<code class="code">include/ext/*_filebuf.h</code>, and on
|
|
||||||
<a class="ulink" href="http://www.informatik.uni-konstanz.de/~kuehl/c++/iostream/" target="_top">Dietmar
|
|
||||||
Kühl's IOStreams page</a>.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt11ch24.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="io.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt11ch25s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 24. Iostream Objects </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Buffering</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,34 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 26. Memory Based Streams</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="io.html" title="Part XI. Input and Output" /><link rel="prev" href="bk01pt11ch25s02.html" title="Buffering" /><link rel="next" href="bk01pt11ch27.html" title="Chapter 27. File Based Streams" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 26. Memory Based Streams</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt11ch25s02.html">Prev</a> </td><th width="60%" align="center">Part XI. Input and Output</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt11ch27.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.io.memstreams"></a>Chapter 26. Memory Based Streams</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt11ch26.html#manual.io.memstreams.compat">Compatibility With strstream</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.io.memstreams.compat"></a>Compatibility With strstream</h2></div></div></div><p>
|
|
||||||
</p><p>Stringstreams (defined in the header <code class="code"><sstream></code>)
|
|
||||||
are in this author's opinion one of the coolest things since
|
|
||||||
sliced time. An example of their use is in the Received Wisdom
|
|
||||||
section for Chapter 21 (Strings),
|
|
||||||
<a class="ulink" href="../21_strings/howto.html#1.1internal" target="_top"> describing how to
|
|
||||||
format strings</a>.
|
|
||||||
</p><p>The quick definition is: they are siblings of ifstream and ofstream,
|
|
||||||
and they do for <code class="code">std::string</code> what their siblings do for
|
|
||||||
files. All that work you put into writing <code class="code"><<</code> and
|
|
||||||
<code class="code">>></code> functions for your classes now pays off
|
|
||||||
<span class="emphasis"><em>again!</em></span> Need to format a string before passing the string
|
|
||||||
to a function? Send your stuff via <code class="code"><<</code> to an
|
|
||||||
ostringstream. You've read a string as input and need to parse it?
|
|
||||||
Initialize an istringstream with that string, and then pull pieces
|
|
||||||
out of it with <code class="code">>></code>. Have a stringstream and need to
|
|
||||||
get a copy of the string inside? Just call the <code class="code">str()</code>
|
|
||||||
member function.
|
|
||||||
</p><p>This only works if you've written your
|
|
||||||
<code class="code"><<</code>/<code class="code">>></code> functions correctly, though,
|
|
||||||
and correctly means that they take istreams and ostreams as
|
|
||||||
parameters, not i<span class="emphasis"><em>f</em></span>streams and o<span class="emphasis"><em>f</em></span>streams. If they
|
|
||||||
take the latter, then your I/O operators will work fine with
|
|
||||||
file streams, but with nothing else -- including stringstreams.
|
|
||||||
</p><p>If you are a user of the strstream classes, you need to update
|
|
||||||
your code. You don't have to explicitly append <code class="code">ends</code> to
|
|
||||||
terminate the C-style character array, you don't have to mess with
|
|
||||||
"freezing" functions, and you don't have to manage the
|
|
||||||
memory yourself. The strstreams have been officially deprecated,
|
|
||||||
which means that 1) future revisions of the C++ Standard won't
|
|
||||||
support them, and 2) if you use them, people will laugh at you.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt11ch25s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="io.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt11ch27.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Buffering </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 27. File Based Streams</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,49 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 27. File Based Streams</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="io.html" title="Part XI. Input and Output" /><link rel="prev" href="bk01pt11ch26.html" title="Chapter 26. Memory Based Streams" /><link rel="next" href="bk01pt11ch27s02.html" title="Binary Input and Output" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 27. File Based Streams</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt11ch26.html">Prev</a> </td><th width="60%" align="center">Part XI. Input and Output</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt11ch27s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.io.filestreams"></a>Chapter 27. File Based Streams</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt11ch27.html#manual.io.filestreams.copying_a_file">Copying a File</a></span></dt><dt><span class="sect1"><a href="bk01pt11ch27s02.html">Binary Input and Output</a></span></dt><dt><span class="sect1"><a href="bk01pt11ch27s03.html">More Binary Input and Output</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.io.filestreams.copying_a_file"></a>Copying a File</h2></div></div></div><p>
|
|
||||||
</p><p>So you want to copy a file quickly and easily, and most important,
|
|
||||||
completely portably. And since this is C++, you have an open
|
|
||||||
ifstream (call it IN) and an open ofstream (call it OUT):
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
#include <fstream>
|
|
||||||
|
|
||||||
std::ifstream IN ("input_file");
|
|
||||||
std::ofstream OUT ("output_file"); </pre><p>Here's the easiest way to get it completely wrong:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
OUT << IN;</pre><p>For those of you who don't already know why this doesn't work
|
|
||||||
(probably from having done it before), I invite you to quickly
|
|
||||||
create a simple text file called "input_file" containing
|
|
||||||
the sentence
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
The quick brown fox jumped over the lazy dog.</pre><p>surrounded by blank lines. Code it up and try it. The contents
|
|
||||||
of "output_file" may surprise you.
|
|
||||||
</p><p>Seriously, go do it. Get surprised, then come back. It's worth it.
|
|
||||||
</p><p>The thing to remember is that the <code class="code">basic_[io]stream</code> classes
|
|
||||||
handle formatting, nothing else. In particular, they break up on
|
|
||||||
whitespace. The actual reading, writing, and storing of data is
|
|
||||||
handled by the <code class="code">basic_streambuf</code> family. Fortunately, the
|
|
||||||
<code class="code">operator<<</code> is overloaded to take an ostream and
|
|
||||||
a pointer-to-streambuf, in order to help with just this kind of
|
|
||||||
"dump the data verbatim" situation.
|
|
||||||
</p><p>Why a <span class="emphasis"><em>pointer</em></span> to streambuf and not just a streambuf? Well,
|
|
||||||
the [io]streams hold pointers (or references, depending on the
|
|
||||||
implementation) to their buffers, not the actual
|
|
||||||
buffers. This allows polymorphic behavior on the part of the buffers
|
|
||||||
as well as the streams themselves. The pointer is easily retrieved
|
|
||||||
using the <code class="code">rdbuf()</code> member function. Therefore, the easiest
|
|
||||||
way to copy the file is:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
OUT << IN.rdbuf();</pre><p>So what <span class="emphasis"><em>was</em></span> happening with OUT<<IN? Undefined
|
|
||||||
behavior, since that particular << isn't defined by the Standard.
|
|
||||||
I have seen instances where it is implemented, but the character
|
|
||||||
extraction process removes all the whitespace, leaving you with no
|
|
||||||
blank lines and only "Thequickbrownfox...". With
|
|
||||||
libraries that do not define that operator, IN (or one of IN's
|
|
||||||
member pointers) sometimes gets converted to a void*, and the output
|
|
||||||
file then contains a perfect text representation of a hexadecimal
|
|
||||||
address (quite a big surprise). Others don't compile at all.
|
|
||||||
</p><p>Also note that none of this is specific to o<span class="emphasis"><em>*f*</em></span>streams.
|
|
||||||
The operators shown above are all defined in the parent
|
|
||||||
basic_ostream class and are therefore available with all possible
|
|
||||||
descendants.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt11ch26.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="io.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt11ch27s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 26. Memory Based Streams </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Binary Input and Output</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,8 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 28. Interacting with C</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="io.html" title="Part XI. Input and Output" /><link rel="prev" href="bk01pt11ch27s03.html" title="More Binary Input and Output" /><link rel="next" href="bk01pt11ch28s02.html" title="Performance" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 28. Interacting with C</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt11ch27s03.html">Prev</a> </td><th width="60%" align="center">Part XI. Input and Output</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt11ch28s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.io.c"></a>Chapter 28. Interacting with C</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt11ch28.html#manual.io.c.FILE">Using FILE* and file descriptors</a></span></dt><dt><span class="sect1"><a href="bk01pt11ch28s02.html">Performance</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.io.c.FILE"></a>Using FILE* and file descriptors</h2></div></div></div><p>
|
|
||||||
See the <a class="link" href="bk01pt12ch38.html" title="Chapter 38. Input and Output">extensions</a> for using
|
|
||||||
<span class="type">FILE</span> and <span class="type">file descriptors</span> with
|
|
||||||
<code class="classname">ofstream</code> and
|
|
||||||
<code class="classname">ifstream</code>.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt11ch27s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="io.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt11ch28s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">More Binary Input and Output </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Performance</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,37 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 29. Compile Time Checks</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12pr03.html" title="" /><link rel="next" href="debug_mode.html" title="Chapter 30. Debug Mode" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 29. Compile Time Checks</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12pr03.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="debug_mode.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.compile_checks"></a>Chapter 29. Compile Time Checks</h2></div></div></div><p>
|
|
||||||
Also known as concept checking.
|
|
||||||
</p><p>In 1999, SGI added <span class="emphasis"><em>concept checkers</em></span> to their implementation
|
|
||||||
of the STL: code which checked the template parameters of
|
|
||||||
instantiated pieces of the STL, in order to insure that the parameters
|
|
||||||
being used met the requirements of the standard. For example,
|
|
||||||
the Standard requires that types passed as template parameters to
|
|
||||||
<code class="code">vector</code> be “<span class="quote">Assignable</span>” (which means what you think
|
|
||||||
it means). The checking was done during compilation, and none of
|
|
||||||
the code was executed at runtime.
|
|
||||||
</p><p>Unfortunately, the size of the compiler files grew significantly
|
|
||||||
as a result. The checking code itself was cumbersome. And bugs
|
|
||||||
were found in it on more than one occasion.
|
|
||||||
</p><p>The primary author of the checking code, Jeremy Siek, had already
|
|
||||||
started work on a replacement implementation. The new code has been
|
|
||||||
formally reviewed and accepted into
|
|
||||||
<a class="ulink" href="http://www.boost.org/libs/concept_check/concept_check.htm" target="_top">the
|
|
||||||
Boost libraries</a>, and we are pleased to incorporate it into the
|
|
||||||
GNU C++ library.
|
|
||||||
</p><p>The new version imposes a much smaller space overhead on the generated
|
|
||||||
object file. The checks are also cleaner and easier to read and
|
|
||||||
understand.
|
|
||||||
</p><p>They are off by default for all versions of GCC from 3.0 to 3.4 (the
|
|
||||||
latest release at the time of writing).
|
|
||||||
They can be enabled at configure time with
|
|
||||||
<a class="ulink" href="../configopts.html" target="_top"><code class="literal">--enable-concept-checks</code></a>.
|
|
||||||
You can enable them on a per-translation-unit basis with
|
|
||||||
<code class="code">#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher
|
|
||||||
(or with <code class="code">#define _GLIBCPP_CONCEPT_CHECKS</code> for versions
|
|
||||||
3.1, 3.2 and 3.3).
|
|
||||||
</p><p>Please note that the upcoming C++ standard has first-class
|
|
||||||
support for template parameter constraints based on concepts in the core
|
|
||||||
language. This will obviate the need for the library-simulated concept
|
|
||||||
checking described above.
|
|
||||||
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12pr03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="debug_mode.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 30. Debug Mode</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,394 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 32. Allocators</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch31s05.html" title="Testing" /><link rel="next" href="bitmap_allocator.html" title="bitmap_allocator" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 32. Allocators</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch31s05.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bitmap_allocator.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.allocator"></a>Chapter 32. Allocators</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt12ch32.html#manual.ext.allocator.mt">mt_allocator</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt12ch32.html#allocator.mt.intro">Intro</a></span></dt><dt><span class="sect2"><a href="bk01pt12ch32.html#allocator.mt.design_issues">Design Issues</a></span></dt><dt><span class="sect2"><a href="bk01pt12ch32.html#allocator.mt.impl">Implementation</a></span></dt><dt><span class="sect2"><a href="bk01pt12ch32.html#allocator.mt.example_single">Single Thread Example</a></span></dt><dt><span class="sect2"><a href="bk01pt12ch32.html#allocator.mt.example_multi">Multiple Thread Example</a></span></dt></dl></dd><dt><span class="sect1"><a href="bitmap_allocator.html">bitmap_allocator</a></span></dt><dd><dl><dt><span class="sect2"><a href="bitmap_allocator.html#allocator.bitmap.design">Design</a></span></dt><dt><span class="sect2"><a href="bitmap_allocator.html#allocator.bitmap.impl">Implementation</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.allocator.mt"></a>mt_allocator</h2></div></div></div><p>
|
|
||||||
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.mt.intro"></a>Intro</h3></div></div></div><p>
|
|
||||||
The mt allocator [hereinafter referred to simply as "the allocator"]
|
|
||||||
is a fixed size (power of two) allocator that was initially
|
|
||||||
developed specifically to suit the needs of multi threaded
|
|
||||||
applications [hereinafter referred to as an MT application]. Over
|
|
||||||
time the allocator has evolved and been improved in many ways, in
|
|
||||||
particular it now also does a good job in single threaded
|
|
||||||
applications [hereinafter referred to as a ST application]. (Note:
|
|
||||||
In this document, when referring to single threaded applications
|
|
||||||
this also includes applications that are compiled with gcc without
|
|
||||||
thread support enabled. This is accomplished using ifdef's on
|
|
||||||
__GTHREADS). This allocator is tunable, very flexible, and capable
|
|
||||||
of high-performance.
|
|
||||||
</p><p>
|
|
||||||
The aim of this document is to describe - from an application point of
|
|
||||||
view - the "inner workings" of the allocator.
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.mt.design_issues"></a>Design Issues</h3></div></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.mt.overview"></a>Overview</h4></div></div></div><p> There are three general components to the allocator: a datum
|
|
||||||
describing the characteristics of the memory pool, a policy class
|
|
||||||
containing this pool that links instantiation types to common or
|
|
||||||
individual pools, and a class inheriting from the policy class that is
|
|
||||||
the actual allocator.
|
|
||||||
</p><p>The datum describing pools characteristics is
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
template<bool _Thread>
|
|
||||||
class __pool
|
|
||||||
</pre><p> This class is parametrized on thread support, and is explicitly
|
|
||||||
specialized for both multiple threads (with <code class="code">bool==true</code>)
|
|
||||||
and single threads (via <code class="code">bool==false</code>.) It is possible to
|
|
||||||
use a custom pool datum instead of the default class that is provided.
|
|
||||||
</p><p> There are two distinct policy classes, each of which can be used
|
|
||||||
with either type of underlying pool datum.
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
template<bool _Thread>
|
|
||||||
struct __common_pool_policy
|
|
||||||
|
|
||||||
template<typename _Tp, bool _Thread>
|
|
||||||
struct __per_type_pool_policy
|
|
||||||
</pre><p> The first policy, <code class="code">__common_pool_policy</code>, implements a
|
|
||||||
common pool. This means that allocators that are instantiated with
|
|
||||||
different types, say <code class="code">char</code> and <code class="code">long</code> will both
|
|
||||||
use the same pool. This is the default policy.
|
|
||||||
</p><p> The second policy, <code class="code">__per_type_pool_policy</code>, implements
|
|
||||||
a separate pool for each instantiating type. Thus, <code class="code">char</code>
|
|
||||||
and <code class="code">long</code> will use separate pools. This allows per-type
|
|
||||||
tuning, for instance.
|
|
||||||
</p><p> Putting this all together, the actual allocator class is
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
template<typename _Tp, typename _Poolp = __default_policy>
|
|
||||||
class __mt_alloc : public __mt_alloc_base<_Tp>, _Poolp
|
|
||||||
</pre><p> This class has the interface required for standard library allocator
|
|
||||||
classes, namely member functions <code class="code">allocate</code> and
|
|
||||||
<code class="code">deallocate</code>, plus others.
|
|
||||||
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.mt.impl"></a>Implementation</h3></div></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.mt.tune"></a>Tunable Parameters</h4></div></div></div><p>Certain allocation parameters can be modified, or tuned. There
|
|
||||||
exists a nested <code class="code">struct __pool_base::_Tune</code> that contains all
|
|
||||||
these parameters, which include settings for
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>Alignment</p></li><li><p>Maximum bytes before calling <code class="code">::operator new</code> directly</p></li><li><p>Minimum bytes</p></li><li><p>Size of underlying global allocations</p></li><li><p>Maximum number of supported threads</p></li><li><p>Migration of deallocations to the global free list</p></li><li><p>Shunt for global <code class="code">new</code> and <code class="code">delete</code></p></li></ul></div><p>Adjusting parameters for a given instance of an allocator can only
|
|
||||||
happen before any allocations take place, when the allocator itself is
|
|
||||||
initialized. For instance:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
#include <ext/mt_allocator.h>
|
|
||||||
|
|
||||||
struct pod
|
|
||||||
{
|
|
||||||
int i;
|
|
||||||
int j;
|
|
||||||
};
|
|
||||||
|
|
||||||
int main()
|
|
||||||
{
|
|
||||||
typedef pod value_type;
|
|
||||||
typedef __gnu_cxx::__mt_alloc<value_type> allocator_type;
|
|
||||||
typedef __gnu_cxx::__pool_base::_Tune tune_type;
|
|
||||||
|
|
||||||
tune_type t_default;
|
|
||||||
tune_type t_opt(16, 5120, 32, 5120, 20, 10, false);
|
|
||||||
tune_type t_single(16, 5120, 32, 5120, 1, 10, false);
|
|
||||||
|
|
||||||
tune_type t;
|
|
||||||
t = allocator_type::_M_get_options();
|
|
||||||
allocator_type::_M_set_options(t_opt);
|
|
||||||
t = allocator_type::_M_get_options();
|
|
||||||
|
|
||||||
allocator_type a;
|
|
||||||
allocator_type::pointer p1 = a.allocate(128);
|
|
||||||
allocator_type::pointer p2 = a.allocate(5128);
|
|
||||||
|
|
||||||
a.deallocate(p1, 128);
|
|
||||||
a.deallocate(p2, 5128);
|
|
||||||
|
|
||||||
return 0;
|
|
||||||
}
|
|
||||||
</pre></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.mt.init"></a>Initialization</h4></div></div></div><p>
|
|
||||||
The static variables (pointers to freelists, tuning parameters etc)
|
|
||||||
are initialized as above, or are set to the global defaults.
|
|
||||||
</p><p>
|
|
||||||
The very first allocate() call will always call the
|
|
||||||
_S_initialize_once() function. In order to make sure that this
|
|
||||||
function is called exactly once we make use of a __gthread_once call
|
|
||||||
in MT applications and check a static bool (_S_init) in ST
|
|
||||||
applications.
|
|
||||||
</p><p>
|
|
||||||
The _S_initialize() function:
|
|
||||||
- If the GLIBCXX_FORCE_NEW environment variable is set, it sets the bool
|
|
||||||
_S_force_new to true and then returns. This will cause subsequent calls to
|
|
||||||
allocate() to return memory directly from a new() call, and deallocate will
|
|
||||||
only do a delete() call.
|
|
||||||
</p><p>
|
|
||||||
- If the GLIBCXX_FORCE_NEW environment variable is not set, both ST and MT
|
|
||||||
applications will:
|
|
||||||
- Calculate the number of bins needed. A bin is a specific power of two size
|
|
||||||
of bytes. I.e., by default the allocator will deal with requests of up to
|
|
||||||
128 bytes (or whatever the value of _S_max_bytes is when _S_init() is
|
|
||||||
called). This means that there will be bins of the following sizes
|
|
||||||
(in bytes): 1, 2, 4, 8, 16, 32, 64, 128.
|
|
||||||
|
|
||||||
- Create the _S_binmap array. All requests are rounded up to the next
|
|
||||||
"large enough" bin. I.e., a request for 29 bytes will cause a block from
|
|
||||||
the "32 byte bin" to be returned to the application. The purpose of
|
|
||||||
_S_binmap is to speed up the process of finding out which bin to use.
|
|
||||||
I.e., the value of _S_binmap[ 29 ] is initialized to 5 (bin 5 = 32 bytes).
|
|
||||||
</p><p>
|
|
||||||
- Create the _S_bin array. This array consists of bin_records. There will be
|
|
||||||
as many bin_records in this array as the number of bins that we calculated
|
|
||||||
earlier. I.e., if _S_max_bytes = 128 there will be 8 entries.
|
|
||||||
Each bin_record is then initialized:
|
|
||||||
- bin_record->first = An array of pointers to block_records. There will be
|
|
||||||
as many block_records pointers as there are maximum number of threads
|
|
||||||
(in a ST application there is only 1 thread, in a MT application there
|
|
||||||
are _S_max_threads).
|
|
||||||
This holds the pointer to the first free block for each thread in this
|
|
||||||
bin. I.e., if we would like to know where the first free block of size 32
|
|
||||||
for thread number 3 is we would look this up by: _S_bin[ 5 ].first[ 3 ]
|
|
||||||
|
|
||||||
The above created block_record pointers members are now initialized to
|
|
||||||
their initial values. I.e. _S_bin[ n ].first[ n ] = NULL;
|
|
||||||
</p><p>
|
|
||||||
- Additionally a MT application will:
|
|
||||||
- Create a list of free thread id's. The pointer to the first entry
|
|
||||||
is stored in _S_thread_freelist_first. The reason for this approach is
|
|
||||||
that the __gthread_self() call will not return a value that corresponds to
|
|
||||||
the maximum number of threads allowed but rather a process id number or
|
|
||||||
something else. So what we do is that we create a list of thread_records.
|
|
||||||
This list is _S_max_threads long and each entry holds a size_t thread_id
|
|
||||||
which is initialized to 1, 2, 3, 4, 5 and so on up to _S_max_threads.
|
|
||||||
Each time a thread calls allocate() or deallocate() we call
|
|
||||||
_S_get_thread_id() which looks at the value of _S_thread_key which is a
|
|
||||||
thread local storage pointer. If this is NULL we know that this is a newly
|
|
||||||
created thread and we pop the first entry from this list and saves the
|
|
||||||
pointer to this record in the _S_thread_key variable. The next time
|
|
||||||
we will get the pointer to the thread_record back and we use the
|
|
||||||
thread_record->thread_id as identification. I.e., the first thread that
|
|
||||||
calls allocate will get the first record in this list and thus be thread
|
|
||||||
number 1 and will then find the pointer to its first free 32 byte block
|
|
||||||
in _S_bin[ 5 ].first[ 1 ]
|
|
||||||
When we create the _S_thread_key we also define a destructor
|
|
||||||
(_S_thread_key_destr) which means that when the thread dies, this
|
|
||||||
thread_record is returned to the front of this list and the thread id
|
|
||||||
can then be reused if a new thread is created.
|
|
||||||
This list is protected by a mutex (_S_thread_freelist_mutex) which is only
|
|
||||||
locked when records are removed or added to the list.
|
|
||||||
</p><p>
|
|
||||||
- Initialize the free and used counters of each bin_record:
|
|
||||||
- bin_record->free = An array of size_t. This keeps track of the number
|
|
||||||
of blocks on a specific thread's freelist in each bin. I.e., if a thread
|
|
||||||
has 12 32-byte blocks on it's freelists and allocates one of these, this
|
|
||||||
counter would be decreased to 11.
|
|
||||||
|
|
||||||
- bin_record->used = An array of size_t. This keeps track of the number
|
|
||||||
of blocks currently in use of this size by this thread. I.e., if a thread
|
|
||||||
has made 678 requests (and no deallocations...) of 32-byte blocks this
|
|
||||||
counter will read 678.
|
|
||||||
|
|
||||||
The above created arrays are now initialized with their initial values.
|
|
||||||
I.e. _S_bin[ n ].free[ n ] = 0;
|
|
||||||
</p><p>
|
|
||||||
- Initialize the mutex of each bin_record: The bin_record->mutex
|
|
||||||
is used to protect the global freelist. This concept of a global
|
|
||||||
freelist is explained in more detail in the section "A multi
|
|
||||||
threaded example", but basically this mutex is locked whenever a
|
|
||||||
block of memory is retrieved or returned to the global freelist
|
|
||||||
for this specific bin. This only occurs when a number of blocks
|
|
||||||
are grabbed from the global list to a thread specific list or when
|
|
||||||
a thread decides to return some blocks to the global freelist.
|
|
||||||
</p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.mt.deallocation"></a>Deallocation Notes</h4></div></div></div><p> Notes about deallocation. This allocator does not explicitly
|
|
||||||
release memory. Because of this, memory debugging programs like
|
|
||||||
valgrind or purify may notice leaks: sorry about this
|
|
||||||
inconvenience. Operating systems will reclaim allocated memory at
|
|
||||||
program termination anyway. If sidestepping this kind of noise is
|
|
||||||
desired, there are three options: use an allocator, like
|
|
||||||
<code class="code">new_allocator</code> that releases memory while debugging, use
|
|
||||||
GLIBCXX_FORCE_NEW to bypass the allocator's internal pools, or use a
|
|
||||||
custom pool datum that releases resources on destruction.
|
|
||||||
</p><p>
|
|
||||||
On systems with the function <code class="code">__cxa_atexit</code>, the
|
|
||||||
allocator can be forced to free all memory allocated before program
|
|
||||||
termination with the member function
|
|
||||||
<code class="code">__pool_type::_M_destroy</code>. However, because this member
|
|
||||||
function relies on the precise and exactly-conforming ordering of
|
|
||||||
static destructors, including those of a static local
|
|
||||||
<code class="code">__pool</code> object, it should not be used, ever, on systems
|
|
||||||
that don't have the necessary underlying support. In addition, in
|
|
||||||
practice, forcing deallocation can be tricky, as it requires the
|
|
||||||
<code class="code">__pool</code> object to be fully-constructed before the object
|
|
||||||
that uses it is fully constructed. For most (but not all) STL
|
|
||||||
containers, this works, as an instance of the allocator is constructed
|
|
||||||
as part of a container's constructor. However, this assumption is
|
|
||||||
implementation-specific, and subject to change. For an example of a
|
|
||||||
pool that frees memory, see the following
|
|
||||||
<a class="ulink" href="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/ext/mt_allocator/deallocate_local-6.cc?view=markup" target="_top">
|
|
||||||
example.</a>
|
|
||||||
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.mt.example_single"></a>Single Thread Example</h3></div></div></div><p>
|
|
||||||
Let's start by describing how the data on a freelist is laid out in memory.
|
|
||||||
This is the first two blocks in freelist for thread id 3 in bin 3 (8 bytes):
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
+----------------+
|
|
||||||
| next* ---------|--+ (_S_bin[ 3 ].first[ 3 ] points here)
|
|
||||||
| | |
|
|
||||||
| | |
|
|
||||||
| | |
|
|
||||||
+----------------+ |
|
|
||||||
| thread_id = 3 | |
|
|
||||||
| | |
|
|
||||||
| | |
|
|
||||||
| | |
|
|
||||||
+----------------+ |
|
|
||||||
| DATA | | (A pointer to here is what is returned to the
|
|
||||||
| | | the application when needed)
|
|
||||||
| | |
|
|
||||||
| | |
|
|
||||||
| | |
|
|
||||||
| | |
|
|
||||||
| | |
|
|
||||||
| | |
|
|
||||||
+----------------+ |
|
|
||||||
+----------------+ |
|
|
||||||
| next* |<-+ (If next == NULL it's the last one on the list)
|
|
||||||
| |
|
|
||||||
| |
|
|
||||||
| |
|
|
||||||
+----------------+
|
|
||||||
| thread_id = 3 |
|
|
||||||
| |
|
|
||||||
| |
|
|
||||||
| |
|
|
||||||
+----------------+
|
|
||||||
| DATA |
|
|
||||||
| |
|
|
||||||
| |
|
|
||||||
| |
|
|
||||||
| |
|
|
||||||
| |
|
|
||||||
| |
|
|
||||||
| |
|
|
||||||
+----------------+
|
|
||||||
</pre><p>
|
|
||||||
With this in mind we simplify things a bit for a while and say that there is
|
|
||||||
only one thread (a ST application). In this case all operations are made to
|
|
||||||
what is referred to as the global pool - thread id 0 (No thread may be
|
|
||||||
assigned this id since they span from 1 to _S_max_threads in a MT application).
|
|
||||||
</p><p>
|
|
||||||
When the application requests memory (calling allocate()) we first look at the
|
|
||||||
requested size and if this is > _S_max_bytes we call new() directly and return.
|
|
||||||
</p><p>
|
|
||||||
If the requested size is within limits we start by finding out from which
|
|
||||||
bin we should serve this request by looking in _S_binmap.
|
|
||||||
</p><p>
|
|
||||||
A quick look at _S_bin[ bin ].first[ 0 ] tells us if there are any blocks of
|
|
||||||
this size on the freelist (0). If this is not NULL - fine, just remove the
|
|
||||||
block that _S_bin[ bin ].first[ 0 ] points to from the list,
|
|
||||||
update _S_bin[ bin ].first[ 0 ] and return a pointer to that blocks data.
|
|
||||||
</p><p>
|
|
||||||
If the freelist is empty (the pointer is NULL) we must get memory from the
|
|
||||||
system and build us a freelist within this memory. All requests for new memory
|
|
||||||
is made in chunks of _S_chunk_size. Knowing the size of a block_record and
|
|
||||||
the bytes that this bin stores we then calculate how many blocks we can create
|
|
||||||
within this chunk, build the list, remove the first block, update the pointer
|
|
||||||
(_S_bin[ bin ].first[ 0 ]) and return a pointer to that blocks data.
|
|
||||||
</p><p>
|
|
||||||
Deallocation is equally simple; the pointer is casted back to a block_record
|
|
||||||
pointer, lookup which bin to use based on the size, add the block to the front
|
|
||||||
of the global freelist and update the pointer as needed
|
|
||||||
(_S_bin[ bin ].first[ 0 ]).
|
|
||||||
</p><p>
|
|
||||||
The decision to add deallocated blocks to the front of the freelist was made
|
|
||||||
after a set of performance measurements that showed that this is roughly 10%
|
|
||||||
faster than maintaining a set of "last pointers" as well.
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="allocator.mt.example_multi"></a>Multiple Thread Example</h3></div></div></div><p>
|
|
||||||
In the ST example we never used the thread_id variable present in each block.
|
|
||||||
Let's start by explaining the purpose of this in a MT application.
|
|
||||||
</p><p>
|
|
||||||
The concept of "ownership" was introduced since many MT applications
|
|
||||||
allocate and deallocate memory to shared containers from different
|
|
||||||
threads (such as a cache shared amongst all threads). This introduces
|
|
||||||
a problem if the allocator only returns memory to the current threads
|
|
||||||
freelist (I.e., there might be one thread doing all the allocation and
|
|
||||||
thus obtaining ever more memory from the system and another thread
|
|
||||||
that is getting a longer and longer freelist - this will in the end
|
|
||||||
consume all available memory).
|
|
||||||
</p><p>
|
|
||||||
Each time a block is moved from the global list (where ownership is
|
|
||||||
irrelevant), to a threads freelist (or when a new freelist is built
|
|
||||||
from a chunk directly onto a threads freelist or when a deallocation
|
|
||||||
occurs on a block which was not allocated by the same thread id as the
|
|
||||||
one doing the deallocation) the thread id is set to the current one.
|
|
||||||
</p><p>
|
|
||||||
What's the use? Well, when a deallocation occurs we can now look at
|
|
||||||
the thread id and find out if it was allocated by another thread id
|
|
||||||
and decrease the used counter of that thread instead, thus keeping the
|
|
||||||
free and used counters correct. And keeping the free and used counters
|
|
||||||
corrects is very important since the relationship between these two
|
|
||||||
variables decides if memory should be returned to the global pool or
|
|
||||||
not when a deallocation occurs.
|
|
||||||
</p><p>
|
|
||||||
When the application requests memory (calling allocate()) we first
|
|
||||||
look at the requested size and if this is >_S_max_bytes we call new()
|
|
||||||
directly and return.
|
|
||||||
</p><p>
|
|
||||||
If the requested size is within limits we start by finding out from which
|
|
||||||
bin we should serve this request by looking in _S_binmap.
|
|
||||||
</p><p>
|
|
||||||
A call to _S_get_thread_id() returns the thread id for the calling thread
|
|
||||||
(and if no value has been set in _S_thread_key, a new id is assigned and
|
|
||||||
returned).
|
|
||||||
</p><p>
|
|
||||||
A quick look at _S_bin[ bin ].first[ thread_id ] tells us if there are
|
|
||||||
any blocks of this size on the current threads freelist. If this is
|
|
||||||
not NULL - fine, just remove the block that _S_bin[ bin ].first[
|
|
||||||
thread_id ] points to from the list, update _S_bin[ bin ].first[
|
|
||||||
thread_id ], update the free and used counters and return a pointer to
|
|
||||||
that blocks data.
|
|
||||||
</p><p>
|
|
||||||
If the freelist is empty (the pointer is NULL) we start by looking at
|
|
||||||
the global freelist (0). If there are blocks available on the global
|
|
||||||
freelist we lock this bins mutex and move up to block_count (the
|
|
||||||
number of blocks of this bins size that will fit into a _S_chunk_size)
|
|
||||||
or until end of list - whatever comes first - to the current threads
|
|
||||||
freelist and at the same time change the thread_id ownership and
|
|
||||||
update the counters and pointers. When the bins mutex has been
|
|
||||||
unlocked, we remove the block that _S_bin[ bin ].first[ thread_id ]
|
|
||||||
points to from the list, update _S_bin[ bin ].first[ thread_id ],
|
|
||||||
update the free and used counters, and return a pointer to that blocks
|
|
||||||
data.
|
|
||||||
</p><p>
|
|
||||||
The reason that the number of blocks moved to the current threads
|
|
||||||
freelist is limited to block_count is to minimize the chance that a
|
|
||||||
subsequent deallocate() call will return the excess blocks to the
|
|
||||||
global freelist (based on the _S_freelist_headroom calculation, see
|
|
||||||
below).
|
|
||||||
</p><p>
|
|
||||||
However if there isn't any memory on the global pool we need to get
|
|
||||||
memory from the system - this is done in exactly the same way as in a
|
|
||||||
single threaded application with one major difference; the list built
|
|
||||||
in the newly allocated memory (of _S_chunk_size size) is added to the
|
|
||||||
current threads freelist instead of to the global.
|
|
||||||
</p><p>
|
|
||||||
The basic process of a deallocation call is simple: always add the
|
|
||||||
block to the front of the current threads freelist and update the
|
|
||||||
counters and pointers (as described earlier with the specific check of
|
|
||||||
ownership that causes the used counter of the thread that originally
|
|
||||||
allocated the block to be decreased instead of the current threads
|
|
||||||
counter).
|
|
||||||
</p><p>
|
|
||||||
And here comes the free and used counters to service. Each time a
|
|
||||||
deallocation() call is made, the length of the current threads
|
|
||||||
freelist is compared to the amount memory in use by this thread.
|
|
||||||
</p><p>
|
|
||||||
Let's go back to the example of an application that has one thread
|
|
||||||
that does all the allocations and one that deallocates. Both these
|
|
||||||
threads use say 516 32-byte blocks that was allocated during thread
|
|
||||||
creation for example. Their used counters will both say 516 at this
|
|
||||||
point. The allocation thread now grabs 1000 32-byte blocks and puts
|
|
||||||
them in a shared container. The used counter for this thread is now
|
|
||||||
1516.
|
|
||||||
</p><p>
|
|
||||||
The deallocation thread now deallocates 500 of these blocks. For each
|
|
||||||
deallocation made the used counter of the allocating thread is
|
|
||||||
decreased and the freelist of the deallocation thread gets longer and
|
|
||||||
longer. But the calculation made in deallocate() will limit the length
|
|
||||||
of the freelist in the deallocation thread to _S_freelist_headroom %
|
|
||||||
of it's used counter. In this case, when the freelist (given that the
|
|
||||||
_S_freelist_headroom is at it's default value of 10%) exceeds 52
|
|
||||||
(516/10) blocks will be returned to the global pool where the
|
|
||||||
allocating thread may pick them up and reuse them.
|
|
||||||
</p><p>
|
|
||||||
In order to reduce lock contention (since this requires this bins
|
|
||||||
mutex to be locked) this operation is also made in chunks of blocks
|
|
||||||
(just like when chunks of blocks are moved from the global freelist to
|
|
||||||
a threads freelist mentioned above). The "formula" used can probably
|
|
||||||
be improved to further reduce the risk of blocks being "bounced back
|
|
||||||
and forth" between freelists.
|
|
||||||
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch31s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bitmap_allocator.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Testing </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> bitmap_allocator</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,6 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 33. Containers</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bitmap_allocator.html" title="bitmap_allocator" /><link rel="next" href="bk01pt12ch33s02.html" title="HP/SGI" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 33. Containers</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bitmap_allocator.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch33s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.containers"></a>Chapter 33. Containers</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt12ch33.html#manual.ext.containers.pbds">Policy Based Data Structures</a></span></dt><dt><span class="sect1"><a href="bk01pt12ch33s02.html">HP/SGI</a></span></dt><dt><span class="sect1"><a href="bk01pt12ch33s03.html">Deprecated HP/SGI</a></span></dt></dl></div><p>
|
|
||||||
</p><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.containers.pbds"></a>Policy Based Data Structures</h2></div></div></div><p>
|
|
||||||
<a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/ext/pb_ds/index.html" target="_top">More details here</a>.
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bitmap_allocator.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch33s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">bitmap_allocator </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> HP/SGI</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,38 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 34. Utilities</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch33s03.html" title="Deprecated HP/SGI" /><link rel="next" href="bk01pt12ch35.html" title="Chapter 35. Algorithms" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 34. Utilities</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch33s03.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch35.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.util"></a>Chapter 34. Utilities</h2></div></div></div><p>
|
|
||||||
The <functional> header contains many additional functors
|
|
||||||
and helper functions, extending section 20.3. They are
|
|
||||||
implemented in the file stl_function.h:
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p><code class="code">identity_element</code> for addition and multiplication. *
|
|
||||||
</p></li><li><p>The functor <code class="code">identity</code>, whose <code class="code">operator()</code>
|
|
||||||
returns the argument unchanged. *
|
|
||||||
</p></li><li><p>Composition functors <code class="code">unary_function</code> and
|
|
||||||
<code class="code">binary_function</code>, and their helpers <code class="code">compose1</code>
|
|
||||||
and <code class="code">compose2</code>. *
|
|
||||||
</p></li><li><p><code class="code">select1st</code> and <code class="code">select2nd</code>, to strip pairs. *
|
|
||||||
</p></li><li><p><code class="code">project1st</code> and <code class="code">project2nd</code>. * </p></li><li><p>A set of functors/functions which always return the same result. They
|
|
||||||
are <code class="code">constant_void_fun</code>, <code class="code">constant_binary_fun</code>,
|
|
||||||
<code class="code">constant_unary_fun</code>, <code class="code">constant0</code>,
|
|
||||||
<code class="code">constant1</code>, and <code class="code">constant2</code>. * </p></li><li><p>The class <code class="code">subtractive_rng</code>. * </p></li><li><p>mem_fun adaptor helpers <code class="code">mem_fun1</code> and
|
|
||||||
<code class="code">mem_fun1_ref</code> are provided for backwards compatibility. </p></li></ul></div><p>
|
|
||||||
20.4.1 can use several different allocators; they are described on the
|
|
||||||
main extensions page.
|
|
||||||
</p><p>
|
|
||||||
20.4.3 is extended with a special version of
|
|
||||||
<code class="code">get_temporary_buffer</code> taking a second argument. The
|
|
||||||
argument is a pointer, which is ignored, but can be used to specify
|
|
||||||
the template type (instead of using explicit function template
|
|
||||||
arguments like the standard version does). That is, in addition to
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
get_temporary_buffer<int>(5);
|
|
||||||
</pre><p>
|
|
||||||
you can also use
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
get_temporary_buffer(5, (int*)0);
|
|
||||||
</pre><p>
|
|
||||||
A class <code class="code">temporary_buffer</code> is given in stl_tempbuf.h. *
|
|
||||||
</p><p>
|
|
||||||
The specialized algorithms of section 20.4.4 are extended with
|
|
||||||
<code class="code">uninitialized_copy_n</code>. *
|
|
||||||
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch33s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch35.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Deprecated HP/SGI </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 35. Algorithms</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,20 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 35. Algorithms</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch34.html" title="Chapter 34. Utilities" /><link rel="next" href="bk01pt12ch36.html" title="Chapter 36. Numerics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 35. Algorithms</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch34.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch36.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.algorithms"></a>Chapter 35. Algorithms</h2></div></div></div><p>25.1.6 (count, count_if) is extended with two more versions of count
|
|
||||||
and count_if. The standard versions return their results. The
|
|
||||||
additional signatures return void, but take a final parameter by
|
|
||||||
reference to which they assign their results, e.g.,
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
void count (first, last, value, n);</pre><p>25.2 (mutating algorithms) is extended with two families of signatures,
|
|
||||||
random_sample and random_sample_n.
|
|
||||||
</p><p>25.2.1 (copy) is extended with
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
copy_n (_InputIter first, _Size count, _OutputIter result);</pre><p>which copies the first 'count' elements at 'first' into 'result'.
|
|
||||||
</p><p>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper
|
|
||||||
predicates. Look in the doxygen-generated pages for notes on these.
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p><code class="code">is_heap</code> tests whether or not a range is a heap.</p></li><li><p><code class="code">is_sorted</code> tests whether or not a range is sorted in
|
|
||||||
nondescending order.</p></li></ul></div><p>25.3.8 (lexicographical_compare) is extended with
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
|
|
||||||
_InputIter2 first2, _InputIter2 last2)</pre><p>which does... what?
|
|
||||||
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch34.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch36.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 34. Utilities </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 36. Numerics</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,17 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 36. Numerics</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch35.html" title="Chapter 35. Algorithms" /><link rel="next" href="bk01pt12ch37.html" title="Chapter 37. Iterators" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 36. Numerics</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch35.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch37.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.numerics"></a>Chapter 36. Numerics</h2></div></div></div><p>26.4, the generalized numeric operations such as accumulate, are extended
|
|
||||||
with the following functions:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
power (x, n);
|
|
||||||
power (x, n, moniod_operation);</pre><p>Returns, in FORTRAN syntax, "x ** n" where n>=0. In the
|
|
||||||
case of n == 0, returns the <a class="ulink" href="#ch20" target="_top">identity element</a> for the
|
|
||||||
monoid operation. The two-argument signature uses multiplication (for
|
|
||||||
a true "power" implementation), but addition is supported as well.
|
|
||||||
The operation functor must be associative.
|
|
||||||
</p><p>The <code class="code">iota</code> function wins the award for Extension With the
|
|
||||||
Coolest Name. It "assigns sequentially increasing values to a range.
|
|
||||||
That is, it assigns value to *first, value + 1 to *(first + 1) and so
|
|
||||||
on." Quoted from SGI documentation.
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
void iota(_ForwardIter first, _ForwardIter last, _Tp value);</pre></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch35.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch37.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 35. Algorithms </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 37. Iterators</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,11 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 37. Iterators</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch36.html" title="Chapter 36. Numerics" /><link rel="next" href="bk01pt12ch38.html" title="Chapter 38. Input and Output" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 37. Iterators</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch36.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch38.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.iterators"></a>Chapter 37. Iterators</h2></div></div></div><p>24.3.2 describes <code class="code">struct iterator</code>, which didn't exist in the
|
|
||||||
original HP STL implementation (the language wasn't rich enough at the
|
|
||||||
time). For backwards compatibility, base classes are provided which
|
|
||||||
declare the same nested typedefs:
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>input_iterator</p></li><li><p>output_iterator</p></li><li><p>forward_iterator</p></li><li><p>bidirectional_iterator</p></li><li><p>random_access_iterator</p></li></ul></div><p>24.3.4 describes iterator operation <code class="code">distance</code>, which takes
|
|
||||||
two iterators and returns a result. It is extended by another signature
|
|
||||||
which takes two iterators and a reference to a result. The result is
|
|
||||||
modified, and the function returns nothing.
|
|
||||||
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch36.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch38.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 36. Numerics </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 38. Input and Output</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,48 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 38. Input and Output</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch37.html" title="Chapter 37. Iterators" /><link rel="next" href="bk01pt12ch39.html" title="Chapter 39. Demangling" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 38. Input and Output</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch37.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch39.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.io"></a>Chapter 38. Input and Output</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bk01pt12ch38.html#manual.ext.io.filebuf_derived">Derived filebufs</a></span></dt></dl></div><p>
|
|
||||||
Extensions allowing <code class="code">filebuf</code>s to be constructed from
|
|
||||||
"C" types like FILE*s and file descriptors.
|
|
||||||
</p><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.io.filebuf_derived"></a>Derived filebufs</h2></div></div></div><p>The v2 library included non-standard extensions to construct
|
|
||||||
<code class="code">std::filebuf</code>s from C stdio types such as
|
|
||||||
<code class="code">FILE*</code>s and POSIX file descriptors.
|
|
||||||
Today the recommended way to use stdio types with libstdc++
|
|
||||||
IOStreams is via the <code class="code">stdio_filebuf</code> class (see below),
|
|
||||||
but earlier releases provided slightly different mechanisms.
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>3.0.x <code class="code">filebuf</code>s have another ctor with this signature:
|
|
||||||
<code class="code">basic_filebuf(__c_file_type*, ios_base::openmode, int_type);
|
|
||||||
</code>
|
|
||||||
This comes in very handy in a number of places, such as
|
|
||||||
attaching Unix sockets, pipes, and anything else which uses file
|
|
||||||
descriptors, into the IOStream buffering classes. The three
|
|
||||||
arguments are as follows:
|
|
||||||
</p><div class="itemizedlist"><ul type="circle"><li><p><code class="code">__c_file_type* F </code>
|
|
||||||
// the __c_file_type typedef usually boils down to stdio's FILE
|
|
||||||
</p></li><li><p><code class="code">ios_base::openmode M </code>
|
|
||||||
// same as all the other uses of openmode
|
|
||||||
</p></li><li><p><code class="code">int_type B </code>
|
|
||||||
// buffer size, defaults to BUFSIZ if not specified
|
|
||||||
</p></li></ul></div><p>
|
|
||||||
For those wanting to use file descriptors instead of FILE*'s, I
|
|
||||||
invite you to contemplate the mysteries of C's <code class="code">fdopen()</code>.
|
|
||||||
</p></li><li><p>In library snapshot 3.0.95 and later, <code class="code">filebuf</code>s bring
|
|
||||||
back an old extension: the <code class="code">fd()</code> member function. The
|
|
||||||
integer returned from this function can be used for whatever file
|
|
||||||
descriptors can be used for on your platform. Naturally, the
|
|
||||||
library cannot track what you do on your own with a file descriptor,
|
|
||||||
so if you perform any I/O directly, don't expect the library to be
|
|
||||||
aware of it.
|
|
||||||
</p></li><li><p>Beginning with 3.1, the extra <code class="code">filebuf</code> constructor and
|
|
||||||
the <code class="code">fd()</code> function were removed from the standard
|
|
||||||
filebuf. Instead, <code class="code"><ext/stdio_filebuf.h></code> contains
|
|
||||||
a derived class called
|
|
||||||
<a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/class____gnu__cxx_1_1stdio__filebuf.html" target="_top"><code class="code">__gnu_cxx::stdio_filebuf</code></a>.
|
|
||||||
This class can be constructed from a C <code class="code">FILE*</code> or a file
|
|
||||||
descriptor, and provides the <code class="code">fd()</code> function.
|
|
||||||
</p></li></ul></div><p>If you want to access a <code class="code">filebuf</code>'s file descriptor to
|
|
||||||
implement file locking (e.g. using the <code class="code">fcntl()</code> system
|
|
||||||
call) then you might be interested in Henry Suter's
|
|
||||||
<a class="ulink" href="http://suter.home.cern.ch/suter/RWLock.html" target="_top">RWLock</a>
|
|
||||||
class.
|
|
||||||
</p><p>
|
|
||||||
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch37.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch39.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 37. Iterators </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 39. Demangling</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,71 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 39. Demangling</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch38.html" title="Chapter 38. Input and Output" /><link rel="next" href="concurrency.html" title="Chapter 40. Concurrency" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 39. Demangling</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch38.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="concurrency.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.demangle"></a>Chapter 39. Demangling</h2></div></div></div><p>
|
|
||||||
Transforming C++ ABI identifiers (like RTTI symbols) into the
|
|
||||||
original C++ source identifiers is called
|
|
||||||
“<span class="quote">demangling.</span>”
|
|
||||||
</p><p>
|
|
||||||
If you have read the <a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaceabi.html" target="_top">source
|
|
||||||
documentation for <code class="code">namespace abi</code></a> then you are
|
|
||||||
aware of the cross-vendor C++ ABI in use by GCC. One of the
|
|
||||||
exposed functions is used for demangling,
|
|
||||||
<code class="code">abi::__cxa_demangle</code>.
|
|
||||||
</p><p>
|
|
||||||
In programs like <span class="command"><strong>c++filt</strong></span>, the linker, and other tools
|
|
||||||
have the ability to decode C++ ABI names, and now so can you.
|
|
||||||
</p><p>
|
|
||||||
(The function itself might use different demanglers, but that's the
|
|
||||||
whole point of abstract interfaces. If we change the implementation,
|
|
||||||
you won't notice.)
|
|
||||||
</p><p>
|
|
||||||
Probably the only times you'll be interested in demangling at runtime
|
|
||||||
are when you're seeing <code class="code">typeid</code> strings in RTTI, or when
|
|
||||||
you're handling the runtime-support exception classes. For example:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
#include <exception>
|
|
||||||
#include <iostream>
|
|
||||||
#include <cxxabi.h>
|
|
||||||
|
|
||||||
struct empty { };
|
|
||||||
|
|
||||||
template <typename T, int N>
|
|
||||||
struct bar { };
|
|
||||||
|
|
||||||
|
|
||||||
int main()
|
|
||||||
{
|
|
||||||
int status;
|
|
||||||
char *realname;
|
|
||||||
|
|
||||||
// exception classes not in <stdexcept>, thrown by the implementation
|
|
||||||
// instead of the user
|
|
||||||
std::bad_exception e;
|
|
||||||
realname = abi::__cxa_demangle(e.what(), 0, 0, &status);
|
|
||||||
std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n';
|
|
||||||
free(realname);
|
|
||||||
|
|
||||||
|
|
||||||
// typeid
|
|
||||||
bar<empty,17> u;
|
|
||||||
const std::type_info &ti = typeid(u);
|
|
||||||
|
|
||||||
realname = abi::__cxa_demangle(ti.name(), 0, 0, &status);
|
|
||||||
std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n';
|
|
||||||
free(realname);
|
|
||||||
|
|
||||||
return 0;
|
|
||||||
}
|
|
||||||
</pre><p>
|
|
||||||
This prints
|
|
||||||
</p><pre class="screen">
|
|
||||||
<code class="computeroutput">
|
|
||||||
St13bad_exception => std::bad_exception : 0
|
|
||||||
3barI5emptyLi17EE => bar<empty, 17> : 0
|
|
||||||
</code>
|
|
||||||
</pre><p>
|
|
||||||
The demangler interface is described in the source documentation
|
|
||||||
linked to above. It is actually written in C, so you don't need to
|
|
||||||
be writing C++ in order to demangle C++. (That also means we have to
|
|
||||||
use crummy memory management facilities, so don't forget to free()
|
|
||||||
the returned char array.)
|
|
||||||
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch38.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="concurrency.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 38. Input and Output </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 40. Concurrency</td></tr></table></div></body></html>
|
|
||||||
|
|
@ -1,88 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 40. Concurrency</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.0" /><meta name="keywords" content=" ISO C++ , library " /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="extensions.html" title="Part XII. Extensions" /><link rel="prev" href="bk01pt12ch39.html" title="Chapter 39. Demangling" /><link rel="next" href="bk01pt12ch40s02.html" title="Implementation" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 40. Concurrency</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt12ch39.html">Prev</a> </td><th width="60%" align="center">Part XII. Extensions</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt12ch40s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.concurrency"></a>Chapter 40. Concurrency</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="concurrency.html#manual.ext.concurrency.design">Design</a></span></dt><dd><dl><dt><span class="sect2"><a href="concurrency.html#manual.ext.concurrency.design.threads">Interface to Locks and Mutexes</a></span></dt><dt><span class="sect2"><a href="concurrency.html#manual.ext.concurrency.design.atomics">Interface to Atomic Functions</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt12ch40s02.html">Implementation</a></span></dt><dd><dl><dt><span class="sect2"><a href="bk01pt12ch40s02.html#manual.ext.concurrency.impl.atomic_fallbacks">Using Builtin Atomic Functions</a></span></dt><dt><span class="sect2"><a href="bk01pt12ch40s02.html#manual.ext.concurrency.impl.thread">Thread Abstraction</a></span></dt></dl></dd><dt><span class="sect1"><a href="bk01pt12ch40s03.html">Use</a></span></dt></dl></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.concurrency.design"></a>Design</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.design.threads"></a>Interface to Locks and Mutexes</h3></div></div></div><p>The file <ext/concurrence.h> contains all the higher-level
|
|
||||||
constructs for playing with threads. In contrast to the atomics layer,
|
|
||||||
the concurrence layer consists largely of types. All types are defined within <code class="code">namespace __gnu_cxx</code>.
|
|
||||||
</p><p>
|
|
||||||
These types can be used in a portable manner, regardless of the
|
|
||||||
specific environment. They are carefully designed to provide optimum
|
|
||||||
efficiency and speed, abstracting out underlying thread calls and
|
|
||||||
accesses when compiling for single-threaded situations (even on hosts
|
|
||||||
that support multiple threads.)
|
|
||||||
</p><p>The enumerated type <code class="code">_Lock_policy</code> details the set of
|
|
||||||
available locking
|
|
||||||
policies: <code class="code">_S_single</code>, <code class="code">_S_mutex</code>,
|
|
||||||
and <code class="code">_S_atomic</code>.
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p><code class="code">_S_single</code></p><p>Indicates single-threaded code that does not need locking.
|
|
||||||
</p></li><li><p><code class="code">_S_mutex</code></p><p>Indicates multi-threaded code using thread-layer abstractions.
|
|
||||||
</p></li><li><p><code class="code">_S_atomic</code></p><p>Indicates multi-threaded code using atomic operations.
|
|
||||||
</p></li></ul></div><p>The compile-time constant <code class="code">__default_lock_policy</code> is set
|
|
||||||
to one of the three values above, depending on characteristics of the
|
|
||||||
host environment and the current compilation flags.
|
|
||||||
</p><p>Two more datatypes make up the rest of the
|
|
||||||
interface: <code class="code">__mutex</code>, and <code class="code">__scoped_lock</code>.
|
|
||||||
</p><p>
|
|
||||||
</p><p>The scoped lock idiom is well-discussed within the C++
|
|
||||||
community. This version takes a <code class="code">__mutex</code> reference, and
|
|
||||||
locks it during construction of <code class="code">__scoped_locke</code> and
|
|
||||||
unlocks it during destruction. This is an efficient way of locking
|
|
||||||
critical sections, while retaining exception-safety.
|
|
||||||
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.concurrency.design.atomics"></a>Interface to Atomic Functions</h3></div></div></div><p>
|
|
||||||
Two functions and one type form the base of atomic support.
|
|
||||||
</p><p>The type <code class="code">_Atomic_word</code> is a signed integral type
|
|
||||||
supporting atomic operations.
|
|
||||||
</p><p>
|
|
||||||
The two functions functions are:
|
|
||||||
</p><pre class="programlisting">
|
|
||||||
_Atomic_word
|
|
||||||
__exchange_and_add_dispatch(volatile _Atomic_word*, int);
|
|
||||||
|
|
||||||
void
|
|
||||||
__atomic_add_dispatch(volatile _Atomic_word*, int);
|
|
||||||
</pre><p>Both of these functions are declared in the header file
|
|
||||||
<ext/atomicity.h>, and are in <code class="code">namespace __gnu_cxx</code>.
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p>
|
|
||||||
<code class="code">
|
|
||||||
__exchange_and_add_dispatch
|
|
||||||
</code>
|
|
||||||
</p><p>Adds the second argument's value to the first argument. Returns the old value.
|
|
||||||
</p></li><li><p>
|
|
||||||
<code class="code">
|
|
||||||
__atomic_add_dispatch
|
|
||||||
</code>
|
|
||||||
</p><p>Adds the second argument's value to the first argument. Has no return value.
|
|
||||||
</p></li></ul></div><p>
|
|
||||||
These functions forward to one of several specialized helper
|
|
||||||
functions, depending on the circumstances. For instance,
|
|
||||||
</p><p>
|
|
||||||
<code class="code">
|
|
||||||
__exchange_and_add_dispatch
|
|
||||||
</code>
|
|
||||||
</p><p>
|
|
||||||
Calls through to either of:
|
|
||||||
</p><div class="itemizedlist"><ul type="disc"><li><p><code class="code">__exchange_and_add</code>
|
|
||||||
</p><p>Multi-thread version. Inlined if compiler-generated builtin atomics
|
|
||||||
can be used, otherwise resolved at link time to a non-builtin code
|
|
||||||
sequence.
|
|
||||||
</p></li><li><p><code class="code">__exchange_and_add_single</code>
|
|
||||||
</p><p>Single threaded version. Inlined.</p></li></ul></div><p>However, only <code class="code">__exchange_and_add_dispatch</code>
|
|
||||||
and <code class="code">__atomic_add_dispatch</code> should be used. These functions
|
|
||||||
can be used in a portable manner, regardless of the specific
|
|
||||||
environment. They are carefully designed to provide optimum efficiency
|
|
||||||
and speed, abstracting out atomic accesses when they are not required
|
|
||||||
(even on hosts that support compiler intrinsics for atomic
|
|
||||||
operations.)
|
|
||||||
</p><p>
|
|
||||||
In addition, there are two macros
|
|
||||||
</p><p>
|
|
||||||
<code class="code">
|
|
||||||
_GLIBCXX_READ_MEM_BARRIER
|
|
||||||
</code>
|
|
||||||
</p><p>
|
|
||||||
<code class="code">
|
|
||||||
_GLIBCXX_WRITE_MEM_BARRIER
|
|
||||||
</code>
|
|
||||||
</p><p>
|
|
||||||
Which expand to the appropriate write and read barrier required by the
|
|
||||||
host hardware and operating system.
|
|
||||||
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt12ch39.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt12ch40s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 39. Demangling </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Implementation</td></tr></table></div></body></html>
|
|
||||||
Loading…
Reference in New Issue