Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r50848 - in trunk/libs/scope_exit/doc/html: . scope_exit
From: daniel_james_at_[hidden]
Date: 2009-01-28 10:32:47

Author: danieljames
Date: 2009-01-28 10:32:46 EST (Wed, 28 Jan 2009)
New Revision: 50848
URL: http://svn.boost.org/trac/boost/changeset/50848

Log:
Generate the scope_exit documentation.
Added:
   trunk/libs/scope_exit/doc/html/
   trunk/libs/scope_exit/doc/html/index.html (contents, props changed)
   trunk/libs/scope_exit/doc/html/scope_exit/
   trunk/libs/scope_exit/doc/html/scope_exit/acknowledge.html (contents, props changed)
   trunk/libs/scope_exit/doc/html/scope_exit/alternatives.html (contents, props changed)
   trunk/libs/scope_exit/doc/html/scope_exit/compilers.html (contents, props changed)
   trunk/libs/scope_exit/doc/html/scope_exit/conf.html (contents, props changed)
   trunk/libs/scope_exit/doc/html/scope_exit/ref.html (contents, props changed)
   trunk/libs/scope_exit/doc/html/scope_exit/tutorial.html (contents, props changed)

Added: trunk/libs/scope_exit/doc/html/index.html
==============================================================================
--- (empty file)
+++ trunk/libs/scope_exit/doc/html/index.html 2009-01-28 10:32:46 EST (Wed, 28 Jan 2009)
@@ -0,0 +1,77 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Chapter 1. Boost.ScopeExit</title>
+<link rel="stylesheet" href="../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="next" href="scope_exit/tutorial.html" title="Tutorial">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav"><a accesskey="n" href="scope_exit/tutorial.html"><img src="../../../../doc/html/images/next.png" alt="Next"></a></div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div>
+<div><h2 class="title">
+<a name="scope_exit"></a>Chapter 1. Boost.ScopeExit</h2></div>
+<div><div class="author"><h3 class="author">
+Alexander Nasonov
+</h3></div></div>
+<div>Copyright © 2006 -2009 Alexander Nasonov</div>
+<div><div class="legalnotice">
+<a name="id1036342"></a>
+ 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" target="_top">
+ http://www.boost.org/LICENSE_1_0.txt </a>)
+ 
+</div></div>
+</div></div>
+<div class="toc">
+Table of Contents
+<dl>
+<dt> Introduction</dt>
+<dt> Tutorial</dt>
+<dt> Alternatives</dt>
+<dt> Supported Compilers</dt>
+<dt> Configuration</dt>
+<dt> Reference</dt>
+<dt> Acknowledge</dt>
+</dl>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="scope_exit.intro"></a> Introduction</h2></div></div></div>
+
+ Nowadays, every C++ developer is familiar with RAII
+ technique. It binds resource acquisition and release to initialization and
+ destruction of a variable that holds the resource. But there are times when
+ writing a special class for such variable is not worth the effort.
+ 
+
+ This is when <a class="link" href="index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> macro comes into play.
+ You put resource acquisition directly in your code and next to it you write
+ a code that releases the resource.
+ 
+
+ Read <a class="link" href="scope_exit/tutorial.html" title="Tutorial">Tutorial</a> to find out how to
+ write programs with <a class="link" href="index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> or jump straight
+ to the <a class="link" href="scope_exit/ref.html" title="Reference">Reference</a> section.
+ 
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left">Last revised: January 28, 2009 at 15:23:21 GMT</td>
+<td align="right"><div class="copyright-footer"></div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav"><a accesskey="n" href="scope_exit/tutorial.html"><img src="../../../../doc/html/images/next.png" alt="Next"></a></div>
+</body>
+</html>

Added: trunk/libs/scope_exit/doc/html/scope_exit/acknowledge.html
==============================================================================
--- (empty file)
+++ trunk/libs/scope_exit/doc/html/scope_exit/acknowledge.html 2009-01-28 10:32:46 EST (Wed, 28 Jan 2009)
@@ -0,0 +1,66 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Acknowledge</title>
+<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="prev" href="ref.html" title="Reference">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ref.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="scope_exit.acknowledge"></a> Acknowledge</h2></div></div></div>
+
+ (in chronological order)
+ 
+
+ Maxim Yegorushkin for sending me a code where he used a local struct to clean
+ up resources.
+ 
+
+ Andrei Alexandrescu for pointing me to scope(exit)
+ construct of the D
+ programming language.
+ 
+
+ Pavel Vozenilek and Maxim Yanchenko for reviews of early drafts of the library.
+ 
+
+ Steven Watanabe for his valuable ideas.
+ 
+
+ Jody Hagins for good comments that helped to significantly improve the documentation.
+ 
+
+ Richard Webb for testing the library on MSVC compiler.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2006 -2009 Alexander Nasonov
+ 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" target="_top">
+ http://www.boost.org/LICENSE_1_0.txt </a>)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="ref.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/scope_exit/doc/html/scope_exit/alternatives.html
==============================================================================
--- (empty file)
+++ trunk/libs/scope_exit/doc/html/scope_exit/alternatives.html 2009-01-28 10:32:46 EST (Wed, 28 Jan 2009)
@@ -0,0 +1,303 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Alternatives</title>
+<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="prev" href="tutorial.html" title="Tutorial">
+<link rel="next" href="compilers.html" title="Supported Compilers">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tutorial.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="compilers.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="scope_exit.alternatives"></a> Alternatives</h2></div></div></div>
+<a name="alternatives.try_catch"></a><h4>
+<a name="id1037675"></a>
+ try-catch
+ </h4>
+
+ This is an example of using a badly designed <code class="computeroutput">File</code>
+ class. An instance of <code class="computeroutput">File</code>
+ doesn't close a file in a destructor, a programmer is expected to call the
+ <code class="computeroutput">close</code> member function explicitly.
+ 
+<pre class="programlisting">File passwd;
+try {
+ passwd.open("/etc/passwd");
+ // ...
+ passwd.close();
+}
+catch(...) {
+ log("could not get user info");
+ if(passwd.is_open())
+ passwd.close();
+ throw;
+}
+</pre>
+
+ Note the following:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ the <code class="computeroutput">passwd</code> object is defined
+ outside of the <code class="computeroutput">try</code> block because
+ this object is required inside the <code class="computeroutput">catch</code>
+ block to close the file,
+ </li>
+<li>
+ the <code class="computeroutput">passwd</code> object is not
+ fully constructed until after the <code class="computeroutput">open</code>
+ member function returns, and
+ </li>
+<li>
+ if opening throws, the <code class="computeroutput">passwd.close()</code> should not be called, hence the call to
+ <code class="computeroutput">passwd.is_open()</code>.
+ </li>
+</ul></div>
+
+ <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> doesn't have any of these problems:
+ 
+<pre class="programlisting">try {
+ File passwd("/etc/passwd");
+ BOOST_SCOPE_EXIT( (&passwd) ) {
+ passwd.close();
+ } BOOST_SCOPE_EXIT_END
+ // ...
+}
+catch(...) {
+ log("could not get user info");
+ throw;
+}
+</pre>
+<a name="alternatives.raii"></a><h4>
+<a name="id1038144"></a>
+ RAII
+ </h4>
+
+ RAII
+ is absolutely perfect for the <code class="computeroutput">File</code>
+ class introduced above. Use of a properly designed <code class="computeroutput">File</code>
+ class would look like:
+ 
+<pre class="programlisting">try {
+ File passwd("/etc/passwd");
+ // ...
+}
+catch(...) {
+ log("could not get user info");
+ throw;
+}
+</pre>
+
+ However, using RAII
+ to build up a <a href="http://www.research.att.com/~bs/glossary.html#Gstrong-guarantee" target="_top">strong
+ guarantee</a> could introduce a lot of non-reusable RAII
+ types. For example:
+ 
+<pre class="programlisting">m_persons.push_back(person);
+pop_back_if_not_commit pop_back_if_not_commit_guard(commit, m_persons);
+</pre>
+
+ The <code class="computeroutput">pop_back_if_not_commit</code>
+ class is either defined out of the scope or as a local class:
+ 
+<pre class="programlisting">class pop_back_if_not_commit {
+ bool m_commit;
+ std::vector<Person>& m_vec;
+ // ...
+ ~pop_back_if_not_commit() {
+ if(!m_commit)
+ m_vec.pop_back();
+ }
+};
+</pre>
+
+ In some cases <a href="http://www.research.att.com/~bs/glossary.html#Gstrong-guarantee" target="_top">strong
+ guarantee</a> can be accomplished with standard utilities:
+ 
+<pre class="programlisting">std::auto_ptr<Person> spSuperMan(new Superman);
+m_persons.push_back(spSuperMan.get());
+spSuperMan.release(); // m_persons successfully took ownership.
+</pre>
+
+ or with specialized containers such as <a href="../../../../../libs/ptr_container/doc/ptr_container.html" target="_top">Boost
+ Pointer Container Library</a> or <a href="../../../../../libs/multi_index/doc/index.html" target="_top">Boost
+ Multi-Index Containers Library</a>.
+ 
+<a name="alternatives._ulink_url__http___www_ddj_com_dept_cpp_184403758__scopeguard__ulink_"></a><h4>
+<a name="id1038643"></a>
+ ScopeGuard
+ </h4>
+
+ Imagine that you add a new currency rate:
+ 
+<pre class="programlisting">bool commit = false;
+std::string currency("EUR");
+double rate = 1.3326;
+std::map<std::string, double> rates;
+bool currency_rate_inserted =
+ rates.insert(std::make_pair(currency, rate)).second;
+</pre>
+
+ and then continue a transaction. If it cannot be completed, you erase the currency
+ from <code class="computeroutput">rates</code>. This is how you
+ can do this with ScopeGuard
+ and Boost.Lambda:
+ 
+<pre class="programlisting">using namespace boost::lambda;
+
+ON_BLOCK_EXIT(
+ if_(currency_rate_inserted && !_1) [
+ bind(
+ static_cast<
+ std::map<std::string,double>::size_type (std::map<std::string,double>::*)(std::string const&)
+ >(&std::map<std::string,double>::erase)
+ , &rates
+ , currency
+ )
+ ]
+ , boost::cref(commit)
+ );
+
+// ...
+
+commit = true;
+</pre>
+
+ Note that
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Boost.lambda expressions are hard to write correctly, for example, overloaded
+ function must be explicitly casted, as demonstrated in this example,
+ </li>
+<li>
+ condition in <code class="computeroutput">if_</code> expression
+ refers to <code class="computeroutput">commit</code> variable
+ indirectly through the <code class="computeroutput">_1</code>
+ placeholder,
+ </li>
+<li>
+ setting a breakpoint inside <code class="computeroutput">if_[ ... ]</code>
+ requires in-depth knowledge of Boost.Lambda
+ and debugging techniques.
+ </li>
+</ul></div>
+
+ This code will look much better with native lambda expressions proposed for
+ C++0x:
+ 
+<pre class="programlisting">ON_BLOCK_EXIT(
+ [currency_rate_inserted, &commit, &rates, &currency]() -> void
+ {
+ if(currency_rate_inserted && !commit)
+ rates.erase(currency);
+ }
+);
+</pre>
+
+ With <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> you can simply do
+ 
+<pre class="programlisting">BOOST_SCOPE_EXIT( (currency_rate_inserted)(&commit)(&rates)(&currency) )
+{
+ if(currency_rate_inserted && !commit)
+ rates.erase(currency);
+} BOOST_SCOPE_EXIT_END
+
+// ...
+
+commit = true;
+</pre>
+<a name="alternatives.c__0x"></a><h4>
+<a name="id1039632"></a>
+ C++0x
+ </h4>
+
+ In future releases <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> will take advantages
+ of C++0x features.
+ 
+<div class="itemizedlist"><ul type="disc"><li>
+ Passing capture list as <a href="../../../../../libs/preprocessor/index.html" target="_top">Boost.Preprocessor
+ sequence</a> will be replaced with a traditional macro invocation style:
+ </li></ul></div>
+<pre class="programlisting">BOOST_SCOPE_EXIT(currency_rate_inserted, &commit, &rates, &currency)
+{
+ if(currency_rate_inserted && !commit)
+ rates.erase(currency);
+} BOOST_SCOPE_EXIT_END
+</pre>
+<div class="itemizedlist"><ul type="disc"><li>
+<code class="computeroutput">BOOST_SCOPE_EXIT_END</code> will
+ be replaced with a semicolon:
+ </li></ul></div>
+<pre class="programlisting">BOOST_SCOPE_EXIT(currency_rate_inserted, &commit, &rates, &currency)
+{
+ if(currency_rate_inserted && !commit)
+ rates.erase(currency);
+};
+</pre>
+<div class="itemizedlist"><ul type="disc"><li>
+ Users will be able to capture local variables implicitly with lambda capture
+ defaults <code class="computeroutput">&</code> and <code class="computeroutput">=</code>:
+ </li></ul></div>
+<pre class="programlisting">BOOST_SCOPE_EXIT(&, currency_rate_inserted)
+{
+ if(currency_rate_inserted && !commit)
+ rates.erase(currency);
+};
+</pre>
+<div class="itemizedlist"><ul type="disc"><li>
+ It will be possible to capture <code class="computeroutput">this</code>
+ pointer.
+ </li></ul></div>
+<a name="alternatives.the_d_programming_language"></a><h4>
+<a name="id1040070"></a>
+ The D Programming Language
+ </h4>
+
+ ScopeExit is similar to scope(exit)
+ feature built into the D
+ programming language.
+ 
+
+ A curious reader may notice that the library doesn't implement <code class="computeroutput">scope(success)</code> and <code class="computeroutput">scope(failure)</code> of the D
+ language. Unfortunately, it's not possible in C++ because failure or success
+ condition cannot be determined by calling <code class="computeroutput">std::uncaught_exception</code>.
+ It's not a big problem, though. These two constructs can be expressed in terms
+ of scope(exit)
+ and a <code class="computeroutput">bool commit</code>
+ variable as explained in <a class="link" href="tutorial.html" title="Tutorial">Tutorial</a>.
+ Refer to Guru of the Week #47
+ for more details about <code class="computeroutput">std::uncaught_exception</code>
+ and if it has any good use at all.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2006 -2009 Alexander Nasonov
+ 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" target="_top">
+ http://www.boost.org/LICENSE_1_0.txt </a>)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tutorial.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="compilers.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/scope_exit/doc/html/scope_exit/compilers.html
==============================================================================
--- (empty file)
+++ trunk/libs/scope_exit/doc/html/scope_exit/compilers.html 2009-01-28 10:32:46 EST (Wed, 28 Jan 2009)
@@ -0,0 +1,61 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Supported Compilers</title>
+<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="prev" href="alternatives.html" title="Alternatives">
+<link rel="next" href="conf.html" title="Configuration">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="alternatives.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="conf.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="scope_exit.compilers"></a> Supported Compilers</h2></div></div></div>
+
+ The library should be usable on any compiler that supports Boost.Typeof
+ except
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ MSVC 7.1 and 8.0 fail to link if a function with <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a>
+ is included by multiple translation units.
+ </li>
+<li>
+ GCC 3.3 can't compile <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> inside
+ a template. See <a href="http://lists.boost.org/Archives/boost/2007/02/116235.php" target="_top">this
+ thread</a> for more details.
+ </li>
+</ul></div>
+
+ The author tested the library on GCC 3.3, 3.4, 4.1, 4.2 and Intel 10.1.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2006 -2009 Alexander Nasonov
+ 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" target="_top">
+ http://www.boost.org/LICENSE_1_0.txt </a>)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="alternatives.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="conf.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/scope_exit/doc/html/scope_exit/conf.html
==============================================================================
--- (empty file)
+++ trunk/libs/scope_exit/doc/html/scope_exit/conf.html 2009-01-28 10:32:46 EST (Wed, 28 Jan 2009)
@@ -0,0 +1,49 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Configuration</title>
+<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="prev" href="compilers.html" title="Supported Compilers">
+<link rel="next" href="ref.html" title="Reference">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="compilers.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ref.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="scope_exit.conf"></a> Configuration</h2></div></div></div>
+
+ Normally, no configuration is required for the library but note that the library
+ depends on Boost.Typeof
+ and you may want to configure or enforce <a href="../../../../../libs/typeof/index.html" target="_top">typeof
+ emulation</a>.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2006 -2009 Alexander Nasonov
+ 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" target="_top">
+ http://www.boost.org/LICENSE_1_0.txt </a>)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="compilers.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="ref.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/scope_exit/doc/html/scope_exit/ref.html
==============================================================================
--- (empty file)
+++ trunk/libs/scope_exit/doc/html/scope_exit/ref.html 2009-01-28 10:32:46 EST (Wed, 28 Jan 2009)
@@ -0,0 +1,153 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Reference</title>
+<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="prev" href="conf.html" title="Configuration">
+<link rel="next" href="acknowledge.html" title="Acknowledge">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="conf.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="acknowledge.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="scope_exit.ref"></a> Reference</h2></div></div></div>
+<a name="ref.boost_scope_exit"></a><h4>
+<a name="id1040305"></a>
+ BOOST_SCOPE_EXIT
+ </h4>
+
+ A <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> declaration has the following
+ synopsis:
+ 
+<pre class="programlisting">#include <boost/scope_exit.hpp>
+
+BOOST_SCOPE_EXIT ( scope-exit-capture-list )
+ function-body
+BOOST_SCOPE_EXIT_END
+</pre>
+
+ where
+ 
+<pre class="programlisting">scope-exit-capture-list:
+ ( scope-exit-capture )
+ scope-exit-capture-list ( scope-exit-capture )
+
+scope-exit-capture:
+ identifier
+ &identifier
+</pre>
+
+ The <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> declaration schedules an execution
+ of <code class="computeroutput">scope-exit-body</code>
+ at the end of the current scope. The <code class="computeroutput">scope-exit-body</code> statements are executed in the reverse
+ order of <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> declarations in the given
+ scope. The scope must be local.
+ 
+
+ Each <code class="computeroutput">identifier</code> in <code class="computeroutput">scope-exit-capture-list</code> must
+ be a valid name in enclosing scope and it must appear exactly once in the list.
+ If a <code class="computeroutput">scope-exit-capture</code>
+ starts with the ampersand sign <code class="computeroutput">&</code>,
+ the corresponding <code class="computeroutput">identifier</code>
+ will be available inside <code class="computeroutput">scope-exit-body</code>; otherwise, a copy of it will be made
+ at the point of <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> declaration and
+ that copy will be available inside <code class="computeroutput">scope-exit-body</code>. In the latter case, the <code class="computeroutput">idenitifer</code> must be <code class="computeroutput">CopyConstructible</code>.
+ 
+
+ Only identifiers listed in <code class="computeroutput">scope-exit-capture-list</code>, static variables, <code class="computeroutput">extern</code>
+ variables and functions, and enumerations from the enclosing scope can be used
+ inside the <code class="computeroutput">scope-exit-body</code>.
+ 
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+ <code class="computeroutput">this</code> pointer is not an identifier
+ and cannot be passed to <code class="computeroutput"> scope-exit-capture-list</code>.
+ </td></tr>
+</table></div>
+
+ The <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> uses Boost.Typeof
+ to determine types of <code class="computeroutput">scope-exit-capture-list</code> elements. In order to compile code in
+ typeof emulation mode,
+ all types should be registered with BOOST_TYPEOF_REGISTER_TYPE
+ or BOOST_TYPEOF_REGISTER_TEMPLATE
+ macros, or appropriate Boost.Typeof
+ headers should be included.
+ 
+<a name="ref.boost_scope_exit_tpl"></a><h4>
+<a name="id1041009"></a>
+ BOOST_SCOPE_EXIT_TPL
+ </h4>
+
+ This macro is a workaround for various versions of gcc. These compilers don't
+ compile <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> declaration inside function
+ templates. As a workaround, the <code class="computeroutput">_TPL</code>
+ suffix should be appended to <code class="computeroutput">BOOST_SCOPE_EXIT</code>.
+ 
+
+ The problem boils down to the following code:
+ 
+<pre class="programlisting">template<class T> void foo(T const& t) {
+ int i = 0;
+ struct Local {
+ typedef __typeof__(i) typeof_i;
+ typedef __typeof__(t) typeof_t;
+ };
+ typedef Local::typeof_i i_type;
+ typedef Local::typeof_t t_type;
+}
+
+int main() { foo(0); }
+</pre>
+
+ This can be fixed by adding <code class="computeroutput">typename</code>
+ in front of <code class="computeroutput">Local::typeof_i</code> and <code class="computeroutput">Local::typeof_t</code>.
+ 
+
+ See also <a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37920" target="_top">GCC
+ bug 37920</a>.
+ 
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+ Although <code class="computeroutput">BOOST_SCOPE_EXIT_TPL</code>
+ has the same suffix as the <code class="computeroutput">BOOST_TYPEOF_TPL</code>,
+ it doesn't follow a convention of the Boost.Typeof.
+ </td></tr>
+</table></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2006 -2009 Alexander Nasonov
+ 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" target="_top">
+ http://www.boost.org/LICENSE_1_0.txt </a>)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="conf.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="acknowledge.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/scope_exit/doc/html/scope_exit/tutorial.html
==============================================================================
--- (empty file)
+++ trunk/libs/scope_exit/doc/html/scope_exit/tutorial.html 2009-01-28 10:32:46 EST (Wed, 28 Jan 2009)
@@ -0,0 +1,151 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Tutorial</title>
+<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="prev" href="../index.html" title="Chapter 1. Boost.ScopeExit">
+<link rel="next" href="alternatives.html" title="Alternatives">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="alternatives.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="scope_exit.tutorial"></a> Tutorial</h2></div></div></div>
+
+ Imagine that you want to make many modifications to data members of the <code class="computeroutput">World</code> class in the <code class="computeroutput">World::addPerson</code>
+ function. You start with adding a new <code class="computeroutput">Person</code>
+ object to a vector of persons:
+ 
+<pre class="programlisting">void World::addPerson(Person const& person) {
+ bool commit = false;
+ m_persons.push_back(person); // (1) direct action
+</pre>
+
+ Some operation down the road may throw an exception and all changes to involved
+ objects should be rolled back. This all-or-nothing semantic is also known as
+ <a href="http://www.research.att.com/~bs/glossary.html#Gstrong-guarantee" target="_top">strong
+ guarantee</a>.
+ 
+
+ In particular, last added person must be deleted from <code class="computeroutput">m_persons</code>
+ when the function throws. All you need is to define a delayed action (release
+ of a resource) right after the direct action (resource acquisition):
+ 
+<pre class="programlisting">void World::addPerson(Person const& aPerson) {
+ bool commit = false;
+ m_persons.push_back(aPerson); // (1) direct action
+ BOOST_SCOPE_EXIT( (&commit)(&m_persons) )
+ {
+ if(!commit)
+ m_persons.pop_back(); // (2) rollback action
+ } BOOST_SCOPE_EXIT_END
+
+ // ... // (3) other operations
+
+ commit = true; // (4) turn all rollback actions into no-op
+}
+</pre>
+
+ The block below point <code class="computeroutput">(1)</code> is a <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a>
+ declaration. Unlike point <code class="computeroutput">(1)</code>, an execution of the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a>
+ body will be delayed until the end of the current scope. In this case it will
+ be executed either after point <code class="computeroutput">(4)</code> or on any
+ exception.
+ 
+
+ The <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> declaration starts with <code class="computeroutput">BOOST_SCOPE_EXIT</code> macro invocation which accepts
+ Boost.Preprocessor sequence
+ of captured variables. If a capture starts with the ampersand sign <code class="computeroutput">&</code>, a reference to the captured variable
+ will be available inside the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit">ScopeExit</a> body;
+ otherwise, a copy of the variable will be made after the point <code class="computeroutput">(1)</code>
+ and only the copy will be available inside the body.
+ 
+
+ In the example above, variables <code class="computeroutput">commit</code>
+ and <code class="computeroutput">m_persons</code> are passed by
+ reference because the final value of the <code class="computeroutput">commit</code>
+ variable should be used to determine whether to execute rollback action or
+ not and the action should modify the <code class="computeroutput">m_persons</code>
+ object, not its copy. This is a most common case but passing a variable by
+ value is sometimes useful as well.
+ 
+
+ Consider a more complex case where <code class="computeroutput">World::addPerson</code>
+ can save intermediate states at some points and roll back to the last saved
+ state. You can use <code class="computeroutput">Person::m_evolution</code> to store a version of changes
+ and increment it to cancel all rollback actions associated with those changes.
+ 
+
+ If you pass a current value of <code class="computeroutput">m_evolution</code>
+ stored in the <code class="computeroutput">checkpoint</code> variable
+ by value, it will remain unchanged until the end of aa scope and you can compare
+ it with the final value of the <code class="computeroutput">m_evolution</code>.
+ If the latter wasn't incremented since you saved it, the rollback action inside
+ the block should be executed:
+ 
+<pre class="programlisting">void World::addPerson(Person const& aPerson) {
+ m_persons.push_back(aPerson);
+
+ // This block must be no-throw
+ Person& person = m_persons.back();
+ Person::evolution_t checkpoint = person.m_evolution;
+
+ BOOST_SCOPE_EXIT( (checkpoint)(&person)(&m_persons) )
+ {
+ if(checkpoint == person.m_evolution)
+ m_persons.pop_back();
+ } BOOST_SCOPE_EXIT_END
+
+ // ...
+
+ checkpoint = ++person.m_evolution;
+
+ // Assign new id to the person
+ World::id_t const prev_id = person.m_id;
+ person.m_id = m_next_id++;
+ BOOST_SCOPE_EXIT( (checkpoint)(&person)(&m_next_id)(prev_id) )
+ {
+ if(checkpoint == person.m_evolution) {
+ m_next_id = person.m_id;
+ person.m_id = prev_id;
+ }
+ } BOOST_SCOPE_EXIT_END
+
+ // ...
+
+ checkpoint = ++person.m_evolution;
+}
+</pre>
+
+ Full code listing can be found in world.cpp.
+ 
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2006 -2009 Alexander Nasonov
+ 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" target="_top">
+ http://www.boost.org/LICENSE_1_0.txt </a>)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="alternatives.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Date view	Thread view	Subject view	Author view

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