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