Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r77031 - trunk/libs/scope_exit/doc/html/scope_exit
From: lorcaminiti_at_[hidden]
Date: 2012-02-14 20:23:14

Author: lcaminiti
Date: 2012-02-14 20:23:13 EST (Tue, 14 Feb 2012)
New Revision: 77031
URL: http://svn.boost.org/trac/boost/changeset/77031

Log:
Updated ScopeExit docs.
Added:
   trunk/libs/scope_exit/doc/html/scope_exit/Acknowledgements.html (contents, props changed)
   trunk/libs/scope_exit/doc/html/scope_exit/Getting_Started.html (contents, props changed)
   trunk/libs/scope_exit/doc/html/scope_exit/No_Variadic_Macros.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/tutorial.html (contents, props changed)

Added: trunk/libs/scope_exit/doc/html/scope_exit/Acknowledgements.html
==============================================================================
--- (empty file)
+++ trunk/libs/scope_exit/doc/html/scope_exit/Acknowledgements.html 2012-02-14 20:23:13 EST (Tue, 14 Feb 2012)
@@ -0,0 +1,75 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Acknowledgements</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">
+<link rel="prev" href="No_Variadic_Macros.html" title="Annex: No Variadic Macros">
+</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="No_Variadic_Macros.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a>
+</div>
+<div class="section scope_exit_Acknowledgements">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="scope_exit.Acknowledgements"></a><a class="link" href="Acknowledgements.html" title="Acknowledgements">Acknowledgements</a>
+</h2></div></div></div>
+
+ Alexander Nasonov is the original library author.
+ 
+
+ Lorenzo Caminiti added variadic macro support, capture of the object <code class="computeroutput">this_</code>, empty captures using <code class="computeroutput">void</code>, and <code class="computeroutput">BOOST_SCOPE_EXIT_ALL</code>.
+ 
+
+ Thanks to the following people (in chronological order).
+ 
+
+ Maxim Yegorushkin for sharing code where he used a local struct to clean up
+ resources.
+ 
+
+ Andrei Alexandrescu for pointing out the 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.
+ 
+
+ Adam Butcher for a workaround to error C2355 when deducing the type of <code class="computeroutput">this</code> on some MSVC versions.
+ 
+</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-2012 Alexander Nasonov, Lorenzo Caminiti
+ Distributed under the Boost Software License, Version 1.0 (see accompanying
+ file LICENSE_1_0.txt or a copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="No_Variadic_Macros.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/scope_exit/doc/html/scope_exit/Getting_Started.html
==============================================================================
--- (empty file)
+++ trunk/libs/scope_exit/doc/html/scope_exit/Getting_Started.html 2012-02-14 20:23:13 EST (Tue, 14 Feb 2012)
@@ -0,0 +1,102 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Getting Started</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">
+<link rel="prev" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">
+<link rel="next" href="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="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Tutorial.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+<div class="section scope_exit_Getting_Started">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="scope_exit.Getting_Started"></a><a class="link" href="Getting_Started.html" title="Getting Started">Getting Started</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><a href="Getting_Started.html#scope_exit.Getting_Started.compilers_and_platforms">Compilers
+ and Platforms</a></dt>
+<dt>Installation</dt>
+</dl></div>
+
+ This section explains how to setup a system to use this library.
+ 
+<div class="section scope_exit_Getting_Started_compilers_and_platforms">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="scope_exit.Getting_Started.compilers_and_platforms"></a><a class="link" href="Getting_Started.html#scope_exit.Getting_Started.compilers_and_platforms" title="Compilers and Platforms">Compilers
+ and Platforms</a>
+</h3></div></div></div>
+
+ The library should be usable on any compiler that supports Boost.Typeof
+ except:
+ 
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+ MSVC 7.1 and 8.0 fail to link if a function with <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ is included by multiple translation units. Furthermore, on MSVC 7.1 and
+ 8.0 it is possible to capture the object <code class="computeroutput">this_</code>
+ only with native Boost.Typeof
+ (and not in type-of emulation
+ mode).
+ </li>
+<li class="listitem">
+ GCC 3.3 cannot compile <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ inside a template (see http://lists.boost.org/Archives/boost/2007/02/116235.php
+ for more details).
+ </li>
+</ul></div>
+
+ The authors tested the library on GCC 3.3, 3.4, 4.1, 4.2, 4.5.3 (with and
+ without C++11 features <code class="literal">-std=c++0x</code>), MSVC 8.0, and Intel
+ 10.1 under Linux, Cygwin, and Windows 7.
+ 
+</div>
+<div class="section scope_exit_Getting_Started_installation">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="scope_exit.Getting_Started.installation"></a><a class="link" href="Getting_Started.html#scope_exit.Getting_Started.installation" title="Installation">Installation</a>
+</h3></div></div></div>
+
+ This library is composed of header files only. Therefore there is no pre-compiled
+ object file which needs to be installed. Programmers can simply instruct
+ the compiler where to find the library header files (<code class="computeroutput">-I</code> option on GCC, <code class="computeroutput">/I</code> option on MSVC, etc) and compile code
+ using the library.
+ 
+
+ The library implementation uses Boost.Typeof
+ to automatically deduce the types of the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ captured variables (see the <a class="link" href="Tutorial.html" title="Tutorial">Tutorial</a>
+ section). In order to compile code in <a href="http://www.boost.org/libs/typeof" target="_top">type-of
+ emulation</a> mode, all types should be properly registered with BOOST_TYPEOF_REGISTER_TYPE
+ or BOOST_TYPEOF_REGISTER_TEMPLATE
+ macros, or appropriate Boost.Typeof
+ headers should be included.
+ 
+</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-2012 Alexander Nasonov, Lorenzo Caminiti
+ Distributed under the Boost Software License, Version 1.0 (see accompanying
+ file LICENSE_1_0.txt or a copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Tutorial.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Added: trunk/libs/scope_exit/doc/html/scope_exit/No_Variadic_Macros.html
==============================================================================
--- (empty file)
+++ trunk/libs/scope_exit/doc/html/scope_exit/No_Variadic_Macros.html 2012-02-14 20:23:13 EST (Tue, 14 Feb 2012)
@@ -0,0 +1,191 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Annex: No Variadic Macros</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">
+<link rel="prev" href="Alternatives.html" title="Annex: Alternatives">
+<link rel="next" href="Acknowledgements.html" title="Acknowledgements">
+</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/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Acknowledgements.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+<div class="section scope_exit_No_Variadic_Macros">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="scope_exit.No_Variadic_Macros"></a><a class="link" href="No_Variadic_Macros.html" title="Annex: No Variadic Macros">Annex: No Variadic Macros</a>
+</h2></div></div></div>
+
+ This section presents an alternative syntax for compilers without variadic
+ macro support.
+ 
+<h6>
+<a name="scope_exit.No_Variadic_Macros.h0"></a>
+ <a name="scope_exit.No_Variadic_Macros.sequence_syntax"></a><a class="link" href="No_Variadic_Macros.html#scope_exit.No_Variadic_Macros.sequence_syntax">Sequence
+ Syntax</a>
+ </h6>
+
+ Most modern compilers support variadic macros (notably, these include GCC,
+ MSVC, and all C++11 compilers). However, in the rare case that programmers
+ need to use this library on a complier without variaidc macros, this library
+ also allows to specify the capture list using a Boost.Preprocessor
+ sequence where tokens are separated by round parenthesis <code class="computeroutput">()</code>:
+ 
+<pre class="programlisting">(capture1) (capture2) ... // All compilers.
+</pre>
+
+ Instead of the comma-separated list that we have seen so far which requires
+ variadic macros:
+ 
+<pre class="programlisting">capture1, capture2, ... // Only compilers with variadic macros.
+</pre>
+
+ For example, the following syntax is accepted on all compilers with and without
+ variadic macros (see also world_seq.cpp):
+ 
+
+
+<pre class="programlisting">void world::add_person(person const& a_person) {
+ bool commit = false;
+
+ persons_.push_back(a_person);
+ BOOST_SCOPE_EXIT( (&commit) (&persons_) ) {
+ if(!commit) persons_.pop_back();
+ } BOOST_SCOPE_EXIT_END
+
+ // ...
+
+ commit = true;
+}
+</pre>
+
+ 
+
+ Furthermore, older versions of this library used to only support the Boost.Preprocessor sequence
+ syntax so the above syntax is also supported for backward compatibility. However,
+ in the current version of this library and on compilers with variadic macros,
+ the comma-separated syntax we have seen so far is preferred because more readable
+ (see also world.cpp):
+ 
+
+
+<pre class="programlisting">void world::add_person(person const& a_person) {
+ bool commit = false;
+
+ persons_.push_back(a_person); // (1) direct action
+ // Following block is executed when the enclosing scope exits.
+ BOOST_SCOPE_EXIT(&commit, &persons_) {
+ if(!commit) persons_.pop_back(); // (2) rollback action
+ } BOOST_SCOPE_EXIT_END
+
+ // ... // (3) other operations
+
+ commit = true; // (4) disable rollback actions
+}
+</pre>
+
+ 
+
+ Note how the same macros accept both syntaxes on compilers with variadic macros
+ and only the Boost.Preprocessor
+ sequence syntax on compilers without variadic macros. Finally, an empty capture
+ list is always specified using <code class="computeroutput">void</code>
+ on compilers with and without variaidc macros (see also world_void.cpp):
+ 
+
+
+<pre class="programlisting">struct world_t {
+ std::vector<person> persons;
+ bool commit;
+} world; // Global variable.
+
+void add_person(person const& a_person) {
+ world.commit = false;
+ world.persons.push_back(a_person);
+
+ BOOST_SCOPE_EXIT(void) { // No captures.
+ if(!world.commit) world.persons.pop_back();
+ } BOOST_SCOPE_EXIT_END
+
+ // ...
+
+ world.commit = true;
+}
+</pre>
+
+ 
+<h6>
+<a name="scope_exit.No_Variadic_Macros.h1"></a>
+ <a name="scope_exit.No_Variadic_Macros.examples"></a><a class="link" href="No_Variadic_Macros.html#scope_exit.No_Variadic_Macros.examples">Examples</a>
+ </h6>
+
+ The following is a list of most of the examples presented in this documentation
+ reprogrammed using the Boost.Preprocessor
+ sequence syntax instead of the comma-separated list:
+ 
+<div class="informaltable"><table class="table">
+<colgroup><col></colgroup>
+<thead><tr><th>
+ 
+ Files
+ 
+ </th></tr></thead>
+<tbody>
+<tr><td>
+ 
+ world_checkpoint_seq.cpp
+ 
+ </td></tr>
+<tr><td>
+ 
+ world_this_seq.cpp
+ 
+ </td></tr>
+<tr><td>
+ 
+ world_checkpoint_all_seq.cpp
+ 
+ </td></tr>
+<tr><td>
+ 
+ world_tpl_seq.cpp
+ 
+ </td></tr>
+<tr><td>
+ 
+ try_catch_seq.cpp
+ 
+ </td></tr>
+<tr><td>
+ 
+ scope_guard_seq.cpp
+ 
+ </td></tr>
+</tbody>
+</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-2012 Alexander Nasonov, Lorenzo Caminiti
+ Distributed under the Boost Software License, Version 1.0 (see accompanying
+ file LICENSE_1_0.txt or a copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="Alternatives.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="Acknowledgements.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></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 2012-02-14 20:23:13 EST (Tue, 14 Feb 2012)
@@ -0,0 +1,318 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Annex: Alternatives</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">
+<link rel="prev" href="../BOOST_SCOPE_EXIT_CONFIG_NO_CPP11.html" title="Macro BOOST_SCOPE_EXIT_CONFIG_NO_CPP11">
+<link rel="next" href="No_Variadic_Macros.html" title="Annex: No Variadic Macros">
+</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="../BOOST_SCOPE_EXIT_CONFIG_NO_CPP11.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="No_Variadic_Macros.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+<div class="section scope_exit_Alternatives">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="scope_exit.Alternatives"></a><a class="link" href="Alternatives.html" title="Annex: Alternatives">Annex: Alternatives</a>
+</h2></div></div></div>
+
+ This section presents some alternatives and work related to <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>.
+ 
+<h6>
+<a name="scope_exit.Alternatives.h0"></a>
+ <a name="scope_exit.Alternatives.try_catch"></a><a class="link" href="Alternatives.html#scope_exit.Alternatives.try_catch">Try-Catch</a>
+ </h6>
+
+ This is an example of using a badly designed <code class="computeroutput">file</code>
+ class. An instance of <code class="computeroutput">file</code>
+ does not close the file in its destructor, a programmer is expected to call
+ the <code class="computeroutput">close</code> member function explicitly.
+ For example (see also try_catch.cpp):
+ 
+
+
+<pre class="programlisting">file passwd;
+try {
+ passwd.open("/etc/passwd");
+ // ...
+ passwd.close();
+} catch(...) {
+ std::clog << "could not get user info" << std::endl;
+ if(passwd.is_open()) passwd.close();
+ throw;
+}
+</pre>
+
+ 
+
+ Note the following issues with this approach:
+ 
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+ 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 class="listitem">
+ The <code class="computeroutput">passwd</code> object is not
+ fully constructed until after the <code class="computeroutput">open</code>
+ member function returns.
+ </li>
+<li class="listitem">
+ 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>
+
+ The <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a> approach does not have
+ any of these issues. For example (see also try_catch.cpp):
+ 
+
+
+<pre class="programlisting">try {
+ file passwd("/etc/passwd");
+ BOOST_SCOPE_EXIT(&passwd) {
+ passwd.close();
+ } BOOST_SCOPE_EXIT_END
+} catch(...) {
+ std::clog << "could not get user info" << std::endl;
+ throw;
+}
+</pre>
+
+ 
+<h6>
+<a name="scope_exit.Alternatives.h1"></a>
+ <a name="scope_exit.Alternatives.raii"></a><a class="link" href="Alternatives.html#scope_exit.Alternatives.raii">RAII</a>
+ </h6>
+
+ 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(...) {
+ std::clog << "could not get user info" << std::endl;
+ 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">persons_.push_back(a_person);
+pop_back_if_not_commit pop_back_if_not_commit_guard(commit, 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 commit_;
+ std::vector<person>& vec_;
+ // ...
+ ~pop_back_if_not_commit() {
+ if(!commit_) 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> superman_ptr(new superman());
+persons_.push_back(superman_ptr.get());
+superman_ptr.release(); // persons_ successfully took ownership
+</pre>
+
+ Or with specialized containers such as Boost.PointerContainer
+ or Boost.Multi-Index.
+ 
+<h6>
+<a name="scope_exit.Alternatives.h2"></a>
+ <a name="scope_exit.Alternatives.scope_guards"></a><a class="link" href="Alternatives.html#scope_exit.Alternatives.scope_guards">Scope
+ Guards</a>
+ </h6>
+
+ Imagine that a new currency rate is introduced before performing a transaction:
+ 
+
+
+<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;
+// Transaction...
+</pre>
+
+ 
+
+ If the transaction does not complete, the currency must be erased from <code class="computeroutput">rates</code>. This can be done with ScopeGuard
+ and Boost.Lambda (or
+ Boost.Phoenix):
+ 
+<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 the following issues with this approach:
+ 
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+ Boost.Lambda expressions
+ are hard to write correctly (e.g., overloaded functions must be explicitly
+ casted, as demonstrated in the example above).
+ </li>
+<li class="listitem">
+ The condition in the <code class="computeroutput">if_</code>
+ expression refers to <code class="computeroutput">commit</code>
+ variable indirectly through the <code class="computeroutput">_1</code>
+ placeholder reducing readability.
+ </li>
+<li class="listitem">
+ 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 C++11 lambdas:
+ 
+<pre class="programlisting">ON_BLOCK_EXIT(
+ [currency_rate_inserted, &commit, &rates, &currency]() {
+ if(currency_rate_inserted && !commit) rates.erase(currency);
+ }
+);
+
+// ...
+
+commit = true;
+</pre>
+
+ With <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a> we can simply do the
+ following (see also scope_guard.cpp):
+ 
+
+
+<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>
+
+ 
+<h6>
+<a name="scope_exit.Alternatives.h3"></a>
+ <a name="scope_exit.Alternatives.the_d_programming_language"></a><a class="link" href="Alternatives.html#scope_exit.Alternatives.the_d_programming_language">The
+ D Programming Language</a>
+ </h6>
+
+ <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a> is similar to scope(exit)
+ feature built into the D
+ programming language.
+ 
+
+ A curious reader may notice that the library does not implement <code class="computeroutput">scope(success)</code> and <code class="computeroutput">scope(failure)</code> of the D
+ language. Unfortunately, these are not possible in C++ because failure or success
+ conditions cannot be determined by calling <code class="computeroutput">std::uncaught_exception</code>
+ (see 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). However, this is not a big problem because
+ these two D's
+ constructs can be expressed in terms of scope(exit)
+ and a <code class="computeroutput">bool commit</code>
+ variable as explained in the <a class="link" href="Tutorial.html" title="Tutorial">Tutorial</a>
+ section.
+ 
+<h6>
+<a name="scope_exit.Alternatives.h4"></a>
+ <a name="scope_exit.Alternatives.c__11_lambdas"></a><a class="link" href="Alternatives.html#scope_exit.Alternatives.c__11_lambdas">C++11
+ Lambdas</a>
+ </h6>
+
+ Using C++11 lambdas, it is relatively easy to implement the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ construct. For example (see also world_lambda.cpp):
+ 
+
+
+<pre class="programlisting">#include <functional>
+
+struct scope_exit {
+ scope_exit(std::function<void (void)> f) : f_(f) {}
+ ~scope_exit(void) { f_(); }
+private:
+ std::function<void (void)> f_;
+};
+
+void world::add_person(person const& a_person) {
+ bool commit = false;
+
+ persons_.push_back(a_person);
+ scope_exit on_exit1([&commit, &persons_]() { // Use C++11 lambda.
+ if(!commit) persons_.pop_back();
+ });
+
+ // ...
+
+ commit = true;
+}
+</pre>
+
+ 
+
+ However, this library allows to program the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ construct in a way that is portable between C++03 and C++11 compilers.
+ 
+</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-2012 Alexander Nasonov, Lorenzo Caminiti
+ Distributed under the Boost Software License, Version 1.0 (see accompanying
+ file LICENSE_1_0.txt or a copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../BOOST_SCOPE_EXIT_CONFIG_NO_CPP11.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="No_Variadic_Macros.html"><img src="../../../../../doc/src/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 2012-02-14 20:23:13 EST (Tue, 14 Feb 2012)
@@ -0,0 +1,434 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Tutorial</title>
+<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
+<link rel="home" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">
+<link rel="prev" href="Getting_Started.html" title="Getting Started">
+<link rel="next" href="../reference.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="Getting_Started.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../reference.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+<div class="section scope_exit_Tutorial">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="scope_exit.Tutorial"></a><a class="link" href="Tutorial.html" title="Tutorial">Tutorial</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt>Capturing Variables</dt>
+<dt><a href="Tutorial.html#scope_exit.Tutorial.capturing_the_object__this_">Capturing
+ The Object <code class="computeroutput">this</code></a></dt>
+<dt><a href="Tutorial.html#scope_exit.Tutorial.capturing_no_variable">Capturing
+ No Variable</a></dt>
+<dt><a href="Tutorial.html#scope_exit.Tutorial.capturing_all_variables__c__11_only_">Capturing
+ All Variables (C++11 Only)</a></dt>
+<dt><a href="Tutorial.html#scope_exit.Tutorial.gcc_template_workaround">GCC Template
+ Workaround</a></dt>
+</dl></div>
+
+ This section illustrates how to use this library.
+ 
+<div class="section scope_exit_Tutorial_capturing_variables">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="scope_exit.Tutorial.capturing_variables"></a><a class="link" href="Tutorial.html#scope_exit.Tutorial.capturing_variables" title="Capturing Variables">Capturing Variables</a>
+</h3></div></div></div>
+
+ Imagine that we want to make many modifications to data members of some
+ <code class="computeroutput">world</code> class in its <code class="computeroutput">world::add_person</code> member function. We start with
+ adding a new <code class="computeroutput">person</code> object
+ to a vector of persons:
+ 
+<pre class="programlisting">void world::add_person(person const& a_person) {
+ bool commit = false;
+
+ persons_.push_back(a_person); // (1) direct action
+ ...
+</pre>
+
+ Some operations 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, the last added person must be deleted from <code class="computeroutput">persons_</code>
+ if the function throws. All we need is to define a delayed action (release
+ of a resource) right after the direct action (resource acquisition). For
+ example (see also world.cpp):
+ 
+
+
+<pre class="programlisting">void world::add_person(person const& a_person) {
+ bool commit = false;
+
+ persons_.push_back(a_person); // (1) direct action
+ // Following block is executed when the enclosing scope exits.
+ BOOST_SCOPE_EXIT(&commit, &persons_) {
+ if(!commit) persons_.pop_back(); // (2) rollback action
+ } BOOST_SCOPE_EXIT_END
+
+ // ... // (3) other operations
+
+ commit = true; // (4) disable rollback actions
+}
+</pre>
+
+ 
+
+ The block below point <code class="literal">(1)</code> is a <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ declaration. Unlike point <code class="literal">(1)</code>, an execution of the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.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="literal">(4)</code> or on any exception. (On various versions of the GCC
+ compiler, it is necessary to use <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_TPL.html" title="Macro BOOST_SCOPE_EXIT_TPL">BOOST_SCOPE_EXIT_TPL</a></code>
+ instead of <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT.html" title="Macro BOOST_SCOPE_EXIT">BOOST_SCOPE_EXIT</a></code>
+ within templates, see later in this section for details.)
+ 
+
+ The <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a> declaration starts
+ with the <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT.html" title="Macro BOOST_SCOPE_EXIT">BOOST_SCOPE_EXIT</a></code> macro
+ invocation which accepts a comma-separated list of captured variables (a
+ Boost.Preprocessor
+ sequence is also accepted here for compilers that do not support variadic
+ macros and for backward compatibility with older versions of this library,
+ see the <a class="link" href="No_Variadic_Macros.html" title="Annex: No Variadic Macros">No Variadic Macros</a>
+ section). 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 1.1.0">Boost.ScopeExit</a>
+ body; otherwise, a copy of the variable will be made after the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ declaration at point <code class="literal">(1)</code> and only the copy will be available
+ inside the body (in this case, the captured variable's type must be <code class="computeroutput">CopyConstructible</code>).
+ 
+
+ In the example above, the variables <code class="computeroutput">commit</code>
+ and <code class="computeroutput">persons_</code> are captured
+ by reference because the final value of the <code class="computeroutput">commit</code>
+ variable should be used to determine whether to execute rollback actions
+ or not and the action should modify the <code class="computeroutput">persons_</code>
+ object, not its copy. This is the most common case but passing a variable
+ by value is sometimes useful as well.
+ 
+
+ Finally, the end of the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ body must be marked by the <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_END.html" title="Macro BOOST_SCOPE_EXIT_END">BOOST_SCOPE_EXIT_END</a></code>
+ macro which must follow the closing curly bracket <code class="computeroutput">}</code>
+ of the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a> body. On C++11 it
+ is also possible (but not required) to use a semi-column <code class="computeroutput">;</code>
+ instead of the <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_END.html" title="Macro BOOST_SCOPE_EXIT_END">BOOST_SCOPE_EXIT_END</a></code>
+ macro. [<a name="scope_exit.Tutorial.capturing_variables.f0" href="#ftn.scope_exit.Tutorial.capturing_variables.f0" class="footnote">2</a>]
+ 
+<div class="important"><table border="0" summary="Important">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
+<th align="left">Important</th>
+</tr>
+<tr><td align="left" valign="top">
+ In order to comply with the STL exception safety requirements, the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a> body must never throw (because
+ the library implementation executes the body within a destructor). This
+ is true for all <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a> macros
+ (including <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_TPL.html" title="Macro BOOST_SCOPE_EXIT_TPL">BOOST_SCOPE_EXIT_TPL</a></code>
+ and <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_ALL.html" title="Macro BOOST_SCOPE_EXIT_ALL">BOOST_SCOPE_EXIT_ALL</a></code>)
+ on both C++03 and C++11.
+ </td></tr>
+</table></div>
+
+ Consider a more complex example where <code class="computeroutput">world::add_person</code>
+ can save intermediate states at some point and roll back to the last saved
+ state. We use <code class="computeroutput">person::evolution_</code> to store a version of the changes
+ and increment it to cancel all rollback actions associated with those changes.
+ If we pass a current value of <code class="computeroutput">evolution_</code>
+ stored in the <code class="computeroutput">checkpoint</code>
+ variable by value, it remains unchanged within the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ body so we can compare it with the final value of <code class="computeroutput">evolution_</code>.
+ If the latter was not incremented since we saved it, the rollback action
+ inside the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a> body should
+ be executed. For example (see also world_checkpoint.cpp):
+ 
+
+
+<pre class="programlisting">void world::add_person(person const& a_person) {
+ persons_.push_back(a_person);
+
+ // This block must be no-throw.
+ person& p = persons_.back();
+ person::evolution_t checkpoint = p.evolution_;
+ BOOST_SCOPE_EXIT(checkpoint, &p, &persons_) {
+ if(checkpoint == p.evolution_) persons_.pop_back();
+ } BOOST_SCOPE_EXIT_END
+
+ // ...
+
+ checkpoint = ++p.evolution_;
+
+ // Assign new identifier to the person.
+ world::id_t const prev_id = p.id_;
+ p.id_ = next_id_++;
+ BOOST_SCOPE_EXIT(checkpoint, &p, &next_id_, prev_id) {
+ if(checkpoint == p.evolution_) {
+ next_id_ = p.id_;
+ p.id_ = prev_id;
+ }
+ } BOOST_SCOPE_EXIT_END
+
+ // ...
+
+ checkpoint = ++p.evolution_;
+}
+</pre>
+
+ 
+
+ When multiple <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a> blocks are
+ declared within the same enclosing scope, the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ bodies are executed in the reversed order of their declarations.
+ 
+</div>
+<div class="section scope_exit_Tutorial_capturing_the_object__this_">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="scope_exit.Tutorial.capturing_the_object__this_"></a><a class="link" href="Tutorial.html#scope_exit.Tutorial.capturing_the_object__this_" title="Capturing The Object this">Capturing
+ The Object <code class="computeroutput">this</code></a>
+</h3></div></div></div>
+
+ Within a member function, it is also possible to capture the object <code class="computeroutput">this</code>. However, the special symbol <code class="computeroutput">this_</code> must be used instead of <code class="computeroutput">this</code> in the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ declaration and body to capture and access the object. For example (see also
+ world_this.cpp):
+ 
+
+
+<pre class="programlisting">BOOST_SCOPE_EXIT(&commit, this_) { // Capture object `this_`.
+ if(!commit) this_->persons_.pop_back();
+} BOOST_SCOPE_EXIT_END
+</pre>
+
+ 
+
+ On C++11, it is possible (but not required) to directly use <code class="computeroutput">this</code> instead of the special symbol <code class="computeroutput">this_</code>. [<a name="scope_exit.Tutorial.capturing_the_object__this_.f0" href="#ftn.scope_exit.Tutorial.capturing_the_object__this_.f0" class="footnote">3</a>] For example (see also world_this.cpp):
+ 
+
+
+<pre class="programlisting">BOOST_SCOPE_EXIT(&commit, this) { // Use `this` (C++11).
+ if(!commit) this->persons_.pop_back();
+}; // Use `;` instead of `BOOST_SCOPE_EXIT_END` (C++11).
+</pre>
+
+ 
+
+ It is never possible to capture the object <code class="computeroutput">this_</code>
+ (or <code class="computeroutput">this</code>) by reference because
+ C++ does not allow to take a reference to <code class="computeroutput">this</code>.
+ If the enclosing member function is constant then the captured object will
+ also be constant, otherwise the captured object will be mutable.
+ 
+</div>
+<div class="section scope_exit_Tutorial_capturing_no_variable">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="scope_exit.Tutorial.capturing_no_variable"></a><a class="link" href="Tutorial.html#scope_exit.Tutorial.capturing_no_variable" title="Capturing No Variable">Capturing
+ No Variable</a>
+</h3></div></div></div>
+
+ It is possible to declare <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ code that captures no variable. In this case, the list of captured variables
+ is replaced by the <code class="computeroutput">void</code> keyword
+ (similarly to the C syntax that allows to declare a function with no parameter
+ using <code class="literal">result-type function-name</code><code class="computeroutput">(void)</code>).
+ [<a name="scope_exit.Tutorial.capturing_no_variable.f0" href="#ftn.scope_exit.Tutorial.capturing_no_variable.f0" class="footnote">4</a>] For example, this can be useful when the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ body only needs to access global variables (see also world_void.cpp):
+ 
+
+
+<pre class="programlisting">struct world_t {
+ std::vector<person> persons;
+ bool commit;
+} world; // Global variable.
+
+void add_person(person const& a_person) {
+ world.commit = false;
+ world.persons.push_back(a_person);
+
+ BOOST_SCOPE_EXIT(void) { // No captures.
+ if(!world.commit) world.persons.pop_back();
+ } BOOST_SCOPE_EXIT_END
+
+ // ...
+
+ world.commit = true;
+}
+</pre>
+
+ 
+
+ This same syntax is supported for both compilers with and without variadic
+ macro support.
+ 
+</div>
+<div class="section scope_exit_Tutorial_capturing_all_variables__c__11_only_">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="scope_exit.Tutorial.capturing_all_variables__c__11_only_"></a><a class="link" href="Tutorial.html#scope_exit.Tutorial.capturing_all_variables__c__11_only_" title="Capturing All Variables (C++11 Only)">Capturing
+ All Variables (C++11 Only)</a>
+</h3></div></div></div>
+
+ On C++11 compliers, it is also possible to capture all the variables in scope
+ without naming them one by one using the special macro <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_ALL.html" title="Macro BOOST_SCOPE_EXIT_ALL">BOOST_SCOPE_EXIT_ALL</a></code>
+ instead of <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT.html" title="Macro BOOST_SCOPE_EXIT">BOOST_SCOPE_EXIT</a></code>.
+ [<a name="scope_exit.Tutorial.capturing_all_variables__c__11_only_.f0" href="#ftn.scope_exit.Tutorial.capturing_all_variables__c__11_only_.f0" class="footnote">5</a>]
+ 
+
+ Following the same syntax adopted by C++11 lambdas, the <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_ALL.html" title="Macro BOOST_SCOPE_EXIT_ALL">BOOST_SCOPE_EXIT_ALL</a></code>
+ macro accepts a comma-separated list of captures which must start with either
+ <code class="computeroutput">&</code> or <code class="computeroutput">=</code>
+ to capture all variables in scope respectively by reference or by value (note
+ that no variable name is specified by these leading captures). Additional
+ captures of specific variables can follow the leading <code class="computeroutput">&</code>
+ or <code class="computeroutput">=</code> and they will override
+ the default reference or value captures. For example (see also world_checkpoint_all.cpp):
+ 
+
+
+<pre class="programlisting">void world::add_person(person const& a_person) {
+ persons_.push_back(a_person);
+
+ // This block must be no-throw.
+ person& p = persons_.back();
+ person::evolution_t checkpoint = p.evolution_;
+ BOOST_SCOPE_EXIT_ALL(&, checkpoint, this_) { // Capture all by ref (C++11).
+ if(checkpoint == p.evolution_) this_->persons_.pop_back();
+ } BOOST_SCOPE_EXIT_END
+
+ // ...
+
+ checkpoint = ++p.evolution_;
+
+ // Assign new identifier to the person.
+ world::id_t const prev_id = p.id_;
+ p.id_ = next_id_++;
+ BOOST_SCOPE_EXIT_ALL(=, &p, this) { // Capture all by value, `this` (C++11).
+ if(checkpoint == p.evolution_) {
+ this->next_id_ = p.id_;
+ p.id_ = prev_id;
+ }
+ }; // Use `;` instead of `SCOPE_EXIT_END` (C++11).
+
+ // ...
+
+ checkpoint = ++p.evolution_;
+}
+</pre>
+
+ 
+
+ The first <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a> declaration captures
+ all variables in scope by reference but <code class="computeroutput">checkpoint</code>
+ and <code class="computeroutput">this_</code> which are explicitly
+ captured by value (in particular, <code class="computeroutput">p</code>
+ and <code class="computeroutput">persons_</code> are captured
+ by reference). The second <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ declaration instead captures all variables in scope by value but <code class="computeroutput">p</code> which is captured by reference (in particular,
+ <code class="computeroutput">checkpoint</code>, <code class="computeroutput">prev_id</code>, and <code class="computeroutput">this</code>
+ are captured by value).
+ 
+</div>
+<div class="section scope_exit_Tutorial_gcc_template_workaround">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="scope_exit.Tutorial.gcc_template_workaround"></a><a class="link" href="Tutorial.html#scope_exit.Tutorial.gcc_template_workaround" title="GCC Template Workaround">GCC Template
+ Workaround</a>
+</h3></div></div></div>
+
+ Various versions of the GCC compiler do not compile <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT.html" title="Macro BOOST_SCOPE_EXIT">BOOST_SCOPE_EXIT</a></code>
+ inside templates (see the Reference section
+ for more information). As a workaround, <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_TPL.html" title="Macro BOOST_SCOPE_EXIT_TPL">BOOST_SCOPE_EXIT_TPL</a></code>
+ should be used instead of <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT.html" title="Macro BOOST_SCOPE_EXIT">BOOST_SCOPE_EXIT</a></code>
+ in these cases: [<a name="scope_exit.Tutorial.gcc_template_workaround.f0" href="#ftn.scope_exit.Tutorial.gcc_template_workaround.f0" class="footnote">6</a>]
+ 
+
+
+<pre class="programlisting">template<typename Person>
+void world<Person>::add_person(Person const& a_person) {
+ bool commit = false;
+ persons_.push_back(a_person);
+
+ BOOST_SCOPE_EXIT_TPL(&commit, this_) { // Use `_TPL` postfix.
+ if(!commit) this_->persons_.pop_back();
+ } BOOST_SCOPE_EXIT_END
+
+ // ...
+
+ commit = true;
+}
+</pre>
+
+ 
+
+ The <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_TPL.html" title="Macro BOOST_SCOPE_EXIT_TPL">BOOST_SCOPE_EXIT_TPL</a></code>
+ macro has the exact same syntax of <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT.html" title="Macro BOOST_SCOPE_EXIT">BOOST_SCOPE_EXIT</a></code>.
+ 
+</div>
+<div class="footnotes">
+ <hr width="100" align="left">
+<div class="footnote">[<a id="ftn.scope_exit.Tutorial.capturing_variables.f0" href="#scope_exit.Tutorial.capturing_variables.f0" class="para">2</a>] 
+ The macro <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_END.html" title="Macro BOOST_SCOPE_EXIT_END">BOOST_SCOPE_EXIT_END</a></code>
+ can still be used on C++11 to write portable code that can be used on both
+ C++03 and C++11 compilers. Using <code class="computeroutput">;</code>
+ instead of <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_END.html" title="Macro BOOST_SCOPE_EXIT_END">BOOST_SCOPE_EXIT_END</a></code>
+ on C++03 compilers will generate a (possibly cryptic) compiler error.
+ </div>
+<div class="footnote">[<a id="ftn.scope_exit.Tutorial.capturing_the_object__this_.f0" href="#scope_exit.Tutorial.capturing_the_object__this_.f0" class="para">3</a>] 
+ The special symbol <code class="computeroutput">this_</code>
+ can still be used on C++11 to write portable code that can be used on both
+ C++03 and C++11 compilers. Unfortunately, using <code class="computeroutput">this</code>
+ instead of <code class="computeroutput">this_</code> on C++03
+ compilers leads to undefined behaviour (it will likely generate a compiler
+ error but that is not guaranteed).
+ </div>
+<div class="footnote">[<a id="ftn.scope_exit.Tutorial.capturing_no_variable.f0" href="#scope_exit.Tutorial.capturing_no_variable.f0" class="para">4</a>] 
+ Rationale. Unfortunately, it is not possible
+ to simply invoke the <a class="link" href="../index.html" title="Chapter 1. Boost.ScopeExit 1.1.0">Boost.ScopeExit</a>
+ macro with no parameters <code class="computeroutput">BOOST_SCOPE_EXIT()</code> because the preprocessor cannot detect
+ emptiness of a macro parameter when the parameter can start with a non-alphanumeric
+ symbol (which is the case when capturing a variable by reference <code class="computeroutput">&variable</code>).
+ </div>
+<div class="footnote">[<a id="ftn.scope_exit.Tutorial.capturing_all_variables__c__11_only_.f0" href="#scope_exit.Tutorial.capturing_all_variables__c__11_only_.f0" class="para">5</a>] 
+ Rationale. The <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_ALL.html" title="Macro BOOST_SCOPE_EXIT_ALL">BOOST_SCOPE_EXIT_ALL</a></code>
+ macro is only defined on C++11 compilers. Using <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_ALL.html" title="Macro BOOST_SCOPE_EXIT_ALL">BOOST_SCOPE_EXIT_ALL</a></code>
+ on C++03 compilers will generate a (possibly cryptic) compiler error. Note
+ that a new macro <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_ALL.html" title="Macro BOOST_SCOPE_EXIT_ALL">BOOST_SCOPE_EXIT_ALL</a></code>
+ needed to be introduced instead of reusing <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT.html" title="Macro BOOST_SCOPE_EXIT">BOOST_SCOPE_EXIT</a></code>
+ because <code class="computeroutput">BOOST_SCOPE_EXIT(&)</code> and <code class="computeroutput">BOOST_SCOPE_EXIT(=)</code> could not be distinguished from <code class="computeroutput">BOOST_SCOPE_EXIT(void)</code> or
+ <code class="computeroutput">BOOST_SCOPE_EXIT(this_)</code>
+ using the preprocessor because the symbols <code class="computeroutput">&</code>
+ and <code class="computeroutput">=</code> are neither prefxied
+ or postfixed by alphanumeric tokens (this is not an issue for <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_ALL.html" title="Macro BOOST_SCOPE_EXIT_ALL">BOOST_SCOPE_EXIT_ALL</a></code> which always
+ has <code class="computeroutput">&</code> or <code class="computeroutput">=</code> as the first capture so the first capture
+ token is never compared with neither <code class="computeroutput">void</code>
+ or <code class="computeroutput">this_</code> for this macro).
+ </div>
+<div class="footnote">[<a id="ftn.scope_exit.Tutorial.gcc_template_workaround.f0" href="#scope_exit.Tutorial.gcc_template_workaround.f0" class="para">6</a>] 
+ GCC versions compliant with C++11 do not present this issue and given that
+ <code class="computeroutput"><a class="link" href="../BOOST_SCOPE_EXIT_ALL.html" title="Macro BOOST_SCOPE_EXIT_ALL">BOOST_SCOPE_EXIT_ALL</a></code>
+ is only available on C++11 compilers, there is no need for a <code class="computeroutput">BOOST_SCOPE_EXIT_ALL_TPL</code> macro.
+ </div>
+</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-2012 Alexander Nasonov, Lorenzo Caminiti
+ Distributed under the Boost Software License, Version 1.0 (see accompanying
+ file LICENSE_1_0.txt or a copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="Getting_Started.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../reference.html"><img src="../../../../../doc/src/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