Boost logo

Boost-Commit :

From: daniel_james_at_[hidden]
Date: 2007-11-11 14:14:35


Author: danieljames
Date: 2007-11-11 14:14:34 EST (Sun, 11 Nov 2007)
New Revision: 41012
URL: http://svn.boost.org/trac/boost/changeset/41012

Log:
Move several C++ related articles to the new site.

Fixes #1343, #1344, #1347, #1352, #1353.

Added:
   website/public_html/beta/community/committee.html
      - copied, changed from r40993, /trunk/more/cpp_committee_meetings.html
   website/public_html/beta/community/counted_body.html
      - copied, changed from r40993, /trunk/more/count_bdy.htm
   website/public_html/beta/community/error_handling.html
      - copied, changed from r40993, /trunk/more/error_handling.html
   website/public_html/beta/community/exception_safety.html
      - copied, changed from r40993, /trunk/more/generic_exception_safety.html
   website/public_html/beta/community/generic_programming.html
      - copied, changed from r40993, /trunk/more/generic_programming.html
Text files modified:
   website/public_html/beta/common/menu-community.html | 22
   website/public_html/beta/community/committee.html | 308 ++++++---
   website/public_html/beta/community/counted_body.html | 1014 ++++++++++++++++-----------------
   website/public_html/beta/community/error_handling.html | 483 ++++++++-------
   website/public_html/beta/community/exception_safety.html | 1220 +++++++++++++++++++++------------------
   website/public_html/beta/community/generic_programming.html | 722 ++++++++++++-----------
   6 files changed, 2009 insertions(+), 1760 deletions(-)

Modified: website/public_html/beta/common/menu-community.html
==============================================================================
--- website/public_html/beta/common/menu-community.html (original)
+++ website/public_html/beta/common/menu-community.html 2007-11-11 14:14:34 EST (Sun, 11 Nov 2007)
@@ -8,8 +8,26 @@
     <li><a href="/community/groups.html">Groups <span class=
     "link">&gt;</span></a></li>
 
- <li><a href="/community/cpp.html">C++ <span class=
- "link">&gt;</span></a></li>
+ <li>
+ C++ >
+
+ <ul>
+ <li><a href="/community/committee.html">Committee Meetings
+ <span class="link">&gt;</span></a></li>
+
+ <li><a href="/community/generic_programming.html">Generic Progamming
+ Techniques <span class="link">&gt;</span></a></li>
+
+ <li><a href="/community/error_handling.html">Error and Exception
+ Handling <span class="link">&gt;</span></a></li>
+
+ <li><a href="/community/exception_safety.html">Exception-Safety in
+ Generic Components <span class="link">&gt;</span></a></li>
+
+ <li><a href="/community/counted_body.html">Counted Body Techniques
+ <span class="link">&gt;</span></a></li>
+ </ul>
+ </li>
 
     <li><a href="/community/policy.html">Discussion Policy <span class=
     "link">&gt;</span></a></li>

Copied: website/public_html/beta/community/committee.html (from r40993, /trunk/more/cpp_committee_meetings.html)
==============================================================================
--- /trunk/more/cpp_committee_meetings.html (original)
+++ website/public_html/beta/community/committee.html 2007-11-11 14:14:34 EST (Sun, 11 Nov 2007)
@@ -1,125 +1,199 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
 <head>
-<meta http-equiv="Content-Language" content="en-us">
-<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
-<meta name="ProgId" content="FrontPage.Editor.Document">
-<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
-<title>C++ Committee Meetings</title>
+ <title>C++ Committee Meetings</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
+ <link rel="icon" href="/favicon.ico" type="image/ico" />
+ <link rel="stylesheet" type="text/css" href=
+ "/style/section-community.css" />
+ <!--[if IE]> <style type="text/css"> body { behavior: url(/style/csshover.htc); } </style> <![endif]-->
 </head>
 
-<body bgcolor="#FFFFFF">
+<body>
+ <div id="heading">
+ <!--#include virtual="/common/heading.html" -->
+ </div>
 
-<h1>C++ Committee Meeting FAQ for Boost Members</h1>
-<p><b>Who can attend C++ Committee meetings?</b> Members of
-J16 (the INCITS/ANSI committee) or of a WG21 (ISO) member country committee
-(&quot;national body&quot; in
-ISO-speak). <a href="http://www.ncits.org/">
-INCITS</a> has broadened&nbsp; J16 membership requirements so anyone can
-join, regardless of nationality or employer.</p>
-<p>In addition, a small number of &quot;technical experts&quot; who are not committee
-members can also attend meetings. The &quot;technical expert&quot; umbrella is broad enough to cover
-the
-Boost members who attend meetings.</p>
-<p><b>When and where is the next meeting?</b> There are two meetings a year. The
-Fall meeting is usually in North America, and the Spring meeting is usually
-outside North America. See a general
-<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/meetings">list of meeting locations and
-dates</a>. Detailed information about a particular meeting, including hotel
-information, is usually provided in a paper appearing in one of
-mailings for the prior meeting. If there isn't a link to
-it on the <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/meetings">
-Meetings</a> web page, you will have to go to
-the committee's <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/">
-Papers</a> page and search a bit.</p>
-<p><b>Is there a fee for attending meetings?</b> No, but there can be a lot of
-incidental expenses like travel, lodging, and meals, and there is a $US 800 a
-year INCITS fee to become a voting member.</p>
-<p><b>What is the schedule?</b>&nbsp; The meetings start at 9:00AM on
-Monday, and 8:30AM other days, unless otherwise announced. It is best to arrive
-a half-hour early to grab a good seat, some coffee, tea, or donuts, and to say
-hello to people. (There is also a Sunday evening a WG21 administrative meeting,
-which is closed except to delegates from national bodies.)</p>
-<p>The meetings generally end on Friday, although there is discussion of
-extending them one extra day until the next standard ships. The last day the meeting&nbsp; is generally over by 11:00AM. Because
-the last day's meeting is for formal votes only, it is primarily of interest only to
-actual committee
-members.</p>
-<p>Sometimes there are evening technical sessions; the details aren't
-usually available until the Monday morning meeting.&nbsp; There may be a
-reception one evening, and, yes, significant others are
-invited. Again, details usually&nbsp;become available Monday morning.</p>
-<p><b>What actually happens at the meetings?</b> Monday morning an hour or two
-is spent in full committee on administrivia, and then the committee breaks up
-into working groups (Core, Library, and Enhancements). The full committee also
-gets together later in the week to hear working group progress reports.</p>
-<p>The working groups are where most technical activities take place.&nbsp; Each
-active issue that appears on an issues list is discussed, as are papers from the
-mailing. Most issues are non-controversial and disposed of in a few minutes.
-Technical discussions are often led by long-term committee members, often
-referring to past decisions or longstanding working group practice. Sometimes a
-controversy erupts. It takes first-time attendees awhile to understand the
-discussions and how decisions are actually made. The working group chairperson
-moderates.</p>
-<p>Sometimes straw polls are taken. In a straw poll anyone attending can vote,
-in contrast to the formal votes taken by the full committee, where only voting
-members can vote.</p>
-<p>Lunch break is an hour and a half.&nbsp; Informal subgroups often lunch
-together; a lot of technical problems are discussed or actually solved at lunch,
-or later at dinner. In many ways these discussions involving only a few people
-are the most interesting. Sometimes during the regular meetings, a working group
-chair will break off a sub-group to tackle a difficult problem. </p>
-<p><b>Do I have to stay at the main hotel?</b> No, and committee members on
-tight budgets often stay at other, cheaper, hotels. (The main hotels are usually
-chosen because they have large meeting rooms available, and thus tend to be pricey.)
-The advantage of staying at the main hotel is that it is then easier to
-participate in the off-line discussions which can be at least as interesting
-as what actually happens in the scheduled meetings.</p>
-<p><b>What do people wear at meetings?</b>&nbsp; Programmer casual. No neckties
-to be seen. </p>
-<p><b>What should I bring to a meeting?</b> It is almost essential to have a
-laptop computer along. There is a committee LAN with a wiki and Internet connectivity.
-Wireless connectivity has become the norm, although there is usually a wired hub
-or two for those needed wired access.</p>
-<p><b>What should I do to prepare for a meeting?</b> It is helpful to have
-downloaded the mailing or individual papers for the
-meeting, and read any papers you are interested in. Familiarize yourself with
-the issues lists if you haven't done so already. Decide which of the working
-groups you want to attend.</p>
-<p><b>What is a &quot;<a name="Paper">Paper</a>&quot;?</b> An electronic document containing issues,
-proposals, or anything else the committee is interested in. Very little gets
-discussed at a meeting, much less acted upon, unless it is presented in a paper.&nbsp;
-Papers are available
-to anyone. Papers don't just appear randomly; they become available four (lately
-six) times a
-year, before and after each meeting. Committee members often refer to a paper by
-saying what mailing it was in: &quot;See the pre-Redmond mailing.&quot;</p>
-<p><b>What is a &quot;<a name="Mailing">Mailing</a>&quot;?</b> A mailing is the
-set of papers prepared four to six times a year before and after each meeting,
-or between meetings.&nbsp; It
-is physically just a
-.zip or .gz
-archive of
-all the papers for a meeting. Although the mailing's archive file itself is only available to committee members and technical
-experts, the contents (except copies of the standard) are available to the
-general public as individual papers. The ways of ISO are
-inscrutable.</p>
-<p><b>What is a &quot;Reflector&quot;?</b> The committee's mailing lists are
-called &quot;reflectors&quot;. There are a number of them; &quot;all&quot;, &quot;core&quot;, &quot;lib&quot;, and &quot;ext&quot;
-are the main ones. As a courtesy, Boost technical experts can be added to
-committee reflectors at the request of a committee member. </p>
-<hr>
-<p>Revised
-<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%B %d, %Y" startspan -->April 17, 2005<!--webbot bot="Timestamp" endspan i-checksum="17669" --></p>
-<p>© Copyright Beman Dawes, 2002</p>
-<p>
- Distributed under the Boost Software License, Version 1.0. (See
- accompanying file LICENSE_1_0.txt or copy
- at <a href=
- "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt>)
-</p>
+ <div id="body">
+ <div id="body-inner">
+ <div id="content">
+ <div class="section" id="intro">
+ <div class="section-0">
+ <div class="section-title">
+ <h1>C++ Committee Meetings</h1>
+ </div>
 
-</body>
+ <div class="section-body">
+ <h1>C++ Committee Meeting FAQ for Boost Members</h1>
+
+ <p><strong>Who can attend C++ Committee meetings?</strong>
+ Members of J16 (the INCITS/ANSI committee) or of a WG21 (ISO)
+ member country committee ("national body" in ISO-speak).
+
INCITS has broadened J16
+ membership requirements so anyone can join, regardless of
+ nationality or employer.</p>
+
+ <p>In addition, a small number of "technical experts" who are
+ not committee members can also attend meetings. The "technical
+ expert" umbrella is broad enough to cover the Boost members who
+ attend meetings.</p>
+
+ <p><strong>When and where is the next meeting?</strong> There
+ are two meetings a year. The Fall meeting is usually in North
+ America, and the Spring meeting is usually outside North
+ America. See a general <a href=
+ "http://www.open-std.org/jtc1/sc22/wg21/docs/meetings">list of
+ meeting locations and dates</a>. Detailed information about a
+ particular meeting, including hotel information, is usually
+ provided in a paper appearing in one of <a href=
+ "#Mailing">mailings</a> for the prior meeting. If there isn't a
+ link to it on the <a href=
+ "http://www.open-std.org/jtc1/sc22/wg21/docs/meetings">Meetings</a>
+ web page, you will have to go to the committee's <a href=
+ "http://www.open-std.org/jtc1/sc22/wg21/docs/papers/">Papers</a>
+ page and search a bit.</p>
+
+ <p><strong>Is there a fee for attending meetings?</strong> No,
+ but there can be a lot of incidental expenses like travel,
+ lodging, and meals, and there is a $US 800 a year INCITS fee to
+ become a voting member.</p>
+
+ <p><strong>What is the schedule?</strong> The meetings start at
+ 9:00AM on Monday, and 8:30AM other days, unless otherwise
+ announced. It is best to arrive a half-hour early to grab a
+ good seat, some coffee, tea, or donuts, and to say hello to
+ people. (There is also a Sunday evening a WG21 administrative
+ meeting, which is closed except to delegates from national
+ bodies.)</p>
+
+ <p>The meetings generally end on Friday, although there is
+ discussion of extending them one extra day until the next
+ standard ships. The last day the meeting is generally over by
+ 11:00AM. Because the last day's meeting is for formal votes
+ only, it is primarily of interest only to actual committee
+ members.</p>
+
+ <p>Sometimes there are evening technical sessions; the details
+ aren't usually available until the Monday morning meeting.
+ There may be a reception one evening, and, yes, significant
+ others are invited. Again, details usually become available
+ Monday morning.</p>
+
+ <p><strong>What actually happens at the meetings?</strong>
+ Monday morning an hour or two is spent in full committee on
+ administrivia, and then the committee breaks up into working
+ groups (Core, Library, and Enhancements). The full committee
+ also gets together later in the week to hear working group
+ progress reports.</p>
+
+ <p>The working groups are where most technical activities take
+ place. Each active issue that appears on an issues list is
+ discussed, as are papers from the mailing. Most issues are
+ non-controversial and disposed of in a few minutes. Technical
+ discussions are often led by long-term committee members, often
+ referring to past decisions or longstanding working group
+ practice. Sometimes a controversy erupts. It takes first-time
+ attendees awhile to understand the discussions and how
+ decisions are actually made. The working group chairperson
+ moderates.</p>
+
+ <p>Sometimes straw polls are taken. In a straw poll anyone
+ attending can vote, in contrast to the formal votes taken by
+ the full committee, where only voting members can vote.</p>
+
+ <p>Lunch break is an hour and a half. Informal subgroups often
+ lunch together; a lot of technical problems are discussed or
+ actually solved at lunch, or later at dinner. In many ways
+ these discussions involving only a few people are the most
+ interesting. Sometimes during the regular meetings, a working
+ group chair will break off a sub-group to tackle a difficult
+ problem.</p>
+
+ <p><strong>Do I have to stay at the main hotel?</strong> No,
+ and committee members on tight budgets often stay at other,
+ cheaper, hotels. (The main hotels are usually chosen because
+ they have large meeting rooms available, and thus tend to be
+ pricey.) The advantage of staying at the main hotel is that it
+ is then easier to participate in the off-line discussions which
+ can be at least as interesting as what actually happens in the
+ scheduled meetings.</p>
 
+ <p><strong>What do people wear at meetings?</strong> Programmer
+ casual. No neckties to be seen.</p>
+
+ <p><strong>What should I bring to a meeting?</strong> It is
+ almost essential to have a laptop computer along. There is a
+ committee LAN with a wiki and Internet connectivity. Wireless
+ connectivity has become the norm, although there is usually a
+ wired hub or two for those needed wired access.</p>
+
+ <p><strong>What should I do to prepare for a meeting?</strong>
+ It is helpful to have downloaded the mailing or individual
+ papers for the meeting, and read any papers you are interested
+ in. Familiarize yourself with the issues lists if you haven't
+ done so already. Decide which of the working groups you want to
+ attend.</p>
+
+ <p><strong>What is a "<a name="Paper" id=
+ "Paper">Paper</a>"?</strong> An electronic document containing
+ issues, proposals, or anything else the committee is interested
+ in. Very little gets discussed at a meeting, much less acted
+ upon, unless it is presented in a paper. <a href=
+ "http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/">Papers are
+ available</a> to anyone. Papers don't just appear randomly;
+ they become available four (lately six) times a year, before
+ and after each meeting. Committee members often refer to a
+ paper by saying what mailing it was in: "See the pre-Redmond
+ mailing."</p>
+
+ <p><strong>What is a "<a name="Mailing" id=
+ "Mailing">Mailing</a>"?</strong> A mailing is the set of papers
+ prepared four to six times a year before and after each
+ meeting, or between meetings. It is physically just a <a href=
+ "http://www.open-std.org/jtc1/sc22/wg21/docs/mailings/">.zip or
+ .gz</a> archive of all the papers for a meeting. Although the
+ mailing's archive file itself is only available to committee
+ members and technical experts, the contents (except copies of
+ the standard) are available to the general public as individual
+ papers. The ways of ISO are inscrutable.</p>
+
+ <p><strong>What is a "Reflector"?</strong> The committee's
+ mailing lists are called "reflectors". There are a number of
+ them; "all", "core", "lib", and "ext" are the main ones. As a
+ courtesy, Boost technical experts can be added to committee
+ reflectors at the request of a committee member.</p>
+ </div>
+ </div>
+ </div>
+ </div>
+
+ <div id="sidebar">
+ <!--#include virtual="/common/sidebar-common.html" -->
+ <!--#include virtual="/common/sidebar-community.html" -->
+ </div>
+
+ <div class="clear"></div>
+ </div>
+ </div>
+
+ <div id="footer">
+ <div id="footer-left">
+ <div id="revised">
+ <p>Revised $Date$</p>
+ </div>
+
+ <div id="copyright">
+ <p>Copyright Beman Dawes 2002.</p>
+ </div><!--#include virtual="/common/footer-license.html" -->
+ </div>
+
+ <div id="footer-right">
+ <!--#include virtual="/common/footer-banners.html" -->
+ </div>
+
+ <div class="clear"></div>
+ </div>
+</body>
 </html>

Copied: website/public_html/beta/community/counted_body.html (from r40993, /trunk/more/count_bdy.htm)
==============================================================================
--- /trunk/more/count_bdy.htm (original)
+++ website/public_html/beta/community/counted_body.html 2007-11-11 14:14:34 EST (Sun, 11 Nov 2007)
@@ -1,313 +1,307 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 
-<html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
 <head>
- <meta http-equiv="Content-Language" content="en-us">
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
- <meta name="GENERATOR" content="Microsoft FrontPage 6.0">
- <meta name="Author" content="Kevlin Henney">
- <meta name="KeyWords" content=
- "C++, Reference Counting, Advanced Techniques, Smart Pointers, Patterns">
-
   <title>Counted Body Techniques</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
+ <link rel="icon" href="/favicon.ico" type="image/ico" />
+ <link rel="stylesheet" type="text/css" href=
+ "/style/section-community.css" />
+ <!--[if IE]> <style type="text/css"> body { behavior: url(/style/csshover.htc); } </style> <![endif]-->
 </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">Kevlin Henney<br></font>
- (<a href=
- "mailto:kevlin_at_[hidden]">kevlin_at_[hidden]</a>, <a href=
- "mailto:khenney_at_[hidden]">khenney_at_[hidden]</a>)</b></p>
- </center>
-
- <div style="margin-left: 2em">
- <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>
- </div>
- <hr width="100%">
-
- <h2>And then there were none...</h2>
-
- <div style="margin-left: 2em">
- <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 &amp;
- Vlissides, Addison-Wesley, <font size="-1">ISBN</font> 0-201-63361-2]. The
- intent is given as</p>
-
- <div style="margin-left: 2em">
- <p><i>Provide a surrogate or placeholder for another object to control
- access to it.</i></p>
- </div>
-
- <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>
- </div>
- <hr width="100%">
-
- <h2>Attached vs detached</h2>
-
- <div style="margin-left: 2em">
- <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>
- </div>
- <hr width="100%">
-
- <h2>A requirements based approach</h2>
-
- <div style="margin-left: 2em">
- <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" summary="">
- <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 &gt; #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" summary="">
- <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>
+<body>
+ <div id="heading">
+ <!--#include virtual="/common/heading.html" -->
   </div>
- <hr width="100%">
 
- <h2>Getting smart</h2>
-
- <div style="margin-left: 2em">
- <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>
-
- <div style="margin-left: 2em">
- <pre>
-<tt>template&lt;typename countable_type&gt;
+ <div id="body">
+ <div id="body-inner">
+ <div id="content">
+ <div class="section" id="intro">
+ <div class="section-0">
+ <div class="section-title">
+ <h1>Counted Body Techniques</h1>
+ </div>
+
+ <div class="section-body">
+ <p style="text-align: center"><a href=
+ "/users/people/kevlin_henney.html">Kevlin Henney</a><br />
+ (<a href=
+ "mailto:kevlin_at_[hidden]">kevlin_at_[hidden]</a>)</p>
+
+ <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>
+
+ <h2>And then there were none...</h2>
+
+ <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 PROXY pattern described in <i>Design
+ Patterns</i> [Gamma, Helm, Johnson &amp; Vlissides,
+ Addison-Wesley, ISBN 0-201-63361-2]. The intent is given as</p>
+
+ <blockquote>
+ <p><i>Provide a surrogate or placeholder for another object
+ to control access to it.</i></p>
+ </blockquote>
+
+ <p>Coplien [<i>Advanced C++ Programming Styles and Idioms</i>,
+ Addison-Wesley, ISBN 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, ISBN 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 COPY ON WRITE pattern
+ (a specialisation of LAZY EVALUATION) 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 SMART
+ POINTER 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>
+
+ <h2>Attached vs detached</h2>
+
+ <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, ISBN
+ 0-884842-50-X]:</p>
+
+ <ul>
+ <li>COUNTED BODY or ATTACHED COUNTED HANDLE/BODY 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>DETACHED COUNTED HANDLE/BODY 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 DETACHED
+ COUNTED HANDLE/BODY 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 -
+ <code>counted_ptr</code>. <i>[The Boost name is <a href=
+ "../libs/smart_ptr/shared_ptr.htm"><code>shared_ptr</code></a>
+ rather than <code>counted_ptr</code>.]</i></p>
+
+ <p>A common implementation of COUNTED BODY 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
+ COUNTED BODY approach is perhaps only of use in specialised
+ situations.</p>
+
+ <h2>A requirements based approach</h2>
+
+ <p>It is the question of openness that convinced me to revisit
+ the problems with the COUNTED BODY 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 <code>acquire</code> operation that registers interest
+ in a <i>Countable</i> object.</li>
+
+ <li>A <code>release</code> operation unregisters interest in
+ a <i>Countable</i> object.</li>
+
+ <li>An <code>acquired</code> query that returns whether or
+ not a <i>Countable</i> object is currently acquired.</li>
+
+ <li>A <code>dispose</code> 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 <code>ptr</code> is a non-null
+ pointer to a single object (i.e. not an array) of the type, and
+ <i><code>#function</code></i> indicates number of calls to
+ <code><i>function(</i>ptr<i>)</i></code>:</p>
+
+ <table border="1" cellspacing="2" cellpadding="2" summary="">
+ <tr>
+ <td><i>Expression</i></td>
+
+ <td><i>Return type</i></td>
+
+ <td><i>Semantics and notes</i></td>
+ </tr>
+
+ <tr>
+ <td><code>acquire(ptr)</code></td>
+
+ <td>no requirement</td>
+
+ <td><i>post</i>: <code>acquired(ptr)</code></td>
+ </tr>
+
+ <tr>
+ <td><code>release(ptr)</code></td>
+
+ <td>no requirement</td>
+
+ <td><i>pre</i>: <code>acquired(ptr)<br /></code>
+ <i>post</i>: <code>acquired(ptr) == #acquire -
+ #release</code></td>
+ </tr>
+
+ <tr>
+ <td><code>acquired(ptr)</code></td>
+
+ <td>convertible to <code>bool</code></td>
+
+ <td><i>return</i>: <code>#acquire &gt; #release</code></td>
+ </tr>
+
+ <tr>
+ <td><code>dispose(ptr, ptr)</code></td>
+
+ <td>no requirement</td>
+
+ <td><i>pre</i>: <code>!acquired(ptr)<br /></code>
+ <i>post</i>: <code>*ptr</code> no longer usable</td>
+ </tr>
+ </table>
+
+ <p>Note that the two arguments to <code>dispose</code> 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 <code>null</code> is a null pointer to the
+ <i>Countable</i> type:</p>
+
+ <table border="1" summary="">
+ <tr>
+ <td><i>Expression</i></td>
+
+ <td><i>Return type</i></td>
+
+ <td><i>Semantics and notes</i></td>
+ </tr>
+
+ <tr>
+ <td><code>acquire(null)</code></td>
+
+ <td>no requirement</td>
+
+ <td><i>action</i>: none</td>
+ </tr>
+
+ <tr>
+ <td><code>release(null)</code></td>
+
+ <td>no requirement</td>
+
+ <td><i>action</i>: none</td>
+ </tr>
+
+ <tr>
+ <td><code>acquired(null)</code></td>
+
+ <td>convertible to <code>bool</code></td>
+
+ <td><i>return</i>: <code>false</code></td>
+ </tr>
+
+ <tr>
+ <td><code>dispose(null, null)</code></td>
+
+ <td>no requirement</td>
+
+ <td><i>action</i>: none</td>
+ </tr>
+ </table>
+
+ <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>
+
+ <h2>Getting smart</h2>
+
+ <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>
+ <pre>
+template&lt;typename countable_type&gt;
 class countable_ptr
 {
 public: // construction and destruction
@@ -334,19 +328,15 @@
     countable_type *body;
 
 };
-</tt>
 </pre>
- </div>
 
- <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>
-
- <div style="margin-left: 2em">
- <pre>
-<tt>template&lt;typename countable_type&gt;
+ <p>The interface to this class has been kept intentionally
+ simple, e.g. member templates and <code>throw</code> specs have
+ been omitted, for exposition. The majority of the functions are
+ quite simple in implementation, relying very much on the
+ <code>assign</code> member as a keystone function:</p>
+ <pre>
+template&lt;typename countable_type&gt;
 countable_ptr&lt;countable_type&gt;::countable_ptr(countable_type *initial)
   : body(initial)
 {
@@ -419,24 +409,17 @@
 {
     return assign(rhs);
 }
-</tt>
 </pre>
- </div>
- </div>
- <hr width="100%">
 
- <h2>Public accountability</h2>
+ <h2>Public accountability</h2>
 
- <div style="margin-left: 2em">
- <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>
-
- <div style="margin-left: 2em">
- <pre>
-<tt>class countability
+ <p>Conformance to the requirements means that a type can be
+ used with <code>countable_ptr</code>. 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>
+ <pre>
+class countability
 {
 public: // manipulation
 
@@ -459,27 +442,24 @@
     countability &amp;operator=(const countability &amp;);
 
 };
-</tt>
 </pre>
- </div>
 
- <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>
-
- <div style="margin-left: 2em">
- <pre>
-<tt>void acquire(const countability *ptr)
+ <p>Notice that the manipulation functions are
+ <code>const</code> and that the <code>count</code> member
+ itself is <code>mutable</code>. This is because countability is
+ not a part of an object's abstract state: memory management
+ does not depend on the <code>const</code>-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>
+ <pre>
+void acquire(const countability *ptr)
 {
     if(ptr)
     {
@@ -505,17 +485,12 @@
 {
     delete ptr;
 }
-</tt>
 </pre>
- </div>
 
- <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>
-
- <div style="margin-left: 2em">
- <pre>
-<tt>class example : public countability
+ <p>Any type that now derives from <code>countability</code> may
+ now be used with <code>countable_ptr</code>:</p>
+ <pre>
+class example : public countability
 {
     ...
 };
@@ -526,59 +501,52 @@
     countable_ptr&lt;example&gt; qtr(ptr);
     ptr.clear(); // set ptr to point to null
 } // allocated object deleted when qtr destructs
-</tt>
 </pre>
- </div>
- </div>
- <hr width="100%">
 
- <h2>Runtime mixin</h2>
+ <h2>Runtime mixin</h2>
 
- <div style="margin-left: 2em">
- <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>
-
- <div style="margin-left: 2em">
- <pre>
-<tt>struct countable_new;
+ <p>The challenge is to apply COUNTED BODY 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 <code>void *</code>! It goes without saying
+ that <code>void</code> 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>
+ <pre>
+struct countable_new;
 extern const countable_new countable;
 
 void *operator new(size_t, const countable_new &amp;);
-void operator delete(void *, const countable_new &amp;);</tt>
+void operator delete(void *, const countable_new &amp;);
 </pre>
- </div>
 
- <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>
-
- <div style="margin-left: 2em">
- <pre>
-<tt>struct count
+ <p>We have overloaded <code>operator new</code> with a dummy
+ argument to distinguish it from the regular global
+ <code>operator new</code>. This is comparable to the use of the
+ <code>std::nothrow_t</code> type and <code>std::nothrow</code>
+ object in the standard library. The placement <code>operator
+ delete</code> 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 <code>new</code> expression using
+ <code>countable</code> 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>
+ <pre>
+struct count
 {
     size_t value;
 };
@@ -587,33 +555,30 @@
 {
     return const_cast&lt;count *&gt;(static_cast&lt;const count *&gt;(ptr) - 1);
 }
-</tt>
 </pre>
- </div>
 
- <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>
-
- <div style="margin-left: 2em">
- <pre>
-<tt>void *operator new(size_t size, const countable_new &amp;)
+ <p>An important constraint to observe here is the alignment of
+ <code>count</code> 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
+ <code>union</code> to coalign <code>count</code> 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
+ <code>new</code> or <code>malloc</code>.</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
+ <code>const</code> to non-<code>const</code> -
+ <code>count</code> is in effect a <code>mutable</code>
+ type.</p>
+
+ <p>The allocator functions themselves are fairly
+ straightforward:</p>
+ <pre>
+void *operator new(size_t size, const countable_new &amp;)
 {
     count *allocated = static_cast&lt;count *&gt;(::operator new(sizeof(count) + size));
     *allocated = count(); // initialise the header
@@ -624,17 +589,13 @@
 {
     ::operator delete(header(ptr));
 }
-</tt>
 </pre>
- </div>
 
- <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>
-
- <div style="margin-left: 2em">
- <pre>
-<tt>void acquire(const void *ptr)
+ <p>Given a correctly allocated header, we now need the
+ <i>Countable</i> functions to operate on <code>const void
+ *</code> to complete the picture:</p>
+ <pre>
+void acquire(const void *ptr)
 {
     if(ptr)
     {
@@ -661,32 +622,25 @@
     ptr-&gt;~countable_type();
     operator delete(const_cast&lt;countable_type *&gt;(ptr), countable);
 }
-</tt>
 </pre>
- </div>
 
- <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>
- </div>
- <hr width="100%">
-
- <h2>Getting smarter</h2>
-
- <div style="margin-left: 2em">
- <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>
-
- <div style="margin-left: 2em">
- <pre>
-<tt>class example
+ <p>The most complex of these is the <code>dispose</code>
+ 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 <code>const void *</code>
+ distinguishes it from the earlier dispose shown for <code>const
+ countability *</code>.</p>
+
+ <h2>Getting smarter</h2>
+
+ <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 <code>countable_ptr</code> we defined earlier? Good
+ news: nothing!</p>
+ <pre>
+class example
 {
     ...
 };
@@ -697,78 +651,88 @@
     countable_ptr&lt;example&gt; qtr(ptr);
     ptr.clear(); // set ptr to point to null
 } // allocated object deleted when qtr destructs
-</tt>
 </pre>
- </div>
 
- <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>
+ <p>The <code>new(countable)</code> 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 <code>delete</code> on an object allocated
+ with <code>new(countable)</code>, results in undefined
+ behaviour. This is similar to what happens when you mix
+ <code>new[]</code> with <code>delete</code> or
+ <code>malloc</code> with <code>delete</code>. The whole point
+ of <i>Countable</i> conformance is that <i>Countable</i>
+ objects are used with <code>countable_ptr</code>, and this
+ ensures the correct use.</p>
+
+ <p>However, accidents will happen, and inevitably you may
+ forget to allocate using <code>new(countable)</code> and
+ instead use <code>new</code>. This error and others can be
+ detected in most cases by extending the code shown here to add
+ a check member to the <code>count</code>, 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>
+
+ <h2>Conclusion</h2>
+
+ <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 COUNTED BODY pattern.</li>
+
+ <li>The ability, through control of allocation, to
+ dynamically and non-intrusively add capabilities to fixed
+ types using the RUNTIME MIXIN pattern.</li>
+ </ul>
+
+ <p>The application of the two together gives rise to a new
+ variant of the essential COUNTED BODY pattern, UNINTRUSIVE
+ COUNTED BODY. You can take this theme even further and contrive
+ a simple garbage collection system for C++.</p>
+
+ <p>The complete code for <code>countable_ptr</code>,
+ <code>countability</code>, and the <code>countable new</code>
+ is also available.</p>
+
+ <div style="text-align: right">
+ <i>First published in</i> <a href=
+ "http://www.accu.org/index.php/overloadonline">Overload</a>
+ <i>25, April 1998, ISSN 1354-3172</i>
+ </div>
+ </div>
+ </div>
+ </div>
+ </div>
+
+ <div id="sidebar">
+ <!--#include virtual="/common/sidebar-common.html" -->
+ <!--#include virtual="/common/sidebar-community.html" -->
+ </div>
+
+ <div class="clear"></div>
+ </div>
   </div>
- <hr width="100%">
 
- <h2>Conclusion</h2>
+ <div id="footer">
+ <div id="footer-left">
+ <div id="revised">
+ <p>Revised $Date$</p>
+ </div>
 
- <div style="margin-left: 2em">
- <p>There are two key concepts that this article has introduced:</p>
+ <div id="copyright">
+ <p>Copyright Kevlin Henney 1998-1999.</p>
+ </div><!--#include virtual="/common/footer-license.html" -->
+ </div>
 
- <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>
- </div>
+ <div id="footer-right">
+ <!--#include virtual="/common/footer-banners.html" -->
+ </div>
 
- <div align="right">
- <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</i></font>
+ <div class="clear"></div>
   </div>
-
- <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
- "http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
- height="31" width="88"></a></p>
-
- <p>Revised
- <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->04 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38514" --></p>
-
- <p><i>Copyright &copy; 1998-1999 Kevlin Henney</i></p>
-
- <p><i>Distributed under the Boost Software License, Version 1.0. (See
- accompanying file LICENSE_1_0.txt or copy
- at <a href=
- "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt>)</i></p>
 </body>
 </html>

Copied: website/public_html/beta/community/error_handling.html (from r40993, /trunk/more/error_handling.html)
==============================================================================
--- /trunk/more/error_handling.html (original)
+++ website/public_html/beta/community/error_handling.html 2007-11-11 14:14:34 EST (Sun, 11 Nov 2007)
@@ -1,79 +1,97 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "
http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 
-<html>
- <head>
- <meta name="generator" content=
- "HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org">
- <meta http-equiv="Content-Type" content=
- "text/html; charset=windows-1252">
-
- <title>Error and Exception Handling</title>
- </head>
-
- <body>
- <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:</p>
-
- <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. Volume. 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>
-
- <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>
-
- <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 could have a significant
- performance impact. The guideline mentioned above has a grain of
- truth in it: in time critical code, throwing an exception
- should <em>be</em> the exception, not the rule.</p>
-
- <h3>How should I design my exception classes?</h3>
-
- <ol>
- <li><b>Derive your exception class
- from <code>std::exception</code></b>. Except in *very* rare
- circumstances where you can't afford the cost of a virtual
- table,
- <code>std::exception</code> makes a reasonable exception base class,
- and when used universally, allows programmers to catch "everything"
- without resorting to <code>catch(...)</code>. For more about
- <code>catch(...)</code>, see below.
-
- <li><b>Use <i>virtual</i> inheritance.</b> This insight is due
- to Andrew Koenig. Using virtual inheritance from your
- exception's base class(es) prevents ambiguity problems at the
- catch-site in case someone throws an exception derived from
- multiple bases which have a base class in common:
-
-<pre>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+<head>
+ <title>Error and Exception Handling</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
+ <link rel="icon" href="/favicon.ico" type="image/ico" />
+ <link rel="stylesheet" type="text/css" href=
+ "/style/section-community.css" />
+ <!--[if IE]> <style type="text/css"> body { behavior: url(/style/csshover.htc); } </style> <![endif]-->
+</head>
+
+<body>
+ <div id="heading">
+ <!--#include virtual="/common/heading.html" -->
+ </div>
+
+ <div id="body">
+ <div id="body-inner">
+ <div id="content">
+ <div class="section" id="intro">
+ <div class="section-0">
+ <div class="section-title">
+ <h1>Error and Exception Handling</h1>
+ </div>
+
+ <div class="section-body">
+ <h2>References</h2>
+
+ <p>The following paper is a good introduction to some of the
+ issues of writing robust generic components:</p>
+
+ <blockquote>
+ <p><a href="/community/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. Volume. 1766</a></p>
+ </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>
+
+ <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>
+
+ <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 could have a
+ significant performance impact. The guideline mentioned above
+ has a grain of truth in it: in time critical code, throwing an
+ exception should <em>be</em> the exception, not the rule.</p>
+
+ <h3>How should I design my exception classes?</h3>
+
+ <ol>
+ <li><strong>Derive your exception class from
+ <code>std::exception</code></strong>. Except in *very* rare
+ circumstances where you can't afford the cost of a virtual
+ table, <code>std::exception</code> makes a reasonable
+ exception base class, and when used universally, allows
+ programmers to catch "everything" without resorting to
+ <code>catch(...)</code>. For more about
+ <code>catch(...)</code>, see below.</li>
+
+ <li>
+ <strong>Use <i>virtual</i> inheritance.</strong> This
+ insight is due to Andrew Koenig. Using virtual inheritance
+ from your exception's base class(es) prevents ambiguity
+ problems at the catch-site in case someone throws an
+ exception derived from multiple bases which have a base
+ class in common:
+ <pre>
 #include &lt;iostream&gt;
 struct my_exc1 : std::exception { char const* what() const throw(); };
 struct my_exc2 : std::exception { char const* what() const throw(); };
@@ -83,109 +101,116 @@
 {
    try { throw your_exc3(); }
    catch(std::exception const&amp; e) {}
- catch(...) { std::cout &lt;&lt; &quot;whoops!&quot; &lt;&lt; std::endl; }
+ catch(...) { std::cout &lt;&lt; "whoops!" &lt;&lt; std::endl; }
 }
-</pre>
+</pre>The program above prints <code>"whoops"</code> because the C++ runtime
+can't resolve which <code>exception</code> instance to match in the first
+catch clause.
+ </li>
+
+ <li>
+ <strong><i>Don't</i> embed a std::string object</strong> or
+ any other data member or base class whose copy constructor
+ could throw an exception. That could lead directly to
+ std::terminate() at the throw point. Similarly, it's a bad
+ idea to use a base or member whose ordinary constructor(s)
+ might throw, because, though not necessarily fatal to your
+ program, you may report a different exception than intended
+ from a <i>throw-expression</i> that includes construction
+ such as:
 
-The program above prints <code>&quot;whoops&quot;</code> because the
-C++ runtime can't resolve which <code>exception</code> instance to
-match in the first catch clause.
-
- </li>
-
- <li>
- <b><i>Don't</i> embed a std::string object</b> or any other data
- member or base class whose copy constructor could throw an exception.
- That could lead directly to std::terminate() at the throw point.
- Similarly, it's a bad idea to use a base or member whose ordinary
- constructor(s) might throw, because, though not necessarily fatal to
- your program, you may report a different exception than intended from
- a <i>throw-expression</i> that includes construction such as:
-
- <blockquote>
-<pre>
+ <pre>
 throw some_exception();
 </pre>
- </blockquote>
 
- <p>There are various ways to avoid copying string objects when
- exceptions are copied, including embedding a fixed-length buffer in
- the exception object, or managing strings via reference-counting.
- However, consider the next point before pursuing either of these
- approaches.</p>
- </li>
-
- <li><b>Format the <code>what()</code> message on demand</b>, if you
- feel you really must format the message. Formatting an exception error
- message is typically a memory-intensive operation that could
- potentially throw an exception. This is an operation best delayed until
- after stack unwinding has occurred, and presumably, released some
- resources. It's a good idea in this case to protect your
- <code>what()</code> function with a <code>catch(...)</code> block so
- that you have a fallback in case the formatting code throws</li>
-
- <li><b>Don't worry <i>too</i> much about the <code>what()</code>
- message</b>. It's nice to have a message that a programmer stands a
- chance of figuring out, but you're very unlikely to be able to compose
- a relevant and <i>user</i>-comprehensible error message at the point an
- exception is thrown. Certainly, internationalization is beyond the
- scope of the exception class author. <a href=
- "../people/peter_dimov.htm">Peter Dimov</a> makes an excellent argument
- that the proper use of a <code>what()</code> string is to serve as a
- key into a table of error message formatters. Now if only we could get
- standardized <code>what()</code> strings for exceptions thrown by the
- standard library...</li>
-
- <li><b>Expose relevant information about the cause of the error</b> in
- your exception class' public interface. A fixation on the
- <code>what()</code> message is likely to mean that you neglect to
- expose information someone might need in order to make a coherent
- message for users. For example, if your exception reports a numeric
- range error, it's important to have the actual numbers involved
- available <i>as numbers</i> in the exception class' public interface
- where error reporting code can do something intelligent with them. If
- you only expose a textual representation of those numbers in the
- <code>what()</code> string, you will make life very difficult for
- programmers who need to do something more (e.g. subtraction) with them
- than dumb output.</li>
-
- <li><b>Make your exception class immune to double-destruction</b> if
- possible. Unfortunately, several popular compilers occasionally cause
- exception objects to be destroyed twice. If you can arrange for that to
- be harmless (e.g. by zeroing deleted pointers) your code will be more
- robust.</li>
- </ol>
-
- <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>
-
- <p>Sometimes it is necessary 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>
-
- <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
- because <code>catch(...)</code> will catch these not-really-C++
- exceptions. Fortunately, there is a simple but little-known workaround,
- which is to use the following incantation:</p>
+ <p>There are various ways to avoid copying string objects
+ when exceptions are copied, including embedding a
+ fixed-length buffer in the exception object, or managing
+ strings via reference-counting. However, consider the next
+ point before pursuing either of these approaches.</p>
+ </li>
+
+ <li><strong>Format the <code>what()</code> message on
+ demand</strong>, if you feel you really must format the
+ message. Formatting an exception error message is typically a
+ memory-intensive operation that could potentially throw an
+ exception. This is an operation best delayed until after
+ stack unwinding has occurred, and presumably, released some
+ resources. It's a good idea in this case to protect your
+ <code>what()</code> function with a <code>catch(...)</code>
+ block so that you have a fallback in case the formatting code
+ throws</li>
+
+ <li><strong>Don't worry <i>too</i> much about the
+ <code>what()</code> message</strong>. It's nice to have a
+ message that a programmer stands a chance of figuring out,
+ but you're very unlikely to be able to compose a relevant and
+ <i>user</i>-comprehensible error message at the point an
+ exception is thrown. Certainly, internationalization is
+ beyond the scope of the exception class author. <a href=
+ "../people/peter_dimov.htm">Peter Dimov</a> makes an
+ excellent argument that the proper use of a
+ <code>what()</code> string is to serve as a key into a table
+ of error message formatters. Now if only we could get
+ standardized <code>what()</code> strings for exceptions
+ thrown by the standard library...</li>
+
+ <li><strong>Expose relevant information about the cause of
+ the error</strong> in your exception class' public interface.
+ A fixation on the <code>what()</code> message is likely to
+ mean that you neglect to expose information someone might
+ need in order to make a coherent message for users. For
+ example, if your exception reports a numeric range error,
+ it's important to have the actual numbers involved available
+ <i>as numbers</i> in the exception class' public interface
+ where error reporting code can do something intelligent with
+ them. If you only expose a textual representation of those
+ numbers in the <code>what()</code> string, you will make life
+ very difficult for programmers who need to do something more
+ (e.g. subtraction) with them than dumb output.</li>
+
+ <li><strong>Make your exception class immune to
+ double-destruction</strong> if possible. Unfortunately,
+ several popular compilers occasionally cause exception
+ objects to be destroyed twice. If you can arrange for that to
+ be harmless (e.g. by zeroing deleted pointers) your code will
+ be more robust.</li>
+ </ol>
+
+ <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 <code>assert()</code> or something like
+ it.</p>
+
+ <p>Sometimes it is necessary 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>
+
+ <p><strong>Note for Windows developers</strong>: unfortunately,
+ the native exception-handling used by most Windows compilers
+ actually throws an exception when you use
+ <code>assert()</code>. 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 because
+ <code>catch(...)</code> will catch these not-really-C++
+ exceptions. Fortunately, there is a simple but little-known
+ workaround, which is to use the following incantation:</p>
 
- <blockquote>
-<pre>
+ <pre>
 extern "C" void straight_to_debugger(unsigned int, EXCEPTION_POINTERS*)
 {
     throw;
@@ -193,48 +218,74 @@
 extern "C" void (*old_translator)(unsigned, EXCEPTION_POINTERS*)
          = _set_se_translator(straight_to_debugger);
 </pre>
- </blockquote>
- This technique doesn't work if the SEH is raised from within a catch
- block (or a function called from within a catch block), but it still
- eliminates the vast majority of JIT-masking problems.
-
- <h3>How should I handle exceptions?</h3>
-
- <p>Often the best way to deal with exceptions is to not handle them at
- all. If you can let them pass through your code and allow destructors to
- handle cleanup, your code will be cleaner.</p>
-
- <h4>Avoid <code>catch(...)</code> when possible</h4>
- Unfortunately, operating systems other than Windows also wind non-C++
- "exceptions" (such as thread cancellation) into the C++ EH machinery, and
- there is sometimes no workaround corresponding to the
- <code>_set_se_translator</code> hack described above. The result is that
- <code>catch(...)</code> can have the effect of making some unexpected
- system notification at a point where recovery is impossible look just
- like a C++ exception thrown from a reasonable place, invalidating the
- usual safe assumptions that destructors and catch blocks have taken valid
- steps to ensure program invariants during unwinding.
-
- <p>I reluctantly concede this point to Hillel Y. Sims, after many
- long debates in the newsgroups: until all OSes are "fixed", if
- every exception were derived from <code>std::exception</code> and
- everyone substituted
- <code>catch(std::exception&amp;)</code> for <code>catch(...)</code>, the
- world would be a better place.</p>
-
- <p>Sometimes, <code>catch(...)</code>, is still the most appropriate
- pattern, in spite of bad interactions with OS/platform design choices. If
- you have no idea what kind of exception might be thrown and you really
- <i>must</i> stop unwinding it's probably still your best bet. One obvious
- place where this occurs is at language boundaries.</p>
- <hr>
-
- <p>&copy; Copyright David Abrahams 2001-2003. All rights reserved.</p>
-
- <p>Revised
- <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->
- 21 August, 2003<!--webbot bot="Timestamp" endspan i-checksum="34359" -->
- </p>
- </body>
+ <p>This technique doesn't work if the SEH is raised
+ from within a catch block (or a function called from within a
+ catch block), but it still eliminates the vast majority of
+ JIT-masking problems.</p>
+
+ <h3>How should I handle exceptions?</h3>
+
+ <p>Often the best way to deal with exceptions is to not handle
+ them at all. If you can let them pass through your code and
+ allow destructors to handle cleanup, your code will be
+ cleaner.</p>
+
+ <h4>Avoid <code>catch(...)</code> when
+ possible</h4>Unfortunately, operating systems other than
+ Windows also wind non-C++ "exceptions" (such as thread
+ cancellation) into the C++ EH machinery, and there is sometimes
+ no workaround corresponding to the
+ <code>_set_se_translator</code> hack described above. The
+ result is that <code>catch(...)</code> can have the effect of
+ making some unexpected system notification at a point where
+ recovery is impossible look just like a C++ exception thrown
+ from a reasonable place, invalidating the usual safe
+ assumptions that destructors and catch blocks have taken valid
+ steps to ensure program invariants during unwinding.
+
+ <p>I reluctantly concede this point to Hillel Y. Sims, after
+ many long debates in the newsgroups: until all OSes are
+ "fixed", if every exception were derived from
+ <code>std::exception</code> and everyone substituted
+ <code>catch(std::exception&amp;)</code> for
+ <code>catch(...)</code>, the world would be a better place.</p>
+
+ <p>Sometimes, <code>catch(...)</code>, is still the most
+ appropriate pattern, in spite of bad interactions with
+ OS/platform design choices. If you have no idea what kind of
+ exception might be thrown and you really <i>must</i> stop
+ unwinding it's probably still your best bet. One obvious place
+ where this occurs is at language boundaries.</p>
+ </div>
+ </div>
+ </div>
+ </div>
+
+ <div id="sidebar">
+ <!--#include virtual="/common/sidebar-common.html" -->
+ <!--#include virtual="/common/sidebar-community.html" -->
+ </div>
+
+ <div class="clear"></div>
+ </div>
+ </div>
+
+ <div id="footer">
+ <div id="footer-left">
+ <div id="revised">
+ <p>Revised $Date$</p>
+ </div>
+
+ <div id="copyright">
+ <p>Copyright David Abrahams 2001-2003.</p>
+ </div><!--#include virtual="/common/footer-license.html" -->
+ </div>
+
+ <div id="footer-right">
+ <!--#include virtual="/common/footer-banners.html" -->
+ </div>
+
+ <div class="clear"></div>
+ </div>
+</body>
 </html>
-

Copied: website/public_html/beta/community/exception_safety.html (from r40993, /trunk/more/generic_exception_safety.html)
==============================================================================
--- /trunk/more/generic_exception_safety.html (original)
+++ website/public_html/beta/community/exception_safety.html 2007-11-11 14:14:34 EST (Sun, 11 Nov 2007)
@@ -1,125 +1,156 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<!-- saved from url=(0052)http://people.ne.mediaone.net/abrahams/abrahams.html -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 
- <meta name="generator" content="Microsoft FrontPage 5.0">
- <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"><a href="mailto:david.abrahams_at_[hidden]">
- david.abrahams_at_[hidden]</a></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=
- "#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=
- "#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=
- "#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&amp; result ) // 1
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+<head>
+ <title>Exception-Safety in Generic Components</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
+ <link rel="icon" href="/favicon.ico" type="image/ico" />
+ <link rel="stylesheet" type="text/css" href=
+ "/style/section-community.css" />
+ <!--[if IE]> <style type="text/css"> body { behavior: url(/style/csshover.htc); } </style> <![endif]-->
+</head>
+
+<body>
+ <div id="heading">
+ <!--#include virtual="/common/heading.html" -->
+ </div>
+
+ <div id="body">
+ <div id="body-inner">
+ <div id="content">
+ <div class="section" id="intro">
+ <div class="section-0">
+ <div class="section-title">
+ <h1>Exception-Safety in Generic Components</h1>
+ </div>
+
+ <div class="section-body">
+ <p style="text-align: center"><i><strong>Lessons Learned from
+ Specifying Exception-Safety for the C++ Standard
+ Library</strong></i></p>
+
+ <h3 style="text-align: center">David Abrahams</h3>
+
+ <h3 style="text-align: center"><a href=
+ "mailto:david.abrahams_at_[hidden]">david.abrahams_at_[hidden]</a></h3>
+
+ <p><strong>Abstract.</strong> 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>
+
+ <p><strong>Keywords:</strong> exception-safety, exceptions,
+ STL, C++</p>
+
+ <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
+ &ldquo;reasonable&rdquo; 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>
+
+ <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>
+
+ <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.</p>
+
+ <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 &ldquo;error-safety&rdquo; before C++ had
+ exceptions.</p>
+
+ <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>
+
+ <p><i>&ldquo;Interactions between templates and exceptions are
+ not well-understood.&rdquo;</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>
+
+ <p><i>&ldquo;It is well known to be impossible to write an
+ exception-safe generic container.&rdquo;</i> This claim is
+ often heard with reference to an article by Tom Cargill
+ <a title=
+ "Tom Cargill, &ldquo;Exception Handling: A False Sense of Security&rdquo;, C++ Report, Nov-Dec 1994"
+ href="#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="#footnote1"><sup>1</sup></a> He concludes by suggesting
+ that a solution may not be possible. Unfortunately, his article
+ was read by many as &ldquo;proof&rdquo; 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>
+
+ <p><i>&ldquo;Dealing with exceptions will slow code down, and
+ templates are used specifically to get the best possible
+ performance.&rdquo;</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, &ldquo;Introspective Sorting and Selection Algorithms&rdquo;, Software-Practice and Experience 27(8):983-993, 1997."
+ href="#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
+ &ldquo;traditional&rdquo; 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 &ldquo;traditional&rdquo; error
+ handling must typically test a return value for errors after
+ every single function call; using exceptions completely
+ eliminates that overhead.</p>
+
+ <p><i>&ldquo;Exceptions make it more difficult to reason about
+ a program's behavior.&rdquo;</i> Usually cited in support of
+ this myth is the way &ldquo;hidden&rdquo; 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:</p>
+ <pre>
+ErrorCode f( int&amp; result ) // 1
 { // 2
     X x; // 3
     ErrorCode err = x.g( result ); // 4
@@ -129,14 +160,13 @@
     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
+ <p>In the example above, there is a &ldquo;hidden&rdquo; call
+ to <code>X::~X()</code> in lines 6 and 7. Granted, using
+ exceptions, there is no code devoted to error handling
+ visible:</p>
+ <pre>
+int f() // 1
 { // 2
     X x; // 3
     int result = x.g(); // 4
@@ -144,67 +174,70 @@
     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=
- "#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 &lt;class X&gt;
+ <p>For many programmers more familiar with exceptions, the
+ second example is actually more readable and understandable
+ than the first. The &ldquo;hidden&rdquo; 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>
+
+ <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!)</p>
+
+ <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="#footnote2"><sup>2</sup></a> The generic component might,
+ in return, provide one of the following guarantees:</p>
+
+ <ul>
+ <li>The <i>basic</i> guarantee: that the invariants of the
+ component are preserved, and no resources are leaked.</li>
+
+ <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>
+
+ <li>The <i>no-throw</i> guarantee: that the operation will
+ not throw an exception.</li>
+ </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:</p>
+ <pre>
+template &lt;class X&gt;
 void print_random_sequence()
 {
     std::vector&lt;X&gt; v(10); // A vector of 10 items
@@ -219,133 +252,136 @@
     std::ostream_iterator&lt;X&gt;( 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=
- "#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=
- "#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=
- "#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&lt;T&gt;::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=
- "#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&lt;T&gt;::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 &lt;class Container, class BasicOp&gt;
+ <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="#footnote3"><sup>3</sup></a> It is &ldquo;safe&rdquo; in
+ the sense that it is not allowed to crash, but its output may
+ be unpredictable.</p>
+
+ <p>The <i>strong</i> guarantee provides full
+ &ldquo;commit-or-rollback&rdquo; 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="#footnote4"><sup>4</sup></a>).</p>
+
+ <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="#footnote5"><sup>5</sup></a></p>
+
+ <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&lt;T&gt;::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="#footnote6"><sup>6</sup></a></p>
+
+ <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&lt;T&gt;::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 &ldquo;undoing&rdquo; 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>
+
+ <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 &ldquo;natural&rdquo; 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 &ldquo;natural&rdquo; level of
+ safety.</p>
+
+ <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 &ldquo;make a new copy&rdquo; strategy
+ described above:</p>
+ <pre>
+template &lt;class Container, class BasicOp&gt;
 void MakeOperationStrong( Container&amp; c, const BasicOp&amp; 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=
-"#footnote7"><sup>7</sup></a>
+href="#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&lt;&gt; template: automated container selection to meet exceptionsafety constraints."
- href=
- "#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=
- "#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
+ <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&lt;&gt; template: automated container selection to meet exceptionsafety constraints."
+ href="#footnote8"><sup>8</sup></a></p>
+
+ <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, &ldquo;Introspective Sorting and Selection Algorithms&rdquo;, Software-Practice and Experience 27(8):983-993, 1997."
+ href="#reference6"><sup>[6]</sup></a>, which represents a
+ substantial improvement in worst-case complexity over the
+ well-established <i>quicksort</i>.</p>
+
+ <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 &ldquo;composite container.&rdquo; 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:</p>
+ <pre>
+// SearchableStack - A stack which can be efficiently searched
 // for any value.
 template &lt;class T&gt;
 class SearchableStack
@@ -360,18 +396,18 @@
     std::list&lt;std::set&lt;T&gt;::iterator&gt; 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 &lt;class T&gt; // 1
+ <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:</p>
+ <pre>
+template &lt;class T&gt; // 1
 void SearchableStack&lt;T&gt;::push(const T&amp; t) // 2
 { // 3
     set&lt;T&gt;::iterator i = set_impl.insert(t); // 4
@@ -386,79 +422,84 @@
     } // 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:
+ <p>What does our code actually require of the library? We need
+ to examine the lines where non-const operations occur:</p>
 
- <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&lt;T&gt;::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&lt;T&gt;::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&lt;T&gt;::erase</code>.<a title=
- "One might be tempted to surround the erase operation with a try/catch block to reduce the requirements on set&lt;T&gt; 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=
- "#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&lt;T&gt;::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&lt;TestClass&gt;
+ <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&lt;T&gt;::insert</code>.</li>
+
+ <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&lt;T&gt;::insert.</li>
+
+ <li>Line 11: here we are &ldquo;rolling back&rdquo; 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&lt;T&gt;::erase</code>.<a title=
+ "One might be tempted to surround the erase operation with a try/catch block to reduce the requirements on set&lt;T&gt; 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="#footnote9"><sup>9</sup></a></li>
+
+ <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&lt;T&gt;::iterator</code>.</li>
+ </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."
+ href="#footnote10">10</a></sup></p>
+
+ <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>
+
+ <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."
+ href="#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>
+
+ <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.</p>
+ <pre>
+// Use this as a type parameter, e.g. vector&lt;TestClass&gt;
 struct TestClass
 {
     TestClass( int v = 0 )
@@ -473,22 +514,20 @@
     ~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=
- "#footnote12"><sup>12</sup></a>
 
- <blockquote>
-<pre>extern int gThrowCounter; // The throw counter
+ <p><code>ThisCanThrow</code> simply decrements a &ldquo;throw
+ counter&rdquo; 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="#footnote12"><sup>12</sup></a></p>
+ <pre>
+extern int gThrowCounter; // The throw counter
 void ThisCanThrow()
 {
     if (gThrowCounter-- == 0)
@@ -519,165 +558,220 @@
     }
 }
 </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=
- "#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=
- "#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=
- "#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=
- "#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=
- "#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>.
-
- <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>.
-
- <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>.
-
- <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.awprofessional.com/content/images/020163371x/supplements/Exception_Handling_Article.html">http://www.awprofessional.com/content/images/020163371x/supplements/Exception_Handling_Article.html>.
-
- <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.stlport.org">http://www.stlport.org>.
-
- <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&lt;&gt;</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&lt;T&gt;</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.
+ <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.</p>
+
+ <h2>8 Further Reading</h2>
+
+ <p>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=
+ "#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>
+
+ <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="#reference1"><sup>[1]</sup></a> is only slightly more
+ formal, but relies on hard-to-read &ldquo;standardese&rdquo;
+ 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="#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>
+
+ <p>The original reference implementation <a title=
+ "B. Fomitchev, Adapted SGI STL Version 1.0, with exception handling code by D. Abrahams"
+ href="#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="#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.</p>
+
+ <h2>References</h2>
+
+ <ol>
+ <li><a name="reference1" id="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>.</li>
+
+ <li><a name="reference2" id="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>.</li>
+
+ <li><a name="reference3" id="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>.</li>
+
+ <li><a name="reference4" id="reference4">Tom</a> Cargill,
+ &ldquo;Exception Handling: A False Sense of Security,&rdquo;
+ C++ Report, Nov-Dec 1994, also available at <a href=
+ "
http://www.awprofessional.com/content/images/020163371x/supplements/Exception_Handling_Article.html">
+ http://www.awprofessional.com/content/images/020163371x/supplements/Exception_Handling_Article.html>.</li>
+
+ <li><a name="reference5" id="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.stlport.org">http://www.stlport.org>.</li>
+
+ <li><a name="reference6" id="reference6">D.</a> R. Musser,
+ &ldquo;Introspective Sorting and Selection Algorithms,&rdquo;
+ <i>Software-Practice and Experience</i> 27(8):983-993,
+ 1997.</li>
+
+ <li><a name="reference7" id="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.</li>
+ </ol>
+
+ <h2>Footnotes</h2>
+
+ <p><a name="footnote1" id="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>
+
+ <p><a name="footnote2" id="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>
+
+ <p><a name="footnote3" id="footnote3">3</a> In practice of
+ course, this function would make an extremely poor random
+ sequence generator!</p>
+
+ <p><a name="footnote4" id="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>
+
+ <p><a name="footnote5" id="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>
+
+ <p><a name="footnote6" id="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>
+
+ <p><a name="footnote7" id="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>
+
+ <p><a name="footnote8" id="footnote8">8</a> This suggests
+ another potential use for the oft-wished-for but as yet unseen
+ <code>container_traits&lt;&gt;</code> template: automated
+ container selection to meet exception-safety constraints.</p>
+
+ <p><a name="footnote9" id="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&lt;T&gt;</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>
+
+ <p><a name="footnote10" id="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>
+
+ <p><a name="footnote11" id="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>
+
+ <p><a name="footnote12" id="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>
+
+ <p><a name="footnote13" id="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.</p>
+ </div>
+ </div>
+ </div>
+ </div>
+
+ <div id="sidebar">
+ <!--#include virtual="/common/sidebar-common.html" -->
+ <!--#include virtual="/common/sidebar-community.html" -->
+ </div>
+
+ <div class="clear"></div>
+ </div>
+ </div>
+
+ <div id="footer">
+ <div id="footer-left">
+ <div id="revised">
+ <p>Revised $Date$</p>
+ </div>
+
+ <div id="copyright">
+ <p>Copyright David Abrahams 2001.</p>
+ </div><!--#include virtual="/common/footer-license.html" -->
+ </div>
+
+ <div id="footer-right">
+ <!--#include virtual="/common/footer-banners.html" -->
+ </div>
+
+ <div class="clear"></div>
+ </div>
+</body>
+</html>

Copied: website/public_html/beta/community/generic_programming.html (from r40993, /trunk/more/generic_programming.html)
==============================================================================
--- /trunk/more/generic_programming.html (original)
+++ website/public_html/beta/community/generic_programming.html 2007-11-11 14:14:34 EST (Sun, 11 Nov 2007)
@@ -1,63 +1,71 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "
http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 
-<html>
- <head>
- <meta name="generator" content=
- "Microsoft FrontPage 5.0">
- <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>
- </head>
-
- <body bgcolor="#FFFFFF" text="#000000">
- <img src="../boost.png" alt="boost.png (6897 bytes)" align="center"
- width="277" height="86">
-
- <h1>Generic Programming Techniques</h1>
-
- <p>This is an incomplete survey of some of the generic programming
- techniques used in the boost libraries.</p>
-
- <h2>Table of Contents</h2>
-
- <ul>
- <li>Introduction</li>
-
- <li>The Anatomy of a Concept</li>
-
- <li>Traits</li>
-
- <li>Tag Dispatching</li>
-
- <li>Adaptors</li>
-
- <li>Type Generators</li>
-
- <li>Object Generators</li>
-
- <li>Policy Classes</li>
- </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>
-
- <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>
- </p>
-
- <blockquote>
-<pre>void* memcpy(void* region1, const void* region2, size_t n)
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+<head>
+ <title>Generic Programming Techniques</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
+ <link rel="icon" href="/favicon.ico" type="image/ico" />
+ <link rel="stylesheet" type="text/css" href=
+ "/style/section-community.css" />
+ <!--[if IE]> <style type="text/css"> body { behavior: url(/style/csshover.htc); } </style> <![endif]-->
+</head>
+
+<body>
+ <div id="heading">
+ <!--#include virtual="/common/heading.html" -->
+ </div>
+
+ <div id="body">
+ <div id="body-inner">
+ <div id="content">
+ <div class="section" id="intro">
+ <div class="section-0">
+ <div class="section-title">
+ <h1>Generic Programming Techniques</h1>
+ </div>
+
+ <div class="section-body">
+ <p>This is an incomplete survey of some of the generic
+ programming techniques used in the boost
+ libraries.</p>
+
+ <h2>Table of Contents</h2>
+
+ <ul>
+ <li>Introduction</li>
+
+ <li>The Anatomy of a Concept</li>
+
+ <li>Traits</li>
+
+ <li>Tag Dispatching</li>
+
+ <li>Adaptors</li>
+
+ <li>Type Generators</li>
+
+ <li>Object Generators</li>
+
+ <li>Policy Classes</li>
+ </ul>
+
+ <h2><a name="introduction" id=
+ "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>
+
+ <p>As a simple example of generic programming, we will look at
+ how one might generalize the <code>memcpy()</code> function of
+ the C standard library. An implementation of
+ <code>memcpy()</code> might look like the following:</p>
+ <pre>
+void* memcpy(void* region1, const void* region2, size_t n)
 {
   const char* first = (const char*)region2;
   const char* last = ((const char*)region2) + n;
@@ -67,35 +75,35 @@
   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 <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>
- </p>
 
- <blockquote>
-<pre>template &lt;typename InputIterator, typename OutputIterator&gt;
+ <p>The <code>memcpy()</code> function is already generalized to
+ some extent by the use of <code>void*</code> 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
+ <code>memcpy()</code>, the function's <strong><i>minimal
+ requirements</i></strong> are that it needs 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
+ <strong><i>concepts</i></strong>, in this case the <a href=
+ "http://www.sgi.com/tech/stl/InputIterator.html">Input
+ Iterator</a> concept (for <code>region2</code>) and the
+ <a href="http://www.sgi.com/tech/stl/OutputIterator.html">Output
+ Iterator</a> concept (for <code>region1</code>).</p>
+
+ <p>If we rewrite the <code>memcpy()</code> 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
+ <code>copy()</code> function in the following way:</p>
+ <pre>
+template &lt;typename InputIterator, typename OutputIterator&gt;
 OutputIterator
 copy(InputIterator first, InputIterator last, OutputIterator result)
 {
@@ -104,17 +112,13 @@
   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>
- </p>
-
- <blockquote>
-<pre>#include &lt;list&gt;
+ <p>Using the generic <code>copy()</code> function, we can now
+ copy elements from any kind of sequence, including a linked
+ list that exports iterators such as <code>std::<a href=
+ "http://www.sgi.com/tech/stl/List.html">list</a></code>.</p>
+ <pre>
+#include &lt;list&gt;
 #include &lt;vector&gt;
 #include &lt;iostream&gt;
 
@@ -135,52 +139,60 @@
   std::cout &lt;&lt; std::endl;
 }
 </pre>
- </blockquote>
 
- <h2><a name="concept">Anatomy of a Concept</a></h2>
- A <b><i>concept</i></b> is a set of requirements
- consisting of valid expressions, associated types, invariants, and
- complexity guarantees. A type that satisfies the 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>
-
- <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>
-
- <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>
-
- <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.</li>
- </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>.</p>
-
- <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&lt;T&gt;</a></tt>
- looks something like this:</p>
+ <h2><a name="concept" id="concept">Anatomy of a
+ Concept</a></h2>
 
- <blockquote>
-<pre>template &lt;class Iterator&gt;
+ <p>A <strong><i>concept</i></strong> is a set of requirements
+ consisting of valid expressions, associated types, invariants,
+ and complexity guarantees. A type that satisfies the
+ requirements is said to <strong><i>model</i></strong> the
+ concept. A concept can extend the requirements of another
+ concept, which is called
+ <strong><i>refinement</i></strong>.</p>
+
+ <ul>
+ <li><a name="valid_expression" id=
+ "valid_expression"><strong>Valid Expressions</strong></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>
+
+ <li><a name="associated_type" id=
+ "associated_type"><strong>Associated Types</strong></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>
+
+ <li><strong>Invariants</strong> 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>
+
+ <li><strong>Complexity Guarantees</strong> 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.</li>
+ </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>.</p>
+
+ <h2><a name="traits" id="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 <a href=
+ "http://www.sgi.com/tech/stl/iterator_traits.html"><code>std::iterator_traits&lt;T&gt;</code></a>
+ looks something like this:</p>
+ <pre>
+template &lt;class Iterator&gt;
 struct iterator_traits {
   typedef ... iterator_category;
   typedef ... value_type;
@@ -189,78 +201,89 @@
   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>
-
- <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&lt;T&gt;</tt> which provides
- constants describing the range and capabilities of numeric types.</p>
-
- <h2><a name="tag_dispatching">Tag Dispatching</a></h2>
-
- <p>Tag dispatching is a way of using function overloading to
- dispatch based on properties of a type, and is often used hand in
- hand with traits classes. A good example of this synergy 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>
-
- <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
- this page
- for a more detailed description of iterator tags.</p>
 
- <blockquote>
-<pre>namespace std {
+ <p>The traits' <code>value_type</code> gives generic code the
+ type which the iterator is "pointing at", while the
+ <code>iterator_category</code> can be used to select more
+ efficient algorithms depending on the iterator's
+ capabilities.</p>
+
+ <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>
+
+ <p>For an in-depth description of
+ <code>std::iterator_traits</code>, 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
+ <code>std::numeric_limits&lt;T&gt;</code> which provides
+ constants describing the range and capabilities of numeric
+ types.</p>
+
+ <h2><a name="tag_dispatching" id="tag_dispatching">Tag
+ Dispatching</a></h2>
+
+ <p>Tag dispatching is a way of using function overloading to
+ dispatch based on properties of a type, and is often used hand
+ in hand with traits classes. A good example of this synergy is
+ the implementation of the <a href=
+ "http://www.sgi.com/tech/stl/advance.html"><code>std::advance()</code></a>
+ function in the C++ Standard Library, which increments an
+ iterator <code>n</code> 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 <code>advance()</code> function can simply be
+ implemented with <code>i += n</code>, and is very efficient:
+ constant time. Other iterators must be <code>advance</code>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 <code>n</code> to be negative, so we
+ must decide whether to increment or decrement the iterator.</p>
+
+ <p>The relation between tag dispatching and traits classes is
+ that the property used for dispatching (in this case the
+ <code>iterator_category</code>) is often accessed through a
+ traits class. The main <code>advance()</code> function uses the
+ <a href=
+ "http://www.sgi.com/tech/stl/iterator_traits.html"><code>iterator_traits</code></a>
+ class to get the <code>iterator_category</code>. It then makes
+ a call the the overloaded <code>advance_dispatch()</code>
+ function. The appropriate <code>advance_dispatch()</code> is
+ selected by the compiler based on whatever type the
+ <code>iterator_category</code> resolves to, either <a href=
+ "http://www.sgi.com/tech/stl/input_iterator_tag.html"><code>input_iterator_tag</code></a>,
+ <a href=
+ "http://www.sgi.com/tech/stl/bidirectional_iterator_tag.html"><code>
+ bidirectional_iterator_tag</code></a>, or <a href=
+ "http://www.sgi.com/tech/stl/random_access_iterator_tag.html"><code>
+ random_access_iterator_tag</code></a>. A
+ <strong><i>tag</i></strong> 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.</p>
+ <pre>
+namespace std {
   struct input_iterator_tag { };
   struct bidirectional_iterator_tag { };
   struct random_access_iterator_tag { };
 
   namespace detail {
     template &lt;class InputIterator, class Distance&gt;
- void advance_dispatch(InputIterator&amp; i, Distance n, <b>input_iterator_tag</b>) {
+ void advance_dispatch(InputIterator&amp; i, Distance n, <strong>input_iterator_tag</strong>) {
       while (n--) ++i;
     }
 
     template &lt;class BidirectionalIterator, class Distance&gt;
     void advance_dispatch(BidirectionalIterator&amp; i, Distance n,
- <b>bidirectional_iterator_tag</b>) {
+ <strong>bidirectional_iterator_tag</strong>) {
       if (n &gt;= 0)
         while (n--) ++i;
       else
@@ -269,56 +292,58 @@
 
     template &lt;class RandomAccessIterator, class Distance&gt;
     void advance_dispatch(RandomAccessIterator&amp; i, Distance n,
- <b>random_access_iterator_tag</b>) {
+ <strong>random_access_iterator_tag</strong>) {
       i += n;
     }
   }
 
   template &lt;class InputIterator, class Distance&gt;
   void advance(InputIterator&amp; i, Distance n) {
- typename <b>iterator_traits&lt;InputIterator&gt;::iterator_category</b> category;
- detail::advance_dispatch(i, n, <b>category</b>);
+ typename <strong>iterator_traits&lt;InputIterator&gt;::iterator_category</strong> category;
+ detail::advance_dispatch(i, n, <strong>category</strong>);
   }
 }
 </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>
-
- <p>A more comprehensive review of the adaptors in the standard can be
- found <a href="http://portal.acm.org/citation.cfm?id=249118.249120">
- here</a>.</p>
-
- <h2><a name="type_generator">Type Generators</a></h2>
-
- <p><b>Note:</b> The <i>type generator</i> concept has largely been
- superseded by the more refined notion of a <a href=
- "../libs/mpl/doc/refmanual/metafunction.html"><i>metafunction</i></a>. See
- <i><a href="http://www.boost-consulting.com/mplbook">C++ Template
- Metaprogramming</a></i> for an in-depth discussion of metafunctions.</p>
-
- <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. This example
- uses an old version of <tt><a href=
- "../libs/iterator/doc/iterator_adaptor.html">iterator_adaptor</a></tt>
- whose design didn't allow derived iterator types. As a result, every
- adapted iterator had to be a specialization of <tt>iterator_adaptor</tt>
- itself and generators were a convenient way to produce those types.</p>
+ <h2><a name="adaptors" id="adaptors">Adaptors</a></h2>
 
- <blockquote>
-<pre>template &lt;class Predicate, class Iterator,
+ <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>
+
+ <p>A more comprehensive review of the adaptors in the standard
+ can be found <a href=
+ "http://portal.acm.org/citation.cfm?id=249118.249120">here</a>.</p>
+
+ <h2><a name="type_generator" id="type_generator">Type
+ Generators</a></h2>
+
+ <p><strong>Note:</strong> The <i>type generator</i> concept has
+ largely been superseded by the more refined notion of a
+ metafunction.
+ See <i><a href="http://www.boost-consulting.com/mplbook">C++
+ Template Metaprogramming</a></i> for an in-depth discussion of
+ metafunctions.</p>
+
+ <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)[1]. The generated type is
+ usually expressed as a nested typedef named, appropriately
+ <code>type</code>. A type generator is usually used to
+ consolidate a complicated type expression into a simple one.
+ This example uses an old version of <a href=
+ "../libs/iterator/doc/iterator_adaptor.html"><code>iterator_adaptor</code></a>
+ whose design didn't allow derived iterator types. As a result,
+ every adapted iterator had to be a specialization of
+ <code>iterator_adaptor</code> itself and generators were a
+ convenient way to produce those types.</p>
+ <pre>
+template &lt;class Predicate, class Iterator,
     class Value = <i>complicated default</i>,
     class Reference = <i>complicated default</i>,
     class Pointer = <i>complicated default</i>,
@@ -329,123 +354,146 @@
     typedef iterator_adaptor&lt;
         
         Iterator,filter_iterator_policies&lt;Predicate,Iterator&gt;,
- Value,Reference,Pointer,Category,Distance&gt; <b>type</b>;
+ Value,Reference,Pointer,Category,Distance&gt; <strong>type</strong>;
 };
 </pre>
- </blockquote>
-
- <p>Now, that's complicated, but producing an adapted filter iterator
- using the generator is much easier. You can usually just write:</p>
 
- <blockquote>
-<pre>boost::filter_iterator_generator&lt;my_predicate,my_base_iterator&gt;::type
+ <p>Now, that's complicated, but producing an adapted filter
+ iterator using the generator is much easier. You can usually
+ just write:</p>
+ <pre>
+boost::filter_iterator_generator&lt;my_predicate,my_base_iterator&gt;::type
 </pre>
- </blockquote>
 
- <h2><a name="object_generator">Object Generators</a></h2>
+ <h2><a name="object_generator" id="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&nbsp;T&amp;,&nbsp;const&nbsp;U&amp;)</tt>.</p>
-
- <p>For example, given:</p>
-
- <blockquote>
-<pre>struct widget {
+ <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
+ "<code>make_</code>", after <code>std::<a href=
+ "http://www.sgi.com/tech/stl/pair.html">make_pair</a>(const&nbsp;T&amp;,&nbsp;const&nbsp;U&amp;)</code>.</p>
+
+ <p>For example, given:</p>
+ <pre>
+struct widget {
   void tweak(int);
 };
 std::vector&lt;widget *&gt; 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)
+ <p>By chaining two standard object generators,
+ <code>std::<a href=
+ "http://www.dinkumware.com/htm_cpl/functio2.html#bind2nd">bind2nd</a>()</code>
+ and <code>std::<a href=
+ "http://www.dinkumware.com/htm_cpl/functio2.html#mem_fun">mem_fun</a>()</code>,
+ we can easily tweak all widgets:</p>
+ <pre>
+void tweak_all_widgets1(int arg)
 {
    for_each(widget_ptrs.begin(), widget_ptrs.end(),
- <b>bind2nd</b>(std::<b>mem_fun</b>(&amp;widget::tweak), arg));
+ <strong>bind2nd</strong>(std::<strong>mem_fun</strong>(&amp;widget::tweak), arg));
 }
 </pre>
- </blockquote>
-
- <p>Without using object generators the example above would look like
- this:</p>
 
- <blockquote>
-<pre>void tweak_all_widgets2(int arg)
+ <p>Without using object generators the example above would look
+ like this:</p>
+ <pre>
+void tweak_all_widgets2(int arg)
 {
    for_each(struct_ptrs.begin(), struct_ptrs.end(),
- <b>std::binder2nd&lt;std::mem_fun1_t&lt;void, widget, int&gt; &gt;</b>(
- std::<b>mem_fun1_t&lt;void, widget, int&gt;</b>(&amp;widget::tweak), arg));
+ <strong>std::binder2nd&lt;std::mem_fun1_t&lt;void, widget, int&gt; &gt;</strong>(
+ std::<strong>mem_fun1_t&lt;void, widget, int&gt;</strong>(&amp;widget::tweak), arg));
 }
 </pre>
- </blockquote>
-
- <p>As expressions get more complicated the need to reduce the verbosity
- of type specification gets more compelling.</p>
-
- <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>
-
- <p>Policy classes have been explored in detail by <a href=
- "http://www.moderncppdesign.com/">Andrei Alexandrescu</a> in <a href=
- "http://www.informit.com/articles/article.asp?p=167842">this chapter</a>
- of his book, <i>Modern C++ Design</i>. He writes:</p>
-
- <blockquote>
- <p>In brief, policy-based class design fosters assembling a class with
- complex behavior out of many little classes (called policies), each of
- which takes care of only one behavioral or structural aspect. As the
- name suggests, a policy establishes an interface pertaining to a
- specific issue. You can implement policies in various ways as long as
- you respect the policy interface.</p>
-
- <p>Because you can mix and match policies, you can achieve a
- combinatorial set of behaviors by using a small core of elementary
- components.</p>
- </blockquote>
-
- <p>Andrei's description of policy classes suggests that their power is
- derived from granularity and orthogonality. Less-granular policy
- interfaces have been shown to work well in practice, though. <a href=
- "http://cvs.sourceforge.net/viewcvs.py/*checkout*/boost/boost/libs/utility/Attic/iterator_adaptors.pdf">
- This paper</a> describes an old version of <tt><a href=
- "../libs/iterator/doc/iterator_adaptor.html">iterator_adaptor</a></tt>
- that used non-orthogonal policies. There is also precedent in the
- standard library: <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>.</p>
-
- <h2>Notes</h2>
- <a name="1">[1]</a> Type generators are sometimes viewed as 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 -->06 Nov 2007<!--webbot bot="Timestamp" endspan i-checksum="15272" -->
- </p>
 
- <p>© Copyright David Abrahams 2001.</p>
+ <p>As expressions get more complicated the need to reduce the
+ verbosity of type specification gets more compelling.</p>
 
-<p>Distributed under the Boost Software License, Version 1.0. See
-www.boost.org/LICENSE_1_0.txt</p>
+ <h2><a name="policy" id="policy">Policy Classes</a></h2>
 
- </body>
-</html>
\ No newline at end of file
+ <p>A policy class is a template parameter used to transmit
+ behavior. An example from the standard library is
+ <code>std::<a href=
+ "http://www.dinkumware.com/htm_cpl/memory.html#allocator">allocator</a></code>,
+ which supplies memory management behaviors to standard <a href=
+ "http://www.sgi.com/tech/stl/Container.html">containers</a>.</p>
+
+ <p>Policy classes have been explored in detail by <a href=
+ "http://www.moderncppdesign.com/">Andrei Alexandrescu</a> in
+ <a href=
+ "http://www.informit.com/articles/article.asp?p=167842">this
+ chapter</a> of his book, <i>Modern C++ Design</i>. He
+ writes:</p>
+
+ <blockquote>
+ <p>In brief, policy-based class design fosters assembling a
+ class with complex behavior out of many little classes
+ (called policies), each of which takes care of only one
+ behavioral or structural aspect. As the name suggests, a
+ policy establishes an interface pertaining to a specific
+ issue. You can implement policies in various ways as long as
+ you respect the policy interface.</p>
+
+ <p>Because you can mix and match policies, you can achieve a
+ combinatorial set of behaviors by using a small core of
+ elementary components.</p>
+ </blockquote>
+
+ <p>Andrei's description of policy classes suggests that their
+ power is derived from granularity and orthogonality.
+ Less-granular policy interfaces have been shown to work well in
+ practice, though. <a href=
+ "http://cvs.sourceforge.net/viewcvs.py/*checkout*/boost/boost/libs/utility/Attic/iterator_adaptors.pdf">
+ This paper</a> describes an old version of <a href=
+ "../libs/iterator/doc/iterator_adaptor.html"><code>iterator_adaptor</code></a>
+ that used non-orthogonal policies. There is also precedent in
+ the standard library: <a href=
+ "http://www.dinkumware.com/htm_cpl/string2.html#char_traits"><code>
+ std::char_traits</code></a>, 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>.</p>
+
+ <h2>Notes</h2>
+
+ <p><a name="footnote1" id="footnote1">[1]</a> Type generators
+ are sometimes viewed as a workaround for the lack of
+ ``templated typedefs'' in C++.</p>
+ </div>
+ </div>
+ </div>
+ </div>
+
+ <div id="sidebar">
+ <!--#include virtual="/common/sidebar-common.html" -->
+ <!--#include virtual="/common/sidebar-community.html" -->
+ </div>
+
+ <div class="clear"></div>
+ </div>
+ </div>
+
+ <div id="footer">
+ <div id="footer-left">
+ <div id="revised">
+ <p>Revised $Date$</p>
+ </div>
+
+ <div id="copyright">
+ <p>Copyright David Abrahams 2001.</p>
+ </div><!--#include virtual="/common/footer-license.html" -->
+ </div>
+
+ <div id="footer-right">
+ <!--#include virtual="/common/footer-banners.html" -->
+ </div>
+
+ <div class="clear"></div>
+ </div>
+</body>
+</html>


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk