diff options
| author | nobody <nobody@localhost> | 2001-07-06 20:31:02 +0000 |
|---|---|---|
| committer | nobody <nobody@localhost> | 2001-07-06 20:31:02 +0000 |
| commit | d9fda65293cc99e1ede23fa3993ce25dc702c90d (patch) | |
| tree | f6c594f77b7a91e842a859b42553c4c820a0f4b2 /more | |
| parent | ce5e16b6ae28e66369cdcfc6c416db64fd0298ba (diff) | |
| parent | 7765e717adb093ac3f58d2f49c38d3f3f683364c (diff) | |
| download | boost-d9fda65293cc99e1ede23fa3993ce25dc702c90d.tar.gz | |
This commit was manufactured by cvs2svn to create tag
'Version_1_23_0'.
[SVN r10562]
Diffstat (limited to 'more')
| -rw-r--r-- | more/borland_cpp.html | 362 | ||||
| -rw-r--r-- | more/count_bdy.htm | 1166 | ||||
| -rw-r--r-- | more/discussion_policy.htm | 118 | ||||
| -rw-r--r-- | more/download.html | 140 | ||||
| -rw-r--r-- | more/error_handling.html | 92 | ||||
| -rw-r--r-- | more/faq.htm | 137 | ||||
| -rw-r--r-- | more/feature_model_diagrams.htm | 104 | ||||
| -rw-r--r-- | more/formal_review_process.htm | 139 | ||||
| -rw-r--r-- | more/generic_exception_safety.html | 695 | ||||
| -rw-r--r-- | more/generic_programming.html | 448 | ||||
| -rw-r--r-- | more/header.htm | 93 | ||||
| -rw-r--r-- | more/imp_vars.htm | 201 | ||||
| -rw-r--r-- | more/index.htm | 125 | ||||
| -rw-r--r-- | more/int_const_guidelines.htm | 323 | ||||
| -rw-r--r-- | more/lib_guide.htm | 352 | ||||
| -rw-r--r-- | more/library_reuse.htm | 72 | ||||
| -rw-r--r-- | more/microsoft_vcpp.html | 307 | ||||
| -rw-r--r-- | more/regression.html | 256 | ||||
| -rw-r--r-- | more/submission_process.htm | 127 | ||||
| -rw-r--r-- | more/test_policy.htm | 93 |
20 files changed, 5350 insertions, 0 deletions
diff --git a/more/borland_cpp.html b/more/borland_cpp.html new file mode 100644 index 0000000000..2a6a7b5e53 --- /dev/null +++ b/more/borland_cpp.html @@ -0,0 +1,362 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Portability Hints: Borland C++ 5.5.1</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> + +<p> + +<h1>Portability Hints: Borland C++ 5.5.1</h1> + +It is a general aim for boost libraries to be +<a href="lib_guide.htm#Portability">portable</a>. The primary means +for achieving this goal is to adhere to ISO Standard C++. However, +ISO C++ is a broad and complex standard and most compilers are +not fully conformant to ISO C++ yet. In order to achieve portability +in the light of this restriction, it seems advisable to get acquainted +with those language features that some compilers do not fully +implement yet. +<p> + +This page gives portability hints on some language features of the +Borland C++ version 5.5.1 compiler. Furthermore, the appendix +presents additional problems with Borland C++ version 5.5. Borland +C++ 5.5.1 is a freely available command-line compiler for Win32 +available at +<a href="http://www.borland.com/">http://www.borland.com/</a>. +<p> + +Each entry in the following list describes a particular issue, +complete with sample source code to demonstrate the effect. +Most sample code herein has been verified to compile with gcc 2.95.2 +and Comeau C++ 4.2.44. + + +<h2>Preprocessor symbol</h2> + +The preprocessor symbol <code>__BORLANDC__</code> is defined for all +Borland C++ compilers. Its value is the version number of the +compiler interpreted as a hexadecimal number. The following table +lists some known values. +<p> + +<table border="1"> +<tr> +<th>Compiler</th> +<th><code>__BORLANDC__</code> value</th> +</tr> + +<tr> +<td>Borland C++ Builder 4</td> +<td>0x0540</td> +</tr> + +<tr> +<td>Borland C++ Builder 5</td> +<td>0x0550</td> +</tr> + +<tr> +<td>Borland C++ 5.5</td> +<td>0x0550</td> +</tr> + +<tr> +<td>Borland C++ 5.5.1</td> +<td>0x0551</td> +</tr> + +</table> + +<h2>Core Language</h2> + +<h3>[using-directive] Mixing <code>using</code>-declarations and +<code>using</code>-directives</h3> + +Mixing <code>using</code>-directives (which refer to whole namespaces) +and namespace-level <code>using</code>-declarations (which refer to +individual identifiers within foreign namespaces) causes ambiguities +where there are none. The following code fragment illustrates this: + +<pre> +namespace N { + int x(); +} + +using N::x; +using namespace N; + +int main() +{ + &x; // Ambiguous overload +} +</pre> + + +<h3>[using template] <code>using</code>-declarations for class +templates</h3> + +Identifiers for class templates can be used as arguments to +<code>using</code>-declarations as any other identifier. However, the +following code fails to compile with Borland C++: + +<pre> +template<class T> +class X { }; + +namespace N +{ + // "cannot use template 'X<T>' without specifying specialization parameters" + using ::X; +}; +</pre> + + +<h3>[template const arg] Deduction of constant arguments to function +templates</h3> + +Template function type deduction should omit top-level constness. +However, this code fragment instantiates "f<const int>(int)": + +<pre> +template<class T> +void f(T x) +{ + x = 1; // works + (void) &x; + T y = 17; + y = 20; // "Cannot modify a const object in function f<const int>(int)" + (void) &y; +} + +int main() +{ + const int i = 17; + f(i); +} +</pre> + +The boost/rational.hpp header exhibits this problem in connection with +the gcd() function. + + +<h3>[function address] Resolving addresses of overloaded +functions</h3> + +Addresses of overloaded functions are not in all contexts properly +resolved (std:13.4 [over.over]); here is a small example: +<pre> +template<class Arg> +void f( void(*g)(Arg) ); + +void h(int); +void h(double); + +template<class T> +void h2(T); + +int main() +{ + void (*p)(int) = h; // this works (std:13.4-1.1) + void (*p2)(unsigned char) = h2; // this works as well (std:13.4-1.1) + f<int>(h2); // this also works (std:13.4-1.3) + + // "Cannot generate template specialization from h(int)", + // "Could not find a match for f<Arg>(void (*)(int))" + f<double>(h); // should work (std:13.4-1.3) + + f( (void(*)(double))h); // C-style cast works (std:13.4-1.6 with 5.4) + + // "Overloaded 'h' ambiguous in this context" + f(static_cast<void(*)(double)>(h)); // should work (std:13.4-1.6 with 5.2.9) +} +</pre> + +<strong>Workaround:</strong> Always use C-style casts when determining +addresses of (potentially) overloaded functions. + +<h3>[string conversion] Converting <code>const char *</code> to +<code>std::string</code></h3> + +Implicitly converting <code>const char *</code> parameters to +<code>std::string</code> arguments fails if template functions are +explicitly instantiated (it works in the usual cases, though): + +<pre> +#include <string> + +template<class T> +void f(const std::string & s) +{} + +int main() +{ + f<double>("hello"); // "Could not find a match for f<T>(char *)" +} + +</pre> + +<strong>Workaround:</strong> Avoid explicit template function +instantiations (they have significant problems with Microsoft Visual +C++) and pass default-constructed unused dummy arguments with the +appropriate type. Alternatively, if you wish to keep to the explicit +instantiation, you could use an explicit conversion to +<code>std::string</code> or declare the template function as taking a +<code>const char *</code> parameter. + + +<h3>[template value defaults] Dependent default arguments for template +value parameters</h3> + +Template value parameters which default to an expression dependent on +previous template parameters don't work: + +<pre> +template<class T> +struct A +{ + static const bool value = true; +}; + +// "Templates must be classes or functions", "Declaration syntax error" +template<class T, bool v = A<T>::value> +struct B {}; + +int main() +{ + B<int> x; +} + +</pre> + + +<strong>Workaround:</strong> If the relevant non-type template +parameter is an implementation detail, use inheritance and a fully +qualified identifier (for example, ::N::A<T>::value). + + +<h3>[function partial ordering] Partial ordering of function +templates</h3> + +Partial ordering of function templates, as described in std:14.5.5.2 +[temp.func.order], does not work: + +<pre> +#include <iostream> + +template<class T> struct A {}; + +template<class T1> +void f(const A<T1> &) +{ + std::cout << "f(const A<T1>&)\n"; +} + +template<class T> +void f(T) +{ + std::cout << "f(T)\n"; +} + +int main() +{ + A<double> a; + f(a); // output: f(T) (wrong) + f(1); // output: f(T) (correct) +} +</pre> + +<strong>Workaround:</strong> Declare all such functions uniformly as +either taking a value or a reference parameter. + + +<h2>Library</h2> + + +<h3>[cmath.abs] Function <code>double std::abs(double)</code> +missing</h3> + +The function <code>double std::abs(double)</code> should be defined +(std:26.5-5 [lib.c.math]), but it is not: + +<pre> +#include <cmath> + +int main() +{ + double (*p)(double) = std::abs; // error +} +</pre> + +Note that <code>int std::abs(int)</code> will be used without warning +if you write <code>std::abs(5.1)</code>. +<p> +Similar remarks apply to seemingly all of the other standard math +functions, where Borland C++ fails to provide <code>float</code> and +<code>long double</code> overloads. +<p> +<strong>Workaround:</strong> Use <code>std::fabs</code> instead if +type genericity is not required. + +<h2>Appendix: Additional issues with Borland C++ version 5.5</h2> + +These issues are documented mainly for historic reasons. If you are +still using Borland C++ version 5.5, you are strongly encouraged to +obtain an upgrade to version 5.5.1, which fixes the issues described +in this section. + +<h3>[inline friend] Inline friend functions in template classes</h3> + +If a friend function of some class has not been declared before the +friend function declaration, the function is declared at the namespace +scope surrounding the class definition. Together with class templates +and inline definitions of friend functions, the code in the following +fragment should declare (and define) a non-template function "bool +N::f(int,int)", which is a friend of class N::A<int>. However, +Borland C++ v5.5 expects the function f to be declared beforehand: + +<pre> +namespace N { +template<class T> +class A +{ + // "f is not a member of 'N' in function main()" + friend bool f(T x, T y) { return x < y; } +}; +} + +int main() +{ + N::A<int> a; +} +</pre> + +This technique is extensively used in boost/operators.hpp. Giving in +to the wish of the compiler doesn't work in this case, because then +the "instantiate one template, get lots of helper functions at +namespace scope" approach doesn't work anymore. Defining +BOOST_NO_OPERATORS_IN_NAMESPACE (a define +BOOST_NO_INLINE_FRIENDS_IN_CLASS_TEMPLATES would match this case +better) works around this problem and leads to another one, see +[using-template]. + +<p> + +<hr> + +2000-09-30 <a href="../people/jens_maurer.htm">Jens Maurer</a> +</body> +</html> diff --git a/more/count_bdy.htm b/more/count_bdy.htm new file mode 100644 index 0000000000..0dd6f0bc79 --- /dev/null +++ b/more/count_bdy.htm @@ -0,0 +1,1166 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> + +<HTML> + +<HEAD> + + <TITLE>Counted Body Techniques</TITLE> + + <META NAME="GENERATOR" CONTENT="Microsoft FrontPage 4.0"> + + <META NAME="Author" CONTENT="Kevlin Henney"> + + <META NAME="KeyWords" CONTENT="C++, Reference Counting, Advanced Techniques, Smart Pointers, Patterns"> + +</HEAD> + +<BODY bgcolor="#FFFFFF" text="#000000"> + + + +<H1 ALIGN=CENTER><I><FONT SIZE=+4>Counted Body Techniques</FONT></I></H1> + + + +<CENTER><P><B><FONT SIZE=+1><a href="../people/kevlin_henney.htm">Kevlin Henney</a><BR> + +</FONT>(<A HREF="mailto:kevlin@acm.org">kevlin@acm.org</A>, <a HREF="mailto:khenney@qatraining.com">khenney@qatraining.com</a>)</B></P></CENTER> + + + +<UL> + +<P>Reference counting techniques? Nothing new, you might think. Every good + +C++ text that takes you to an intermediate or advanced level will introduce + +the concept. It has been explored with such thoroughness in the past that + +you might be forgiven for thinking that everything that can be said has + +been said. Well, let's start from first principles and see if we can unearth + +something new....</P> + +</UL> + + + + +<HR WIDTH="100%"> +<H2>And then there were none...</H2> + + +<UL> + +<P>The principle behind reference counting is to keep a running usage count + +of an object so that when it falls to zero we know the object is unused. + +This is normally used to simplify the memory management for dynamically + +allocated objects: keep a count of the number of references held to that + +object and, on zero, delete the object.</P> + + + +<P>How to keep a track of the number of users of an object? Well, normal + +pointers are quite dumb, and so an extra level of indirection is required + +to manage the count. This is essentially the P<FONT SIZE=-1>ROXY</FONT> + +pattern described in <I>Design Patterns</I> [Gamma, Helm, Johnson & + +Vlissides, Addison-Wesley, <FONT SIZE=-1>ISBN </FONT>0-201-63361-2]. The + +intent is given as</P> + + + +<UL> + +<P><I>Provide a surrogate or placeholder for another object to control + +access to it.</I></P> + +</UL> + + + +<P>Coplien [<I>Advanced C++ Programming Styles and Idioms</I>, Addison-Wesley, + +<FONT SIZE=-1>ISBN </FONT>0-201-56365-7] defines a set of idioms related + +to this essential separation of a handle and a body part. The <I>Taligent + +Guide to Designing Programs </I>[Addison-Wesley, <FONT SIZE=-1>ISBN </FONT>0-201-40888-0] + +identifies a number of specific categories for proxies (aka surrogates). + +Broadly speaking they fall into two general categories:</P> + + + +<UL> + +<LI><I>Hidden</I>: The handle is the object of interest, hiding the body + +itself. The functionality of the handle is obtained by delegation to the + +body, and the user of the handle is unaware of the body. Reference counted + +strings offer a transparent optimisation. The body is shared between copies + +of a string until such a time as a change is needed, at which point a copy + +is made. Such a C<FONT SIZE=-1>OPY</FONT> <FONT SIZE=-1>ON</FONT> W<FONT SIZE=-1>RITE</FONT> + +pattern (a specialisation of L<FONT SIZE=-1>AZY</FONT> E<FONT SIZE=-1>VALUATION</FONT>) + +requires the use of a hidden reference counted body.</LI> + + + +<LI><I>Explicit</I>: Here the body is of interest and the handle merely + +provides intelligence for its access and housekeeping. In C++ this is often + +implemented as the S<FONT SIZE=-1>MART</FONT> P<FONT SIZE=-1>OINTER</FONT> + +idiom. One such application is that of reference counted smart pointers + +that collaborate to keep a count of an object, deleting it when the count + +falls to zero.</LI> + +</UL> + +</UL> + + + + +<HR WIDTH="100%"> +<H2>Attached vs detached</H2> + + +<UL> + +<P>For reference counted smart pointers there are two places the count + +can exist, resulting in two different patterns, both outlined in <I>Software + +Patterns</I> [Coplien, SIGS, <FONT SIZE=-1>ISBN </FONT>0-884842-50-X]:</P> + + + +<UL> + +<LI>C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT> or A<FONT SIZE=-1>TTACHED</FONT> + +C<FONT SIZE=-1>OUNTED</FONT> H<FONT SIZE=-1>ANDLE</FONT>/B<FONT SIZE=-1>ODY</FONT> + +places the count within the object being counted. The benefits are that + +countability is a part of the object being counted, and that reference + +counting does not require an additional object. The drawbacks are clearly + +that this is intrusive, and that the space for the reference count is wasted + +when the object is not heap based. Therefore the reference counting ties + +you to a particular implementation and style of use.</LI> + + + +<LI>D<FONT SIZE=-1>ETACHED</FONT> C<FONT SIZE=-1>OUNTED</FONT> H<FONT SIZE=-1>ANDLE</FONT>/B<FONT SIZE=-1>ODY</FONT> + +places the count outside the object being counted, such that they are handled + +together. The clear benefit of this is that this technique is completely + +unintrusive, with all of the intelligence and support apparatus in the + +smart pointer, and therefore can be used on classes created independently + +of the reference counted pointer. The main disadvantage is that frequent + +use of this can lead to a proliferation of small objects, i.e. the counter, + +being created on the heap.</LI> + +</UL> + + + +<P>Even with this simple analysis, it seems that the D<FONT SIZE=-1>ETACHED</FONT> + +C<FONT SIZE=-1>OUNTED</FONT> H<FONT SIZE=-1>ANDLE</FONT>/B<FONT SIZE=-1>ODY</FONT> + +approach is ahead. Indeed, with the increasing use of templates this is + +often the favourite, and is the principle behind the common - but not standard + +- <TT><FONT SIZE=+1>counted_ptr</FONT></TT>. +<I>[The Boost name is <a href="../libs/smart_ptr/shared_ptr.htm"><TT><FONT SIZE=+1>shared_ptr</FONT></TT></a> + +rather than <TT><FONT SIZE=+1>counted_ptr</FONT></TT>.]</I></P> + + + +<P>A common implementation of C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT> + +is to provide the counting mechanism in a base class that the counted type + +is derived from. Either that, or the reference counting mechanism is provided + +anew for each class that needs it. Both of these approaches are unsatisfactory + +because they are quite closed, coupling a class into a particular framework. + +Added to this the non-cohesiveness of having the count lying dormant in + +a non-counted object, and you get the feeling that excepting its use in + +widespread object models such as COM and CORBA the C<FONT SIZE=-1>OUNTED</FONT> + +B<FONT SIZE=-1>ODY</FONT> approach is perhaps only of use in specialised + +situations.</P> + +</UL> + + + +<HR WIDTH="100%"> +<H2>A requirements based approach</H2> + + +<UL> + +<P>It is the question of openness that convinced me to revisit the problems + +with the C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT> idiom. + +Yes, there is a certain degree of intrusion expected when using this idiom, + +but is there anyway to minimise this and decouple the choice of counting + +mechanism from the smart pointer type used?</P> + + + +<P>In recent years the most instructive body of code and specification + +for constructing open general purpose components has been the Stepanov + +and Lee's STL (Standard Template Library), now part of the C++ standard + +library. The STL approach makes extensive use of compile time polymorphism + +based on well defined operational requirements for types. For instance, + +each container, contained and iterator type is defined by the operations + +that should be performable on an object of that type, often with annotations + +describing additional constraints. Compile time polymorphism, as its name + +suggests, resolves functions at compile time based on function name and + +argument usage, i.e. overloading. This is less intrusive, although less + +easily diagnosed if incorrect, than runtime poymorphism that is based on + +types, names and function signatures.</P> + + + +<P>This requirements based approach can be applied to reference counting. + +The operations we need for a type to be <I>Countable</I> are loosely:</P> + + + +<UL> + +<LI>An <TT><FONT SIZE=+1>acquire</FONT></TT> operation that registers interest + +in a <I>Countable </I>object.</LI> + + + +<LI>A <TT><FONT SIZE=+1>release</FONT></TT> operation unregisters interest + +in a <I>Countable </I>object.</LI> + + + +<LI>An <TT><FONT SIZE=+1>acquired</FONT></TT> query that returns whether + +or not a <I>Countable </I>object is currently acquired.</LI> + + + +<LI>A <TT><FONT SIZE=+1>dispose</FONT></TT> operation that is responsible + +for disposing of an object that is no longer acquired.</LI> + +</UL> + + + +<P>Note that the count is deduced as a part of the abstract state of this + +type, and is not mentioned or defined in any other way. The openness of + +this approach derives in part from the use of global functions, meaning + +that no particular member functions are implied; a perfect way to wrap + +up an existing counted body class without modifying the class itself. The + +other aspect to the openness comes from a more precise specification of + +the operations.</P> + + + +<P>For a type to be <I>Countable</I> it must satisfy the following requirements, + +where <TT><FONT SIZE=+1>ptr</FONT></TT> is a non-null pointer to a single + +object (i.e. not an array) of the type, and <I><TT><FONT SIZE=+1>#function</FONT></TT></I> + +indicates number of calls to <TT><FONT SIZE=+1><I>function(</I>ptr<I>)</I></FONT></TT>:</P> + + + +<CENTER><TABLE BORDER=1 CELLSPACING=2 CELLPADDING=2 > + +<TR> + +<TD><I>Expression</I></TD> + + + +<TD><I>Return type</I></TD> + + + +<TD><I>Semantics and notes</I></TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>acquire(ptr)</FONT></TT></TD> + + + +<TD>no requirement</TD> + + + +<TD><I>post</I>: <TT><FONT SIZE=+1>acquired(ptr)</FONT></TT></TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>release(ptr)</FONT></TT></TD> + + + +<TD>no requirement</TD> + + + +<TD><I>pre</I>: <TT><FONT SIZE=+1>acquired(ptr)<BR> + +</FONT></TT><I>post</I>: <TT><FONT SIZE=+1>acquired(ptr) == #acquire - + +#release</FONT></TT></TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>acquired(ptr)</FONT></TT></TD> + + + +<TD>convertible to <TT><FONT SIZE=+1>bool</FONT></TT></TD> + + + +<TD><I>return</I>: <TT><FONT SIZE=+1>#acquire > #release</FONT></TT></TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>dispose(ptr, ptr)</FONT></TT></TD> + + + +<TD>no requirement</TD> + + + +<TD><I>pre</I>: <TT><FONT SIZE=+1>!acquired(ptr)<BR> + +</FONT></TT><I>post</I>: <TT><FONT SIZE=+1>*ptr</FONT></TT> no longer usable</TD> + +</TR> + +</TABLE></CENTER> + + + +<P>Note that the two arguments to <TT><FONT SIZE=+1>dispose</FONT></TT> + +are to support selection of the appropriate type safe version of the function + +to be called. In the general case the intent is that the first argument + +determines the type to be deleted, and would typically be templated, while + +the second selects which template to use, e.g. by conforming to a specific + +base class.</P> + + + +<P>In addition the following requirements must also be satisfied, where + +<TT><FONT SIZE=+1>null</FONT></TT> is a null pointer to the <I>Countable</I> + +type:</P> + + + +<CENTER><TABLE BORDER=1 > + +<TR> + +<TD><I>Expression</I></TD> + + + +<TD><I>Return type</I></TD> + + + +<TD><I>Semantics and notes</I></TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>acquire(null)</FONT></TT></TD> + + + +<TD>no requirement</TD> + + + +<TD><I>action</I>: none</TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>release(null)</FONT></TT></TD> + + + +<TD>no requirement</TD> + + + +<TD><I>action</I>: none</TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>acquired(null)</FONT></TT></TD> + + + +<TD>convertible to <TT><FONT SIZE=+1>bool</FONT></TT></TD> + + + +<TD><I>return</I>: <TT><FONT SIZE=+1>false</FONT></TT></TD> + +</TR> + + + +<TR> + +<TD><TT><FONT SIZE=+1>dispose(null, null)</FONT></TT></TD> + + + +<TD>no requirement</TD> + + + +<TD><I>action</I>: none</TD> + +</TR> + +</TABLE></CENTER> + + + +<P>Note that there are no requirements on these functions in terms of exceptions + +thrown or not thrown, except that if exceptions are thrown the functions + +themselves should be exception safe.</P> + +</UL> + + + +<HR WIDTH="100%"> +<H2>Getting smart</H2> + + +<UL> + +<P>Given the <I>Countable</I> requirements for a type, it is possible to + +define a generic smart pointer type that uses them for reference counting:</P> + + + +<UL> +<PRE><TT>template<typename countable_type> +class countable_ptr +{ +public: // construction and destruction + + explicit countable_ptr(countable_type *); + countable_ptr(const countable_ptr &); + ~countable_ptr(); + +public: // access + + countable_type *operator->() const; + countable_type &operator*() const; + countable_type *get() const; + +public: // modification + + countable_ptr &clear(); + countable_ptr &assign(countable_type *); + countable_ptr &assign(const countable_ptr &); + countable_ptr &operator=(const countable_ptr &); + +private: // representation + + countable_type *body; + +}; +</TT></PRE> + +</UL> + + + +<P>The interface to this class has been kept intentionally simple, e.g. + +member templates and <TT><FONT SIZE=+1>throw</FONT></TT> specs have been + +omitted, for exposition. The majority of the functions are quite simple + +in implementation, relying very much on the <TT><FONT SIZE=+1>assign</FONT></TT> + +member as a keystone function:</P> + + + +<UL> + +<PRE><TT>template<typename countable_type> +countable_ptr<countable_type>::countable_ptr(countable_type *initial) + : body(initial) +{ + acquire(body); +} + +template<typename countable_type> +countable_ptr<countable_type>::countable_ptr(const countable_ptr &other) + : body(other.body) +{ + acquire(body); +} + +template<typename countable_type> +countable_ptr<countable_type>::~countable_ptr() +{ + clear(); +} + +template<typename countable_type> +countable_type *countable_ptr<countable_type>::operator->() const +{ + return body; +} + +template<typename countable_type> +countable_type &countable_ptr<countable_type>::operator*() const +{ + return *body; +} + +template<typename countable_type> +countable_type *countable_ptr<countable_type>::get() const +{ + return body; +} + +template<typename countable_type> +countable_ptr<countable_type> &countable_ptr<countable_type>::clear() +{ + return assign(0); +} + +template<typename countable_type> +countable_ptr<countable_type> &countable_ptr<countable_type>::assign(countable_type *rhs) +{ + // set to rhs (uses Copy Before Release idiom which is self assignment safe) + acquire(rhs); + countable_type *old_body = body; + body = rhs; + + // tidy up + release(old_body); + if(!acquired(old_body)) + { + dispose(old_body, old_body); + } + + return *this; +} + +template<typename countable_type> +countable_ptr<countable_type> &countable_ptr<countable_type>::assign(const countable_ptr &rhs) +{ + return assign(rhs.body); +} + +template<typename countable_type> +countable_ptr<countable_type> &countable_ptr<countable_type>::operator=(const countable_ptr &rhs) +{ + return assign(rhs); +} +</TT></PRE> + +</UL> + +</UL> + + + +<HR WIDTH="100%"> +<H2>Public accountability</H2> + + +<UL> + +<P>Conformance to the requirements means that a type can be used with <TT><FONT SIZE=+1>countable_ptr</FONT></TT>. + +Here is an implementation mix-in class (<I>mix-imp</I>) that confers countability + +on its derived classes through member functions. This class can be used + +as a class adaptor:</P> + + + +<UL> + +<PRE><TT>class countability +{ +public: // manipulation + + void acquire() const; + void release() const; + size_t acquired() const; + +protected: // construction and destruction + + countability(); + ~countability(); + +private: // representation + + mutable size_t count; + +private: // prevention + + countability(const countability &); + countability &operator=(const countability &); + +}; +</TT></PRE> + +</UL> + + + +<P>Notice that the manipulation functions are <TT><FONT SIZE=+1>const</FONT></TT> + +and that the <TT><FONT SIZE=+1>count</FONT></TT> member itself is <TT><FONT SIZE=+1>mutable</FONT></TT>. + +This is because countability is not a part of an object's abstract state: + +memory management does not depend on the <TT><FONT SIZE=+1>const</FONT></TT>-ness + +or otherwise of an object. I won't include the definitions of the member + +functions here as you can probably guess them: increment, decrement and + +return the current count, respectively for the manipulation functions. + +In a multithreaded environment you should ensure that such read and write + +operations are atomic.</P> + + + +<P>So how do we make this class <I>Countable</I>? A simple set of forwarding + +functions does the job:</P> + + + +<UL> + +<PRE><TT>void acquire(const countability *ptr) +{ + if(ptr) + { + ptr->acquire(); + } +} + +void release(const countability *ptr) +{ + if(ptr) + { + ptr->release(); + } +} + +size_t acquired(const countability *ptr) +{ + return ptr ? ptr->acquired() : 0; +} + +template<class countability_derived> +void dispose(const countability_derived *ptr, const countability *) +{ + delete ptr; +} +</TT></PRE> + +</UL> + + + +<P>Any type that now derives from <TT><FONT SIZE=+1>countability</FONT></TT> + +may now be used with <TT><FONT SIZE=+1>countable_ptr</FONT></TT>:</P> + + + +<UL> + +<PRE><TT>class example : public countability +{ + ... +}; + +void simple() +{ + countable_ptr<example> ptr(new example); + countable_ptr<example> qtr(ptr); + ptr.clear(); // set ptr to point to null +} // allocated object deleted when qtr destructs +</TT></PRE> +</UL> +</UL> + + + + +<HR WIDTH="100%"> +<H2>Runtime mixin</H2> + + +<UL> + +<P>The challenge is to apply C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT> + +in a non-intrusive fashion, such that there is no overhead when an object + +is not counted. What we would like to do is confer this capability on a + +per object rather than on a per class basis. Effectively we are after <I>Countability + +</I>on any object, i.e. anything pointed to by a <TT><FONT SIZE=+1>void + +*</FONT></TT>! It goes without saying that <TT><FONT SIZE=+1>void</FONT></TT> + +is perhaps the least committed of any type.</P> + + + +<P>The forces to resolve on this are quite interesting, to say the least. + +Interesting, but not insurmountable. Given that the class of a runtime + +object cannot change dynamically in any well defined manner, and the layout + +of the object must be fixed, we have to find a new place and time to add + +the counting state. The fact that this must be added only on heap creation + +suggests the following solution:</P> + + + +<UL> + +<PRE><TT>struct countable_new; +extern const countable_new countable; + +void *operator new(size_t, const countable_new &); +void operator delete(void *, const countable_new &);</TT></PRE> +</UL> + + + +<P>We have overloaded <TT><FONT SIZE=+1>operator new</FONT></TT> with a + +dummy argument to distinguish it from the regular global <TT><FONT SIZE=+1>operator + +new</FONT></TT>. This is comparable to the use of the <TT><FONT SIZE=+1>std::nothrow_t</FONT></TT> + +type and <TT><FONT SIZE=+1>std::nothrow</FONT></TT> object in the standard + +library. The placement <TT><FONT SIZE=+1>operator delete</FONT></TT> is + +there to perform any tidy up in the event of failed construction. Note + +that this is not yet supported on all that many compilers.</P> + + + +<P>The result of a <TT><FONT SIZE=+1>new</FONT></TT> expression using <TT><FONT SIZE=+1>countable</FONT></TT> + +is an object allocated on the heap that has a header block that holds the + +count, i.e. we have extended the object by prefixing it. We can provide + +a couple of features in an anonymous namespace (not shown) in the implementation + +file for for supporting the count and its access from a raw pointer:</P> + + + +<UL> + +<PRE><TT>struct count +{ + size_t value; +}; + +count *header(const void *ptr) +{ + return const_cast<count *>(static_cast<const count *>(ptr) - 1); +} +</TT></PRE> + +</UL> + + + +<P>An important constraint to observe here is the alignment of <TT><FONT SIZE=+1>count</FONT></TT> + +should be such that it is suitably aligned for any type. For the definition + +shown this will be the case on almost all platforms. However, you may need + +to add a padding member for those that don't, e.g. using an anonymous <TT><FONT SIZE=+1>union</FONT></TT> + +to coalign <TT><FONT SIZE=+1>count</FONT></TT> and the most aligned type. + +Unfortunately, there is no portable way of specifying this such that the + +minimum alignment is also observed - this is a common problem when specifying + +your own allocators that do not directly use the results of either <TT><FONT SIZE=+1>new</FONT></TT> + +or <TT><FONT SIZE=+1>malloc</FONT></TT>.</P> + + + +<P>Again, note that the count is not considered to be a part of the logical + +state of the object, and hence the conversion from <TT><FONT SIZE=+1>const</FONT></TT> + +to non-<TT><FONT SIZE=+1>const</FONT></TT> - <TT><FONT SIZE=+1>count</FONT></TT> + +is in effect a <TT><FONT SIZE=+1>mutable</FONT></TT> type.</P> + + + +<P>The allocator functions themselves are fairly straightforward:</P> + + + +<UL> + +<PRE><TT>void *operator new(size_t size, const countable_new &) +{ + count *allocated = static_cast<count *>(::operator new(sizeof(count) + size)); + *allocated = count(); // initialise the header + return allocated + 1; // adjust result to point to the body +} + +void operator delete(void *ptr, const countable_new &) +{ + ::operator delete(header(ptr)); +} +</TT></PRE> + +</UL> + + + +<P>Given a correctly allocated header, we now need the <I>Countable </I>functions + +to operate on <TT><FONT SIZE=+1>const void *</FONT></TT> to complete the + +picture:</P> + + + +<UL> + +<PRE><TT>void acquire(const void *ptr) +{ + if(ptr) + { + ++header(ptr)->value; + } +} + +void release(const void *ptr) +{ + if(ptr) + { + --header(ptr)->value; + } +} + +size_t acquired(const void *ptr) +{ + return ptr ? header(ptr)->value : 0; +} + +template<typename countable_type> +void dispose(const countable_type *ptr, const void *) +{ + ptr->~countable_type(); + operator delete(const_cast<countable_type *>(ptr), countable); +} +</TT></PRE> + +</UL> + + + +<P>The most complex of these is the <TT><FONT SIZE=+1>dispose</FONT></TT> + +function that must ensure that the correct type is destructed and also + +that the memory is collected from the correct offset. It uses the value + +and type of first argument to perform this correctly, and the second argument + +merely acts as a strategy selector, i.e. the use of <TT><FONT SIZE=+1>const + +void *</FONT></TT> distinguishes it from the earlier dispose shown for + +<TT><FONT SIZE=+1>const countability *</FONT></TT>.</P> + +</UL> + + + + +<HR WIDTH="100%"> +<H2>Getting smarter</H2> + + + +<UL> + +<P>Now that we have a way of adding countability at creation for objects + +of any type, what extra is needed to make this work with the <TT><FONT SIZE=+1>countable_ptr</FONT></TT> + +we defined earlier? Good news: nothing!</P> + + + +<UL> + +<PRE><TT>class example +{ + ... +}; + +void simple() +{ + countable_ptr<example> ptr(new(countable) example); + countable_ptr<example> qtr(ptr); + ptr.clear(); // set ptr to point to null +} // allocated object deleted when qtr destructs +</TT></PRE> + +</UL> + + + +<P>The <TT><FONT SIZE=+1>new(countable)</FONT></TT> expression defines + +a different policy for allocation and deallocation and, in common with + +other allocators, any attempt to mix your allocation policies, e.g. call + +<TT><FONT SIZE=+1>delete</FONT></TT> on an object allocated with <TT><FONT SIZE=+1>new(countable)</FONT></TT>, + +results in undefined behaviour. This is similar to what happens when you + +mix <TT><FONT SIZE=+1>new[]</FONT></TT> with <TT><FONT SIZE=+1>delete</FONT></TT> + +or <TT><FONT SIZE=+1>malloc</FONT></TT> with <TT><FONT SIZE=+1>delete</FONT></TT>. + +The whole point of <I>Countable </I>conformance is that <I>Countable </I>objects + +are used with <TT><FONT SIZE=+1>countable_ptr</FONT></TT>, and this ensures + +the correct use.</P> + + + +<P>However, accidents will happen, and inevitably you may forget to allocate + +using <TT><FONT SIZE=+1>new(countable)</FONT></TT> and instead use <TT><FONT SIZE=+1>new</FONT></TT>. + +This error and others can be detected in most cases by extending the code + +shown here to add a check member to the <TT><FONT SIZE=+1>count</FONT></TT>, + +validating the check on every access. A benefit of ensuring clear separation + +between header and implementation source files means that you can introduce + +a checking version of this allocator without having to recompile your code.</P> + +</UL> + + + + +<HR WIDTH="100%"> +<H2>Conclusion</H2> + + + +<UL> + +<P>There are two key concepts that this article has introduced:</P> + + + +<UL> + +<LI>The use of a generic requirements based approach to simplify and adapt + +the use of the C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT> pattern.</LI> + + + +<LI>The ability, through control of allocation, to dynamically and non-intrusively + +add capabilities to fixed types using the R<FONT SIZE=-1>UNTIME</FONT> + +M<FONT SIZE=-1>IXIN</FONT> pattern.</LI> + +</UL> + + + +<P>The application of the two together gives rise to a new variant of the + +essential C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT> pattern, + +U<FONT SIZE=-1>NINTRUSIVE</FONT> C<FONT SIZE=-1>OUNTED</FONT> B<FONT SIZE=-1>ODY</FONT>. + +You can take this theme even further and contrive a simple garbage collection + +system for C++.</P> + + + +<P>The complete code for <TT><FONT SIZE=+1>countable_ptr</FONT></TT>, <TT><FONT SIZE=+1>countability</FONT></TT>, + +and the <TT><FONT SIZE=+1>countable new</FONT></TT> is also available.</P> + +</UL> + + + +<DIV ALIGN=right><P> + +<HR WIDTH="100%"><FONT SIZE=-1><I>First published in </I><a href="http://www.accu.org/c++sig/public/Overload.html">Overload</a> <I>25, + +April 1998, ISSN 1354-3172<BR> + +© Copyright Kevlin Henney, 1998, 1999</I></FONT></DIV> + + + +</BODY> + +</HTML> + diff --git a/more/discussion_policy.htm b/more/discussion_policy.htm new file mode 100644 index 0000000000..f49f40cb52 --- /dev/null +++ b/more/discussion_policy.htm @@ -0,0 +1,118 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Boost Discussion Policy</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Boost Discussion Policy</h1> +<p>Email discussion is the tie that binds boost members together into a community. +If the discussion is stimulating and effective, the community thrives. If +the discussion degenerates into name calling and ill will, the community withers +and dies.</p> +<h2>Acceptable topics</h2> +<ul> + <li>Queries to determine interest in a possible library submission.</li> + <li>Technical discussions about a proposed or existing library, including bug + reports and requests for help.</li> + <li>Formal Reviews of proposed libraries.</li> + <li>Reports of user experiences with Boost libraries.</li> + <li>Boost administration or policies.</li> + <li>Compiler specific workarounds as applied to Boost libraries.</li> +</ul> +<p>Other topics related to boost development may be acceptable, at the discretion of moderators. If unsure, go ahead and post. The moderators +will let you know.</p> +<h2>Unacceptable topics</h2> +<ul> + <li>Advertisements for commercial products.</li> + <li>Requests for help getting non-boost code to compile with your compiler. + Try the comp.lang.c++.moderated newsgroup instead.</li> + <li>Requests for help interpreting the C++ standard. Try the comp.std.c++ + newsgroup instead.</li> + <li>Job offers.</li> +</ul> +<h2>Prohibited behavior</h2> +<p>Prohibited behavior will not be tolerated. The moderators will ban +postings by abusers.</p> +<h3>Flame wars</h3> +<p>Personal insults, argument for the sake of argument, and all the other +behaviors which fall into the "flame war" category are +prohibited. Discussions should focus on technical arguments, not the +personality traits or motives of participants.</p> +<h3>Third-party attacks</h3> +<p>Attacks on third parties such as software vendors, hardware vendors, or any +other organizations, are prohibited. Boost exists to unite and serve the +entire C++ community, not to disparage the work of others.</p> +<p>Does this mean that we ban the occasional complaint or wry remark about a +troublesome compiler? No, but be wary of overdoing it.</p> +<h3>Off-topic posts</h3> +<p>Discussions which stray from the acceptable topics are strongly discouraged. +While off-topic posts are often well meaning and not as individually corrosive +as other abuses, cumulatively the distraction damages the effectiveness of +discussion.</p> +<h2>Culture</h2> +<p>In addition to technical skills, Boost members value collaboration, +acknowledgement of the help of others, and a certain level of politeness. Boost +membership is very international, and ranges widely in age and other +characteristics. Think of discussion as occurring among colleagues in a widely read forum, rather +than among a few close friends.</p> + +<p>Always remember that the cumulative effort spent by people reading +your contribution scales with the (already large) number of boost +members. Thus, do invest time and effort to make your message as +readable as possible. Adhere to English syntax and grammar rules such +as proper capitalization. Avoid copious informalism, colloquial +language, or abbreviations, they may not be understood by all readers. +Re-read your message before submitting it.</p> + +<h2>Guidelines for effective discussions</h2> +<p>Apply social engineering to prevent heated technical discussion from +degenerating into a shouting match.</p> +<ul> + <li>Questions help. If someone suggests something that you don't think + will work, then replying with a question like "will that compile?" + or "won't that fail to compile, or am I missing something?" is a + lot smoother than "That's really stupid - it won't compile." + Saying "that fails to compile for me, and seems to violate section + n.n.n of the standard" would be yet another way to be firm without + being abrasive.</li> + <li>If most of the discussion has been code-free generalities, posting a bit + of sample code can focus people on the practical issues.</li> + <li>If most of the discussion has been in terms of specific code, try to talk + a bit about hidden assumptions and generalities that may be preventing + discussion closure.</li> + <li>Taking a time-out is often effective. Just say: "Let me think + about that for a day or two. Let's take a time-out to digest the + discussion so far."</li> +</ul> +<p>Avoid Parkinson's Bicycle Shed. Parkinson described a committee formed +to oversee design of an early nuclear power plant. There were three agenda +items - when to have tea, where to put the bicycle shed, and how to +ensure nuclear safety. Tea was was disposed of quickly as trivial. +Nuclear safety was discussed for only +an hour - it was so complex, scary, and technical that even +among experts few felt comfortable with the issues. Endless days were then +spent discussing where to put the bicycle shed (the parking lot would +be a modern equivalent) because everyone +understood the issues and felt comfortable discussing them. </p> +<hr> +<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->06 July, 2001<!--webbot bot="Timestamp" endspan i-checksum="21072" --> +</p> + +</body> + +</html> diff --git a/more/download.html b/more/download.html new file mode 100644 index 0000000000..1c0b471016 --- /dev/null +++ b/more/download.html @@ -0,0 +1,140 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Boost Download and Installation</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> + +<h1>Boost Download and Installation</h1> + +The boost libraries are intended for easy download and <a href="#Installation">installation</a>. +However, unlike other packages, there is no global setup and +configuration tool. + +<h2>Download</h2> +The boost libraries are available in various formats: +<ul> + <li><a href="ftp://boost.sourceforge.net/pub/boost/release/">FTP download</a> all of Boost as a single archive +file (<a href="#.zip">.zip</a> or <a href="#.tar.gz">.tar.gz</a>) file from our + SourceForge FTP site. Older versions also available. (FTP download is + suggested first since it doesn't count against our web site host's monthly + fee. But some users behind firewalls can't use FTP, and the + SourceForge FTP site is sometimes down or very busy.)</li> +</ul> +<ul> + <li><a href="../boost_all.zip">ZIP download</a> all of Boost as a single archive +file from our web site.</li> +</ul> +<ul> + <li><a href="../boost_all.tar.gz">TAR.GZ download</a> all of Boost as a single archive +file from our web site.</li> +</ul> +<ul> + <li><a href="#CVS">Command line</a> or <a href="#Browser">browser</a> access + to Boost's CVS repository.</li> +</ul> +<ul> + <li>Download individual files from links in the documentation on the web + site. Because of the number of files involved, and <a href="../libs/hdr_depend.html">header + dependencies</a>, this option usually isn't very useful.</li> +</ul> + +<h3><a name=".zip">.zip</a> file</h3> + +The .zip format is widely supported by both free decoders and +commercial compress/archive utilities. If you don't already have a +.zip file decoder, download one from the +<a href="http://www.info-zip.org/">Info-ZIP</a> +web site, which supplies versions for many operating systems. +<p> +Text file line endings in the .zip file are as supplied by each library +developer. This works fine for Windows, but not for Unix/Linux. The +.tar.gz file supplies Unix/Linux friendly line endings. + + +<h3><a name=".tar.gz">.tar.gz</a> file</h3> + +The .tar.gz format is widely supported on Unix/Linux platforms. Some +Windows compress/archive utilities can read the format as well. Because +the gzip format compresses the archive as a single file rather than compressing +each file individually, the .tar.gz file is smaller that the .zip file. +<p>Text file line endings in the .tar.gz file have been converted to newlines +for ease of use on Unix/Linux platforms.</p> + +<h3><a name="CVS">CVS</a> command line access</h3> + +For those who have CVS installed, the libraries are also available +from the public CVS repository. The general procedure for +command-line clients is something like this: +<blockquote> +<code> +cvs -d:pserver:anonymous@cvs.boost.sourceforge.net:/cvsroot/boost login +</code> +<br> +[Hit <return> when it asks for a password] +<br> +<code> +cvs -z3 -d:pserver:anonymous@cvs.boost.sourceforge.net:/cvsroot/boost checkout boost +<br> +cvs -d:pserver:anonymous@cvs.boost.sourceforge.net:/cvsroot/boost logout +</code> +</blockquote> + +Read the manual for your CVS client for further information. +<p> +This access is read-only; if you are a library author and wish to have +CVS write access, please contact one of the +<a href="mailto:boost-owner@yahoogroups.com">moderators</a>. + + +<h3>CVS <a name="Browser">Browser</a> access via WebCVS</h3> + +For access to the CVS archive from any modern web browser, you can also use the <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/boost/boost/">web +browser interface</a>. Try one of the color diffs to see how a file +has changed over time. + + + +<h2><a name="Installation">Installation</a></h2> + +Many boost libraries are implemented entirely within their header +files. The only preparation for their use is to add the path for the +parent directory of the boost headers sub-directory to your compiler's +list of <code>#include</code> search directories. +<p> +For example, using Windows 2000, if you have unzipped release 1.20.2 +from boost_all.zip into the top level directory of your C drive, for +Borland, GCC, and Metrowerks compilers add '-Ic:/boost_1_20_2' to the +compiler command line, and for the Microsoft compiler add '/I +"c:/boost_1_20_2"'. For IDE's, add 'c:/boost_1_20_2' (or whatever you +have renamed it to) to the search list using the appropriate GUI +dialog. + +<p> +A few boost libraries are implemented by separate source files, and +thus require compilation on your system to link properly. Boost does +not currently have an overall "build" or "make" mechanism in place. +Some of the individual libraries do include make and/or project files +for various compilers. +<p> + +<hr> + +Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->22 June, 2001<!--webbot bot="Timestamp" endspan i-checksum="19850" --> +<p>Written by <a href="../people/jens_maurer.htm">Jens Maurer</a> +2001-02-11</p> + +</body> +</html> diff --git a/more/error_handling.html b/more/error_handling.html new file mode 100644 index 0000000000..21b5e93fec --- /dev/null +++ b/more/error_handling.html @@ -0,0 +1,92 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> + <meta name="generator" content="HTML Tidy, see www.w3.org"> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + + <title>Error and Exception Handling</title> + + <h1>Error and Exception Handling</h1> + + <h2>References</h2> + + <p>The following paper is a good introduction to some of the issues of + writing robust generic components: + + <blockquote> + <a href="generic_exception_safety.html">D. Abrahams: ``Exception Safety + in Generic Components''</a>, originally published in <a href= + "http://www.springer.de/cgi-bin/search_book.pl?isbn=3-540-41090-2">M. + Jazayeri, R. Loos, D. Musser (eds.): Generic Programming, Proc. of a + Dagstuhl Seminar, Lecture Notes on Computer Science 1766</a> + </blockquote> + + <h2>Guidelines</h2> + + <h3>When should I use exceptions?</h3> + + <p>The simple answer is: ``whenever the semantic and performance + characteristics of exceptions are appropriate.'' + + <p>An oft-cited guideline is to ask yourself the question ``is this an + exceptional (or unexpected) situation?'' This guideline has an attractive + ring to it, but is usually a mistake. The problem is that one person's + ``exceptional'' is another's ``expected'': when you really look at the + terms carefully, the distinction evaporates and you're left with no + guideline. After all, if you check for an error condition, then in some + sense you expect it to happen, or the check is wasted code. + + <p>A more appropriate question to ask is: ``do we want stack unwinding + here?'' Because actually handling an exception is likely to be + significantly slower than executing mainline code, you should also ask: + ``Can I afford stack unwinding here?'' For example, a desktop application + performing a long computation might periodically check to see whether the + user had pressed a cancel button. Throwing an exception could allow the + operation to be cancelled gracefully. On the other hand, it would probably + be inappropriate to throw and <i>handle</i> exceptions in the inner loop of + this computation because that would have a significant performance impact. + + <h3>What About Programmer Errors?</h3> + + <p>As a developer, if I have violated a precondition of a library I'm + using, I don't want stack unwinding. What I want is a core dump or the + equivalent - a way to inspect the state of the program at the exact point + where the problem was detected. That usually means <tt>assert()</tt> or + something like it. + + <p>Sometimes it is neccessary to have resilient APIs which can stand up to + nearly any kind of client abuse, but there is usually a significant cost to + this approach. For example, it usually requires that each object used by a + client be tracked so that it can be checked for validity. If you need that + sort of protection, it can usually be provided as a layer on top of a + simpler API. Beware half-measures, though. An API which promises resilience + against some, but not all abuse is an invitation to disaster. Clients will + begin to rely on the protection and their expectations will grow to cover + unprotected parts of the interface. + + <p><b>Note for Windows developers</b>: unfortunately, the native + exception-handling used by most Windows compilers actually throws an + exception when you use <tt>assert()</tt>. Actually, this is true of other + programmer errors such as segmentation faults and divide-by-zero errors. + One problem with this is that if you use JIT (Just In Time) debugging, + there will be collateral exception-unwinding before the debugger comes up. + Fortunately, there is a simple but little-known workaround, which is to use + the following incantation: + + <blockquote> +<pre> +extern "C" void straight_to_debugger(unsigned int, EXCEPTION_POINTERS*) +{ + throw; +} +extern "C" void (*old_translator)(unsigned, EXCEPTION_POINTERS*) + = _set_se_translator(straight_to_debugger); +</pre> + </blockquote> + <hr> + + <p>© Copyright David Abrahams 2001. Permission to copy, use, modify, + sell and distribute this document is granted provided this copyright notice + appears in all copies. This document is provided "as is" without express or + implied warranty, and with no claim as to its suitability for any purpose. + + <p>Revised + <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->17 March, 2001<!--webbot bot="Timestamp" endspan i-checksum="28779" --> diff --git a/more/faq.htm b/more/faq.htm new file mode 100644 index 0000000000..b059f26049 --- /dev/null +++ b/more/faq.htm @@ -0,0 +1,137 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Boost FAQ</title> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="Microsoft Border" content="none, default"> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" WIDTH="277" + HEIGHT="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home </big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries </big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People </big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ </big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More </big></font></a></td> + </tr> +</table> + +<h1>Boost Frequently Asked Questions</h1> + +<p><strong>How do I download the libraries?</strong> + See <a href="../libs/libraries.htm#Download">Download</a> instructions.</p> + +<p><b>What support is available for the libraries?</b> Try the <a +href="mailto:boost@yahoogroups.com">boost@yahoogroups.com</a> mailing list. </p> + +<p><b>What do the Boost version numbers mean? </b>The scheme is x.y.z, where x is incremented only for massive changes, such as a reorganization of many libraries, y is incremented whenever a new library is added, and z is incremented for maintenance releases. y and z are reset to 0 if +the value to the left changes. <br> +<br> +<b>How can the Boost libraries be used successfully for important projects? +</b>Many of the Boost libraries are actively maintained and improved, so backward compatibility with prior version isn't always possible. Deal with this by freezing the version of the Boost libraries used by your project. Only upgrade at points in your project's life cycle where a bit of change will not cause problems. Individual bug fixes can always be obtained from the CVS repository. </p> + +<p><b>How is a library accepted for posting on the site?</b> +See <a href="submission_process.htm">Library Submission Process</a></p> + +<p><b>Is there any assurance libraries actually work as claimed?</b> No. The review +process will hopefully eliminate the most seriously flawed libraries, but a well +constructed library with hidden defects is likely to slip through. Encouraging ordinary +users to report their experience with a library is intended to address such concerns. </p> + +<p><b>How does someone submit a comment?</b> Send email to <a +href="mailto:boost@yahoogroups.com">boost@yahoogroups.com</a>. </p> + +<p><strong>How does someone submit a library?</strong> See <a href="lib_guide.htm">Library +Guidelines</a></p> + +<p><b>Are commercial libraries requiring a fee acceptable?</b> No. However, a library that +a commercial enterprise makes available without fee is acceptable. If the description of +the library makes a low-key plug for the supplier, that is acceptable as long as the +library delivers real value and isn’t just a Trojan horse for the plug.</p> + +<p><b>Are shareware libraries acceptable?</b> No. At least initially, only free libraries +will be accepted.</p> + +<p><strong>Are open source license libraries acceptable?</strong> Some +are, many are not. +Open source licenses often require redistribution or availability of source code, +inclusion of license document with machine-executable redistribution, give the initial +developer rights to licensee modifications, or need a lawyer to understand. These +would be immediate disqualifications for many business, commercial, and consumer +applications. Boost aims to avoid subjecting users to hard-to-comply-with license +terms. See <a href="lib_guide.htm#License">License requirements</a>.<br> +<br> +This is subject to review for a particularly important piece of software, or as the +industry changes.</p> + +<p><b>Must full source code be provided?</b> Yes, these are source code libraries.</p> + +<p><b>What about documentation?</b> A very simple library might be accepted with only a +well commented header file. For more substantial libraries, some form of documentation is +certainly going to be expected. HTML is the preferred form.</p> + +<p><b>Are platform specific libraries acceptable?</b> There is a preference for portable +libraries. Libraries will be accepted that have portable interfaces but require platform +specific implementations, as long as the author supplies implementations for a couple of +disparate major operating systems.</p> + +<p><b>Must a library do useful work? </b>No. A library meant as a teaching example or +demonstration might not actually do any work.</p> + +<p><b>Who owns the libraries?</b> Presumably many authors will copyright their libraries. +Others authors may wish to place their libraries in the public domain. The Boost.org +policy is to only accept libraries with a clear copyright notice. It is up to +potential users to decide if they find the copyright terms acceptable, and to not use +libraries with unacceptable copyrights.</p> + +<p><b>Is there a formal relationship between Boost.org and the C++ Standards Committee?</b> + No. The people who started Boost.org were all on the committee, but that was just +happenstance.</p> + +<p><b>Will the Boost.org libraries become part of the next C++ Standard?</b> Some +might, someday off in the future, but that is up to the standards committee. To the +extent a library becomes "existing practice", the likelihood increases that +someone will propose it for future standardization. Submitting a library to Boost.org is +one way to establish existing practice - as long as enough people are interested to +download and use it!</p> + +<p><b>Is the web site a commercial business?</b> No. It is just some people getting together +as a kind of cyberspace civic association. If it ever needs to incorporate, it would be as +non-profit organization.</p> + +<p><b>Is there any charge for submitting libraries or reviews to Boost.org?</b> No. Unlike +the standards committees, you don’t have to pay to volunteer!</p> + +<p><b>Will the site include material beyond libraries?</b> The main focus is on libraries, +but if people contribute occasional articles or other material to make the site more +interesting, that could be a nice fit.</p> + +<p><b>Why isn't there a separate boost mailing list for my favorite +library? </b> One of the reasons for boost's success has been the cross-pollination of ideas between diverse library +projects and the occasional look into other threads by otherwise uninterested parties. The more people participate, the less they tend to be annoyed by +"noise".</p> + +<p><b>How can I cope with the large volume of boost mailing list messages?</b> +One approach is to use the YahooGroups digest option; that cuts the email blizzard +down to about three (long) messages per day, so you can glance over the subjects +summary at the top and quickly read what you think is important. The +YahooGroups "no mail/web only" option is best if you just occasionally +want to look at messages.</p> + +<p>Yet another approach is to use your email program's capabilities to filter messages and automatically +transfer them into several boost folders. Then only read the folders you +care about. Boost list posters are +encouraged to include keywords in the subject like "thread", +"review", and "CVS" to aid message filtering.</p> + +<hr> + +<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->24 April, 2001<!--webbot bot="Timestamp" endspan i-checksum="29814" --> +</p> +</body> +</html> diff --git a/more/feature_model_diagrams.htm b/more/feature_model_diagrams.htm new file mode 100644 index 0000000000..b865d085de --- /dev/null +++ b/more/feature_model_diagrams.htm @@ -0,0 +1,104 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Feature Model Diagrams</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<p><img border="0" src="../c++boost.gif" width="277" height="86"></p> +<h1>Feature Model Diagrams in text and HTML</h1> +<p>By <a href="../people/beman_dawes.html">Beman Dawes</a></p> +<h2>Introduction</h2> +<p>In their seminal book, Generative Programming, Czarnecki and Eisenecker (<a href="#Generative Programming">C&E</a>) +describe how to build feature models [C&E 4.4] consisting of a feature +diagram plus semantic, rationale, and other attributes. Feature models are +then used to drive design cycles which eventually lead to manual or automatic +assembly of configurations.</p> +<p>Feature models provide a language to describe the library variability that is +often such an issue in boost.org discussions. The Whorf hypothesis that +"Language shapes the way we think, and determines what we can think +about" seems to apply. In discussion of library variability issues, +we have been crippled by lack of a good language. With feature models we now +have a language to carry on the dialog.</p> +<p>The graphical feature diagrams presented by C&E are not in a suitable +form for the email discussions boost.org depends upon. The hierarchical nature +of feature diagrams can be represented by a simple text-based feature diagram +language. A feature model can also take advantage of the hyperlinks +inherent in HTML.</p> +<h2><a name="Grammar">Grammar</a></h2> +<p>The grammar for the feature diagram language is expressed in Extended +Bakus-Naur Form; ::= represents productions, [...] represents options, {...} +represents zero or more instances, and represents | alternatives.</p> +<blockquote> + <pre>feature-model ::= concept-name details { feature }</pre> + <pre>feature ::= feature-name [details]</pre> + <pre>details ::= "(" feature-list ")" // required features + | "[" feature-list "]" // optional features</pre> + <pre>feature-list ::= element { "|" element } // one only + | element { "+" element } // one or more + | element { "," element } // all + // [a+b] equivalent to [a,b]</pre> + <pre>element ::= feature + | details</pre> + <pre>concept-name ::= name</pre> + <pre>feature-name ::= name</pre> +</blockquote> +<p>The usual lexical conventions apply. Names are case-insensitive and consist +of a leading letter, followed by letters, digits, underscores or hyphens, with +no spaces allowed.</p> +<p>At least one instance of each name should be hyperlinked to the corresponding +<a href="#Feature Descriptions">Feature Description</a>.</p> +<p>While the grammar is intended for written communication between people, it +may also be trivially machine parsed for use by automatic tools.</p> +<h2><a name="Feature Descriptions">Feature Description</a></h2> +<p>Descriptive information is associated with each concept or feature. According +to [C&E 4.4.2] this includes:</p> +<ul> + <li>Semantic descriptions.</li> + <li>Rationale.</li> + <li>Stakeholders and client programs.</li> + <li>Exemplar systems.</li> + <li>Constraints and default dependency rules.</li> + <li>Availability sites, binding sites, and binding mode.</li> + <li>Open/Closed attribute.</li> +</ul> +<h2>What is a Feature?</h2> +<p>A feature [C&E 4.9.1] is "anything users or client programs might +want to control about a concept. Thus, during feature modeling, we +document no only functional features ... but also implementation features, ..., +various optimizations, alternative implementation techniques, and so on."</p> +<h2>Example</h2> +<blockquote> + <pre>special-container ( organization, + performance, + interface ) // all required</pre> + <pre>organization [ ordered + indexed ] // zero or more (4 configurations)</pre> + <pre>indexed [ hash-function ] // zero or one (2 configurations)</pre> + <pre>performance ( fast | small | balanced ) // exactly one (3 configurations)</pre> + <pre>interface ( STL-style + cursor-style ) // one or more (3 configurations)</pre> +</blockquote> +<p>There should be feature descriptions for <code>some-container, organization, +ordered, indexed, hash-function, performance, fast, small, balanced, interface, +STL-style, and cursor-style</code>.</p> +<p>The number of possible configurations is (2 + 2*2) * 3 * 3 = 54, +assuming no constraints.</p> +<p>There are equivalent representations. For example:</p> +<blockquote> + <pre>special-container ( organization[ ordered+indexed[ hash-function ]], + performance( fast|small|balanced ), + interface( STL-style+cursor-style ) )</pre> +</blockquote> +<h2>References</h2> +<p>Krzysztof Czarnecki and Ulrich W. Eisenecker, <a name="Generative Programming" href="http://www.generative-programming.org">Generative +Programming</a>, Addison-Wesley, 2000, ISBN 0-210-30977-7</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->10 February 2001<!--webbot bot="Timestamp" endspan i-checksum="40602" --></p> +<p>© Copyright Beman Dawes, 2000</p> + +</body> + +</html> diff --git a/more/formal_review_process.htm b/more/formal_review_process.htm new file mode 100644 index 0000000000..317386b238 --- /dev/null +++ b/more/formal_review_process.htm @@ -0,0 +1,139 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Boost Formal Review Process</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Boost Formal Review Process</h1> +<p>The Formal Review process determines if a proposed library should be accepted +as a Boost library.</p> +<p>The final "accept" or "reject" decision is made by the <a href="#Review Manager"> +Review Manager</a>, based on review comments received from boost mailing list +members.</p> +<p>Reviews are scheduled so that:</p> +<ul> + <li>Each library gets review time proportional to its size, complexity, and + importance.</li> + <li>Only a small number of libraries are under active review at any one time.</li> + <li>Members know ahead of time when a particular library will be under active + review. </li> +</ul> +<h2>Comments</h2> +<p> Boost mailing list members are encouraged to submit Formal Review +comments:</p> +<blockquote> + <ul> + <li>Publicly on the mailing list.</li> + <li>Privately to the Review Manager.</li> + <li>Privately to the library submitter.</li> + </ul> +</blockquote> +<p>Private comments to a library submitter may be helpful to her or him, but +won't help the Review Manager reach a decision, so the other forms are +preferred.</p> +<h2>Preparing review comments</h2> +<p>Comments may be brief or lengthy, but basically the Review Manager needs your +answers to several questions. If you identify problems along the way, +please note if they are minor, serious, or showstoppers.</p> +<ul> + <li>What is your evaluation of the design?<br> + </li> + <li>What is your evaluation of the implementation?<br> + </li> + <li>What is your evaluation of the documentation?<br> + </li> + <li>What is your evaluation of the potential usefulness of the library?<br> + </li> + <li>Did you try to use the library? With what compiler? Did you + have any problems?<br> + </li> + <li>How much effort did you put into your evaluation? A glance? A quick + reading? In-depth study?<br> + </li> + <li>Are you knowledgeable about the problem domain?<br> + </li> + <li>Finally, do you think the library should be accepted as a Boost + library? Be sure to say this explicitly so that your other comments + don't obscure your overall opinion.</li> +</ul> +<h2>Results</h2> +<p>At the conclusion of the comment period, the Review Manager will post a +message to the mailing list saying if the library has been accepted or +rejected. A rationale should be provided, but its extent is up to the +Review Manager.</p> +<h2>Notes for <a name="Review Manager"> Review Manager</a>s</h2> +<p>Before a library can be scheduled for formal review, an active boost member not +connected with the library submission must volunteer to be the "Review +Manager" for the library.</p> +<p>The review manager:</p> +<ul> + <li>Checks the submission to make sure it really is complete enough to warrant + formal review. See the <a href="lib_guide.htm">Boost Library + Requirements and Guidelines</a>. If necessary, work with the submitter + to verify the code compiles and runs correctly on several compilers and + platforms.</li> +</ul> +<ul> + <li>Sets the schedule, after discussion with the boost webmaster, currently + Beman Dawes.</li> +</ul> +<ul> + <li>Posts a notice of the review schedule on both the regular boost mailing + list and the boost-announce mailing list.</li> +</ul> +<blockquote> + <blockquote> + <p>The notice should include a brief description of the library and what it + does, to let readers know if the library is one they are interested in.</p> + </blockquote> +</blockquote> +<ul> + <li>Urges people to do reviews if they aren't forthcoming.</li> +</ul> +<ul> + <li>Follows review discussions regarding the library, moderating or answering + questions as needed.</li> +</ul> +<ul> + <li>Decides if +there is consensus to accept the library, and if there are any conditions + attached.</li> +</ul> +<ul> + <li>Posts a message informing members of the review results.</li> +</ul> +<p>In other words, it is the Review Manager's responsibility to make sure the +review process works smoothly.</p> +<h2>Notes for Library Authors</h2> +<p>A proposed library should remain stable during the review period; it will just +confuse and irritate reviewers if there are numerous changes. It +is, however, useful to upload fixes for serious bugs right away, particularly +those which prevent reviewers from fully evaluating the library. Post a +notice of such fixes on the mailing list.</p> +<p>Library improvements suggested by reviewers should be held until after the +completion of review period. Such changes can then be incorporated in the <a href="submission_process.htm#Final">final +submission file</a> sent to the webmaster for posting. If the suggested +changes might affect reviewer's judgments, post a notice of the pending +change on the mailing list.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->26 June, 2001<!--webbot bot="Timestamp" endspan i-checksum="19858" --></p> +<p> </p> + +</body> + +</html> diff --git a/more/generic_exception_safety.html b/more/generic_exception_safety.html new file mode 100644 index 0000000000..41e50965f9 --- /dev/null +++ b/more/generic_exception_safety.html @@ -0,0 +1,695 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- saved from url=(0052)http://people.ne.mediaone.net/abrahams/abrahams.html --> + + <meta name="generator" content="HTML Tidy, see www.w3.org"> + <title>Exception-Safety in Generic Components</title> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta content="MSHTML 5.50.4522.1800" name="GENERATOR"> + + <h1 align="center">Exception-Safety in Generic Components</h1> + + <p align="center"><i><b>Lessons Learned from Specifying Exception-Safety + for the C++ Standard Library</b></i> + + <h3 align="center">David Abrahams</h3> + + <h3 align="center">Dragon Systems</h3> + + <h3 align="center"><code><a href= + "mailto:David_Abrahams@dragonsys.com">David_Abrahams@dragonsys.com</a></code></h3> + + <p><b>Abstract.</b> This paper represents the knowledge accumulated in + response to a real-world need: that the C++ Standard Template Library + exhibit useful and well-defined interactions with exceptions, the + error-handling mechanism built-in to the core C++ language. It explores the + meaning of exception-safety, reveals surprising myths about exceptions and + genericity, describes valuable tools for reasoning about program + correctness, and outlines an automated testing procedure for verifying + exception-safety. + + <p><b>Keywords:</b> exception-safety, exceptions, STL, C++ + + <h2>1 What is exception-safety?</h2> + + <p>Informally, exception-safety in a component means that it exhibits + reasonable behavior when an exception is thrown during its execution. For + most people, the term ``reasonable'' includes all the usual + expectations for error-handling: that resources should not be leaked, and + that the program should remain in a well-defined state so that execution + can continue. For most components, it also includes the expectation that + when an error is encountered, it is reported to the caller. + + <p>More formally, we can describe a component as minimally exception-safe + if, when exceptions are thrown from within that component, its invariants + are intact. Later on we'll see that at least three different levels of + exception-safety can be usefully distinguished. These distinctions can help + us to describe and reason about the behavior of large systems. + + <p>In a generic component, we usually have an additional expectation of + <i>exception-neutrality</i>, which means that exceptions thrown by a + component's type parameters should be propagated, unchanged, to the + component's caller. + + <h2>2 Myths and Superstitions</h2> + + <p>Exception-safety seems straightforward so far: it doesn't constitute + anything more than we'd expect from code using more traditional + error-handling techniques. It might be worthwhile, however, to examine the + term from a psychological viewpoint. Nobody ever spoke of + ``error-safety'' before C++ had exceptions. + + <p>It's almost as though exceptions are viewed as a <i>mysterious + attack</i> on otherwise correct code, from which we must protect ourselves. + Needless to say, this doesn't lead to a healthy relationship with error + handling! During standardization, a democratic process which requires broad + support for changes, I encountered many widely-held superstitions. In order + to even begin the discussion of exception-safety in generic components, it + may be worthwhile confronting a few of them. + + <p><i>``Interactions between templates and exceptions are not + well-understood.''</i> This myth, often heard from those who consider + these both new language features, is easily disposed of: there simply are + no interactions. A template, once instantiated, works in all respects like + an ordinary class or function. A simple way to reason about the behavior of + a template with exceptions is to think of how a specific instantiation of + that template works. Finally, the genericity of templates should not cause + special concern. Although the component's client supplies part of the + operation (which may, unless otherwise specified, throw arbitrary + exceptions), the same is true of operations using familiar virtual + functions or simple function pointers. + + <p><i>``It is well known to be impossible to write an exception-safe + generic container.''</i> This claim is often heard with reference to + an article by Tom Cargill <a title= + "Tom Cargill, ``Exception Handling: A False Sense of Security'', C++ Report, Nov-Dec 1994" + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#reference4"><sup>[4]</sup></a> + in which he explores the problem of exception-safety for a generic stack + template. In his article, Cargill raises many useful questions, but + unfortunately fails to present a solution to his problem.<a title= + "Probably the greatest impediment to a solution in Cargill's case was an unfortunate combination of choices on his part: the interface he chose for his container was incompatible with his particular demands for safety. By changing either one he might have solved the problem." + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#footnote1"><sup>1</sup></a> + He concludes by suggesting that a solution may not be possible. + Unfortunately, his article was read by many as ``proof'' of that + speculation. Since it was published there have been many examples of + exception-safe generic components, among them the C++ standard library + containers. + + <p><i>``Dealing with exceptions will slow code down, and templates are + used specifically to get the best possible performance.''</i> A good + implementation of C++ will not devote a single instruction cycle to dealing + with exceptions until one is thrown, and then it can be handled at a speed + comparable with that of calling a function <a title= + "D. R. Musser, ``Introspective Sorting and Selection Algorithms'', Software-Practice and Experience 27(8):983-993, 1997." + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#reference7"><sup>[7]</sup></a>. + That alone gives programs using exceptions performance equivalent to that + of a program which ignores the possibility of errors. Using exceptions can + actually result in faster programs than ``traditional'' error + handling methods for other reasons. First, a catch block clearly indicates + to the compiler which code is devoted to error-handling; it can then be + separated from the usual execution path, improving locality of reference. + Second, code using ``traditional'' error handling must typically + test a return value for errors after every single function call; using + exceptions completely eliminates that overhead. + + <p><i>``Exceptions make it more difficult to reason about a program's + behavior.''</i> Usually cited in support of this myth is the way + ``hidden'' execution paths are followed during stack-unwinding. + Hidden execution paths are nothing new to any C++ programmer who expects + local variables to be destroyed upon returning from a function: + + <blockquote> +<pre> +ErrorCode f( int& result ) // 1 +{ // 2 + X x; // 3 + ErrorCode err = x.g( result ); // 4 + if ( err != kNoError ) // 5 + return err; // 6 + // ...More code here... + return kNoError; // 7 +} +</pre> + </blockquote> + + <p>In the example above, there is a ``hidden'' call to + <code>X::~X()</code> in lines 6 and 7. Granted, using exceptions, there is + no code devoted to error handling visible: + + <blockquote> +<pre> +int f() // 1 +{ // 2 + X x; // 3 + int result = x.g(); // 4 + // ...More code here... + return result; // 5 +} +</pre> + </blockquote> + + <p>For many programmers more familiar with exceptions, the second example + is actually more readable and understandable than the first. The + ``hidden'' code paths include the same calls to destructors of + local variables. In addition, they follow a simple pattern which acts + <i>exactly</i> as though there were a potential return statement after each + function call in case of an exception. Readability is enhanced because the + normal path of execution is unobscured by error-handling, and return values + are freed up to be used in a natural way. + + <p>There is an even more important way in which exceptions can enhance + correctness: by allowing simple class invariants. In the first example, if + <code>x</code>'s constructor should need to allocate resources, it has no + way to report a failure: in C++, constructors have no return values. The + usual result when exceptions are avoided is that classes requiring + resources must include a separate initializer function which finishes the + job of construction. The programmer can therefore never be sure, when an + object of class <code>X</code> is used, whether he is handling a + full-fledged <code>X</code> or some abortive attempt to construct one (or + worse: someone simply forgot to call the initializer!) + + <h2>3 A contractual basis for exception-safety</h2> + + <p>A non-generic component can be described as exception-safe in isolation, + but because of its configurability by client code, exception-safety in a + generic component usually depends on a contract between the component and + its clients. For example, the designer of a generic component might require + that an operation which is used in the component's destructor not throw any + exceptions.<a title= + " It is usually inadvisable to throw an exception from a destructor in C++, since the destructor may itself be called during the stack-unwinding caused by another exception. If the second exception is allowed to propagate beyond the destructor, the program is immediately terminated." + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#footnote2"><sup>2</sup></a> + The generic component might, in return, provide one of the following + guarantees: + + <ul> + <li>The <i>basic</i> guarantee: that the invariants of the component are + preserved, and no resources are leaked. + + <li>The <i>strong</i> guarantee: that the operation has either completed + successfully or thrown an exception, leaving the program state exactly as + it was before the operation started. + + <li>The <i>no-throw</i> guarantee: that the operation will not throw an + exception. + </ul> + + <p>The basic guarantee is a simple minimum standard for exception-safety to + which we can hold all components. It says simply that after an exception, + the component can still be used as before. Importantly, the preservation of + invariants allows the component to be destroyed, potentially as part of + stack-unwinding. This guarantee is actually less useful than it might at + first appear. If a component has many valid states, after an exception we + have no idea what state the component is in|only that the state is valid. + The options for recovery in this case are limited: either destruction or + resetting the component to some known state before further use. Consider + the following example: + + <blockquote> +<pre> +template <class X> +void print_random_sequence() +{ + std::vector<X> v(10); // A vector of 10 items + try { + // Provides only the <i>basic</i> guarantee + v.insert( v.begin(), X() ); + } + catch(...) {} // ignore any exceptions above + // print the vector's contents + std::cout "(" << v.size() << ") "; + std::copy( v.begin(), v.end(), + std::ostream_iterator<X>( std::cout, " " ) ); +} +</pre> + </blockquote> + + <p>Since all we know about v after an exception is that it is valid, the + function is allowed to print any random sequence of <code>X</code>s.<a + title= + "In practice of course, this function would make an extremely poor random sequence generator!" + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#footnote3"><sup>3</sup></a> + It is ``safe'' in the sense that it is not allowed to crash, but + its output may be unpredictable. + + <p>The <i>strong</i> guarantee provides full + ``commit-or-rollback'' semantics. In the case of C++ standard + containers, this means, for example, that if an exception is thrown all + iterators remain valid. We also know that the container has exactly the + same elements as before the exception was thrown. A transaction that has no + effects if it fails has obvious benefits: the program state is simple and + predictable in case of an exception. In the C++ standard library, nearly + all of the operations on the node-based containers list, set, multiset, + map, and multimap provide the <i>strong</i> guarantee.<a title= + "It is worth noting that mutating algorithms usually cannot provide the strong guarantee: to roll back a modified element of a range, it must be set back to its previous value using operator=, which itself might throw. In the C++ standard library, there are a few exceptions to this rule, whose rollback behavior consists only of destruction: uninitialized_copy, uninitialized_fill, and uninitialized_fill_n." + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#footnote4"><sup>4</sup></a>). + + <p>The <i>no-throw</i> guarantee is the strongest of all, and it says that + an operation is guaranteed not to throw an exception: it always completes + successfully. This guarantee is necessary for most destructors, and indeed + the destructors of C++ standard library components are all guaranteed not + to throw exceptions. The <i>no-throw</i> guarantee turns out to be + important for other reasons, as we shall see.<a title= + "All type parameters supplied by clients of the C++ standard library are required not to throw from their destructors. In return, all components of the C++ standard library provide at least the basic guarantee." + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#footnote5"><sup>5</sup></a> + + <h2>4 Legal Wrangling</h2> + + <p>Inevitably, the contract can get more complicated: a quid pro quo + arrangement is possible. Some components in the C++ Standard Library give + one guarantee for arbitrary type parameters, but give a stronger guarantee + in exchange for additional promises from the client type that no exceptions + will be thrown. For example, the standard container operation + <code>vector<T>::erase</code> gives the <i>basic</i> guarantee for + any <code>T</code>, but for types whose copy constructor and copy + assignment operator do not throw, it gives the <i>no-throw</i> guarantee.<a + title= + "Similar arrangements might have been made in the C++ standard for many of the mutating algorithms, but were never considered due to time constraints on the standardization process." + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#footnote6"><sup>6</sup></a> + + <h2>5 What level of exception-safety should a component specify?</h2> + + <p>From a client's point-of-view, the strongest possible level of safety + would be ideal. Of course, the <i>no-throw</i> guarantee is simply + impossible for many operations, but what about the <i>strong</i> guarantee? + For example, suppose we wanted atomic behavior for + <code>vector<T>::insert</code>. Insertion into the middle of a vector + requires copying elements after the insertion point into later positions, + to make room for the new element. If copying an element can fail, rolling + back the operation would require ``undoing'' the previous + copies...which depends on copying again. If copying back should fail (as it + likely would), we have failed to meet our guarantee. + + <p>One possible alternative would be to redefine <code>insert</code> to + build the new array contents in a fresh piece of memory each time, and only + destroy the old contents when that has succeeded. Unfortunately, there is a + non-trivial cost if this approach is followed: insertions near the end of a + vector which might have previously caused only a few copies would now cause + every element to be copied. The <i>basic</i> guarantee is a + ``natural'' level of safety for this operation, which it can + provide without violating its performance guarantees. In fact all of the + operations in the library appear to have such a ``natural'' level + of safety. + + <p>Because performance requirements were already a well-established part of + the draft standard and because performance is a primary goal of the STL, + there was no attempt to specify more safety than could be provided within + those requirements. Although not all of the library gives the <i>strong</i> + guarantee, almost any operation on a standard container which gives the + <i>basic</i> guarantee can be made <i>strong</i> using the ``make a + new copy'' strategy described above: + + <blockquote> +<pre> +template <class Container, class BasicOp> +void MakeOperationStrong( Container& c, const BasicOp& op ) +{ + Container tmp(c); // Copy c + op(tmp); // Work on the copy + c.swap(tmp); // Cannot fail<a title= +"Associative containers whose Compare object might throw an exception when copied cannot use this technique, since the swap function might fail." + href= +"http://people.ne.mediaone.net/abrahams/abrahams.html#footnote7"><sup>7</sup></a> +} +</pre> + </blockquote> + + <p>This technique can be folded into a wrapper class to make a similar + container which provides stronger guarantees (and different performance + characteristics).<a title= + "This suggests another potential use for the oft-wished-for but as yet unseen container traits<> template: automated container selection to meet exceptionsafety constraints." + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#footnote8"><sup>8</sup></a> + + <h2>6 Should we take everything we can get?</h2> + + <p>By considering a particular implementation, we can hope to discern a + natural level of safety. The danger in using this to establish requirements + for a component is that the implementation might be restricted. If someone + should come up with a more-efficient implementation which we'd like to use, + we may find that it's incompatible with our exception-safety requirements. + One might expect this to be of no concern in the well-explored domains of + data structures and algorithms covered by the STL, but even there, advances + are being made. A good example is the recent <i>introsort</i> algorithm <a + title= + "D. R. Musser, ``Introspective Sorting and Selection Algorithms'', Software-Practice and Experience 27(8):983-993, 1997." + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#reference6"><sup>[6]</sup></a>, + which represents a substantial improvement in worst-case complexity over + the well-established <i>quicksort</i>. + + <p>To determine exactly how much to demand of the standard components, I + looked at a typical real-world scenario. The chosen test case was a + ``composite container.'' Such a container, built of two or more + standard container components, is not only commonly needed, but serves as a + simple representative case for maintaining invariants in larger systems: + + <blockquote> +<pre> +// SearchableStack - A stack which can be efficiently searched +// for any value. +template <class T> +class SearchableStack +{ + public: + void push(const T& t); // O(log n) + void pop(); // O(log n) + bool contains(const T& t) const; // O(log n) + const T& top() const; // O(1) + private: + std::set<T> set_impl; + std::list<std::set<T>::iterator> list_impl; +}; +</pre> + </blockquote> + + <p>The idea is that the list acts as a stack of set iterators: every + element goes into the set first, and the resulting position is pushed onto + the list. The invariant is straightforward: the set and the list should + always have the same number of elements, and every element of the set + should be referenced by an element of the list. The following + implementation of the push function is designed to give the <i>strong</i> + guarantee within the natural levels of safety provided by set and list: + + <blockquote> +<pre> +template <class T> // 1 +void SearchableStack<T>::push(const T& t) // 2 +{ // 3 + set<T>::iterator i = set_impl.insert(t); // 4 + try // 5 + { // 6 + list_impl.push_back(i); // 7 + } // 8 + catch(...) // 9 + { // 10 + set_impl.erase(i); // 11 + throw; // 12 + } // 13 +} // 14 +</pre> + </blockquote> + + <p>What does our code actually require of the library? We need to examine + the lines where non-const operations occur: + + <ul> + <li>Line 4: if the insertion fails but <code>set_impl</code> is modified + in the process, our invariant is violated. We need to be able to rely on + the <i>strong</i> guarantee from <code>set<T>::insert</code>. + + <li>Line 7: likewise, if <code>push_back</code> fails, but + <code>list_impl</code> is modified in the process, our invariant is + violated, so we need to be able to rely on the <i>strong</i> guarantee + from list<T>::insert. + + <li>Line 11: here we are ``rolling back'' the insertion on line + 4. If this operation should fail, we will be unable to restore our + invariant. We absolutely depend on the <i>no-throw</i> guarantee from + <code>set<T>::erase</code>.<a title= + "One might be tempted to surround the erase operation with a try/catch block to reduce the requirements on set<T> and the problems that arise in case of an exception, but in the end that just begs the question. First, erase just failed and in this case there are no viable alternative ways to produce the necessary result. Second and more generally, because of the variability of its type parameters a generic component can seldom be assured that any alternatives will succeed." + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#footnote9"><sup>9</sup></a> + + <li>Line 11: for the same reasons, we also depend on being able to pass + the <code>i</code> to the <code>erase</code> function: we need the + <i>no-throw</i> guarantee from the copy constructor of + <code>set<T>::iterator</code>. + </ul> + + <p>I learned a great deal by approaching the question this way during + standardization. First, the guarantee specified for the composite container + actually depends on stronger guarantees from its components (the + <i>no-throw</i> guarantees in line 11). Also, I took advantage of all of + the natural level of safety to implement this simple example. Finally, the + analysis revealed a requirement on iterators which I had previously + overlooked when operations were considered on their own. The conclusion was + that we should provide as much of the natural level of safety as possible. + Faster but less-safe implementations could always be provided as extensions + to the standard components. <sup><a title= + "The prevalent philosophy in the design of STL was that functionality that wasn't essential to all uses should be left out in favor of efficiency, as long as that functionality could be obtained when needed by adapting the base components. This departs from that philosophy, but it would be difficult or impossible to obtain even the basic guarantee by adapting a base component that doesn't already have it." + name="#footnote10">10</a></sup> + + <h2>7 Automated testing for exception-safety</h2> + + <p>As part of the standardization process, I produced an exception-safe + reference implementation of the STL. Error-handling code is seldom + rigorously tested in real life, in part because it is difficult to cause + error conditions to occur. It is very common to see error-handling code + which crashes the first time it is executed ...in a shipping product! To + bolster confidence that the implementation actually worked as advertised, I + designed an automated test suite, based on an exhaustive technique due to + my colleague Matt Arnold. + + <p>The test program started with the basics: reinforcement and + instrumentation, especially of the global operators <code>new</code> and + <code>delete</code>.<sup><a title= + "An excellent discussion on how to fortify memory subsystems can be found in: Steve Maguire, Writing Solid Code, Microsoft Press, Redmond, WA, 1993, ISBN 1-55615- 551-4." + name="#footnote11">11</a></sup>Instances of the components (containers and + algorithms) were created, with type parameters chosen to reveal as many + potential problems as possible. For example, all type parameters were given + a pointer to heap-allocated memory, so that leaking a contained object + would be detected as a memory leak. + + <p>Finally, a scheme was designed that could cause an operation to throw an + exception at each possible point of failure. At the beginning of every + client-supplied operation which is allowed to throw an exception, a call to + <code>ThisCanThrow</code> was added. A call to <code>ThisCanThrow</code> + also had to be added everywhere that the generic operation being tested + might throw an exception, for example in the global operator + <code>new</code>, for which an instrumented replacement was supplied. + + <blockquote> +<pre> +// Use this as a type parameter, e.g. vector<TestClass> +struct TestClass +{ + TestClass( int v = 0 ) + : p( ThisCanThrow(), new int( v ) ) {} + TestClass( const TestClass& rhs ) + : p( ThisCanThrow(), new int( *rhs.p ) ) {} + const TestClass& operator=( const TestClass& rhs ) + { ThisCanThrow(); *p = *rhs.p; } + bool operator==( const TestClass& rhs ) + { ThisCanThrow(); return *p == *rhs.p; } + ...etc... + ~TestClass() { delete p; } +}; +</pre> + </blockquote> + + <p><code>ThisCanThrow</code> simply decrements a ``throw + counter'' and, if it has reached zero, throws an exception. Each test + takes a form which begins the counter at successively higher values in an + outer loop and repeatedly attempts to complete the operation being tested. + The result is that the operation throws an exception at each successive + step along its execution path that can possibly fail. For example, here is + a simplified version of the function used to test the <i>strong</i> + guarantee: <a title= + "Note that this technique requires that the operation being tested be exception-neutral. If the operation ever tries to recover from an exception and proceed, the throw counter will be negative, and subsequent operations that might fail will not be tested for exception-safety." + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#footnote12"><sup>12</sup></a> + + <blockquote> +<pre> +extern int gThrowCounter; // The throw counter +void ThisCanThrow() +{ + if (gThrowCounter-- == 0) + throw 0; +} + +template <class Value, class Operation> +void StrongCheck(const Value& v, const Operation& op) +{ + bool succeeded = false; + for (long nextThrowCount = 0; !succeeded; ++nextThrowCount) + { + Value duplicate = v; + try + { + gThrowCounter = nextThrowCount; + op( duplicate ); // Try the operation + succeeded = true; + } + catch(...) // Catch all exceptions + { + bool unchanged = duplicate == v; // Test <i>strong</i> guarantee + assert( unchanged ); + } + // Specialize as desired for each container type, to check + // integrity. For example, size() == distance(begin(),end()) + CheckInvariant(v); // Check any invariant + } +} +</pre> + </blockquote> + + <p>Notably, this kind of testing is much easier and less intrusive with a + generic component than with non-generics, because testing-specific type + parameters can be used without modifying the source code of the component + being tested. Also, generic functions like <code>StrongCheck</code> above + were instrumental in performing the tests on a wide range of values and + operations. + + <h2>8 Further Reading</h2> + To my knowledge, there are currently only two descriptions of STL + exception-safety available. The original specification <a title= + "D. Abrahams, Exception Safety in STLport" href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#reference2"><sup>[2]</sup></a> + for the reference exception-safe implementation of the STL is an informal + specification, simple and self-explanatory (also verbose), and uses the + <i>basic-</i> and <i>strong-</i>guarantee distinctions outlined in this + article. It explicitly forbids leaks, and differs substantively from the + final C++ standard in the guarantees it makes, though they are largely + identical. I hope to produce an updated version of this document soon. + + <p>The description of exception-safety in the C++ Standard <a title= + "International Standard ISO/IEC 14882, Information Technology-Programming Languages-C++, Document Number ISO/IEC 14882-1998" + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#reference1"><sup>[1]</sup></a> + is only slightly more formal, but relies on hard-to-read + ``standardese'' and an occasionally subtle web of implication.<a + title= + "The changes to the draft standard which introduced exception-safety were made late in the process, when amendments were likely to be rejected solely on the basis of the number of altered words. Unfortunately, the result compromises clarity somewhat in favor of brevity. Greg Colvin was responsible for the clever language-lawyering needed to minimize the extent of these changes." + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#footnote13"><sup>13</sup></a> + In particular, leaks are not treated directly at all. It does have the + advantage that it <i>is</i> the standard. + + <p>The original reference implementation <a title= + "B. Fomitchev, Adapted SGI STL Version 1.0, with exception handling code by D. Abrahams" + href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#reference5"><sup>[5]</sup></a> + of the exception-safe STL is an adaptation of an old version of the SGI + STL, designed for C++ compilers with limited features. Although it is not a + complete STL implementation, the code may be easier to read, and it + illustrates a useful base-class technique for eliminating + exception-handling code in constructors. The full test suite <a title= + "D. Abrahams and B. Fomitchev, Exception Handling Test Suite" href= + "http://people.ne.mediaone.net/abrahams/abrahams.html#reference3"><sup>[3]</sup></a> + used to validate the reference implementation has been used successfully to + validate all recent versions of the SGI STL, and has been adapted to test + one other vendor's implementation (which failed). As noted on the + documentation page, it also seems to have the power to reveal hidden + compiler bugs, particularly where optimizers interact with + exception-handling code. + + <h2>References</h2> + + <ol> + <li><a name="reference1">International</a> Standard ISO/IEC 14882, + <i>Information Technology-Programming Languages-C++</i>, Document Number + ISO/IEC 14882-1998, available from <a href= + "http://webstore.ansi.org/ansidocstore/default.asp">http://webstore.ansi.org/ansidocstore/default.asp</a>. + + <li><a name="reference2">D.</a> Abrahams, <i>Exception Safety in + STLport</i>, available at <a href= + "http://www.stlport.org/doc/exception_safety.html">http://www.stlport.org/doc/exception_safety.html</a>. + + <li><a name="reference3">D.</a> Abrahams and B. Fomitchev, <i>Exception + Handling Test Suite</i>, available at <a href= + "http://www.stlport.org/doc/eh_testsuite.html">http://www.stlport.org/doc/eh_testsuite.html</a>. + + <li><a name="reference4">Tom</a> Cargill, ``Exception Handling: A + False Sense of Security,'' C++ Report, Nov-Dec 1994, also available + at <a href= + "http://www.awl.com/cp/mec++-cargill.html">http://www.awl.com/cp/mec++-cargill.html</a>. + + <li><a name="reference5">B.</a> Fomitchev, <i>Adapted SGI STL Version + 1.0</i>, with exception handling code by D. Abrahams, available at <a + href= + "http://www.metabyte.com/~fbp/stl/old.html">http://www.metabyte.com/~fbp/stl/old.html</a>. + + <li><a name="reference6">D.</a> R. Musser, ``Introspective Sorting + and Selection Algorithms,'' <i>Software-Practice and Experience</i> + 27(8):983-993, 1997. + + <li><a name="reference7">Bjarne</a> Stroustrup, <i>The Design And + Evolution of C++</i>. Addison Wesley, Reading, MA, 1995, ISBN + 0-201-54330-3, Section 16.9.1. + </ol> + + <h2>Footnotes</h2> + + <p><a name="footnote1">1</a> Probably the greatest impediment to a solution + in Cargill's case was an unfortunate combination of choices on his part: + the interface he chose for his container was incompatible with his + particular demands for safety. By changing either one he might have solved + the problem. + + <p><a name="footnote2">2</a> It is usually inadvisable to throw an + exception from a destructor in C++, since the destructor may itself be + called during the stack-unwinding caused by another exception. If the + second exception is allowed to propagate beyond the destructor, the program + is immediately terminated. + + <p><a name="footnote3">3</a> In practice of course, this function would + make an extremely poor random sequence generator! + + <p><a name="footnote4">4</a> It is worth noting that mutating algorithms + usually cannot provide the <i>strong</i> guarantee: to roll back a modified + element of a range, it must be set back to its previous value using + <code>operator=</code>, which itself might throw. In the C++ standard + library, there are a few exceptions to this rule, whose rollback behavior + consists only of destruction: <code>uninitialized_copy</code>, + <code>uninitialized_fill</code>, and <code>uninitialized_fill_n</code>. + + <p><a name="footnote5">5</a> All type parameters supplied by clients of the + C++ standard library are required not to throw from their destructors. In + return, all components of the C++ standard library provide at least the + <i>basic</i> guarantee. + + <p><a name="footnote6">6</a> Similar arrangements might have been made in + the C++ standard for many of the mutating algorithms, but were never + considered due to time constraints on the standardization process. + + <p><a name="footnote7">7</a> Associative containers whose + <code>Compare</code> object might throw an exception when copied cannot use + this technique, since the swap function might fail. + + <p><a name="footnote8">8</a> This suggests another potential use for the + oft-wished-for but as yet unseen <code>container_traits<></code> + template: automated container selection to meet exception-safety + constraints. + + <p><a name="footnote9">9</a> One might be tempted to surround the erase + operation with a <code>try</code>/<code>catch</code> block to reduce the + requirements on <code>set<T></code> and the problems that arise in + case of an exception, but in the end that just begs the question. First, + erase just failed and in this case there are no viable alternative ways to + produce the necessary result. Second and more generally, because of the + variability of its type parameters a generic component can seldom be + assured that any alternatives will succeed. + + <p><a name="footnote10">10</a> The prevalent philosophy in the design of + STL was that functionality that wasn't essential to all uses should be left + out in favor of efficiency, as long as that functionality could be obtained + when needed by adapting the base components. This departs from that + philosophy, but it would be difficult or impossible to obtain even the + <i>basic</i> guarantee by adapting a base component that doesn't already + have it. + + <p><a name="footnote11">11</a> An excellent discussion on how to fortify + memory subsystems can be found in: Steve Maguire, Writing Solid Code, + Microsoft Press, Redmond, WA, 1993, ISBN 1-55615- 551-4. + + <p><a name="footnote12">12</a> Note that this technique requires that the + operation being tested be exception-neutral. If the operation ever tries to + recover from an exception and proceed, the throw counter will be negative, + and subsequent operations that might fail will not be tested for + exception-safety. + + <p><a name="footnote13">13</a> The changes to the draft standard which + introduced exception-safety were made late in the process, when amendments + were likely to be rejected solely on the basis of the number of altered + words. Unfortunately, the result compromises clarity somewhat in favor of + brevity. Greg Colvin was responsible for the clever language-lawyering + needed to minimize the extent of these changes. + diff --git a/more/generic_programming.html b/more/generic_programming.html new file mode 100644 index 0000000000..9cd5d80342 --- /dev/null +++ b/more/generic_programming.html @@ -0,0 +1,448 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> + + <meta name="generator" content="HTML Tidy, see www.w3.org"> + <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> + <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> + <meta name="ProgId" content="FrontPage.Editor.Document"> + + <title>Generic Programming Techniques</title> + + <img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" + width="277" height="86"> + + <body bgcolor="#FFFFFF" text="#000000"> + + <h1>Generic Programming Techniques</h1> + + <p>This is an incomplete survey of some of the generic programming + techniques used in the <a href="../index.htm">boost</a> libraries. + + <h2>Table of Contents</h2> + + <ul> + <li><a href="#introduction">Introduction</a> + + <li><a href="#concept">The Anatomy of a Concept</a> + + <li><a href="#traits">Traits</a> + + <li><a href="#tag_dispatching">Tag Dispatching</a> + + <li><a href="#adaptors">Adaptors</a> + + <li><a href="#type_generator">Type Generators</a> + + <li><a href="#object_generator">Object Generators</a> + + <li><a href="#policy">Policy Classes</a> + </ul> + + <h2><a name="introduction">Introduction</a></h2> + + <p>Generic programming is about generalizing software components so that + they can be easily reused in a wide variety of situations. In C++, class + and function templates are particularly effective mechanisms for generic + programming because they make the generalization possible without + sacrificing efficiency. + + <p>As a simple example of generic programming, we will look at how one + might generalize the <tt>memcpy()</tt> function of the C standard library. + An implementation of <tt>memcpy()</tt> might look like the following: + <br> + <br> + + <blockquote> +<pre> +void* memcpy(void* region1, const void* region2, size_t n) +{ + const char* first = (const char*)region2; + const char* last = ((const char*)region2) + n; + char* result = (char*)region1; + while (first != last) + *result++ = *first++; + return result; +} +</pre> + </blockquote> + The <tt>memcpy()</tt> function is already generalized to some extent by the + use of <tt>void*</tt> so that the function can be used to copy arrays of + different kinds of data. But what if the data we would like to copy is not + in an array? Perhaps it is in a linked list. Can we generalize the notion + of copy to any sequence of elements? Looking at the body of + <tt>memcpy()</tt>, the function's <b><i>minimal requirements</i></b> are + that it needs to to <i>traverse</i> through the sequence using some sort of + pointer, <i>access</i> elements pointed to, <i>write</i> the elements to + the destination, and <i>compare</i> pointers to know when to stop. The C++ + standard library groups requirements such as these into + <b><i>concepts</i></b>, in this case the <a href= + "http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a> concept + (for <tt>region2</tt>) and the <a href= + "http://www.sgi.com/tech/stl/OutputIterator.html">Output Iterator</a> + concept (for <tt>region1</tt>). + + <p>If we rewrite the <tt>memcpy()</tt> as a function template, and use the + <a href="http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a> + and <a href="http://www.sgi.com/tech/stl/OutputIterator.html">Output + Iterator</a> concepts to describe the requirements on the template + parameters, we can implement a highly reusable <tt>copy()</tt> function in + the following way: + <br> + <br> + + <blockquote> +<pre> +template <typename InputIterator, typename OutputIterator> +OutputIterator +copy(InputIterator first, InputIterator last, OutputIterator result) +{ + while (first != last) + *result++ = *first++; + return result; +} +</pre> + </blockquote> + + <p>Using the generic <tt>copy()</tt> function, we can now copy elements + from any kind of sequence, including a linked list that exports iterators + such as <tt>std::<a href= + "http://www.sgi.com/tech/stl/List.html">list</a></tt>. + <br> + <br> + + <blockquote> +<pre> +#include <list> +#include <vector> +#include <iostream> + +int main() +{ + const int N = 3; + std::vector<int> region1(N); + std::list<int> region2; + + region2.push_back(1); + region2.push_back(0); + region2.push_back(3); + + std::copy(region2.begin(), region2.end(), region1.begin()); + + for (int i = 0; i < N; ++i) + std::cout << region1[i] << " "; + std::cout << std::endl; +} +</pre> + </blockquote> + + <h2><a name="concept">Anatomy of a Concept</a></h2> + A <b><i>concept</i></b> is a set requirements, where the requirements + consist of valid expressions, associated types, invariants, and complexity + guarantees. A type that satisfies the set of requirements is said to + <b><i>model</i></b> the concept. A concept can extend the requirements of + another concept, which is called <b><i>refinement</i></b>. + + <ul> + <li><a name="valid_expression"><b>Valid Expressions</b></a> are C++ + expressions which must compile successfully for the objects involved in + the expression to be considered <i>models</i> of the concept. + + <li><a name="associated_type"><b>Associated Types</b></a> are types that + are related to the modeling type in that they participate in one or more + of the valid expressions. Typically associated types can be accessed + either through typedefs nested within a class definition for the modeling + type, or they are accessed through a <a href="#traits">traits class</a>. + + <li><b>Invariants</b> are run-time characteristics of the objects that + must always be true, that is, the functions involving the objects must + preserve these characteristics. The invariants often take the form of + pre-conditions and post-conditions. + + <li><b>Complexity Guarantees</b> are maximum limits on how long the + execution of one of the valid expressions will take, or how much of + various resources its computation will use. + </ul> + + <p>The concepts used in the C++ Standard Library are documented at the <a + href="http://www.sgi.com/tech/stl/table_of_contents.html">SGI STL site</a>. + + <h2><a name="traits">Traits</a></h2> + + <p>A traits class provides a way of associating information with a + compile-time entity (a type, integral constant, or address). For example, + the class template <tt><a href= + "http://www.sgi.com/tech/stl/iterator_traits.html">std::iterator_traits<T></a></tt> + looks something like this: + + <blockquote> +<pre> +template <class Iterator> +struct iterator_traits { + typedef ... iterator_category; + typedef ... value_type; + typedef ... difference_type; + typedef ... pointer; + typedef ... reference; +}; +</pre> + </blockquote> + The traits' <tt>value_type</tt> gives generic code the type which the + iterator is "pointing at", while the <tt>iterator_category</tt> can be used + to select more efficient algorithms depending on the iterator's + capabilities. + + <p>A key feature of traits templates is that they're <i>non-intrusive</i>: + they allow us to associate information with arbitrary types, including + built-in types and types defined in third-party libraries, Normally, traits + are specified for a particular type by (partially) specializing the traits + template. + + <p>For an in-depth description of <tt>std::iterator_traits</tt>, see <a + href="http://www.sgi.com/tech/stl/iterator_traits.html">this page</a> + provided by SGI. Another very different expression of the traits idiom in + the standard is <tt>std::numeric_limits<T></tt> which provides + constants describing the range and capabilities of numeric types. + + <h2><a name="tag_dispatching">Tag Dispatching</a></h2> + + <p>A technique that often goes hand in hand with traits classes is tag + dispatching, which is a way of using function overloading to dispatch based + on properties of a type. A good example of this is the implementation of the + <a href= + "http://www.sgi.com/tech/stl/advance.html"><tt>std::advance()</tt></a> + function in the C++ Standard Library, which increments an iterator + <tt>n</tt> times. Depending on the kind of iterator, there are different + optimizations that can be applied in the implementation. If the iterator is + <a href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">random + access</a> (can jump forward and backward arbitrary distances), then the + <tt>advance()</tt> function can simply be implemented with <tt>i += n</tt>, + and is very efficient: constant time. Other iterators must be + <tt>advance</tt>d in steps, making the operation linear in n. If the + iterator is <a href= + "http://www.sgi.com/tech/stl/BidirectionalIterator.html">bidirectional</a>, + then it makes sense for <tt>n</tt> to be negative, so we must decide whether + to increment or decrement the iterator. + + <p>The relation between tag dispatching and traits classes is that the + property used for dispatching (in this case the <tt>iterator_category</tt>) + is often accessed through a traits class. The main <tt>advance()</tt> function + uses the <a href= + "http://www.sgi.com/tech/stl/iterator_traits.html"><tt>iterator_traits</tt></a> + class to get the <tt>iterator_category</tt>. It then makes a call the the + overloaded <tt>advance_dispatch()</tt> function. The appropriate + <tt>advance_dispatch()</tt> is selected by the compiler based on whatever + type the <tt>iterator_category</tt> resolves to, either <a href= + "http://www.sgi.com/tech/stl/input_iterator_tag.html"><tt>input_iterator_tag</tt></a>, + <a href= + "http://www.sgi.com/tech/stl/bidirectional_iterator_tag.html"><tt>bidirectional_iterator_tag</tt></a>, + or <a href= + "http://www.sgi.com/tech/stl/random_access_iterator_tag.html"><tt>random_access_iterator_tag</tt></a>. + A <b><i>tag</i></b> is simply a class whose only purpose is to convey some + property for use in tag dispatching and similar techniques. Refer to <a + href="http://www.sgi.com/tech/stl/iterator_tags.html">this page</a> for a + more detailed description of iterator tags. + + <blockquote> +<pre> +namespace std { + struct input_iterator_tag { }; + struct bidirectional_iterator_tag { }; + struct random_access_iterator_tag { }; + + namespace detail { + template <class InputIterator, class Distance> + void advance_dispatch(InputIterator& i, Distance n, <b>input_iterator_tag</b>) { + while (n--) ++i; + } + + template <class BidirectionalIterator, class Distance> + void advance_dispatch(BidirectionalIterator& i, Distance n, + <b>bidirectional_iterator_tag</b>) { + if (n >= 0) + while (n--) ++i; + else + while (n++) --i; + } + + template <class RandomAccessIterator, class Distance> + void advance_dispatch(RandomAccessIterator& i, Distance n, + <b>random_access_iterator_tag</b>) { + i += n; + } + } + + template <class InputIterator, class Distance> + void advance(InputIterator& i, Distance n) { + typename <b>iterator_traits<InputIterator>::iterator_category</b> category; + detail::advance_dispatch(i, n, <b>category</b>); + } +} +</pre> + </blockquote> + + <h2><a name="adaptors">Adaptors</a></h2> + + <p>An <i>adaptor</i> is a class template which builds on another type or + types to provide a new interface or behavioral variant. Examples of + standard adaptors are <a href= + "http://www.sgi.com/tech/stl/ReverseIterator.html">std::reverse_iterator</a>, + which adapts an iterator type by reversing its motion upon + increment/decrement, and <a href= + "http://www.sgi.com/tech/stl/stack.html">std::stack</a>, which adapts a + container to provide a simple stack interface. + + <p>A more comprehensive review of the adaptors in the standard can be found + <a href= + "http://www.cs.rpi.edu/~wiseb/xrds/ovp2-3b.html#SECTION00015000000000000000"> + here</a>. + + <h2><a name="type_generator">Type Generators</a></h2> + + <p>A <i>type generator</i> is a template whose only purpose is to + synthesize a new type or types based on its template argument(s)<a href= + "#1">[1]</a>. The generated type is usually expressed as a nested typedef + named, appropriately <tt>type</tt>. A type generator is usually used to + consolidate a complicated type expression into a simple one, as in + <tt>boost::<a href= + "../libs/utility/filter_iterator.htm">filter_iterator_generator</a></tt>, + which looks something like this: + + <blockquote> +<pre> +template <class Predicate, class Iterator, + class Value = <i>complicated default</i>, + class Reference = <i>complicated default</i>, + class Pointer = <i>complicated default</i>, + class Category = <i>complicated default</i>, + class Distance = <i>complicated default</i> + > +struct filter_iterator_generator { + typedef iterator_adaptor< + Iterator,filter_iterator_policies<Predicate,Iterator>, + Value,Reference,Pointer,Category,Distance> <b>type</b>; +}; +</pre> + </blockquote> + + <p>Now, that's complicated, but producing an adapted filter iterator is + much easier. You can usually just write: + + <blockquote> +<pre> +boost::filter_iterator_generator<my_predicate,my_base_iterator>::type +</pre> + </blockquote> + + <h2><a name="object_generator">Object Generators</a></h2> + + <p>An <i>object generator</i> is a function template whose only purpose is + to construct a new object out of its arguments. Think of it as a kind of + generic constructor. An object generator may be more useful than a plain + constructor when the exact type to be generated is difficult or impossible + to express and the result of the generator can be passed directly to a + function rather than stored in a variable. Most Boost object generators are + named with the prefix "<tt>make_</tt>", after <tt>std::<a href= + "http://www.sgi.com/tech/stl/pair.html">make_pair</a>(const T&, const U&)</tt>. + + <p>For example, given: + + <blockquote> +<pre> +struct widget { + void tweak(int); +}; +std::vector<widget *> widget_ptrs; +</pre> + </blockquote> + By chaining two standard object generators, <tt>std::<a href= + "http://www.dinkumware.com/htm_cpl/functio2.html#bind2nd">bind2nd</a>()</tt> + and <tt>std::<a href= + "http://www.dinkumware.com/htm_cpl/functio2.html#mem_fun">mem_fun</a>()</tt>, + we can easily tweak all widgets: + + <blockquote> +<pre> +void tweak_all_widgets1(int arg) +{ + for_each(widget_ptrs.begin(), widget_ptrs.end(), + <b>bind2nd</b>(std::<b>mem_fun</b>(&widget::tweak), arg)); +} +</pre> + </blockquote> + + <p>Without using object generators the example above would look like this: + + <blockquote> +<pre> +void tweak_all_widgets2(int arg) +{ + for_each(struct_ptrs.begin(), struct_ptrs.end(), + <b>std::binder2nd<std::mem_fun1_t<void, widget, int> ></b>( + std::<b>mem_fun1_t<void, widget, int></b>(&widget::tweak), arg)); +} +</pre> + </blockquote> + + <p>As expressions get more complicated the need to reduce the verbosity of + type specification gets more compelling. + + <h2><a name="policy">Policy Classes</a></h2> + + <p>A policy class is a template parameter used to transmit behavior. An + example from the standard library is <tt>std::<a href= + "http://www.dinkumware.com/htm_cpl/memory.html#allocator">allocator</a></tt>, + which supplies memory management behaviors to standard <a href= + "http://www.sgi.com/tech/stl/Container.html">containers</a>. + + <p>Policy classes have been explored in detail by <a href= + "mailto:andrewalex@hotmail.com">Andrei Alexandrescu</a> in <a href= + "http://www.cs.ualberta.ca/~hoover/cmput401/XP-Notes/xp-conf/Papers/7_3_Alexandrescu.pdf"> + this paper</a>. He writes: + + <blockquote> + <p>Policy classes are implementations of punctual design choices. They + are inherited from, or contained within, other classes. They provide + different strategies under the same syntactic interface. A class using + policies is templated having one template parameter for each policy it + uses. This allows the user to select the policies needed. + + <p>The power of policy classes comes from their ability to combine + freely. By combining several policy classes in a template class with + multiple parameters, one achieves combinatorial behaviors with a linear + amount of code. + </blockquote> + + <p>Andrei's description of policy classes describe their power as being + derived from their granularity and orthogonality. Boost has probably + diluted the distinction in the <a href= + "../libs/utility/iterator_adaptors.htm">Iterator Adaptors</a> library, + where we transmit all of an adapted iterator's behavior in a single policy + class. There is precedent for this, however: <tt><a href= + "http://www.dinkumware.com/htm_cpl/string2.html#char_traits">std::char_traits</a></tt>, + despite its name, acts as a policies class that determines the behaviors of + <a href= + "http://www.dinkumware.com/htm_cpl/string2.html#basic_string">std::basic_string</a>. + + <h2>Notes</h2> + <a name="1">[1]</a> Type generators are a workaround for the lack of + ``templated typedefs'' in C++. + <hr> + + <p>Revised + <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->14 Mar 2001<!--webbot bot="Timestamp" endspan i-checksum="14885" --> + + + <p>© Copyright David Abrahams 2001. Permission to copy, use, modify, + sell and distribute this document is granted provided this copyright notice + appears in all copies. This document is provided "as is" without express or + implied warranty, and with no claim as to its suitability for any purpose. + <!-- LocalWords: HTML html charset gif alt htm struct SGI namespace std libs + --> + <!-- LocalWords: InputIterator BidirectionalIterator RandomAccessIterator pdf + --> + <!-- LocalWords: typename Alexandrescu templated Andrei's Abrahams memcpy int + --> + + <!-- LocalWords: const OutputIterator iostream pre cpl + --> + + </body> diff --git a/more/header.htm b/more/header.htm new file mode 100644 index 0000000000..6fdfbbfeba --- /dev/null +++ b/more/header.htm @@ -0,0 +1,93 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Boost Header policy</title> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<meta name="Microsoft Border" content="none, default"> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Boost Header Policy</h1> +<p>Header files are the place where a library comes into contact with user code +and other libraries. To co-exist peacefully and productively, headers must +be "good neighbors".</p> +<p>Here are the standards for namespace boost headers. Many of +these are also reasonable guidelines for general use. +<ul> + <li>Headers should have a .hpp (lowercase) filename extension. </li> + <li>Wrap the header in #ifndef guards so that multiple inclusion is + benign. Use a naming convention that minimizes the chance of clashes + with macro names from other's code. The <a href="#Sample header">sample + header</a> uses the Boost convention of all uppercase letters, with the + header name prefixed by the namespace name, and suffixed with HPP, separated + by underscores.</li> + <li>Wrap the header contents in a namespace to prevent global namespace + pollution. The namespace approach to pollution control is strongly preferred + to older approaches such as adding funny prefixes to global names. + Libraries which are designed to work well with other Boost libraries should + be placed namespace <tt>boost</tt>.</li> + <li>Place the header file in a sub-directory to prevent conflict with + identically named header files in other libraries. The parent + directory is added to the compiler's include search path. Then both + your code and user code specifies the sub-directory in <tt>#include</tt> + directives. Thus the header <a href="#Sample header">sample header</a> + would be included by <tt>#include <boost/furball.hpp></tt></li> + <li>The preferred ordering for class definitions is public members, protected + members, and finally private members.</li> + <li>Include the boost/config.hpp <a href="../libs/config/index.htm">configuration + header</a> if there is a need to deal with compiler or platform + configuration issues.</li> +</ul> +<h2><a name="Sample header"></a>Sample Header</h2> +<pre><tt>// Boost general library furball.hpp header file ---------------------------// + +// (C) Copyright Your Name 1998. Permission to copy, use, modify, sell and +// distribute this software is granted provided this copyright notice appears +// in all copies. This software is provided "as is" without express or implied +// warranty, and with no claim as to its suitability for any purpose. + +// See http://www.boost.org for updates, documentation, and revision history. + +#ifndef BOOST_FURBALL_HPP +#define BOOST_FURBALL_HPP + +namespace boost { + +// Furball class declaration -----------------------------------------------// + + class furball + { + public: + void throw_up(); + private: + int whatever; + }; // furball + +} // namespace + +#endif // BOOST_FURBALL_HPP</tt></pre> +<h2>Coding Style</h2> +<p>The alert reader will have noticed that the <a href="#Sample header">sample +header</a> employs a certain coding style for indentation, positioning braces, +commenting ending braces, and similar formatting issues. These stylistic +issues are viewed as personal preferences and are not part of the Boost Header +Policy.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->06 February, 2001<!--webbot bot="Timestamp" endspan i-checksum="40406" --></p> + +</body> + +</html> diff --git a/more/imp_vars.htm b/more/imp_vars.htm new file mode 100644 index 0000000000..2829c13b00 --- /dev/null +++ b/more/imp_vars.htm @@ -0,0 +1,201 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Boost Implementation Variations</title> +</head> + +<body link="#0000ff" vlink="#800080" bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Boost Implementation Variations</h1> +<h2>Separation of interface and implementation</h2> +<p>The interface specifications for boost.org library components (as well as for +quality software in general) are conceptually separate from implementations of +those interfaces. This may not be obvious, particularly when a component is +implemented entirely within a header, but this separation of interface and +implementation is always assumed. From the perspective of those concerned with +software design, portability, and standardization, the interface is what is +important, while the implementation is just a detail.</p> +<p>Dietmar Kühl, one of the original boost.org contributors, comments "The +main contribution is the interface, which is augmented with an implementation, +proving that it is possible to implement the corresponding class and providing a +free implementation."</p> +<b> +<h2>Implementation variations</h2> +</b> +<p>There may be a need for multiple implementations of an interface, to +accommodate either platform dependencies or performance tradeoffs. Examples of +platform dependencies include compiler shortcomings, file systems, thread +mechanisms, and graphical user interfaces. The classic example of a performance +tradeoff is a fast implementation which uses a lot of memory versus a slower +implementation which uses less memory.</p> +<p>Boost libraries generally use a <a href="../libs/config/index.htm">configuration +header</a>, boost/config.hpp, to capture compiler and platform +dependencies. Although the use of boost/config.hpp is not required, it is +the preferred approach for simple configuration problems. </p> +<h2>Boost policy</h2> +<p>The Boost policy is to avoid platform dependent variations in interface +specifications, but supply implementations which are usable over a wide range of +platforms and applications. That means boost libraries will use the +techniques below described as appropriate for dealing with platform +dependencies.</p> +<p>The Boost policy toward implementation variations designed to enhance +performance is to avoid them unless the benefits greatly exceed the full +costs. The term "full costs" is intended to include both +tangible costs like extra maintenance, and intangible cost like increased +difficulty in user understanding.</p> +<b> +<h2>Techniques for providing implementation variations</h2> +</b> +<p>Several techniques may be used to provide implementation variations. Each is +appropriate in some situations, and not appropriate in other situations.</p> +<h3>Single general purpose implementation</h3> +<p>The first technique is to simply not provide implementation variation at +all. Instead, provide a single general purpose implementation, and forgo +the increased complexity implied by all other techniques.</p> +<p><b>Appropriate:</b> When it is possible to write a single portable +implementation which has reasonable performance across a wide range of +platforms. Particularly appropriate when alternative implementations differ only +in esoteric ways.</p> +<p><b>Not appropriate:</b> When implementation requires platform specific +features, or when there are multiple implementation possible with widely +differing performance characteristics.</p> +<p>Beman Dawes comments "In design discussions some implementation is often +alleged to be much faster than another, yet a timing test discovers no +significant difference. The lesson is that while algorithmic differences may +affect speed dramatically, coding differences such as changing a class from +virtual to non-virtual members or removing a level of indirection are unlikely +to make any measurable difference unless deep in an inner loop. And even in an +inner loop, modern CPU’s often execute such competing code sequences in the +same number of clock cycles! A single general purpose implementation is +often just fine."</p> +<p>Or as Donald Knuth said, "Premature optimization is the root of all +evil." (Computing Surveys, vol 6, #4, p 268).</p> +<h3>Macros</h3> +<p>While the evils of macros are well known, there remain a few cases where +macros are the preferred solution:</p> +<blockquote> + <ul> + <li> Preventing multiple inclusion of headers via #include guards.</li> + <li> Passing minor configuration information from a configuration + header to other files.</li> + </ul> +</blockquote> +<p><b>Appropriate:</b> For small compile-time variations which would +otherwise be costly or confusing to install, use, or maintain. More appropriate +to communicate within and between library components than to communicate with +library users.</p> +<p><b>Not appropriate: </b> If other techniques will do.</p> +<p>To minimize the negative aspects of macros:</p> +<blockquote> + <ul> + <li>Only use macros when they are clearly superior to other + techniques. They should be viewed as a last resort.</li> + <li>Names should be all uppercase, and begin with the namespace name. This + will minimize the chance of name collisions. For example, the #include + guard for a boost header called foobar.h might be named BOOST_FOOBAR_H.</li> + </ul> +</blockquote> +<h3>Separate files</h3> +<p>A library component can have multiple variations, each contained in its own +separate file or files. The files for the most appropriate variation are +copied to the appropriate include or implementation directories at installation +time.</p> +<p>The way to provide this approach in boost libraries is to include specialized +implementations as separate files in separate sub-directories in the .ZIP +distribution file. For example, the structure within the .ZIP distribution file +for a library named foobar which has both default and specialized variations +might look something like:</p> +<blockquote> + <pre>foobar.h // The default header file +foobar.cpp // The default implementation file +readme.txt // Readme explains when to use which files +self_contained/foobar.h // A variation with everything in the header +linux/foobar.cpp // Implementation file to replace the default +win32/foobar.h // Header file to replace the default +win32/foobar.cpp // Implementation file to replace the default</pre> +</blockquote> +<p><b>Appropriate:</b> When different platforms require different +implementations, or when there are major performance differences between +possible implementations. </p> +<p><b>Not appropriate:</b> When it makes sense to use more that one of the +variations in the same installation.</p> +<h3>Separate components</h3> +<p>Rather than have several implementation variations of a single component, +supply several separate components. For example, the Boost library currently +supplies <code>scoped_ptr</code> and <code>shared_ptr</code> classes rather than +a single <code>smart_ptr</code> class parameterized to distinguish between the +two cases. There are several ways to make the component choice:</p> +<blockquote> + <ul> + <li>Hardwired by the programmer during coding.</li> + <li>Chosen by programmer written runtime logic (trading off some extra + space, time, and program complexity for the ability to select the + implementation at run-time.)</li> + </ul> +</blockquote> +<p><b>Appropriate: </b>When the interfaces for the variations diverge, and when +it is reasonably to use more than one of the variations. When run-time selection +of implementation is called for.</p> +<p><b>Not appropriate:</b> When the variations are data type, traits, or +specialization variations which can be better handled by making the component a +template. Also not appropriate when choice of variation is best done by some +setup or installation mechanism outside of the program itself. Thus +usually not appropriate to cope with platform differences.</p> +<p><b>Note:</b> There is a related technique where the interface is specified as +an abstract (pure virtual) base class (or an interface definition language), and +the implementation choice is passed off to some third-party, such as a +dynamic-link library or object-request broker. While that is a powerful +technique, it is way beyond the scope of this discussion.</p> +<h3>Template-based approaches</h3> +<p>Turning a class or function into a template is often an elegant way to cope +with variations. Template-based approaches provide optimal space and time +efficiency in return for constraining the implementation selection to compile +time. </p> +<p>Important template techniques include:</p> +<blockquote> + <ul> + <li>Data type parameterization. This allows a single component to + operate on a variety of data types, and is why templates were originally + invented.</li> + <li>Traits parameterization. If parameterization is complex, bundling + up aspects into a single traits helper class can allow great variation + while hiding messy details. The C++ Standard Library provides + several examples of this idiom, such as <code>iterator_traits<></code> + (24.3.1 lib.iterator.traits) and <tt>char_traits<></tt> (21.2 + lib.char.traits).</li> + <li>Specialization. A template parameter can be used purely for the + purpose of selecting a specialization. For example:</li> + </ul> + <blockquote> + <blockquote> + <pre>SomeClass<fast> my_fast_object; // fast and small are empty classes +SomeClass<small> my_small_object; // used just to select specialization</pre> + </blockquote> + </blockquote> +</blockquote> +<p><b>Appropriate: </b>When the need for variation is due to data type or +traits, or is performance related like selecting among several algorithms, and +when a program might reasonably use more than one of the variations.</p> +<p><b>Not appropriate:</b> When the interfaces for variations are +different, or when choice of variation is best done by some mechanism outside of +the program itself. Thus usually not appropriate to cope with platform +differences.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->06 February, 2001<!--webbot bot="Timestamp" endspan i-checksum="40406" --></p> + +</body> + +</html> diff --git a/more/index.htm b/more/index.htm new file mode 100644 index 0000000000..f117e0cbd4 --- /dev/null +++ b/more/index.htm @@ -0,0 +1,125 @@ +<html> + +<head> +<meta http-equiv="Content-Type" +content="text/html; charset=iso-8859-1"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0"> +<title>Boost More Information</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" cellpadding="2" bgcolor="#007F7F"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" + alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font color="#FFFFFF" size="4" + face="Arial">Home</font></a></td> + <td><a href="../libs/libraries.htm"><font color="#FFFFFF" + size="4" face="Arial">Libraries</font></a></td> + <td><a href="../people/people.htm"><font color="#FFFFFF" + size="4" face="Arial">People</font></a></td> + <td><a href="faq.htm"><font color="#FFFFFF" size="4" + face="Arial">FAQ</font></a></td> + <td><a href="index.htm"><font color="#FFFFFF" size="4" + face="Arial">More</font></a></td> + </tr> +</table> + +<h1>More Information</h1> + +<h2>Boost Policies</h2> + +<blockquote> + <p><a href="discussion_policy.htm"><b>Mailing List Discussion + Policy.</b></a> What's acceptable and what isn't.</p> + <p><a href="lib_guide.htm"><b>Library Requirements and + Guidelines</b></a>. Basic standards for those preparing + a submission.</p> + <p><a href="test_policy.htm"><b>Test Policy and Protocols</b></a>. + How testing works at Boost.</p> + <p><a href="submission_process.htm"><b>Library Submission + Process</b></a>. How to submit a library to Boost.</p> + <p><a href="formal_review_process.htm"><b>Library Formal + Review Process</b></a>. Including how to submit a review + comment.</p> + <p><a href="header.htm"><b>Header Policy</b></a>. + Headers are where a library contacts its users, so + programming practices are particularly important.</p> + <p><a href="imp_vars.htm"><b>Implementation Variations</b></a>. + Sometimes one size fits all, sometimes it doesn't. This + page deals with the trade-offs.</p> + <p><a href="library_reuse.htm"><b>Library Reuse</b></a>. + Should Boost libraries use other boost libraries? What + about the C++ Standard Library? It's another trade-off.</p> +</blockquote> + +<h2>Boost Whatever</h2> + +<blockquote> + <p><a href="../status/compiler_status.html"><b>Compiler + Status</b></a> Describes what library works with + which compiler.</p> + <p><a href="regression.html"><b>Internal Regression Test + Suite</b></a> Describes the tool for generating + the compiler status tables </p> + <p><a href="../libs/hdr_depend.html"><b>Header Dependencies</b></a> + Describes what other headers each boost header includes.</p> +</blockquote> + +<h2>Articles and Papers</h2> + +<blockquote> + <p><a href="error_handling.html"><b>Error and Exception + Handling</b></a> describes approaches to errors and + exceptions by <a href="../people/dave_abrahams.htm">David + Abrahams</a>. </p> + <p><a href="count_bdy.htm"><b>Counted Body Techniques</b></a> + by <a href="../people/kevlin_henney.htm">Kevlin Henney</a> is + must reading for those interested in reference counting, a + widely used object management idiom. Originally + published in <a + href="http://www.accu.org/c++sig/public/Overload.html">Overload</a> + magazine.</p> + <p><a href="generic_programming.html"><b>Generic Programming + Techniques</b></a> by <a href="../people/dave_abrahams.htm">David + Abrahams</a> and <a href="../people/jeremy_siek.htm">Jeremy + Siek</a>describe some of the techniques used in Boost + libraries.</p> + <p><a href="feature_model_diagrams.htm"><b>Feature Model + Diagrams in text and HTML</b></a> describes how to represent + feature model diagrams in text form.</p> + <p><a href="borland_cpp.html"><b>Portability Hints: Borland C++ + 5.5.1</b></a> describes Borland C++ portability issues, with + suggested workarounds.</p> + <p><a href="microsoft_vcpp.html"><b>Portability Hints: + Microsoft VC++ 6.0 SP4</b></a> describes Microsoft C++ + portability issues, with suggested workarounds.</p> + <p><a href="int_const_guidelines.htm"><strong>Coding + Guidelines for Integral Constant Expressions</strong></a> + describes how to work through the maze of compiler related + bugs surrounding this tricky topic.</p> +</blockquote> + +<h2>Links</h2> + +<blockquote> + <p>The C++ Standard (ISO/IEC 14882) is available online as a + PDF file from the <a href="http://www.ansi.org">ANSI</a> (American + National Standards Institute) Electronic Standards Store. + The price is $US 18.00. The document is certainly not a + tutorial, but is interesting to those who care about the + precise specification of the language and the standard + library.</p> +</blockquote> + +<p> </p> + +<hr> + +<p>Revised <!--webbot bot="Timestamp" startspan s-type="EDITED" +s-format="%d %B, %Y" -->09 May, 2001<!--webbot bot="Timestamp" +i-checksum="13972" endspan --></p> +</body> +</html> diff --git a/more/int_const_guidelines.htm b/more/int_const_guidelines.htm new file mode 100644 index 0000000000..ef3cf145c1 --- /dev/null +++ b/more/int_const_guidelines.htm @@ -0,0 +1,323 @@ +<html> + +<head> +<meta http-equiv="Content-Type" +content="text/html; charset=iso-8859-1"> +<meta name="Template" +content="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot"> +<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0"> +<title></title> +</head> + +<body bgcolor="#FFFFFF" link="#0000FF" vlink="#800080"> + +<h2 align="center">Coding Guidelines for Integral Constant +Expressions</h2> + +<p>Integral Constant Expressions are used in many places in C++; +as array bounds, as bit-field lengths, as enumerator +initialisers, and as arguments to non-type template parameters. +However many compilers have problems handling integral constant +expressions; as a result of this, programming using non-type +template parameters in particular can be fraught with difficulty, +often leading to the incorrect assumption that non-type template +parameters are unsupported by a particular compiler. This short +article is designed to provide a set of guidelines and +workarounds that, if followed, will allow integral constant +expressions to be used in a manner portable to all the compilers +currently supported by boost. Although this article is mainly +targeted at boost library authors, it may also be useful for +users who want to understand why boost code is written in a +particular way, or who want to write portable code themselves.</p> + +<h3>What is an Integral Constant Expression?</h3> + +<p>Integral constant expressions are described in section 5.19 of +the standard, and are sometimes referred to as "compile time +constants". An integral constant expression can be one of +the following:</p> + +<ol> + <li>A literal integral value, for example 0u or 3L.</li> + <li>An enumerator value.</li> + <li>Global integral constants, for example: <font + face="Courier New"><code><br> + </code></font><code>const int my_INTEGRAL_CONSTANT = 3;</code></li> + <li>Static member constants, for example: <br> + <code>struct myclass<br> + { static const int value = 0; };</code></li> + <li>Member enumerator values, for example:<br> + <code>struct myclass<br> + { enum{ value = 0 }; };</code></li> + <li>Non-type template parameters of integral or enumerator + type.</li> + <li>The result of a <code>sizeof</code> expression, for + example:<br> + <code>sizeof(foo(a, b, c))</code></li> + <li>The result of a <code>static_cast</code>, where the + target type is an integral or enumerator type, and the + argument is either another integral constant expression, + or a floating-point literal.</li> + <li>The result of applying a binary operator to two integral + constant expressions: <br> + <code>INTEGRAL_CONSTANT1 op INTEGRAL_CONSTANT2 <br> + p</code>rovided that the operator is not an assignment + operator, or comma operator.</li> + <li>The result of applying a unary operator to an integral + constant expression: <br> + <code>op INTEGRAL_CONSTANT1<br> + </code>provided that the operator is not the increment or + decrement operator.</li> +</ol> + +<p> </p> + +<h3>Coding Guidelines</h3> + +<p>The following guidelines are declared in no particular order (in +other words you need to obey all of them - sorry!), and may also +be incomplete, more guidelines may be added as compilers change +and/or more problems are encountered.</p> + +<p><b><i>When declaring constants that are class members always +use the macro BOOST_STATIC_CONSTANT.</i></b></p> + +<pre>template <class T> +struct myclass +{ + BOOST_STATIC_CONSTANT(int, value = sizeof(T)); +};</pre> + +<p>Rationale: not all compilers support inline initialisation of +member constants, others treat member enumerators in strange ways +(they're not always treated as integral constant expressions). +The BOOST_STATIC_CONSTANT macro uses the most appropriate method +for the compiler in question.</p> + +<p><b><i>Don't declare integral constant expressions whose type +is wider than int.</i></b></p> + +<p>Rationale: while in theory all integral types are usable in +integral constant expressions, in practice many compilers limit +integral constant expressions to types no wider than <b>int</b>.</p> + +<p><b><i>Don't use logical operators in integral constant +expressions; use template meta-programming instead.</i></b></p> + +<p>The header <boost/type_traits/ice.hpp> contains a number +of workaround templates, that fulfil the role of logical +operators, for example instead of:</p> + +<p><code>INTEGRAL_CONSTANT1 || INTEGRAL_CONSTANT2</code></p> + +<p>Use:</p> + +<p><code>::boost::type_traits::ice_or<INTEGRAL_CONSTANT1,INTEGRAL_CONSTANT2>::value</code></p> + +<p>Rationale: A number of compilers (particularly the Borland and +Microsoft compilers), tend to not to recognise integral constant +expressions involving logical operators as genuine integral +constant expressions. The problem generally only shows up when +the integral constant expression is nested deep inside template +code, and is hard to reproduce and diagnose.</p> + +<p><b><i>Don't use any operators in an integral constant +expression used as a non-type template parameter</i></b></p> + +<p>Rather than:</p> + +<p><code>typedef myclass<INTEGRAL_CONSTANT1 == +INTEGRAL_CONSTANT2> mytypedef;</code></p> + +<p>Use:</p> + +<p><code>typedef myclass< some_symbol> mytypedef;</code></p> + +<p>Where <code>some_symbol</code> is the symbolic name of a an +integral constant expression whose value is <code>(INTEGRAL_CONSTANT1 +== INTEGRAL_CONSTANT2).</code></p> + +<p>Rationale: the older EDG based compilers (some of which are +used in the most recent version of that platform's compiler), +don't recognise expressions containing operators as non-type +template parameters, even though such expressions can be used as +integral constant expressions elsewhere.</p> + +<p><b><i>Always use a fully qualified name to refer to an +integral constant expression.</i></b></p> + +<p>For example:</p> + +<pre><code>typedef</code> myclass< ::boost::is_integral<some_type>::value> mytypedef;</pre> + +<p>Rationale: at least one compiler (Borland's), doesn't +recognise the name of a constant as an integral constant +expression unless the name is fully qualified (which is to say it +starts with ::).</p> + +<p><b><i>Always leave a space after a '<' and before '::'</i></b></p> + +<p>For example:</p> + +<pre><code>typedef</code> myclass< ::boost::is_integral<some_type>::value> mytypedef; + ^ + ensure there is space here!</pre> + +<p>Rationale: <: is a legal digraph in it's own right, so <:: +is interpreted as the same as [:.</p> + +<p><b><i>Don't use local names as integral constant expressions</i></b></p> + +<p>Example:</p> + +<pre>template <class T> +struct foobar +{ + BOOST_STATIC_CONSTANT(int, temp = computed_value); + typedef myclass<temp> mytypedef; // error +};</pre> + +<p>Rationale: At least one compiler (Borland's) doesn't accept +this.</p> + +<p>Although it is possible to fix this by using:</p> + +<pre>template <class T> +struct foobar +{ + BOOST_STATIC_CONSTANT(int, temp = computed_value); + typedef foobar self_type; + typedef myclass<(self_type::temp)> mytypedef; // OK +};</pre> + +<p>This breaks at least one other compiler (VC6), it is better to +move the integral constant expression computation out into a +separate traits class:</p> + +<pre>template <class T> +struct foobar_helper +{ + BOOST_STATIC_CONSTANT(int, temp = computed_value); +}; + +template <class T> +struct foobar +{ + typedef myclass< ::foobar_helper<T>::value> mytypedef; // OK +};</pre> + +<p><b><i>Don't use dependent default parameters for non-type +template parameters.</i></b></p> + +<p>For example:</p> + +<pre>template <class T, int I = ::boost::is_integral<T>::value> // Error can't deduce value of I in some cases. +struct foobar;</pre> + +<p>Rationale: this kind of usage fails for Borland C++. Note that +this is only an issue where the default value is dependent upon a +previous template parameter, for example the following is fine:</p> + +<pre>template <class T, int I = 3> // OK, default value is not dependent +struct foobar;</pre> + +<p> </p> + +<h3>Unresolved Issues</h3> + +<p>The following issues are either unresolved or have fixes that +are compiler specific, and/or break one or more of the coding +guidelines.</p> + +<p><b><i>Be careful of numeric_limits</i></b></p> + +<p>There are three issues here:</p> + +<ol> + <li>The header <limits> may be absent - it is + recommended that you never include <limits> + directly but use <boost/pending/limits.hpp> instead. + This header includes the "real" <limits> + header if it is available, otherwise it supplies it's own + std::numeric_limits definition. Boost also defines the + macro BOOST_NO_LIMITS if <limits> is absent.</li> + <li>The implementation of std::numeric_limits may be defined + in such a way that its static-const members may not be + usable as integral constant expressions. This contradicts + the standard but seems to be a bug that affects at least + two standard library vendors; boost defines + BOOST_NO_LIMITS_COMPILE_TIME_CONSTANTS in <boost/config.hpp> + when this is the case.</li> + <li>There is a strange bug in VC6, where the members of std::numeric_limits + can be "prematurely evaluated" in template + code, for example:</li> +</ol> + +<pre>template <class T> +struct limits_test +{ + BOOST_STATIC_ASSERT(::std::numeric_limits<T>::is_specialized); +};</pre> + +<p>This code fails to compile with VC6 even though no instances +of the template are ever created; for some bizarre reason <code>::std::numeric_limits<T>::is_specialized +</code>always evaluates to false, irrespective of what the +template parameter T is. The problem seems to be confined to +expressions which depend on std::numeric_limts: for example if +you replace <code>::std::numeric_limits<T>::is_specialized</code> +with <code>::boost::is_arithmetic<T>::value</code>, then +everything is fine. The following workaround also works but +conflicts with the coding guidelines:</p> + +<pre>template <class T> +struct limits_test +{ + BOOST_STATIC_CONSTANT(bool, check = ::std::numeric_limits<T>::is_specialized); + BOOST_STATIC_ASSERT(check); +};</pre> + +<p>So it is probably best to resort to something like this:</p> + +<pre>template <class T> +struct limits_test +{ +#ifdef BOOST_MSVC + BOOST_STATIC_CONSTANT(bool, check = ::std::numeric_limits<T>::is_specialized); + BOOST_STATIC_ASSERT(check); +#else + BOOST_STATIC_ASSERT(::std::numeric_limits<T>::is_specialized); +#endif +};</pre> + +<p><b><i>Be careful how you use the sizeof operator</i></b></p> + +<p>As far as I can tell, all compilers treat sizeof expressions +correctly when the argument is the name of a type (or a template-id), +however problems can occur if:</p> + +<ol> + <li>The argument is the name of a member-variable, or a local + variable (code may not compile with VC6).</li> + <li>The argument is an expression which involves the creation + of a temporary (code will not compile with Borland C++).</li> + <li>The argument is an expression involving an overloaded + function call (code compiles but the result is a garbage + value with Metroworks C++).</li> +</ol> + +<p><b><i>Don't use boost::is_convertible unless you have to</i></b></p> + +<p>Since is_convertible is implemented in terms of the sizeof +operator, it consistently gives the wrong value when used with +the Metroworks compiler, and may not compile with the Borland's +compiler (depending upon the template arguments used).</p> + +<hr> + +<p>Copyright Dr John Maddock 2001, all rights reserved.</p> + +<p> </p> + +<p> </p> +</body> +</html> diff --git a/more/lib_guide.htm b/more/lib_guide.htm new file mode 100644 index 0000000000..8355ee6679 --- /dev/null +++ b/more/lib_guide.htm @@ -0,0 +1,352 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Boost Library Requirements and Guidelines</title> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<meta name="Microsoft Border" content="none, default"> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1 align="left">Boost Library Requirements and Guidelines</h1> +<p align="left">This page describes requirements and guidelines for the content +of a library submitted to Boost.</p> +<p align="left">See the <a href="submission_process.htm">Boost Library +Submission Process</a> page for a description of the process involved.</p> +<h2 align="left">Requirements</h2> +<p>To avoid the frustration and wasted time of a proposed library being +rejected, it must meets these requirements:</p> +<ul> + <li>The license must meet the <a href="#License">license requirements</a> + below. Restricted licenses like the GPL and LGPL are not acceptable. + </li> + <li>The + copyright <a href="#Ownership">ownership</a> must be clear. + </li> + <li>The library must be generally useful and not restricted to a narrow + problem domain. + </li> + <li>The library must meet the <a href="#Portability">portability requirements</a> + below. + </li> + <li>The library must come reasonably close to meeting the <a href="#Guidelines">Guidelines</a> + below. + <ul> + <li><a href="#Design and Programming">Design and Programming</a></li> + <li><a href="#Directory structure">Directory Structure</a></li> + <li><a href="#Documentation">Documentation</a></li> + </ul> + </li> + <li>The author must be willing to participate in discussions on the mailing + list, and to refine the library accordingly.</li> +</ul> +<p>There's no requirement that an author read the mailing list for a time before +making a submission. It has been noted, however, that submissions which begin +"I just started to read this mailing list ..." seem to fail, often +embarrassingly.</p> +<h3 align="left"><a name="License">License</a> requirements</h3> +<ul> + <li>Must be simple to read and understand. + </li> + <li>Must grant permission to copy, use and modify the software for any use + (commercial and non-commercial) for no fee. + </li> + <li>Must require that the license appear on all copies of the software source + code. + </li> + <li>Must not require that the license appear with executables or other binary + uses of the library. + </li> + <li>Must not require that the source code be + available for execution or other binary uses of the library. + </li> + <li>May restrict the use of the name and description of the library to the + standard version found on the Boost web site.</li> +</ul> +<h3 align="left"><a name="Portability">Portability</a> requirements</h3> +<ul> + <li> + <p align="left">A library's interface must portable and not restricted to a + particular compiler or operating system. + </li> + <li> + <p align="left">A library's implementation must if possible be portable and + not restricted to a particular compiler or operating system. If a + portable implementation is not possible, non-portable constructions are + acceptable if reasonably easy to port to other environments, and + implementations are provided for at least two popular operating systems + (such as UNIX and Windows). + </li> + <li> + <p align="left">There is no requirement that a library run on C++ compilers + which do not conform to the ISO standard. + </li> + <li> + <p align="left">There is no requirement that a library run on any particular + C++ compiler. Boost contributors often try to ensure their libraries + work with popular compilers. The boost/config.hpp <a href="../libs/config/index.htm">configuration + header</a> is the preferred mechanism for working around compiler + deficiencies.</li> +</ul> +<p align="left">Since there is no absolute way to prove portability, many boost +submissions demonstrate practical portability by compiling and executing +correctly with two different C++ compilers, often under different operating +systems. Otherwise reviewers may disbelieve that porting is in fact +practical.</p> +<h3 align="left"><a name="Ownership">Ownership</a></h3> +<p align="left">Are you sure you own the library you are thinking of +submitting? "How to Copyright Software" by MJ Salone, Nolo +Press, 1990 says:</p> +<blockquote> + <p align="left">Doing work on your own time that is very similar to + programming you do for your employer on company time can raise nasty legal + problems. In this situation, it's best to get a written release from + your employer in advance.</p> +</blockquote> +<p align="left">Place a copyright notice in all the important files you submit. +Boost.org won't accept libraries without clear copyright information.</p> +<h2 align="left"><a name="Guidelines">Guidelines</a></h2> +<p align="left">Please use these guidelines as a checklist for preparing the +content a library submission. Not every guideline applies to every +library, but a reasonable effort to comply is expected.</p> +<h3><a name="Design and Programming">Design and Programming</a></h3> +<ul> + <li>Aim for ISO Standard C++. Than means making effective use of the standard + features of the language, and avoiding non-standard compiler extensions. It + also means using the C++ Standard Library where applicable.</li> +</ul> +<ul> + <li>Headers should be good neighbors. See the <a href="header.htm">header + policy</a>.</li> +</ul> +<ul> + <li>Follow quality programming practices. See, for example, "Effective + C++" 2nd Edition, and "More Effective C++", both by Scott + Meyers, published by Addison Wesley.</li> +</ul> +<ul> + <li>Use the C++ Standard Library or other Boost libraries, but only when the + benefits outweigh the costs. Do not use libraries other than the C++ + Standard Library or Boost. See <a href="library_reuse.htm">Library reuse</a>.</li> +</ul> +<ul> + <li>Read <a href="imp_vars.htm">Implementation Variation</a> to see how to + supply performance, platform, or other implementation variations.</li> +</ul> +<ul> + <li>Use the lowercase/underscore <a href="#Naming">naming conventions</a> of + the C++ standard library. Template parameter names begin with an + uppercase letter. Macro (gasp!) names should be all uppercase and begin with + BOOST_.</li> +</ul> +<ul> + <li>Choose meaningful names - explicit is better than implicit, and readability counts. + There is a strong preference for clear and descriptive names, even if + lengthy.</li> +</ul> +<ul> + <li>Use exceptions to report errors where appropriate, and write code that is + safe in the face of exceptions.</li> +</ul> +<ul> + <li>Avoid exception-specifications. See <a href="#Exception-specification">exception-specification + rationale</a>.</li> +</ul> +<ul> + <li>Provide sample programs or confidence tests so potential users can see how + to use your library.</li> +</ul> +<ul> + <li>Provide a regression test program or programs which follow the <a href="test_policy.htm">Test + Policies and Protocols</a>.</li> +</ul> +<ul> + <li>Although some boost members use proportional fonts, tabs, and unrestricted + line lengths in their own code, boost's widely distributed source code + should follow more conservative guidelines: + <ul> + <li>Use fixed-width fonts. See <a href="#code fonts">fonts rationale</a>.</li> + <li>Use spaces rather than tabs.</li> + <li>Limit line lengths to 80 characters.</li> + </ul> + </li> +</ul> +<ul> + <li>Begin all source files with: + <ul> + <li>A comment line describing the contents of the file.</li> + <li>Comments describing copyright and licensing.</li> + <li>A comment line referencing the Boost home page in the form:<br> + <code>// See http://www.boost.org for updates, documentation, and + revision history.</code><br> + [Including revision history in source files is no longer recommended; + the publicly available CVS repository better serves that purpose.]</li> + </ul> + </li> +</ul> +<h3><a name="Directory structure">Directory Structure</a> and Filenames</h3> +<ul> + <li>File and directory names must contain only lowercase ASCII letters , + numbers, underscores, and a period. Leading character must be + alphabetic. Maximum length 31. Only a single period is permitted. + These requirements ensure file and directory names are relatively portable.</li> + <li>All libraries have at their highest level a primary directory named for + the particular library. The primary directory may have sub-directories.</li> + <li>For very simple libraries implemented entirely within the library header, + all files go in the primary directory (except headers, which go in the boost + header directory).</li> +</ul> +<blockquote> + <p><b>Boost standard sub-directory names</b></p> + <table border="1" cellpadding="5"> + <tr> + <td><b>Sub-directory</b></td> + <td><b>Contents</b></td> + <td><b>Required</b></td> + </tr> + <tr> + <td><code>build</code></td> + <td>Library build files such as make files or IDE project files.</td> + <td>If any build files.</td> + </tr> + <tr> + <td>doc</td> + <td>Documentation (HTML) files.</td> + <td>If several doc files.</td> + </tr> + <tr> + <td><code>example</code></td> + <td>Sample program files.</td> + <td>If several sample files.</td> + </tr> + <tr> + <td><code>src</code></td> + <td>Source files which must be compiled to build the library. </td> + <td>If any source files.</td> + </tr> + <tr> + <td><code>test</code></td> + <td>Regression or other test programs or scripts.</td> + <td>If several test files.</td> + </tr> + </table> +</blockquote> +<h3><a name="Documentation">Documentation</a></h3> +<p>Even the simplest library needs some documentation; the amount should be +proportional to the need. The documentation should assume the readers have +a basic knowledge of C++, but are not necessarily experts.</p> +<p>The format for documentation should be HTML, and should not require an +advanced browser or server-side extensions.</p> +<p>There is no single right way to do documentation. HTML documentation is often +organized quite differently from traditional printed documents. Task-oriented +styles differ from reference oriented styles. In the end, it comes down to the +question: Is the documentation sufficient for the mythical "average" +C++ programmer to use the library successfully?</p> +<p>Appropriate topics for documentation often include: +<ul> + <li>General introduction to the library.</li> + <li>Description of each class.</li> + <li>Relationship between classes.</li> + <li>For each function, as applicable, description, requirements + (preconditions), effects, post-conditions, returns, and throws.</li> + <li>Discussion of error detection and recovery strategy.</li> + <li>How to use including description of typical uses.</li> + <li>How to compile and link.</li> + <li>How to test.</li> + <li>Version or revision history.</li> + <li>Rationale for design decisions. See <a href="#Rationale">Rationale + rationale</a>.</li> + <li>Acknowledgements. See <a href="#Acknowledgements">Acknowledgments + rationale.</a></li> +</ul> +<h2>Rationale</h2> +<p>Rationale for some of the requirements and guidelines follows.</p> +<hr> +<h3><a name="Exception-specification">Exception-specification</a> rationale</h3> +<p>Exception specifications [ISO 15.4] are sometimes coded to indicate what +exceptions may be thrown, or because the programmer hopes they will improved +performance. But consider the following member from a smart pointer:</p> +<pre> T& operator*() const throw() { return *ptr; }</pre> +<p>This function calls no other functions; it only manipulates fundamental data +types like pointers Therefore, no runtime behavior of the +exception-specification can ever be invoked. The function is completely +exposed to the compiler; indeed it is declared inline Therefore, a smart +compiler can easily deduce that the functions are incapable of throwing +exceptions, and make the same optimizations it would have made based on the +empty exception-specification. A "dumb" compiler, however, may make +all kinds of pessimizations.</p> +<p>For example, some compilers turn off inlining if there is an +exception-specification. Some compilers add try/catch blocks. Such +pessimizations can be a performance disaster which makes the code unusable in +practical applications.</p> +<p>Although initially appealing, an exception-specification tends to have +consequences that require <b>very</b> careful thought to understand. The biggest +problem with exception-specifications is that programmers use them as though +they have the effect the programmer would like, instead of the effect they +actually have.</p> +<p>A non-inline function is the one place a "throws nothing" +exception-specification may have some benefit with some compilers.</p> +<hr> +<h3><a name="Naming">Naming</a> conventions rationale</h3> +<p>The C++ standard committee's Library Working Group discussed this issue in +detail, and over a long period of time. The discussion was repeated again in +early boost postings. A short summary:</p> +<ul> + <li>Naming conventions are contentious, and although several are widely used, + no one style predominates. + </li> + <li>Given the intent to propose portions of boost for the next revision of the + C++ standard library, boost decided to follow the standard library's + conventions. + </li> + <li>Once a library settles on a particular convention, a vast majority of + stakeholders want that style to be consistently used. + </li> +</ul> +<hr> +<h3>Source <a name="code fonts">code fonts</a> rationale</h3> +<p>Dave Abrahams comments: An important purpose (I daresay the primary purpose) +of source code is communication: the documentation of intent. This is a doubly +important goal for boost, I think. Using a fixed-width font allows us to +communicate with more people, in more ways (diagrams are possible) right there +in the source. Code written for fixed-width fonts using spaces will read +reasonably well when viewed with a variable-width font, and as far as I can tell +every editor supporting variable-width fonts also supports fixed width. I don't +think the converse is true.</p> +<hr> +<h3><a name="Rationale">Rationale</a> rationale</h3> +<p>Rationale is defined as "The fundamental reasons for something; +basis." by the American Heritage Dictionary.</p> +<p>Beman Dawes comments: Failure to supply contemporaneous rationale for +design decisions is a major defect in many software projects. Lack of accurate +rationale causes issues to revisited endlessly, causes maintenance bugs when a +maintainer changes something without realizing it was done a certain way for +some purpose, and shortens the useful lifetime of software.</p> +<p>Rationale is fairly easy to provide at the time decisions are made, but very +hard to accurately recover even a short time later.</p> +<hr> +<h3><a name="Acknowledgements">Acknowledgements</a> rationale</h3> +<p>As a library matures, it almost always accumulates improvements suggested to +the authors by other boost members. It is a part of the culture of +boost.org to acknowledge such contributions, identifying the person making the +suggestion. Major contributions are usually acknowledged in the +documentation, while minor fixes are often mentioned in comments within the code +itself.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->24 April, 2001<!--webbot bot="Timestamp" endspan i-checksum="29814" --></p> + +</body> + +</html> diff --git a/more/library_reuse.htm b/more/library_reuse.htm new file mode 100644 index 0000000000..35efd133ca --- /dev/null +++ b/more/library_reuse.htm @@ -0,0 +1,72 @@ +<html> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Boost Library Reuse</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> + +<h1>Boost Library reuse: cost versus benefit trade-offs</h1> +<p>A Boost library <b>should not</b> use libraries other than Boost or the C++ +Standard Library.</p> +<p>A Boost library <b>should</b> use other Boost Libraries or the C++ Standard +Library, but only when the benefits outweigh the costs. </p> +<p>The benefits of using components from other libraries may include clearer, +more understandable code, reduced development and maintenance costs, and the +assurance which comes from reusing well-known and trusted building blocks.</p> +<p>The costs may include undesirable coupling between components, and added +compilation and runtime costs. If the interface to the additional +component is complex, using it may make code less readable, and thus actually +increase development and maintenance costs.</p> +<p>Negative effects of coupling become obvious when one library uses a second +library which uses a third, and so on. The worst form of coupling requires the +user understand each of the coupled libraries. Coupling may also reduce the +portability of a library - even in case when all used libraries are +self-sufficient (see example of questionable usage of <iostream> library +below).</p> +<p><b>Example where another boost component should certainly be used:</b> +boost::noncopyable (in <a href="../boost/utility.hpp">boost/utility.hpp</a>) has +considerable benefits; it simplifies code, improves readability, and signals +intent. Costs are low as coupling is limited; noncopyable itself +uses no other classes and its header includes only the lightweight headers +<boost/config.hpp> and <cstddef>. There are no runtime costs +at all. With costs so low and benefits so high, other boost libraries should use +boost::noncopyable when the need arises except in exceptional circumstances.</p> +<p><b>Example where a standard library component might possibly be used:</b> +Providing diagnostic output as a debugging aid can be a nice feature for a +library. Yet using Standard Library <iostream> can involves a lot of +additional cost, particularly if <iostream> is unlikely to be use +elsewhere in the application. In certain GUI or embedded applications, +coupling to <iostream> would be a disqualification. +Consider redesign of the boost library in question so that the user supplies the +diagnostic output mechanism.</p> +<p><b>Example where another boost component should not be used:</b> The +boost dir_it library has considerable coupling and runtime costs, not to mention +portability issues for unsupported operating systems. While completely +appropriate when directory iteration is required, it would not be reasonable for +another boost library to use dir_it just to check that a file is available +before opening. C++ Standard Library file open functionality does this at +lower cost. Don't use dir_it just for the sake of using a boost library.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->06 February 2001<!--webbot bot="Timestamp" endspan i-checksum="40613" --></p> +<p> </p> +<p> </p> + +</body> + +</html> diff --git a/more/microsoft_vcpp.html b/more/microsoft_vcpp.html new file mode 100644 index 0000000000..7f7acbbafe --- /dev/null +++ b/more/microsoft_vcpp.html @@ -0,0 +1,307 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>Portability Hints: Microsoft Visual C++ 6.0 SP4</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> + +<p> + +<h1>Portability Hints: Microsoft Visual C++ 6.0 SP4</h1> + +Similar to the +<a href="borland_cpp.html">portability hints for Borland C++</a>, +this page provides hints on some language features of the Microsoft Visual C++ +version 6.0 service pack 4 compiler. A list of +acknowledged deficiencies can be found at the +<a href="http://support.microsoft.com/support/kb/articles/q243/4/51.asp">Microsoft support site</a>. +<p> + +Each entry in the following list describes a particular issue, +complete with sample source code to demonstrate the effect. +Most sample code herein has been verified to compile with gcc 2.95.2 +and Comeau C++ 4.2.44. + + +<h2>Preprocessor symbol</h2> + +The preprocessor symbol <code>_MSC_VER</code> is defined for all +Microsoft C++ compilers. Its value is the internal version number of the +compiler interpreted as a decimal number. Since a few other compilers +also define this symbol, boost provides the symbol +<code>BOOST_MSVC</code>, which is defined in +<a href="../boost/config.hpp">boost/config.hpp</a> +to the value of _MSC_VER if and only if the compiler is really +Microsoft Visual C++. + +The following table lists some known values. +<p> + +<table border="1"> +<tr> +<th>Compiler</th> +<th><code>BOOST_MSVC</code> value</th> +</tr> + +<tr> +<td>Microsoft Visual C++ 6.0 (up to SP4)</td> +<td>1200</td> +</tr> + +</table> + + +<h2>Core Language</h2> + +<h3>[chained using] Chaining <code>using</code>-declarations</h3> + +Chaining <code>using</code>-declarations does not work. +<pre> +void f(); + +namespace N { + using ::f; +} + +void g() +{ + using N::f; // C2873: 'f': the symbol cannot be used in a using-declaration +} +</pre> + + +<h3>[explicit-instantiation] Explicit function template +instantiation</h3> + +Trying to explicitly instantiate a function template leads to the +wrong function being called silently. + +<pre> +#include <stdio.h> + +template<class T> +void f() +{ + printf("%d\n", sizeof(T)); +} + +int main() +{ + f<double>(); // output: "1" + f<char>(); // output: "1" + return 0; +} +</pre> + + +<h3>[for-scoping] Scopes of definitions in for-loops</h3> + +The scope of variable definitions in <code>for</code> loops should be +local to the loop's body, but it is instead local to the enclosing +block. + + +<pre> +int main() +{ + for(int i = 0; i < 5; ++i) + ; + for(int i = 0; i < 5; ++i) // C2374: 'i': Redefinition; multiple initialization + ; + return 0; +} +</pre> + +<strong>Workaround:</strong> Enclose the offending <code>for</code> +loops in another pair of curly braces. + + +<h3>[inclass-member-init] In-class member initialization</h3> + +In-class member initialization, required to implement a +Standard-conforming <code>std::numeric_limits</code> template, does +not work. + +<pre> +struct A +{ + static const int i = 5; // "invalid syntax for pure virtual method" +}; +</pre> + +<strong>Workaround:</strong> Either use an enum (which has incorrect +type, but can be used in compile-time constant expressions), or define +the value out-of-line (which allows for the correct type, but prohibits +using the constant in compile-time constant expressions). See +<a href="int_const_guidelines.htm">Coding Guidelines for Integral Constant Expressions</a> +for guidelines how to define member constants portably in boost +libraries. + + +<h3>[koenig-lookup] Argument-dependent lookup</h3> + +Argument-dependent lookup, also called Koenig lookup, works for +overloaded operators, but not for ordinary functions. No +additional namespaces induced from the argument types seem to be +considered. + +<pre> +namespace N { + struct A {}; + void f(A); +} + +void g() +{ + N::A a; + f(a); // 'f': undeclared identifier +} +</pre> + + +<h3>[template-friend] Templates as friends</h3> + +A Template cannot be declared a friend of a class. + +<pre> +template<class T> +struct A {}; + +struct B +{ + template<class T> + friend struct A; // "syntax error" +}; +</pre> + + +<h3>[member-template-outofline] Out-of-line definitions of member +templates</h3> + +Defining member templates outside their enclosing class does not work. + +<pre> +template<class T> +struct A +{ + template<class U> + void f(); +}; + +template<class T> +template<class U> // "syntax error" +void A<T>::f() // "T: undeclared identifier" +{ +} +</pre> + +<strong>Workaround:</strong> Define member templates in-line within +their enclosing class. + + +<h3>[partial-spec] Partial specialization</h3> + +Partial specialization of class templates does not work. + +<pre> +template<class T> +struct A {}; + +template<class T> +struct B {}; + +template<class T> +struct A<B<T> > {}; // template class was already defined as a non-template +</pre> + +<strong>Workaround:</strong> In some situations where interface +does not matter, class member templates can simulate partial +specialization. + + +<h3>[template-value] Dependent template value parameters</h3> + +Template value parameters whose type depends on a previous template +parameter provoke an internal compiler error if the correct syntax +(with "typename") is used. + +<pre> +template<class T, typename T::result_type> // C1001: INTERNAL COMPILER ERROR: msc1.cpp, line 1794 +struct B {}; + // (omit "typename" and it compiles) + +</pre> + +<strong>Workaround:</strong> Leave off the "typename" keyword. That makes +the program non-conforming, though. + + +<h3>[wchar_t] <code>wchar_t</code> is not built-in</h3> + +The type <code>wchar_t</code> is not a built-in type. + +<pre> +wchar_t x; // "missing storage class or type identifier" +</pre> + +<strong>Workaround:</strong> When using Microsoft Visual C++, the +header +<a href="../boost/config.hpp">boost/config.hpp</a> +includes <code><cstddef></code>, which defines +<code>wchar_t</code> as a typedef for <code>unsigned +short</code>. Note that this means that the compiler does not regard +<code>wchar_t</code> and <code>unsigned short</code> as distinct +types, as is required by the standard, and so ambiguities may emanate +when overloading on <code>wchar_t</code>. The macro +<code>BOOST_NO_INTRINSIC_WCHAR_T</code> is defined in this situation. + + +<h3>[delete-const-pointer] Deleting <code>const X *</code> does not work</h3> + +Trying to delete a pointer to a cv-qualified type gives an error: +<pre> +void f() +{ + const int *p = new int(5); + delete p; // C2664: cannot convert from "const int *" to "void *" +} +</pre> + +<strong>Workaround:</strong> Define the function +<pre> +inline void operator delete(const void *p) throw() +{ operator delete(const_cast<void*>(p)); } +</pre> +and similar functions for the other cv-qualifier combinations, for +operator delete[], and for the <code>std::nothrow</code> variants. + + + +<h2>Standard Library</h2> + +<h3>[clib-namespace] C library names in global namespace instead of std</h3> +<p>Library names from the <c...> headers are in the global namespace +instead of namespace std.<p><b>Workaround:</b> The header <a href="../libs/config/index.htm">boost/config.hpp</a> +will define BOOST_NO_STDC_NAMESPACE. It can be used as follows: +<pre># ifdef BOOST_NO_STDC_NAMESPACE + namespace std { using ::abs; using ::fabs; } +# endif</pre> +<p>Because std::size_t and std::ptrdiff_t are so commonly used, the workaround +for these is already provided in boost/config.hpp.<p> +<hr> + +2001-05-04 <a href="../people/jens_maurer.htm">Jens Maurer</a> +</body> +</html> diff --git a/more/regression.html b/more/regression.html new file mode 100644 index 0000000000..94cb8867f1 --- /dev/null +++ b/more/regression.html @@ -0,0 +1,256 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + +<title>Boost Internal Regression Test Suite</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="../more/faq.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="../more/index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> + + +<h1>Boost Internal Regression Test Suite</h1> + +Boost's internal regression test suite produces the +<a href="../status/compiler_status.html">compiler status tables</a>. +<p>Although not ordinarily run by Boost library users, it is documented here for +the benefit of Boost developers, and for Boost users porting to a new platform.</p> + +<h2>Requirements</h2> + +The test suite has been designed to meet to the following requirements. +<ul> +<li>Pure ISO C++, no tools required except a C++ compiler. +<li>Support for tests which expect an error +<li>Flexible configuration +<li>HTML output +</ul> + +These requirements rule out any script-based approach such as dejagnu +(requires Tcl and expect) or even shell scripts. + + +<h2>Running Regression Tests</h2> + +The implementation is provided in a single source file named +<a href="../status/regression.cpp">regression.cpp</a>. +<p> +You should be able to compile and link this file using whatever C++ +compiler is at your disposition. However, you may need to configure +both the compiler and the standard library to use "strict" ISO +compliance mode. Also, you need to extend the search path for include +files with the main boost directory so that the header file +<a href="../boost/config.hpp">boost/config.hpp</a> +can be found. This header file is required to work around compiler +deficiencies. +<p> + +You can then start the resulting executable to run regression tests. +By default, the regression test program reads the file "compiler.cfg" +in the current directory to determine the list of compilers and their +invocation syntax. After that, it reads the file "regression.cfg" in +the current directory to determine the regression tests to run. The +results of the regression tests are written in an HTML formatted text +file. This file is by default named "cs-OS.html" in the current +directory, where "OS" is a placeholder for the name of the operating +system (e.g., "linux" or "win32"). +<p> + +To generate the +<a href="../status/compiler_status.html">compiler status tables</a>, +boost uses the files +<a href="../status/compiler.cfg">status/compiler.cfg</a> +and +<a href="../status/regression.cfg">status/regression.cfg</a>. +<p> + +The regression test program accepts some command-line options to alter +its behavior. +<p> +<table border="1"> + +<tr> +<td>-h <em>or</em> --help</td> +<td>prints a help message +</tr> + +<tr> +<td>--config <em>file</em></td> +<td>Use <em>file</em> instead of "compiler.cfg" as the compiler +configuration file. This allows for private compiler setups.</td> +</tr> + +<tr> +<td>--tests <em>file</em></td> +<td>Use <em>file</em> instead of "regression.cfg" as the tests +configuration file. This allows individual libraries to specify +additional tests not to be published in the main +<a href="../status/compiler_status.html">compiler status tables</a>. +</td> +</tr> + +<tr> +<td>--boost <em>path</em></td> +<td>Use <em>path</em> as the filesystem path to the main boost +directory. The default is "..", i.e. the parent directory.</td> +</tr> + +<tr> +<td>--output <em>file</em><br>-o <em>file</em></td> +<td>Write the HTML output to <em>file</em> instead of the default +"cs-OS.html".</td> +</tr> + +<tr> +<td>--compiler <em>name</em></td> +<td>Run the tests only with compiler <em>name</em>. The <em>name</em> +must be defined in the second line of an applicable compiler +configuration (see below). The default is to run the tests with all +compilers suitable for the platform.</td> +</tr> + +<tr> +<td>--diff</td> +<td>Read the HTML output file before writing it. In the HTML output, +highlight differences in test outcomes compared to the previous +run.</td> +</tr> + +<tr> +<td><em>test</em></td> +<td>Run only the named test. The syntax is the same as in the +configuration file (see below).</td> +</tr> +</table> +<p> +When running only a selected test, you must also provide an alternate +HTML output filename with "--output" so that the full test output is +not accidentally overwritten. +<p> + +You should redirect the output (<code>std::cout</code>) and error +(<code>std::cerr</code>) channels to a suitable log file for later +inspection. + + +<h2>Configuration Files</h2> + +In both configuration files, single-line comments starting with "//" +at the leftmost column are ignored. + +<h3>Compiler Configuration</h3> + +The compiler configuration file can contain descriptions for an +arbitrary number of compilers. Each compiler is configured by a block +of six consecutive text lines. +<ol> +<li>Name of the operating system for which the entry is applicable +(e.g., "linux" or "win32"). +<li>Name of the compiler; should be unique within one operating +system. The name of the compiler should not contain the version +number, because it is expected that regression tests are always run +with the most recent compiler version available. +<li>Name and version number of the compiler. This is printed on +<code>std::cout</code> prior to running a test with that compiler. +<li>Command-line invocation of the compiler to compile a single source +file to an object file. +<li>Command-line invocation of the compiler to compile a single source +file to an executable. +<li>Identification of the compiler for inclusion in the HTML output; +may contain HTML tags such as <br>. +</ol> + +The two command-lines are subject to the following substitutions: +<ul> +<li>Any string starting with a dollar symbol "$", then containing an +arbitrary number of underscores, digits, or uppercase letters, is +replaced by the value of the associated environment variable. +<li>%include is replaced by the path given by the "--boost" command +line option (".." by default). This should be used to extend the +search path of your compiler so that the boost header files are found. +<li>%source is the name of the source file to be compiled, qualified +with the path given by the "--boost" command-line option (".." by +default). +</ul> + + +<h3>Test Configuration</h3> + +The test configuration file can contain descriptions for an arbitrary +number of tests. Each test is described by a single line. The first +word (up to the first space) is the type of the test, the next word +gives the filename of the test relative the directory to be given by the +"--boost" command-line option. Optionally, additional words are +passed on as command-line arguments when the test is executed (only +for types "run" and "run-fail"). In these arguments, "%boost" is +replaced by the path given by the "--boost" command-line option (".." +by default). +<p> + +The following test types are available: +<ul> +<li>compile: The given test file should compile successfully. +Otherwise, the test fails. +<li>compile-fail: The given test file should not compile successfully, +but instead the compiler should give an error message. If the test +does compile successfully, the test fails. +<li>link: The given test file should compile and link successfully. +Otherwise, the test fails. In particular, a <code>main</code> +function must be present in the test file. +<li>link-fail: The given test file should not compile and link +successfully. It is not specified whether the compile or the link +should not succeed. If the test does compile and link successfully, +the test fails. +<li>run: The given test file should compile and link successfully. +After that, the resulting executable is invoked and should return a +zero exit code. If any of these steps fail, the test fails. +<li>run-fail: The given test file is compiled, linked, and, if an +executable was successfully generated, it is invoked. Either +compiling or linking should fail or the resulting executable should +return a non-zero exit code. If compiling and linking succeeds and +the resulting executable returns a zero exit code, the test fails. +</ul> + +<h2>Adapting for a New Platform</h2> + +In order to adapt the regression test suite for a new platform, a few +changes to the <a href="../status/regression.cpp">regression.cpp</a> +are required. + +<ul> +<li>Add an appropriate check for your platform in +<code>get_host()</code> and return a unique string identifying the +platform (this string is used to filter the compile configuration +file). +<li>Verify that <code>get_system_configuration()</code> is +appropriately defined for your platform. For a Unix platform, it most +likely is. The function may return a verbose HTML string describing +the platform. +</ul> + +You also need to configure the compilers available on your platform in +"compiler.cfg" as described above. +<p>You may need to add an entry for the compiler to <a href="../boost/config.hpp">boost/config.hpp</a>, +but only if entries for the compiler is not already present, and the compiler +doesn't fully conform to the ISO C++ Standard.</p> +<h2>History</h2> +<p>The regression.cpp test program was contributed +by Jens Maurer, generalizing and improving an earlier program by Beman Dawes.</p> + +<hr> +2001-01-30<br> +<a href="../people/jens_maurer.htm">Jens Maurer</a> + +</body> +</html> diff --git a/more/submission_process.htm b/more/submission_process.htm new file mode 100644 index 0000000000..658792dcc5 --- /dev/null +++ b/more/submission_process.htm @@ -0,0 +1,127 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Boost Library Submission Process</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Boost Library Submission Process</h1> +<p>This page describes the process of getting a library accepted by Boost. +The process is still evolving, so if you have suggestions for improvement by all +means post them on the mailing list.</p> +<p>See the <a href="lib_guide.htm">Boost Library Requirements and Guidelines</a> +page for issues of content.</p> +<h3><b>Steps for getting a library accepted by Boost:</b></h3> +<ul> + <li><a href="#Learn">Learn about Boost</a>.</li> + <li><a href="#interest">Determine interest</a>.</li> + <li><a href="#Preliminary">Preliminary submission</a>.</li> + <li><a href="#Refinement">Refinement</a>.</li> + <li><a href="#Submission">Submission for review</a>.</li> + <li><a href="#Review">Formal Review</a>.</li> + <li><a href="#site posting">Web site posting</a>.</li> + <li><a href="#People">People page.</a></li> + <li><a href="#Lifecycle">Lifecycle</a>.</li> +</ul> +<h2><a name="Learn">Learn</a> about Boost</h2> +<p>Subscribe to the <a href="../index.htm#Mailing List">mailing list</a> for a +while, or look through the <a href="http://www.yahoogroups.com/messages/boost">archives</a>. +Click around the <a href="../index.htm">web site</a>. Understand the <a href="lib_guide.htm">Requirements</a>. +Read the rest of this page to learn about the process. Otherwise, you will +just end up wasting everyone's time.</p> +<p>There is a culture associated with Boost, aimed at encouraging high quality +libraries by a process of discussion and refinement.</p> +<p>If what you really want is a site that will just post your library without +even looking at it, you should go elsewhere.</p> +<h2>Determine <a name="interest">interest</a></h2> +<p>Potential library submitters should use the <a href="../index.htm#Mailing List">mailing +list</a> as a forum to gauge interest a possible submission.</p> +<p>A message might be as simple as "Is there any interest in a library +which solves Traveling Salesperson problems in linear time?"</p> +<p>A bit of further description or snippet of code may be helpful. Messages +should be plain text; not rich text, HTML, etc.</p> +<p>Please don't post lengthy descriptions, documentation, or code to the mailing +list, and no attachments, even small ones. Please post lengthy material in +the YahooGroups boost <a href="http://www.yahoogroups.com/files/boost/">Files section</a> +(formerly called the " vault"). </p> +<h2><a name="Preliminary">Preliminary</a> submission</h2> +<p>If response to an initial query indicates interest, then post the preliminary +submission files in the <a href="http://www.yahoogroups.com/files/boost/">files section</a> of +the Boost YahooGroups web site if you haven't already done so.</p> +<h2><a name="Refinement">Refinement</a></h2> +<p>Discuss, refine, resubmit. Repeat until satisfied.</p> +<p>The exact details of this process varies a lot. Sometimes it is public, +on the mailing list, sometimes a lot of discussion happens in private +emails. For some libraries the process is over quickly, for others it goes +on for months. It's often challenging, and sometimes leads off in +completely unexpected directions. </p> +<p>The <a href="http://www.yahoogroups.com/messages/boost">archive</a> of past +messages is one way to see how this process worked for other boost +libraries.</p> +<h2><a name="Submission">Submission</a> for review </h2> +<p>All of the files which make up the library should be combined and compressed +into a single submission file using the .zip format. Free encoders +and decoders for this format running on many different platforms are available +at the <a href="http://www.info-zip.org/pub/infozip/">Info-ZIP</a> web site, which +includes a FAQ and much other useful information about the .zip format. Many +commercial compressor-archiver utilities also support this format.</p> +<p>The submission file should contain material as if on the +boost.org web site. The closer the submission file mirrors the final <a href="lib_guide.htm#Directory structure">directory +structure</a> and format of the web site, the better. +<p>Like a preliminary submission, post the final submission .zip file in the <a href="http://www.yahoogroups.com/files/boost/">files section</a> of +the Boost YahooGroups web site +<h2>Formal <a name="Review">Review</a></h2> +<p>Before asking for formal review, your submission should be posted in the +Boost files/vault. Please verify that your submission compiles +and runs under at least two compilers. This flushes out obvious +portability problems. If you don't have access to a second compiler, ask +for help on the Boost mailing list.</p> +<p>Once a library author feels a submission (which presumably is now in the +files/vault) has matured enough for formal review, the author sends a message +requesting a formal review to the mailing list. Please use a subject in +the form "Review Request: library" where <i>library</i> is replaced by +the library name.</p> +<p>See <a href="formal_review_process.htm">Formal Review Process</a> for +details.</p> +<p>Formal Review schedules are posted on the boost mailing list.. </p> +<h2>Boost <a name="site posting">site posting</a> after acceptance</h2> +<p>There are two ways that files are posted on the boost web site:</p> +<ul> + <li>Direct update of the boost CVS repository. This requires write + access, and is primarily used for larger libraries, or for libraries + maintained by very active boost developers.</li> + <li>Packaging all files into a submission file (same content as for submission + for review), and emailing it to the Boost webmaster <a href="mailto:bdawes@acm.org">bdawes@acm.org</a>.</li> +</ul> +<h2><a name="People">People</a> page</h2> +<p>If the boost.org web site doesn't already have your capsule biography +and picture (optional, with not-too-serious pictures preferred), please +send them to the Boost webmaster.. It is +up to you as to whether or not the biography includes your email address or +other contact information. The preferred picture format is .jpg, but other +common formats are acceptable. The preferred image size is 500x375 but the +webmaster has photo editing software and can do the image preparation if +necessary.</p> +<h2><a name="Lifecycle">Lifecycle</a></h2> +<p>Libraries are software; they loose their value over time if not +maintained. Details still hazy.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->24 April, 2001<!--webbot bot="Timestamp" endspan i-checksum="29814" --></p> + +</body> + +</html> diff --git a/more/test_policy.htm b/more/test_policy.htm new file mode 100644 index 0000000000..e39b4aa3f5 --- /dev/null +++ b/more/test_policy.htm @@ -0,0 +1,93 @@ +<html> + +<head> +<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> +<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> +<meta name="ProgId" content="FrontPage.Editor.Document"> +<title>Boost Test Policies and Protocols</title> +</head> + +<body bgcolor="#FFFFFF" text="#000000"> + +<table border="1" bgcolor="#007F7F" cellpadding="2"> + <tr> + <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> + <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> + <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> + <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> + <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> + <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> + </tr> +</table> +<h1>Boost Test Policies and Protocols</h1> +<p>The Boost libraries are intended to be both reliable and portable. +Every experienced programmer knows that means each library must be tested against a suitable number of test cases, on a wide range of platforms, +and then tested again (regression tested) every time a change is made and before +every release. </p> +<p>"Quality assurance based on a wide range of targeted tests" as one +of the key answers to <a href="http://oldwww.comlab.ox.ac.uk/oucl/people/tony.hoare.html">C.A.R +Hoare's</a> question <a href="http://oldwww.comlab.ox.ac.uk/oucl/users/tony.hoare/icse18.html">"How +did software get so reliable without proof."</a></p> +<h2>Regression test</h2> +<p>Boost uses an automatic <a href="regression.html"> regression test suite</a> which generates HTML <a href="../status/compiler_status.html#Compiler Status Tables">compiler +status tables</a>.</p> +<h2>Test Policy</h2> +<h3>Required</h3> +<ul> + <li>Every Boost library should supply one or more suitable test programs to be + exercised by the Boost <a href="regression.html"> regression test suite</a>. In addition to + the usual compile-link-run tests expecting successful completion, + compile-only or compile-and-link-only tests may be performed, and success + for the test may be defined as failure of the steps.</li> + <li>Test program execution must report errors by returning a non-zero value. They + may also write to stdout or stderr, but that output should be relatively + brief. Regardless of other output, a non-zero return value is the only + way the regression test framework will recognize an error has + occurred. Note that test programs to be included in the status tables must + compile, link, and run quickly since the tests are executed many, many, + times.</li> + <li>Libraries with time consuming tests should be divided into a + fast-execution basic test program for the status tables, and a separate + full-coverage test program for exhaustive test cases. The basic test + should concentrate on compilation issues so that the status tables + accurately reflect the library's likelihood of correct compilation on a + platform.</li> + <li>If for any reason the usual test policies do not apply to a particular + library, an alternate test strategy must be implemented. </li> +</ul> +<h3>Optional</h3> +<ul> + <li>Use the Boost Test Library for the construction of simple tests.</li> + <li>[Planned] Use the Boost Unit Test Library for the construction of more complex tests + and test suites.</li> + <li>The Boost Program Execution Library is also available for very simple + tests, but the Boost Test Library is much preferred even for very simple + tests.</li> +</ul> +<h2>Suggested Protocol for Fixing Bugs or Adding Features.</h2> +<ul> + <li>First, add regression test cases that detects the bug or tests the + feature. Sometimes adding one case suggests similar untested cases, and they + are added too.</li> + <li>Second, for bugs, run the regression test and verify that the bug is now + detected.</li> + <li>Third, then, and only then, fix the bug or add the feature.</li> + <li>Finally, rerun the full regression tests - sometimes the change breaks + something else.</li> +</ul> +<h2>History</h2> +<p>The current regression test program was developed by Jens Maurer in December, +2000. The original regression test concept and program, including the automatic +generation of HTML compiler status tables, was developed by Beman Dawes in June, +2000.</p> +<h2>Acknowledgements</h2> +<p>Written by Beman Dawes. Jens Maurer, Paul Moore, Gary Powell and Jeremy Siek contributed helpful suggestions.</p> +<hr> +<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->10 February, 2001<!--webbot bot="Timestamp" endspan i-checksum="40395" --> +</p> +<p> </p> +<p> </p> + +</body> + +</html> |