Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r56333 - in sandbox/stm/branches/vbe/libs/stm/doc: . html html/toward_boost_stm html/toward_boost_stm/appendices html/toward_boost_stm/overview html/toward_boost_stm/reference html/toward_boost_stm/users_guide reference
From: vicente.botet_at_[hidden]
Date: 2009-09-20 19:20:31

Next message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r56334 - sandbox/stm/branches/vbe/libs/stm/test"
Previous message: jeff_at_[hidden]: "[Boost-commit] svn:boost r56332 - in sandbox/explore: boost boost/explore libs/explore/doc"

Author: viboes
Date: 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
New Revision: 56333
URL: http://svn.boost.org/trac/boost/changeset/56333

Log:
TBoost.Stm vbe
* DRAFT documentation ongoing

Added:
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/base_transaction_hpp.html (contents, props changed)
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/non_tx_smart_ptr_hpp.html (contents, props changed)
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/transactional_object_hpp.html (contents, props changed)
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/tx_smart_ptr_hpp.html (contents, props changed)
Text files modified:
   sandbox/stm/branches/vbe/libs/stm/doc/Jamfile.v2 | 8
   sandbox/stm/branches/vbe/libs/stm/doc/acknowledgements.qbk | 2
   sandbox/stm/branches/vbe/libs/stm/doc/appendices.qbk | 6
   sandbox/stm/branches/vbe/libs/stm/doc/case_studies.qbk | 2
   sandbox/stm/branches/vbe/libs/stm/doc/getting_started.qbk | 7
   sandbox/stm/branches/vbe/libs/stm/doc/history.qbk | 4
   sandbox/stm/branches/vbe/libs/stm/doc/html/index.html | 12
   sandbox/stm/branches/vbe/libs/stm/doc/html/standalone_HTML.manifest | 5
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices.html | 6
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/changes.html | 4
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/implementation.html | 104 +
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/rationale.html | 1967 ++++++++++++++++++++++++++++++++++++++-
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/todo.html | 12
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/overview.html | 5
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/overview/intro.html | 791 ++++++++++++++++
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference.html | 66
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/base_contention_manager_hpp.html | 6
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/language_like_hpp.html | 16
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/transaction_hpp.html | 27
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/tx_ptr_hpp.html | 282 -----
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide.html | 8
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/ext_references.html | 19
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/getting_started.html | 12
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/glosary.html | 28
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/tutorial.html | 304 +++++
   sandbox/stm/branches/vbe/libs/stm/doc/implementation.qbk | 48
   sandbox/stm/branches/vbe/libs/stm/doc/installation.qbk | 10
   sandbox/stm/branches/vbe/libs/stm/doc/introduction.qbk | 318 +++++
   sandbox/stm/branches/vbe/libs/stm/doc/overview.qbk | 35
   sandbox/stm/branches/vbe/libs/stm/doc/rationale.qbk | 813 +++++++++++++++-
   sandbox/stm/branches/vbe/libs/stm/doc/reference/language_like.qbk | 68 -
   sandbox/stm/branches/vbe/libs/stm/doc/reference/smart_pointers.qbk | 165 +++
   sandbox/stm/branches/vbe/libs/stm/doc/reference/transaction.qbk | 20
   sandbox/stm/branches/vbe/libs/stm/doc/reference/transaction_object.qbk | 197 ++-
   sandbox/stm/branches/vbe/libs/stm/doc/references.qbk | 32
   sandbox/stm/branches/vbe/libs/stm/doc/tests.qbk | 2
   sandbox/stm/branches/vbe/libs/stm/doc/tickets.qbk | 2
   sandbox/stm/branches/vbe/libs/stm/doc/tutorial.qbk | 442 ++++----
   sandbox/stm/branches/vbe/libs/stm/doc/users_guide.qbk | 18
   39 files changed, 4854 insertions(+), 1019 deletions(-)

Modified: sandbox/stm/branches/vbe/libs/stm/doc/Jamfile.v2
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/Jamfile.v2 (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/Jamfile.v2 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,7 +1,7 @@
# Boost.LUID library documentation Jamfile ---------------------------------
#
-# Copyright Justin E. Gottchlich 2009.
-# Copyright Vicente J. Botet Escriba 2009.
+# Copyright Justin E. Gottchlich 2009.
+# Copyright Vicente J. Botet Escriba 2009.
# Use, modification and
# distribution is subject to the Boost Software License, Version
# 1.0. (See accompanying file LICENSE_1_0.txt or copy at
@@ -50,6 +50,10 @@
 # Use the main Boost stylesheet:
 <xsl:param>html.stylesheet=../../../../doc/html/boostbook.css

+ # TowardBoost.STM:
+ <xsl:param>boost.image.src=../image/Toward_Boost_STM.jpg
+ <xsl:param>boost.image.alt="\"TowardBoostSTM\""
+
 # PDF Options:
 # TOC Generation: this is needed for FOP-0.9 and later:
 #<xsl:param>fop1.extensions=1

Modified: sandbox/stm/branches/vbe/libs/stm/doc/acknowledgements.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/acknowledgements.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/acknowledgements.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,5 +1,5 @@
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
   (C) Copyright 2009 Vicente J. Botet Escriba
  /
  / Distributed under the Boost Software License, Version 1.0. (See accompanying

Modified: sandbox/stm/branches/vbe/libs/stm/doc/appendices.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/appendices.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/appendices.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,6 +1,6 @@
[/
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
   (C) Copyright 2009 Vicente J. Botet Escriba
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at
@@ -48,7 +48,7 @@
* Replace THREAD_ID by boost::thread_id
* [*DONE] Provide a unique array/tuple locker (Boost.Synchro)
* Replace var_auto_lock by boost::synchro::unique_array_locker
-* Replace auto_lock by boost::synchro::unique_locker and redefine use_lock macros
+* Replace auto_lock by boost::synchro::unique_locker and redefine use_lock macros
* use lock_guard when lock/unlock
* Adapt the pool to Boost.Pool
* [*DONE] Provide a thread specific shared pointer (Boost.Interthreads)
@@ -90,7 +90,7 @@
         * [*DONE] Write the A Dynamically Prioritized, Composed Transaction section
         * Write the Lock aware section
         * Write the Lock aware section
-
+
     * [*DONE] Write the References section
     * Write the Glossary section
* Write the Examples section

Modified: sandbox/stm/branches/vbe/libs/stm/doc/case_studies.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/case_studies.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/case_studies.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,5 +1,5 @@
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
   (C) Copyright 2009 Vicente J. Botet Escriba
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at

Modified: sandbox/stm/branches/vbe/libs/stm/doc/getting_started.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/getting_started.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/getting_started.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,6 +1,6 @@
[/
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
   (C) Copyright 2009 Vicente J. Botet Escriba
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at
@@ -31,9 +31,8 @@
         }
         return val;
     }
-
-In the above example, (A) both the write on counter and the read operations function atomically or neither operations are performed. In addition, (C) the transaction begins and ends in legal memory
-states, meaning global int is guaranteed to be read correctly, preventing thread data races from causing inconsistent results. Lastly, (I) the intermediate state of the incremented global int is isolated until the transaction commits. These three attributes fulfill __Boost_STM_s__ conformance to the ACI principles. The above example also gives a basic introduction into __Boost_STM_s__ transactional framework.
+
+In the above example, (A) both the write on counter and the read operations function atomically or neither operations are performed. In addition, (C) the transaction begins and ends in legal memory states, meaning global int is guaranteed to be read correctly, preventing thread data races from causing inconsistent results. Lastly, (I) the intermediate state of the incremented global int is isolated until the transaction commits. These three attributes fulfill __Boost_STM_s__ conformance to the ACI principles. The above example also gives a basic introduction into __Boost_STM_s__ transactional framework.

[endsect]

Modified: sandbox/stm/branches/vbe/libs/stm/doc/history.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/history.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/history.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,5 +1,5 @@
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
   (C) Copyright 2009 Vicente J. Botet Escriba
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at
@@ -12,7 +12,7 @@

[*Features:]

-*
+*

[*Toolsets:]

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/index.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/index.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/index.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -56,9 +56,15 @@
<dt> Header <boost/stm/exceptions.hpp></dt>
<dt><a href="toward_boost_stm/reference/transaction_hpp.html"> Header
 <code class="computeroutput"><boost/stm/transaction.hpp></code></a></dt>
-<dt><a href="toward_boost_stm/reference/transaction_object_hpp.html"> Header
- <code class="computeroutput"><boost/stm/transaction_object.hpp></code></a></dt>
+<dt><a href="toward_boost_stm/reference/base_transaction_hpp.html"> Header
+ <code class="computeroutput"><boost/stm/base_transaction.hpp></code></a></dt>
+<dt><a href="toward_boost_stm/reference/transactional_object_hpp.html">
+ Header <code class="computeroutput"><boost/stm/transactional_object.hpp></code></a></dt>
<dt> Header <boost/stm/tx_ptr.hpp></dt>
+<dt><a href="toward_boost_stm/reference/tx_smart_ptr_hpp.html"> Header
+ <code class="computeroutput"><boost/stm/tx_smart_ptr.hpp></code></a></dt>
+<dt><a href="toward_boost_stm/reference/non_tx_smart_ptr_hpp.html"> Header
+ <code class="computeroutput"><boost/stm/non_tx_smart_ptr.hpp></code></a></dt>
<dt><a href="toward_boost_stm/reference/base_contention_manager_hpp.html">
 Header <code class="computeroutput"><boost/stm/base_contention_manager.hpp></code></a></dt>
<dt><a href="toward_boost_stm/reference/language_like_hpp.html"> Header
@@ -101,7 +107,7 @@
 
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left">Last revised: September 18, 2009 at 22:55:08 GMT</td>
+<td align="left">Last revised: September 20, 2009 at 23:08:52 GMT</td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/standalone_HTML.manifest
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/standalone_HTML.manifest (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/standalone_HTML.manifest 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -10,8 +10,11 @@
toward_boost_stm/reference/data_types_hpp.html
toward_boost_stm/reference/exceptions_hpp.html
toward_boost_stm/reference/transaction_hpp.html
-toward_boost_stm/reference/transaction_object_hpp.html
+toward_boost_stm/reference/base_transaction_hpp.html
+toward_boost_stm/reference/transactional_object_hpp.html
toward_boost_stm/reference/tx_ptr_hpp.html
+toward_boost_stm/reference/tx_smart_ptr_hpp.html
+toward_boost_stm/reference/non_tx_smart_ptr_hpp.html
toward_boost_stm/reference/base_contention_manager_hpp.html
toward_boost_stm/reference/language_like_hpp.html
toward_boost_stm/reference/transaction_bookkeeping_hpp.html

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -40,10 +40,8 @@
<dt><a href="appendices/implementation.html"> Appendix
C: Implementation Notes</a></dt>
<dd><dl>
-<dt><a href="appendices/implementation.html#toward_boost_stm.appendices.implementation.why_there_is_a__if__0____rand___1_____else___preceding_the_for_on_the_atomi_macros_">Why
- there is a <code class="computeroutput">if (0 == rand()+1)
- {} else</code>
- preceding the for on the atomi macros?</a></dt>
+<dt><a href="appendices/implementation.html#toward_boost_stm.appendices.implementation.language_like_macro_blocks">Language-like
+ macro blocks</a></dt>
<dt>Cache</dt>
</dl></dd>
<dt><a href="appendices/acknowledgements.html"> Appendix

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/changes.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/changes.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/changes.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -27,7 +27,7 @@
<a name="toward_boost_stm.appendices.changes"></a><a class="link" href="changes.html" title="Appendix A: History"> Appendix A: History</a>
</h3></div></div></div>
<a name="toward_boost_stm.appendices.changes._emphasis_role__bold__version_0_1__xx_yy__2009__emphasis___emphasis_announcement_of_stm__emphasis_"></a><h5>
-<a name="id4886949"></a>
+<a name="id4897896"></a>
 <a class="link" href="changes.html#toward_boost_stm.appendices.changes._emphasis_role__bold__version_0_1__xx_yy__2009__emphasis___emphasis_announcement_of_stm__emphasis_">Version 0.1, XX YY, 2009 Announcement of
 STM</a>
 </h5>
@@ -47,7 +47,7 @@
 </li>
</ul></div>
<a name="toward_boost_stm.appendices.changes._emphasis_role__bold__tickets___emphasis_"></a><h5>
-<a name="id4887022"></a>
+<a name="id4897968"></a>
 <a class="link" href="changes.html#toward_boost_stm.appendices.changes._emphasis_role__bold__tickets___emphasis_">Tickets:</a>
 </h5>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/implementation.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/implementation.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/implementation.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -28,20 +28,104 @@
 C: Implementation Notes</a>
</h3></div></div></div>
<div class="toc"><dl>
-<dt><a href="implementation.html#toward_boost_stm.appendices.implementation.why_there_is_a__if__0____rand___1_____else___preceding_the_for_on_the_atomi_macros_">Why
- there is a <code class="computeroutput">if (0 == rand()+1)
- {} else</code>
- preceding the for on the atomi macros?</a></dt>
+<dt><a href="implementation.html#toward_boost_stm.appendices.implementation.language_like_macro_blocks">Language-like
+ macro blocks</a></dt>
<dt>Cache</dt>
</dl></div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
-<a name="toward_boost_stm.appendices.implementation.why_there_is_a__if__0____rand___1_____else___preceding_the_for_on_the_atomi_macros_"></a><a class="link" href="implementation.html#toward_boost_stm.appendices.implementation.why_there_is_a__if__0____rand___1_____else___preceding_the_for_on_the_atomi_macros_" title="Why there is a if (0 == rand()+1) {} else preceding the for on the atomi macros?">Why
- there is a <code class="computeroutput">if (0 == rand()+1)
- {} else</code>
- preceding the for on the atomi macros?</a>
+<a name="toward_boost_stm.appendices.implementation.language_like_macro_blocks"></a><a class="link" href="implementation.html#toward_boost_stm.appendices.implementation.language_like_macro_blocks" title="Language-like macro blocks">Language-like
+ macro blocks</a>
</h4></div></div></div>

+ Our language-like lock and transaction parallel constructs are implemented
+ in TBoost.STM as automatic objects wrapped inside of preprocessor macros.
+ Automatic objects are common in C++ and are helpful in ensuring correct
+ lock and transaction behavior as they create deterministic termination
+ points [5, 22]. These deterministic termination points are invoked when
+ the scope containing the automatic object is exited, guaranteeing locks
+ are released and transactions are terminated even in the event of uncaught
+ exceptions. The preprocessor macros used for the locking and transaction
+ constructs are shown in Figures 6 and 8, respectively.
+ 
+<a name="toward_boost_stm.appendices.implementation.language_like_macro_blocks.locking_macros"></a><h6>
+<a name="id4913501"></a>
+ <a class="link" href="implementation.html#toward_boost_stm.appendices.implementation.language_like_macro_blocks.locking_macros">Locking
+ Macros</a>
+ </h6>
+
+ The lock macros use an unoptimized if statement to ensure the variables
+ inside their local for loop are terminated for nonstandard conforming C++
+ compilers (more details to follow). Once the for loop is entered an auto_lock
+ is constructed. Upon construction of the auto_lock, acquisition of the
+ supplied lock is attempted if it has not already been acquired by the locking
+ thread. For the use_lock macro, a blocking lock acquisition call is made
+ which blocks forward progress until the lock is obtained. For the use_timed_lock
+ and try_timed_lock calls, a non-blocking lock acquisition call is made
+ which returns control to the calling thread via exception after MS milliseconds
+ if the lock was not successfully obtained.
+ 
+
+ The post_step() call within the lock macros releases any locks the auto_lock
+ had acquired. The for loop conditional, done_post_step(), returns false
+ until post_step() has been executed. This ensures the lock macro for loops
+ are executed once and only once.
+ 
+<a name="toward_boost_stm.appendices.implementation.language_like_macro_blocks.transaction_macros"></a><h6>
+<a name="id4913550"></a>
+ <a class="link" href="implementation.html#toward_boost_stm.appendices.implementation.language_like_macro_blocks.transaction_macros">Transaction
+ Macros</a>
+ </h6>
+
+ The preprocessor atomic macro for transactions is slightly more complex
+ than the preprocessor locking macros. The additional complexity behind
+ the atomic macro is needed to guarantee two fundamental goals. First, transactions
+ must start and end correctly. Second, transactions must change their retry
+ behavior based on whether they are a child or parent transaction to ensure
+ proper closed nesting, flattened transaction behavior is performed.
+ 
+
+ The atomic preprocessor behaves as follows. Like the lock macros, the atomic
+ macro begins with an unoptimized if statement (details to follow). When
+ the transactional for loop is entered, a transaction automatic object is
+ constructed which initializes the transaction and puts it in-flight. The
+ for loop conditional ensures the following conditions: (1) the transaction
+ is uncommitted, (2) the transaction has the opportunity to throw an exception
+ if necessary, and (3) the transaction is in-flight. Once a transaction
+ commits, the check on (1) !T.committed() ensures the transaction is not
+ executed again. If the transaction has been aborted but is a child transaction,
+ the transaction must be restarted at the parent level. The call to (2)
+ T.check_throw_before_restart() allows an aborted child transaction to throw
+ an exception upward (before it is restarted) so the entire transaction
+ can be restarted from the parent. The check_throw_before_restart() API
+ checks the current run-time state of the thread to determine if another
+ transaction is active above it. This behavior allows transactions to be
+ used at any nesting level while dynamically ensuring the correct retry
+ behavior. Finally, the call to restart_if_not_inflight() ensures the transaction
+ is correctly restarted after each subsequent abort.
+ 
+
+ Once all of the transactional operations within the for loop are executed,
+ a call to no_throw_end() is made which ends the transaction. The no_throw_end()
+ terminates the transaction by either committing or aborting it. Note, however,
+ that no_throw_end() does not throw an exception if the transaction is aborted,
+ whereas the prior TBoost.STM API end() does. This non-throwing behavior
+ deviates from the prior TBoost.STM implementation of automatic objects
+ when end() was invoked within the try / catch body. Furthermore, due to
+ no_throw_end() not throwing an exception if the transaction is aborted,
+ some cases may arise where catch_before_retry or before_retry operations
+ are not invoked when a transaction is aborted. This is a current limitation
+ of the system and is overcome by inserting a manual end() operation as
+ the last operation in the atomic block. The explicit end() (Figure 14)
+ ensures any operations within the before_retry block are executed if the
+ transaction is aborted.
+ 
+<a name="toward_boost_stm.appendices.implementation.language_like_macro_blocks.correcting_non_compliant_compilers"></a><h6>
+<a name="id4913656"></a>
+ <a class="link" href="implementation.html#toward_boost_stm.appendices.implementation.language_like_macro_blocks.correcting_non_compliant_compilers">Correcting
+ Non-Compliant Compilers</a>
+ </h6>
+
 The <code class="computeroutput">if (0 == rand()+1)
 {} else</code>
 expression in the preprocessor atomic macros is used to prevent for loop
@@ -70,11 +154,11 @@
<a name="toward_boost_stm.appendices.implementation.cache"></a><a class="link" href="implementation.html#toward_boost_stm.appendices.implementation.cache" title="Cache">Cache</a>
</h4></div></div></div>
<a name="toward_boost_stm.appendices.implementation.cache.dispersed"></a><h6>
-<a name="id4890531"></a>
+<a name="id4913785"></a>
 <a class="link" href="implementation.html#toward_boost_stm.appendices.implementation.cache.dispersed">Dispersed</a>
 </h6>
<a name="toward_boost_stm.appendices.implementation.cache.compact"></a><h6>
-<a name="id4890552"></a>
+<a name="id4913806"></a>
 <a class="link" href="implementation.html#toward_boost_stm.appendices.implementation.cache.compact">Compact</a>
 </h6>
</div>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/rationale.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/rationale.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/rationale.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -52,10 +52,10 @@
 transactions</a></dt>
<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management">Contention
 management</a></dt>
-<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.unrecoverable_transactions_to_manage_with_i_o">Unrecoverable
- transactions to manage with I/O</a></dt>
<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction">Lock-aware
 transaction</a></dt>
+<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.unrecoverable_transactions_to_manage_with_i_o">Unrecoverable
+ transactions to manage with I/O</a></dt>
</dl></dd>
<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts">C++
 and Library-Specific Concepts</a></dt>
@@ -65,14 +65,16 @@
<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.memory_management">Memory
 Management</a></dt>
<dt>RAII</dt>
-<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.exception_safety">Exception
- Safety</a></dt>
+<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.mixin_versus_wrapper_helpers">Mixin
+ versus wrapper helpers</a></dt>
+<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.why___boost_stm_s___cache_uses_now_memcpy_instead_of_copy_constructor_and_assignement">Why
+ TBoost.STM's cache uses now memcpy instead of copy-constructor and assignement</a></dt>
<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.move_semantics">Move
 semantics</a></dt>
<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.parametric_polymorphism_and_subtype_polymorphism">Parametric
 Polymorphism and Subtype Polymorphism</a></dt>
-<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_atomic_transaction_macro_blocks">Language-like
- atomic transaction macro blocks</a></dt>
+<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks">Language-like
+ macro blocks</a></dt>
</dl></dd>
<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.comparaison_with_other_stm_systems">Comparaison
 with other STM systems</a></dt>
@@ -105,10 +107,10 @@
 transactions</a></dt>
<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management">Contention
 management</a></dt>
-<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.unrecoverable_transactions_to_manage_with_i_o">Unrecoverable
- transactions to manage with I/O</a></dt>
<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction">Lock-aware
 transaction</a></dt>
+<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.unrecoverable_transactions_to_manage_with_i_o">Unrecoverable
+ transactions to manage with I/O</a></dt>
</dl></div>
<div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title">
<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.optimistic_concurrency"></a><a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.optimistic_concurrency" title="Optimistic concurrency">Optimistic
@@ -121,7 +123,9 @@
</h5></div></div></div>

 Transactional memory was founded on the database ACID principle (atomic,
- consistent, isolated and durable), except without the D [24].
+ consistent, isolated and durable), except without the D (durability)
+ because unlike database transactions, TM transactions are not saved to
+ permanent storage (e.g., hard drives).
 
<div class="itemizedlist"><ul type="disc">
<li>
@@ -256,7 +260,7 @@
 read).
 
<div class="table">
-<a name="id4887533"></a>Table 1.1. Comparaison with other STM systems
+<a name="id4898495"></a>Table 1.1. Comparaison with other STM systems
<div class="table-contents"><table class="table" summary="Comparaison with other STM systems">
<colgroup>
<col>
@@ -459,7 +463,7 @@
 handle each specific problem with the most appropriate configuration.
 
<div class="table">
-<a name="id4887918"></a>Table 1.2. Consistency versus Updating policies composition
+<a name="id4898890"></a>Table 1.2. Consistency versus Updating policies composition
<div class="table-contents"><table class="table" summary="Consistency versus Updating policies composition">
<colgroup>
<col>
@@ -605,18 +609,991 @@
 Future versions of TBoost.STM will implement closed nested transactions.
 
</div>
-<div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title">
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management"></a><a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management" title="Contention management">Contention
 management</a>
-</h5></div></div></div></div>
+</h5></div></div></div>
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management.priority_based_tasks"></a><h6>
+<a name="id4899210"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management.priority_based_tasks">Priority-Based
+ Tasks</a>
+ </h6>
+
+ Real-time systems or systems that have strict requirements for task behavior,
+ such as deadline-drive systems, usually guarantee such behavior through
+ priority scheduling. While significant prior TM contention management
+ (CM) research has been done, its attention has been primarily focused
+ on preventing starvation through fairness. In many systems preventing
+ starvation may be sufficient, yet some systems (e.g. deadline-driven
+ or real-time systems) require stronger behavioral guarantees. In these
+ cases, user-defined priority-based transactions are necessary.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management.approach"></a><h6>
+<a name="id4899248"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management.approach">Approach</a>
+ </h6>
+
+ This work extends the prior TM contention management research by concretely
+ implementing user-defined contention managers as determined consequential.
+ We approach this by first presenting a brief background of TM aspects
+ important to understanding the complexities of contention management.
+ Next, we review and expand upon prior contention management work. We
+ then show how consistency models play a significant role in the correctness
+ and capability of priority-based transactional scheduling. We then build
+ user-defined priority-based transactions with TBoost.STM, demonstrating
+ how contention management frameworks work with different consistency
+ checking models. Last, we present our experimental results.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management.attacking__amp__victim_transactions"></a><h6>
+<a name="id4899301"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management.attacking__amp__victim_transactions">Attacking
+ & Victim Transactions</a>
+ </h6>
+
+ We refer to transactions which can identify a memory conflict in another
+ in-flight transaction as attacking transactions. Transactions which are
+ targeted by attacking transactions are referred to as victim transactions.
+ The attacking and victim transaction terms help simplify the invalidation
+ process. An example of attacking and victim transactions is as follows.
+ Consider transaction Tv, a victim transaction and transaction Ta, an
+ attacking transaction. Tv writes to memory location L0. Ta then tries
+ to write to L0. If our STM system only allows single-writers, both Ta
+ and Tv cannot write to L0 at the same time. As Ta is the second transaction
+ attempting to write to L0, the single-writer semantics require it to
+ deal with the conflict located at L0. Handling this conflict makes Ta
+ the attacking transaction as it decides if Tv is aborted. Tv is the victim
+ transaction since Ta may abort it.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management.user_defined_priority_based_transactions"></a><h6>
+<a name="id4899349"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management.user_defined_priority_based_transactions">User-Defined
+ Priority-Based Transactions</a>
+ </h6>
+
+ Validation and invalidation
+ 
+
+ consistency checking are both practical solutions to transactional memory
+ for different classes of problems. When inflight transactions are low
+ and memory usage is high, invalidation may be preferred. When transactional
+ traffic is high and transactions are small, validation may be preferred.
+ Neither type of consistency checking seems to perform universally better
+ than the other. Though certain classes of problems perform better under
+ different consistency checking models, the ramifications of these consistency
+ checking schemes performing within strict user-defined priority-based
+ transactional systems is unclear from prior research. Our work clarifies
+ the advantages and disadvantages of validation and invalidation in user-defined
+ priority-based transactional environments.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management.extensible_polymorphic_contention_management_interface"></a><h6>
+<a name="id4899399"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.contention_management.extensible_polymorphic_contention_management_interface">Extensible
+ Polymorphic Contention Management Interface</a>
+ </h6>
+
+ Due to the innumerable possibilities of consistency checking model combinations,
+ for the remainder of this work, we narrow our scope of consistency checking
+ to commit-time validation and committime invalidation. We do this for
+ a number of reasons. First, validation and invalidation are near opposites
+ and commit-time consistency checking is straight forward in that it is
+ only performed once per transaction. Due to this, we can see the two
+ primary views of consistency checking in an understandable fashion. Second,
+ early TM systems tended toward validation while newer TM systems tend
+ toward invalidation. This makes considering both viewpoints practical.
+ Third, both validation and invalidation perform well under different
+ circumstances. By considering both types, we can help extend their current
+ understanding to user-defined priority-based systems as well. Finally,
+ TBoost.STM supports both commit-time validation and commit-time invalidation.
+ 
+
+ TBoost.STM extensible contention manager supports two types of management:
+ abort behavior management and conflict resolution management. The abort
+ behavior interfaces are somewhat novel compared to prior work, in that
+ they allow TBoost.STM's contention manager to decide how the system should
+ behave when a transaction must abort. These interfaces, shown in bellow,
+ were added as it was determined that not all aborted transactions should
+ behave in the same manner. For example, some transactions which have
+ extremely large read and write sets, should perhaps sleep for some period
+ of time before running again. Other transactions which have already high
+ priorities, should perhaps receive larger priority boosts.
+ 
+<pre class="programlisting">class base_contention_manager {
+public:
+ virtual void abort_on_new(transaction const &t) = 0;
+ virtual void abort_on_delete(transaction const &t, base_transaction_object const &in) = 0;
+ virtual void abort_on_read(transaction const &t, base_transaction_object const &in) = 0;
+ virtual void abort_on_write(transaction &t, base_transaction_object const &in) = 0;
+ // conflict interfaces removed
+};
+</pre>
+
+ The interfaces shown above do not manage any memory contention, instead
+ they only handle how required aborts behave.
+ 
+
+ The second type of TBoost.STM contention management interfaces is shown
+ in below.
+ 
+<pre class="programlisting">class base_contention_manager
+{
+public:
+ // abort interfaces removed
+ virtual bool abort_before_commit(transaction const &t) = 0;
+ virtual bool permission_to_abort(transaction const &lhs, transaction const &rhs) = 0;
+};
+</pre>
+
+ These interfaces implement true management of memory conflicts. The two
+ interfaces shown: abort_before_commit() and permission_to_abort() enable
+ two fundamentally different types of consistency checking. abort_before_commit()
+ is called when TBoost.STM is performing validating consistency checking,
+ while permission_to_abort() is called when TBoost.STM is performing invalidating
+ consistency checking. Both APIs are called internally at different points
+ in the transaction's commit phase.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction"></a><a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction" title="Lock-aware transaction">Lock-aware
+ transaction</a>
+</h5></div></div></div>
+
+ Transactional memory (TM) has garnered significant interest as an alternative
+ to existing concurrency methods due to its simplified programming model,
+ natural composition characteristics and native support of optimistic
+ concurrency. Yet, mutual exclusion locks are ubiquitous in existing parallel
+ software due to their fast execution, inherent property for irreversible
+ operations and long-standing underlying support in modern instruction
+ set architectures (ISAs). For transactions to become practical, lock-based
+ and TM-based concurrency methods must be unified into a single model.
+ 
+
+ TBoost.STM presents a lock-aware transactional memory (LATM) solution
+ with a deliberate library-based approach. Our LATM system supports locks
+ inside of transactions (LiT) and locks outside of transactions (LoT)
+ while preserving the original programmer-intended locking structure.
+ Our solution provides three policies with varying degrees of performance
+ and required programming. The most basic LATM policy enables transactionlock
+ correctness without any programming overhead, while improved performance
+ can be achieved by programmer-specified conflicts between locks and transactions.
+ The differences in LATM policy performance are presented through a number
+ of experimental benchmarks on .
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.introduction"></a><h6>
+<a name="id4900106"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.introduction">Introduction</a>
+ </h6>
+
+ Yet, for all of the benefits of transactional programming, its native
+ inoperability with mutual exclusion locks is a major obstacle to its
+ adoption as a practical solution. Mutual exclusion (implemented through
+ locks) is arguably the most predominant form of thread synchronization
+ used in parallel software, yet its native incompatibility with transactions
+ places a considerable restriction on the practical use of TM in real-world
+ software.
+ 
+
+ A TM system that is cooperative with locks can extend the lifetime and
+ improve the behavior of previously generated parallel programs. TBoost.STM
+ C++ library is a lock-aware transactional memory (LATM) system supporting
+ the simultaneous execution of transactions and locks. Of critical importance
+ is that the extended TBoost.STM LATM system naturally supports lock-based
+ composition for locks placed inside of transactions (LiT), a characteristic
+ previously unavailable in locks. The LATM policies present in TBoost.STM
+ are implemented with software library limitations as a central concern.
+ While novel operating system (OS)-level and language-based transaction-lock
+ cooperative models have been previously found, these implementations
+ use constructs not available in library-based STM systems. While useful,
+ the previously identified OS-level and language-based solutions do not
+ address the critical need for a transaction-lock unified model expressed
+ entirely within the limitations of a software library. In languages that
+ are unlikely to be extended, such as C++, and development environments
+ bound to specific constraints, such as a particular compiler or OS, library
+ based solutions are paramount as they present practical solutions within
+ industry-based constraints. Our approach presents a novel library-based
+ LATM solution aimed at addressing these concerns. TBoost.STM makes the
+ following contributions:
+ 
+<div class="orderedlist"><ol type="1">
+<li>
+ Extension of the TBoost.STM library for support of locks outside of
+ transactions (LoT) and locks inside of transactions (LiT).
+ </li>
+<li>
+ Proof that an LATM LiT system naturally enables lock composition. Analytical
+ examples are examined that show LiT composable locks demonstrating
+ atomicity, isolation and consistency as well as deadlock avoidance.
+ </li>
+<li>
+ Introduction of three novel LATM policies: full lock protection, TM-lock
+ protection, and TX-lock protection. Each LATM policy provides different
+ programming / performance trade offs. Experimental results are provided
+ which highlight the performance and programming differences of the
+ three LATM policies.
+ </li>
+</ol></div>
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.background"></a><h6>
+<a name="id4900206"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.background">Background</a>
+ </h6>
+
+ Transaction-lock interaction does not natively exhibit shared memory
+ consistency and correctness due to differences in underlying critical
+ section semantics. Strongly and weakly isolated transactional memory
+ systems are susceptible to incorrect execution when used with pessimistic
+ critical sections.
+ 
+
+ Mutual exclusion locks use pessimistic critical section semantics; execution
+ of a lock-controlled critical section is limited to one thread and guarantees
+ the executing thread has mutually exclusive (isolated) access to the
+ critical section code region. Transactions use optimistic critical section
+ semantics; transaction controlled critical sections support unlimited
+ concurrent thread execution. Shared memory conflicts arising from simultaneous
+ transaction execution are handled by the TM system during the commit
+ phase of the transaction. Optimistic critical sections and pessimistic
+ critical sections are natively inoperable due to their contradictive
+ semantics as demonstrated in the below example:
+ 
+
+ Lock and transaction violation (code).
+ 
+<pre class="programlisting">1 native_trans<int> x;
+2
+3 int lock_dec() {
+4 lock(L1);
+5 int val = --x;
+6 unlock(L1);
+7 return val;
+8 }
+9
+10 void tx_inc() {
+11 for (transaction t;;t.restart())
+12 try {
+13 ++t.write(x);
+14 t.end(); break;
+15 } catch (aborted_tx &) {}
+16 }
+</pre>
+
+ Without an intervening system, thread T1 executing lock_dec() and thread
+ T2 executing tx_inc() are not guaranteed to operate consistently, as
+ they would if each function were run in a lock-only or transaction-only
+ system, respectively. The following example demonstrates how the correctness
+ of the above code is violated from a deferred update and direct update
+ standpoint.
+ 
+
+ Deferred Update Lock/Transaction Violation. A deferred update TM system
+ stores transactional writes off to the side, updating global memory once
+ the transaction commits. A deferred update system can exhibit an inconsistency
+ in the above code in the following way. Given: x = 0, thread T1 executes
+ lock_dec() and thread T2 executes tx_inc(). T2 executes line 10 - the
+ first half of line 13 (storing a transactional value for x = 0, but not
+ performing the increment). T1 executes lines 3-5 (global x = -1). T2
+ executes the remainder of line 13 and line 14 (++x on its stored reference
+ of 0, setting its local x = 1) and then commits. T1 executes lines 6-7.
+ The resulting global state of x = 1 is incorrect; x = 0 is correct as
+ one thread has incremented it and one thread has decremented it.
+ 
+
+ Direct Update Lock/Transaction Violation. A direct update TM system stores
+ transactional writes directly in global memory, storing an original backup
+ copy off to the side in the event the transaction must be unwound. In
+ a direct update system, threads T1 and T2 can exhibit inconsistencies
+ using the code shown above in a variety of ways; T1 executes line 3 -
+ the first half of line 5 (decrementing x, but not setting val). T2 executes
+ lines 10-13 (incrementing the global x and creating a restore point of
+ x = -1). T1 executes the remainder of line 5 (val = 0). T2 executes line
+ 14, but is required to abort, restoring x to -1. T1 completes and returns
+ val = 0 which is incorrect. T2 never committed its x = 0 and has not
+ successfully committed, therefore, x has never correctly been set to
+ 0.
+ 
+
+ Overcoming Transaction-Lock Inoperability
+ 
+
+ In order for transactions and locks to cooperate, transactions must adhere
+ to a single mutual exclusion rule: Mutual exclusion semantics require
+ that instructions within a mutex guarded critical section be limited
+ to <=1 simultaneous thread of execution.
+ 
+
+ Our LATM implementation adheres to this rule and is discussed in two
+ high-level views:
+ 
+<div class="orderedlist"><ol type="1">
+<li>
+ locks outside of transactions (LoT) and
+ </li>
+<li>
+ locks inside of transactions (LiT).
+ </li>
+</ol></div>
+
+ TBoost.STM supports lock-aware transactions by supplying a pass-through
+ interface that is used in place of prior locking calls.
+ 
+
+ The TBoost.STM locking API is used to perform the additional transaction-lock
+ communication before or after the pthreads interface is called. In all
+ cases, the TBoost.STM pass-through interface results in at least one
+ corresponding call to the appropriated interface to lock, try to lock
+ or unlock the mutual exclusion lock. Further details are provided in
+ later sections.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.locks_outside_of_transactions__lot_"></a><h6>
+<a name="id4900772"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.locks_outside_of_transactions__lot_">Locks
+ Outside of Transactions (LoT)</a>
+ </h6>
+
+ Locks outside of transactions (LoT) are scenarios where a pessimistic
+ critical section of a lock is executed in a thread T1 while an optimistic
+ critical section of a transaction is executed in a thread T2, simultaneously.
+ Thread T1's lock-based pessimistic critical section is entirely outside
+ of thread T2's transaction, thus the term locks outside of transactions
+ or LoT. Figure 5 sets up a running LoT example, used throughout this
+ section, by constructing six functions which are simultaneously executed
+ by six threads. Three of the functions in the below example, tx1(), tx2()
+ and tx3(), are transaction-based, while the other three functions, lock1(),
+ lock2() and lock3(), are lock-based. The functions tx1(), tx2() and lock3()
+ do not have any memory conflict with any other transaction-based or lock-based
+ function and should therefore be able to run concurrently with any of
+ the other functions. However, certain LoT policies inhibit the execution
+ of these nonconflicting functions; details of such inhibited behavior
+ is explained in the following subsections. The below example is used
+ throughout this section to illustrate the differences in the LoT policies.
+ 
+<pre class="programlisting">1 native_trans<int> arr1[99], arr2[99];
+2
+3 void tx1() { /* no conflict */ }
+4 void tx2() { /* no conflict */ }
+5 void tx3() {
+6 for (transaction t;;t.restart())
+7 try {
+8 for (int i = 0; i < 99; ++i)
+9 {
+10 ++t.w(arr1[i]).value();
+11 ++t.w(arr2[i]).value();
+12 }
+13 t.end(); break;
+14 } catch (aborted_tx&) {}
+15 }
+16
+17 int lock1() {
+18 transaction::lock(L1); int sum = 0;
+19 for (int i = 0; i < 99; ++i) sum += arr1[i];
+20 transaction::unlock(L1); return sum;
+21 }
+22 int lock2() {
+23 transaction::lock(L2); int sum = 0;
+24 for (int i = 0; i < 99; ++i) sum += arr2[i];
+25 transaction::unlock(L2); return sum;
+26 }
+27 int lock3() { /* no conflict */ }
+</pre>
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lot_full_lock_protection"></a><h6>
+<a name="id4901914"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lot_full_lock_protection">LoT
+ Full Lock Protection</a>
+ </h6>
+
+ The most basic implementation of transaction-lock cooperation, what we
+ call full lock protection, is to enforce all transactions to commit or
+ abort before a lock's critical section is executed. All locks outside
+ of transactions are protected from transactions violating their critical
+ section execution by disallowing transactions to run in conjunction with
+ locks. Transactions are stalled until all LoT critical sections are complete
+ and their corresponding locks are released.
+ 
+
+ An example of full lock protection is shown in Figure 6 using the previously
+ described six threaded model. Full lock protection has no programmer
+ requirements; no new code is required, aside from alteration of existing
+ locking code to use the LATM passthrough interfaces. Additionally, an
+ understanding of how the locks behave within the system to enable transaction-lock
+ cooperation is also not needed. However, full lock protection suffers
+ some performance penalties. As seen in Figure 6, T1 ?? T3 are blocked
+ for the entire duration of the critical sections obtained in T4 ?? T6,
+ since full lock protection prevents any transactions from running while
+ LoTs are obtained. Although T3 does conflict with T4 ?? T5, T6's critical
+ section does not interfere with any of the transactions and should therefore
+ not prevent any transactions from running concurrently; TM-lock protection,
+ the next level of lock protection, is able to avoid such unnecessary
+ stalling.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lot_tm_lock_protection"></a><h6>
+<a name="id4901994"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lot_tm_lock_protection">LoT
+ TM-Lock Protection</a>
+ </h6>
+
+ TM-lock protection is slightly more complex than full lock protection,
+ yet it can yield better overall system performance. TMlock protection
+ works in the following way: locks which can conflict with transactions
+ are identified by the programmer at startup. Once a conflicting LoT is
+ acquired, all in-flight transactions are either committed or aborted.
+ Transactions are then blocked until the conflicting lock-based critical
+ sections are completed and released. Locks that do not conflict with
+ transactions do not cause any transactions to stall.
+ 
+
+ The identification of locks that can conflict with transactions requires
+ the programmer to (1) write new code and (2) have a basic understanding
+ of the software system. Due to this, the requirements of TM-lock protection
+ are greater on the end programmer. The trade-off for higher programmer
+ requirements is greater overall system performance.
+ 
+
+ TM-lock protection addresses the problem of transactions unnecessarily
+ stalled when T6 is executing. When using TM-lock protection, the end
+ programmer must explicitly express which locks can conflict with the
+ TM system. In this example, locks L1 and L2 from threads T4 and T5 conflict
+ with tx3 in thread T3. The end programmer would explicitly label these
+ locks as conflicting in the following way:
+ 
+<pre class="programlisting">1 transaction::do_tm_conflicting_lock_protection();
+2 transaction::add_tm_conflicting_lock(L1);
+3 transaction::add_tm_conflicting_lock(L2);
+</pre>
+
+ As shown in the six threaded example, TM-lock protection shortens the
+ overall TM run-time by allowing T1 ?? T3 to restart their transactions
+ as soon as L2's critical section is completed. Yet, there still exists
+ unnecessary stalls in threads T1 and T2 as their associated transactions
+ do not conflict with any of the lock-based critical sections of T4 ??T6.
+ The remaining unnecessary stalls are resolved by using TX-lock protection,
+ the third lock protection policy.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lot_tx_lock_protection"></a><h6>
+<a name="id4902177"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lot_tx_lock_protection">LoT
+ TX-Lock Protection</a>
+ </h6>
+
+ TX-lock protection enables maximum performance throughput by identifying
+ only true conflicts as they exist per transaction. TXlock protection
+ is similar to TM-lock protection except rather than requiring conflicting
+ locks be identified at a general TM-level, conflicting locks are identified
+ at a transaction-level. While this level of protection yields the highest
+ level of performance, it also requires the greatest level of familiarity
+ of the locks within the system and the most hand-crafted code.
+ 
+
+ An example of TX-lock protection is in Figure 8. By using TX-lock protection
+ and explicitly identifying conflicting locks per transaction, the system
+ only stalls for true conflicts, increasing overall system performance.
+ The code required for correct TX-lock protection in the prior six threaded
+ example is shown below by extending the original tx3() implementation:
+ 
+<pre class="programlisting">1 void tx3() {
+2 for (transaction t;;t.restart())
+3 try {
+4 // identify conflicting locks
+5 t.add_tx_conflicting_lock(L1);
+6 t.add_tx_conflicting_lock(L2);
+7 for (int i = 0; i < 99; ++i)
+8 {
+9 ++t.w(arr1[i]).value();
+10 ++t.w(arr2[i]).value();
+11 }
+12 t.end(); break;
+13 } catch (aborted_tx&) {}
+14 }
+</pre>
+
+ Using TX-lock protection, threads T1 and T2 are no longer stalled when
+ threads T4 and T5 lock their associated locks, L1 and L2. In fact, only
+ thread T3 (the only true conflict) is stalled while the critical sections
+ created by L1 and L2 are executing, resulting in the highest transaction-lock
+ cooperative performance while still adhering to the rule.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.locks_inside_of_transactions__lit_"></a><h6>
+<a name="id4902702"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.locks_inside_of_transactions__lit_">Locks
+ Inside of Transactions (LiT)</a>
+ </h6>
+
+ Locks inside of transactions (LiT) are scenarios where a lock-based pessimistic
+ critical section is executed partially or completely inside a transaction.
+ Only two of the three possible LiT scenarios are supported by our work:
+ (1) pessimistic critical sections are encapsulated entirely within a
+ transaction or (2) pessimistic critical sections start inside a transaction
+ but end after the transaction has terminated.We do not support LiT scenarios
+ where pessimistic critical sections start before a transaction begins,
+ having the front-end of the transaction encapsulated by the pessimistic
+ critical section. The reason to disallow such behavior is to avoid deadlocks.
+ 
+
+ Consider the following scenario. Thread T1 has an in-flight irrevocable
+ transaction Tx1 and thread T2, after obtaining lock L2, starts a transaction
+ Tx2. Tx2 is not allowed to make forward progress until it is made irrevocable
+ (details to follow). Tx1 is already in-flight and irrevocable. Since
+ two irrevocable transactions cannot run simultaneously as they are not
+ guaranteed to be devoid of conflicts with one another, Tx2 must stall
+ until Tx1 completes. If irrevocable transaction Tx1 requires lock L2
+ to complete its work the system will deadlock. Tx1 cannot make forward
+ progress due to its dependency upon L2 (currently held by Tx2) and Tx2
+ cannot make forward progress as it requires Tx1 to complete before it
+ can run. As such, LiT scenarios where locks encapsulate the front-end
+ of a transaction are disallowed; our implementation immediately throws
+ an exception when this behavior is detected.
+ 
+
+ Irrevocable and Isolated Transactions
+ 
+
+ The LiT algorithms use the same policies as the LoT algorithms: full
+ lock protection, TM-lock protection and TX-lock protection. Locks inside
+ of transactions have the same characteristics as normal mutual exclusion
+ locks, and Lemma 1 must be followed in order to ensure correctness. Since
+ the LiT algorithms use locks acquired inside of transactions and these
+ locks are not guaranteed to have failure atomicity as transactions do,
+ the containing transactions must become irrevocable (see Lemma 2). Irrevocable
+ transactions, characterized by T(irrevocable) = true, are transactions
+ that cannot be aborted. The concept of irrevocable (or inevitable) transactions
+ is not new; Welc et al. and Spear et al. have shown these types of transactions
+ to be of significant importance as well as having a variety of practical
+ uses [17, 19]. We extend the prior work of Welc et al. and Spear et al.
+ by using irrevocable transactions to enable pessimistic critical sections
+ within transactions, as well as to create composable locks within transactions.
+ In addition to irrevocable transactions, the LiT full lock protection
+ and TM-lock protection require a new type of transaction, one that we
+ term as an isolated transaction. Isolated transactions, characterized
+ by T(isolated) = true, are transactions that cannot be aborted and require
+ that no other type of transaction run along side it simultaneously. Isolated
+ transactions can be viewed as a superset of irrevocable transactions;
+ isolated transactions have the properties of irrevocable transactions
+ and must be run in isolation. To demonstrate how the LiT algorithms work,
+ consider the six threaded example shown in Figure 12.
+ 
+
+ 3 LiT Transaction Threads, 3 Locking Threads.
+ 
+<pre class="programlisting">1 native_trans<int> g1, g2, g3, g4;
+2
+3 void tx1() { /* no conflict */ }
+4 void tx2() {
+5 transaction::add_tm_conflicting_lock(L2);
+6 for (transaction t;;t.restart())
+7 try {
+8 t.add_tx_conflicting_lock(L2);
+9 inc2();
+10 t.end(); break;
+11 } catch (aborted_tx&) {}
+12 }
+13 void tx3() {
+14 transaction::add_tm_conflicting_lock(L3);
+15 for (transaction t;;t.restart())
+16 try {
+17 t.add_tx_conflicting_lock(L3);
+18 inc3();
+19 t.end(); break;
+20 } catch (aborted_tx&) {}
+21 }
+22
+23 void inc2() {
+24 lock(L2); ++g2.value(); unlock(L2);
+25 }
+26 void inc3() {
+27 lock(L3); ++g3.value(); unlock(L3);
+28 }
+29 void inc4() { /* no conflict */ }
+</pre>
+
+ In Figure 12 thread T1 executes tx1(), T2 executes tx2(), T3 executes
+ tx3(), T4 executes inc2(), T5 executes inc3() and T6 executes inc4().
+ Threads T1 (tx1()) and T6 (inc4()) do not conflict with any other thread,
+ yet their execution can be inhibited by other threads based on the LiT
+ policy employed. Thread T2 has a true conflict with thread T4 (both threads
+ call inc2()) and thread T3 has a true conflict with thread T5 (both threads
+ call inc3()). A staggered start time is used in the coming diagrams:
+ T1 starts, followed by T2, T3, T4, T5 and finally T6.We label the LiT
+ threads based on the locks they acquire: tx1 acquires lock L1, thread
+ tx2 acquires lock L2 and thread tx3 acquires lock L3. The same taxonomy
+ is used for locking threads: thread lockL2 acquires lock L2, thread lockL3
+ acquires lock L3 and thread lockL4 acquires lock L4.
+ 
+
+ In Figure 12, both add_tm_conflicting_lock() and add_tx_conflicting_lock()
+ are present. If the system is using TM-lock protection only the add_tm_conflicting_lock()
+ is necessary, whereas if the system is using TX-lock protection only
+ the add_tx_conflicting_lock() is necessary. If neither TMlock or TX-lock
+ protection is in use, neither call is needed. These interfaces are supplied
+ for the completeness of the example.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lit_full_lock_protection"></a><h6>
+<a name="id4903745"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lit_full_lock_protection">LiT
+ Full-Lock Protection</a>
+ </h6>
+
+ Figure 13 demonstrates how the six threads interact using the full lock
+ protection policy, as well as showing policy conflicts in comparison
+ to true conflicts. The LiT full lock protection algorithm requires that
+ any transaction that has a lock inside of it be run as an isolated transaction.
+ Prior to a lock inside the transaction being obtained, all other in-flight
+ transactions are aborted or committed and all currently held locks must
+ execute through release. Future attempts to obtain locks outside of the
+ isolated transaction are prevented until the transaction commits. This
+ behavior is required as the system must assume (1) all external locks
+ can conflict with the isolated transaction, so no external locks can
+ be obtained; and (2) all external transactions can conflict with the
+ LiT transaction, and therefore no external transactions can execute.
+ 
+
+ For Figure 13, once tx2 begins, tx1 is stalled as tx2 must run as an
+ isolated transaction. Due to tx2's isolation, tx3 is also stalled. Both
+ lockL2 and lockL3 are also stalled because full lock protection disallows
+ transactions from running while LoT locks are obtained; as tx2 is an
+ isolated transaction, the threads attempting to lock L2 and L3 are stalled
+ until tx2 completes. When tx2 completes, tx3 is started as it has stalled
+ for the longest amount of time. The thread executing lockL4 is stalled
+ until tx3 completes. When tx3 completes, tx1, lockL2, lockL3 and lockL4
+ are all allowed to resume.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lit_tm_lock_protection"></a><h6>
+<a name="id4903818"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lit_tm_lock_protection">LiT
+ TM-Lock Protection</a>
+ </h6>
+
+ Like full lock protection, LiT TM-lock protection runs transactions encapsulating
+ locks in isolation. However, LiT TM-lock protection also requires the
+ end programmer to identify locks obtained within any transaction prior
+ to transaction execution (just as LoT TM-lock protection). Unlike LiT
+ full lock protection, TM-lock protection allows non-conflicting LoT locks
+ to execute along side LiT locks, increasing overall system throughput.
+ 
+
+ As shown in Figure 14 TM-lock protection reduces the overall policy-induced
+ conflicting time to a range closer to the true conflicting time. Since
+ tx2 and tx3 are true conflicts with lockL2 and lockL3, lockL2 and lockL3
+ must stall while tx2 and tx3 are executing. However, lockL4 does not
+ conflict with either tx2 or tx3 and as such, should not be stalled while
+ the LiT transactions are inflight. TM-lock protection correctly identifies
+ this conflict as false, allowing lockL4's execution to be unimpeded by
+ tx2 and tx3's execution.
+ 
+
+ Three problems still exist in the LiT example: (1) tx1 is stalled by
+ tx2 and tx3, (2) lockL2 is stalled by tx3 and (3) lockL3 is stalled by
+ tx2. Ideally, none of these stalls should occur as none represent true
+ conflicts. All three false conflicts are avoided by using the following
+ LiT protection policy, LiT TX-lock protection.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lit_tx_lock_protection"></a><h6>
+<a name="id4903880"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lit_tx_lock_protection">LiT
+ TX-Lock Protection</a>
+ </h6>
+
+ Like LoT TX-lock protection, the Lit TX-lock protection algorithm allows
+ for the highest throughput of both transactions and locks while requiring
+ the highest level of programmer involvement and system understanding.
+ Unlike both prior LiT algorithms, TX-lock protection allows LiT transactions
+ to run as irrevocable transactions, rather than isolated transactions.
+ This optimization can increase overall system throughput substantially
+ if other revocable transactions can be run along side the LiT transaction.
+ 
+
+ With LiT TX-lock protection, the programmer specifies locking conflicts
+ for each transaction. In Figure 12's case, the programmer would specify
+ that tx2 conflicts with L2 and tx3 conflicts with L3. By specifying true
+ transactional conflicts with locks, the TM system can relax the requirement
+ of running LiT transactions in isolation and instead run them as irrevocable.
+ While no two irrevocable transactions can be run simultaneously, as they
+ may conflict with each other (resulting in a violation of their irrevocable
+ characteristic), other non-irrevocable transactions can be run along
+ side them, improving overall system throughput.
+ 
+
+ The run-time result of using LiT TX-lock protection is shown in Figure
+ 15. Transaction tx1 is able to run without being stalled as it has no
+ conflicts with other transactions or locks. Transaction tx2 is run as
+ an irrevocable transaction, rather than as an isolated transaction, allowing
+ tx1 to run along side it. Irrevocable transaction tx3 is prevented from
+ starting as irrevocable transaction tx2 is already in-flight. Likewise,
+ lockL2 cannot lock L2 since tx2 conflicts with L2 and allowing lockL2
+ to proceed would require tx2 to abort. Since tx2 is irrevocable (e.g.
+ unabortable), lockL2 is stalled. However, lockL3 and lockL4 start immediately,
+ since neither conflict with any in-flight transaction. When tx2 completes,
+ both tx3 and lockL2 can try to proceed. Transaction tx3 is stalled by
+ lockL3, but lockL2 executes immediately as its conflict with tx2 has
+ passed. When lockL3 completes tx3 begins and runs through to completion.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lock_composition"></a><h6>
+<a name="id4903970"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lock_composition">Lock
+ Composition</a>
+ </h6>
+
+ Any TM system that supports locks inside of transactions must ensure
+ the pessimistic critical sections of the locks inside of transactions
+ are not violated. This is achieved by making the containing transactions
+ either isolated or irrevocable once the lock inside the transaction is
+ obtained. Lemma 2 proves the necessity of the irrevocability characteristic
+ for LiT transactions.
+ 
+
+ Locks Inside of Transactions Lemma 2. Any lock L obtained during an in-flight
+ transaction Tif requires Tif be immediately and permanently promoted
+ to an irrevocable transaction, characterized by Tif (irrevocable) = true,
+ which cannot be aborted.
+ 
+
+ Proof. (Contradiction) Given: threads T1 and T2 execute inc() and get()
+ from Figure 19, respectively and variables x = 0, y = 0. ++x and ++y
+ operations within inc() are unguarded direct access variable operations
+ that perform no transactional undo or redo logging operation; these operations
+ are irreversible (e.g. normal pessimistic critical section operations).
+ The atomic property of any transaction T requires all memory operations
+ of T are committed or none are committed.
+ 
+
+ Execution: T1 starts transaction Tx1 (Tx1(irrevocable) = false) and completely
+ executes lines 3-7, setting x = 1. T2 executes 13- 14, obtains lock L1,
+ released by Tx1 and flags Tx1 to abort due to its identified lock conflict.
+ T2 reads x = 1 and y = 0, unlocks L1 and returns. Tx1 tries to lock L1,
+ but instead is required to abort, causing the atomic transactional property
+ of Tx1 to be violated since ++x has been performed and will not be undone
+ when Tx1 is aborted.
+ 
+<pre class="programlisting">1 int x = 0, y = 0;
+2
+3 void inc() {
+4 for (transaction t;;t.restart())
+5 try {
+6 t.add_conflicting_lock(L1);
+7 lock(L1); ++x; unlock(L1);
+8 lock(L1); ++y; unlock(L1);
+9 t.end(); break;
+10 } catch (aborted_tx&) {}
+11 }
+12
+13 void get(int &retX, int &retY) {
+14 lock(L1);
+15 retX = x; retY = y;
+16 unlock(L1);
+17 }
+
+Figure 19. Violating LiT Lemma 2.
+</pre>
+
+ Referring again to Figure 19, now consider the correct execution (following
+ Lemma 2) of threads T1 and T2 of inc() and get(), respectively, with
+ variables x = 0, y = 0. T1 starts transaction Tx1 and executes lines
+ 3-7, setting x = 1 and Tx1(irrevocable) = true. T2 executes 13-14, but
+ fails to obtain lock L1 even though it is released by Tx1. T2 fails to
+ obtain lock L1 because in order to do so would require Tx1 be aborted
+ as it has flagged itself as conflicting with lock L1 via t.add_conflicting_lock(L1).
+ Yet, Tx1 cannot be aborted since Tx1(irrevocable) = true. T2 stalls until
+ Tx1 completes, setting x = 1, y = 1. T2 then executes, obtaining the
+ necessary locks and returning x = 1 and y = 1 the atomically correct
+ values for x and y (equivalent values) given transaction Tx1.
+ 
+
+ By incorporating both Lemma 1 and 2, locks inside of transactions naturally
+ compose and emit database ACI characteristics; atomic, consistent and
+ isolated. They are atomic (all operations commit): once a lock is obtained
+ inside a transaction, the transaction becomes irrevocable. This ensures
+ that all operations will commit, irrespective of how many locks are obtained
+ within the LiT transaction. They are consistent: no conflicting locks
+ or transactions can run along side the irrevocable LiT transaction, ensuring
+ memory correctness. They are isolated: conflicting locks or transactions
+ are disallowed from running in conjunction with an LiT transaction, preventing
+ its state from being visible before it commits. Even when a lock is released
+ inside an LiT transaction, other threads remain unable to obtain the
+ lock until the transaction commits.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.criticality_of_lit_lock_composition"></a><h6>
+<a name="id4904675"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.criticality_of_lit_lock_composition">Criticality
+ of LiT Lock Composition</a>
+ </h6>
+
+ The composable nature of LiT locks is critical to the incremental adoption
+ of transactions into pre-existing, lock-based parallel software. To understand
+ this, consider a multi-threaded linked list implemented using mutual
+ exclusion locks. The linked list software is mature, thoroughly tested
+ and contains lookup(), insert() and remove() methods. A software designer
+ wishes to extend the linked list's behavior to include a move() operation.
+ The move() operation behaves in the following way: if element A exists
+ in the list and element B does not exist in the list, element A is removed
+ from the list and element B is inserted into the list.With LiT lock composition,
+ the move() operation could be implemented entirely from the previously
+ built locking implementation. Figure 20 demonstrates how this is achieved
+ within the TBoost.STM LATM extension.
+ 
+<pre class="programlisting">1 bool move(node const &A, node const &B) {
+2 // compose locking operations: lookup(), remove()
+3 // & insert() in an irrevocable & indivisible tx
+4 // to make a new transaction-based move() method
+5 for (transaction t;;t.restart())
+6 try {
+7 t.add_tx_conflicting_lock(list_lock_);
+8 // lookup() uses lock list_lock_
+9 if (lookup(A) && !lookup(B)) {
+10 remove(A); // uses lock list_lock_
+11 insert(B); // uses lock list_lock_
+12 }
+13 else return false;
+14
+15 t.end(); return true;
+16 } catch (aborted_tx&) {}
+17 }
+
+Figure 20. Move Implemented with LiT Lock Composition.
+</pre>
+
+ The move() method in Figure 20 is viewed by other threads as an indivisible
+ operation whose intermediate state is isolated from other threads, even
+ though it contains four disjoint pessimistic critical section invocations
+ (e.g. two lookups, a remove and an insert). Even when listlock
+ is released intermittently during the transaction execution, other threads
+ are prevented from obtaining it until the transaction commits. This behavior
+ ensures each pessimistic critical section within the transaction is prevented
+ from being viewed independently. Once the transaction commits other threads
+ can obtain listlock and view the
+ cumulative affects of the move() operation.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.understanding_lit_lock_composition"></a><h6>
+<a name="id4905286"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.understanding_lit_lock_composition">Understanding
+ LiT Lock Composition</a>
+ </h6>
+
+ Figure 21 shows a transfer function implemented using LiT lock composition.
+ This example was chosen because the code sample is small enough to be
+ presented in full (not possible with the prior linked list move() example).
+ Figure 21 uses LiT TX-lock protection and contains two locks inside of
+ the same transaction that are subsumed by the transaction. The transaction
+ composes the two separate lock-based critical sections into an atomically
+ viewed and isolated operation.
+ 
+
+ Consider threads T1 executing lit_transfer(1), T2 executing get1() and
+ T3 executing get2() with x1 = 0 and x2 = 0 in the time line shown in
+ Figure 22. The dotted vertical lines in the conflicting lock time in
+ Figure 22 demonstrate when T1's transaction tx1 obtains and releases
+ locks L1 and L2 with regard to T2 and T3. Thread T1 starts transaction
+ tx1 and adds L1 and L2 to tx1's conflicting lock list. Next, tx1 locks
+ L2 and becomes irrevocable (Lemma 2). Thread T2 then attempts to lock
+ L1, however, since L1 conflicts with tx1 and tx1 is irrevocable, thread
+ T2 is disallowed from aborting tx1 and is therefore prevented from obtaining
+ L1, stalling instead. After tx1 sets x2 = ??1 and unlocks L2, thread
+ T3 tries to lock L1, however, it is disallowed because L1 is on tx1's
+ conflicting lock list and tx1 is irrevocable. Thus, thread T3 is stalled.
+ Transaction tx1 then locks L1, sets x1 = 1 and unlocks
+ 
+<pre class="programlisting">1 int x1 = 0, x2 = 0;
+2
+3 void lit_transfer(int transfer) {
+4 for (transaction t;;t.restart())
+5 try {
+6 t.add_tx_conflicting_lock(L1);
+7 t.add_tx_conflicting_lock(L2);
+8
+9 lock(L2); x2 -= transfer; unlock(L2);
+10 lock(L1); x1 += transfer; unlock(L1);
+11
+12 t.end(); break;
+13 } catch (aborted_tx&) {}
+14 }
+15
+16 void get1and2(int& val1, int& val2) {
+17 lock(L1); lock(L2);
+18 val1 = x1; val2 = x2;
+19 unlock(L2); unlock(L1);
+20 }
+21 void get1(int& val) {
+22 lock(L1); val = x1; unlock(L1);
+23 }
+24 void get2(int& val) {
+25 lock(L2); val = x2; unlock(L2);
+26 }
+
+Figure 21. LiT Transaction and Two Locking Getters.
+</pre>
+
+ L1. When tx1 commits, threads T2 and T3 are unstalled and read x1 = 1
+ and x2 = ??1, respectively, the correct atomic values for the lit_transfer(1)
+ operation with lock composition.
+ 
+
+ Figure 22. Composed LiT Example using TX-Lock Protection.
+ 
+
+ In the above scenario, both T2 and T3 tried to acquire the unlocked locks
+ L1 and L2 but failed due to tx1's irrevocability even though the locks
+ themselves were available. The characteristic of disallowing lock acquisition
+ even when locks are available is a primary attribute of LiT transactions.
+ This characteristic is not present in systems which use locks alone,
+ and is a key attribute to enabling lock composition. As demonstrated
+ earlier with LoT transactions, a lock and a transaction conflicting with
+ the same lock cannot both execute simultaneously. LiT transactions use
+ this same behavior and extend it to favor transactions over locks once
+ a lock is obtained inside of a transaction, making it irrevocable. By
+ restricting access of locks to in-flight LiT transactions which have
+ acquired (and then released) them, the system ensures any remaining behavior
+ not yet performed by the transaction will occur prior to other threads
+ obtaining such released locks. This ensures
+ 
+
+ all the pessimistic critical sections within an LiT transaction are executed
+ in isolation and consistently without memory interference from outside
+ locking threads. Note that this was the case when T3 tried to acquire
+ lock L2 even after transaction tx1 had completed its operations on its
+ shared memory x2.
+ 
+<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lit_lock_identification"></a><h6>
+<a name="id4906362"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction.lit_lock_identification">LiT
+ Lock Identification</a>
+ </h6>
+
+ LiT TX-lock protection requires that all transaction conflicting locks,
+ those locks used directly inside of transactions, be identified prior
+ to any lock being obtained within the transaction; failure to do so can
+ lead to deadlocks. A simple example of how adding conflicting locks as
+ they are obtained inside of transactions can lead to deadlocks can be
+ derived from Figure 21. If lit_transfer() is executed without adding
+ conflicting locks (e.g. no calls to add_conflicting_lock()), the following
+ deadlock is possible. Thread T1 executes lines 3-5, skips lines 6-7 (the
+ conflict calls) and executes line 9 locking L2 and adding it to its conflicting
+ lock list. Thread T2 then executes lines 16 and part of line 17 of get1and2(),
+ locking L1.Without the transactional code identifying L1 as a conflict,
+ the TM system would not disallow T2 from locking L1. The system is now
+ deadlocked. T2 cannot proceed with locking L2 as L2 has been added to
+ T1 conflicting lock list, yet T1 cannot proceed as lock L1 is held by
+ T2.
+ 
+
+ These deadlocks scenarios are overcome by requiring the LiT TM-lock or
+ TX-lock protection to list all conflicting locks prior to obtaining any
+ locks within transactions. Attempting to use locks inside of transactions
+ without first identifying them as conflicts causes TBoost.STM to throw
+ an exception informing the programmer of the missed conflicting lock
+ and how to correct the error. Recycling the same scenario as above with
+ conflicting locks identified at the start of the transaction avoids deadlocks.
+ For example, thread T1 adds locks L1 and L2 to its conflicting lock list.
+ It then executes lines 3-8 and part of line 9, locking L2 (but not unlocking
+ it). Thread T2 executes lines 16 and part of 17, trying to lock L1, and
+ sees T1's transaction as conflicting. Thread T2 tries to abort T1's transaction,
+ but is disallowed as the transaction is irrevocable (see Lemma 2). T2
+ is therefore stalled prior to obtaining lock L1. T1 continues and executes
+ the remainder of line 9-12, obtaining and releasing lock L1 and finally
+ committing. Once T1's transaction has committed, T2 is allowed to resume
+ and runs to completion.
+ 
+</div>
<div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title">
<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.unrecoverable_transactions_to_manage_with_i_o"></a><a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.unrecoverable_transactions_to_manage_with_i_o" title="Unrecoverable transactions to manage with I/O">Unrecoverable
 transactions to manage with I/O</a>
</h5></div></div></div></div>
-<div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title">
-<a name="toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction"></a><a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.tm_specific_concepts.lock_aware_transaction" title="Lock-aware transaction">Lock-aware
- transaction</a>
-</h5></div></div></div></div>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
@@ -629,14 +1606,16 @@
<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.memory_management">Memory
 Management</a></dt>
<dt>RAII</dt>
-<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.exception_safety">Exception
- Safety</a></dt>
+<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.mixin_versus_wrapper_helpers">Mixin
+ versus wrapper helpers</a></dt>
+<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.why___boost_stm_s___cache_uses_now_memcpy_instead_of_copy_constructor_and_assignement">Why
+ TBoost.STM's cache uses now memcpy instead of copy-constructor and assignement</a></dt>
<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.move_semantics">Move
 semantics</a></dt>
<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.parametric_polymorphism_and_subtype_polymorphism">Parametric
 Polymorphism and Subtype Polymorphism</a></dt>
-<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_atomic_transaction_macro_blocks">Language-like
- atomic transaction macro blocks</a></dt>
+<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks">Language-like
+ macro blocks</a></dt>
</dl></div>

 This section briefly discusses some of the C++ and library-specific concepts
@@ -658,11 +1637,11 @@
 TBoost.STM is built with native language compatibility as a top priority
 - as such, it does not require language extensions or violate natural
 language semantics. Native language compatibility is a foremost concern
- due to C++0x set to specifically resist language extensions [29]. While
- in other languages, such as Java, STM systems which require language
- extensions may be practical, within C++ this same approach seems unrealistic.
- Thus, there is a very practical need for a native language ready STM
- solution for C++.
+ due to C++0x set to specifically resist language extensions. While in
+ other languages, such as Java, STM systems which require language extensions
+ may be practical, within C++ this same approach seems unrealistic. Thus,
+ there is a very practical need for a native language ready STM solution
+ for C++.
 
</div>
<div class="section" lang="en">
@@ -749,41 +1728,352 @@
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h5 class="title">
-<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.exception_safety"></a><a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.exception_safety" title="Exception Safety">Exception
- Safety</a>
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.mixin_versus_wrapper_helpers"></a><a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.mixin_versus_wrapper_helpers" title="Mixin versus wrapper helpers">Mixin
+ versus wrapper helpers</a>
+</h5></div></div></div>
+
+ TBoost.STM's provides some helper classes to make transactional objects.
+ The user should use each one on a per case, taking in account the advantages
+ and liabilities of each one.
+ 
+<div class="orderedlist"><ol type="1">
+<li>
+ mixin; transaction_object
+ </li>
+<li>
+ intrinsic wrapper: transactional_object
+ </li>
+<li>
+ extrinsic wrapper: transactional_reference_cache
+ </li>
+</ol></div>
+
+ Next follows the features the user should question
+ 
+<div class="orderedlist"><ol type="1">
+<li>
+ Allows to use an existing class, for example std::pair class. Does
+ the helper class allows the smart pointers to return an reference to
+ an existing class?
+ <div class="itemizedlist"><ul type="disc">
+<li>
+ mixin: There is no mean
+ </li>
+<li>
+ intrinsic: the associated smart pointers to a transactional_object<std::pair>
+ returns a std::pair reference
+ </li>
+<li>
+ extrinsic: This is exacly the role of the extrinsec approach
+ </li>
+</ul></div>
+</li>
+<li>
+ Allows to use an existing instance variable, for example a variable
+ of type std::pair class. Does the helper class allows the smart pointers
+ to return an reference to an existing class?
+ <div class="itemizedlist"><ul type="disc">
+<li>
+ mixin: There is no mean
+ </li>
+<li>
+ intrinsic: There is no mean
+ </li>
+<li>
+ extrinsic: This is exacly the role of the extrinsec approach
+ </li>
+</ul></div>
+</li>
+<li>
+ Works for class hierarchies. if D isa B, then helper<D> is a
+ helper
+ <div class="itemizedlist"><ul type="disc">
+<li>
+ mixin: This is exactly the role of the extrinsec approach since
+ we have added the base parameter (class B: mixin{} class
+ D: mixin<D,B>{}).
+ </li>
+<li>
+ intrinsic: Not directly, we need to use some form of cast. clas
+ D:B{}. intrinsic* ptr=new intrinsic<D>(); ????
+ </li>
+<li>
+ extrinsic: N/A because the helper is hidden
+ </li>
+</ul></div>
+</li>
+<li>
+ Allows to avoid the forwarding problem for base classes
+ <div class="itemizedlist"><ul type="disc">
+<li>
+ mixin: As the user defines its own class he can define the exact
+ constructors avoiding the problem added the base parameter
+ </li>
+<li>
+ intrinsic: the wrapper must define generic constructors having
+ the forwarding problem.
+ </li>
+<li>
+ extrinsic: N/A because the helper is hidden
+ </li>
+</ul></div>
+</li>
+<li>
+ Allows to avoid the forwarding problem for derived classes
+ <div class="itemizedlist"><ul type="disc">
+<li>
+ mixin: As the inheritance of the base class is done using the helper
+ the base mixin must define generic constructors having the forwarding
+ problem.
+ </li>
+<li>
+ intrinsic: the wrapper must define generic constructors having
+ the forwarding problem.
+ </li>
+<li>
+ extrinsic: N/A because the helper is hidden
+ </li>
+</ul></div>
+</li>
+<li>
+ Performs optimally.
+ <div class="itemizedlist"><ul type="disc">
+<li>
+ mixin: optimal, only one allocation/copy
+ </li>
+<li>
+ intrinsic: optimal, only one allocation/copy
+ </li>
+<li>
+ extrinsic: instead of a single allocation/copy we need two, so
+ no optimal
+ </li>
+</ul></div>
+</li>
+</ol></div>
+
+ The following table is a compilation of the preceding analysis:
+ 
+<div class="table">
+<a name="id4906890"></a>Table 1.3. Comparaison with other STM systems
+<div class="table-contents"><table class="table" summary="Comparaison with other STM systems">
+<colgroup><col></colgroup>
+<thead><tr>
+<th>
+ 
+ feature
+ 
+ </th>
+<th>
+ 
+ Mixin
+ 
+ </th>
+<th>
+ 
+ Intrinsic Wrapper
+ 
+ </th>
+<th>
+ 
+ Extrinsic Wrapper
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ existing class
+ 
+ </td>
+<td>
+ 
+ [No
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ *Yes
+ 
+ </td>
+<td class="auto-generated"> </td>
+</tr>
+<tr>
+<td>
+ 
+ *Yes
+ 
+ </td>
+<td class="auto-generated"> </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ <pre class="programlisting">[
+ [[*existing variable]] [[No]] [[No]] [[*Yes]]
+]
+[
+ [[*existing class hierarchy]] [[No]] [[No]] [[*Yes]]
+]
+[
+ [[*avoid the forwarding problem for base classes]] [[Yes]] [[No]] [[*Yes]]
+]
+[
+ [[*avoid the forwarding problem for derived classes]] [[No]] [[No]] [[*Yes]]
+]
+[
+ [[*Works for class hierarchies]] [[*Yes]] [[No]] [[*Yes]]
+]
+[
+ [[*Performs optimaly]] [[*Yes]] [[*Yes]] [[No]]
+]
+</pre>
+
+ [ [existing variable] [[No]] [[No]]
+ [Yes] ] [ [existing
+ class hierarchy] [[No]] [[No]] [Yes]
+ ] [ [avoid the forwarding problem for base classes]
+ [[Yes]] [[No]] [Yes] ] [ [avoid the forwarding problem for derived classes]
+ [[No]] [[No]] [Yes] ] [ [Works
+ for class hierarchies] [Yes]
+ [[No]] [Yes] ] [ [Performs
+ optimaly] [Yes] [Yes] [[No]] ] ]
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.why___boost_stm_s___cache_uses_now_memcpy_instead_of_copy_constructor_and_assignement"></a><a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.why___boost_stm_s___cache_uses_now_memcpy_instead_of_copy_constructor_and_assignement" title="Why TBoost.STM's cache uses now memcpy instead of copy-constructor and assignement">Why
+ TBoost.STM's cache uses now memcpy instead of copy-constructor and assignement</a>
</h5></div></div></div>
+<div class="toc"><dl>
+<dt>Domain</dt>
+<dt><a href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.why___boost_stm_s___cache_uses_now_memcpy_instead_of_copy_constructor_and_assignement.exception_safety">Exception
+ Safety</a></dt>
+<dt>Performances</dt>
+</dl></div>

- TBoost.STM fulfills Abrahams' basic exception safety guarantee for deferred
- updating, but cannot supply any exception safety guarantee for direct
- updating. The basic guarantee for exception safety states that if an
- exception is thrown, the operation may have side-effects but is in a
- consistent state. The basic guarantee is less strict than the strong
- guarantee which specifies if an exception is thrown there are no side-effects.
- The highest level of exception safety, above the strong guarantee, is
- the nothrow guarantee which disallows exceptions from being thrown entirely.
- 
-
- Within deferred updating, TBoost.STM can only afford to implement the
- basic guarantee because if memory is partially committed and then a user
- exception is thrown, no original state exists for the already committed
- memory. Therefore, already committed memory in a deferred updating system,
- must stay committed since no reverted original state can be used to revert
- the changes. To implement such a system would result in a substantial
- performance degradation to the overall system, effectively doubling memory
- size and copy operations. Due to these costs, a double-copy implementation
- is not performed and the basic guarantee for deferred updating is deemed
- acceptable.
- 
-
- Within direct updating, memory updates are done immediately on global
- memory, so transactions naturally achieve strong exception safety guarantees
- for commits. Aborts within direct updating, however, invoke copy constructors
- for restoration of the original global memory state. These copy constructors
- can throw exceptions which then can lead to a partially restored global
- state for aborted exceptions that are short-circuited by user-defined
- copy constructor exceptions. As such, no exception safety guarantee can
- be made for direct updating when used in C++, a downfall of the updating
- policy.
+ Until version 0.3 TBoost.STM's used the copy-constructor to clone a new
+ object which will be used directly by the derreed update policy and as
+ a backup by the direct update policy. This has some drawbacks:
+ 
+<div class="orderedlist"><ol type="1">
+<li>
+ Domain: Transactional object are limited to CopyConstructible objects
+ </li>
+<li>
+ Exception safety: As the user copy-constructor and assignement can
+ throw exceptions
+ </li>
+<li>
+ Performances: Whole copy, either copy-constructor and assignement,
+ of transactional objects could be expensive
+ </li>
+</ol></div>
+
+ The following sections explain deeply this issues.
+ 
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.why___boost_stm_s___cache_uses_now_memcpy_instead_of_copy_constructor_and_assignement.domain"></a><a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.why___boost_stm_s___cache_uses_now_memcpy_instead_of_copy_constructor_and_assignement.domain" title="Domain">Domain</a>
+</h6></div></div></div>
+
+ It seems a hard limitation to force a STM user to make all its classes
+ CopyConstructible and Assignable.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.why___boost_stm_s___cache_uses_now_memcpy_instead_of_copy_constructor_and_assignement.exception_safety"></a><a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.why___boost_stm_s___cache_uses_now_memcpy_instead_of_copy_constructor_and_assignement.exception_safety" title="Exception Safety">Exception
+ Safety</a>
+</h6></div></div></div>
+
+ With copy-constructor and assignement TBoost.STM fulfills Abrahams'
+ basic exception safety guarantee for deferred updating, but cannot
+ supply any exception safety guarantee for direct updating. The basic
+ guarantee for exception safety states that if an exception is thrown,
+ the operation may have side-effects but is in a consistent state. The
+ basic guarantee is less strict than the strong guarantee which specifies
+ if an exception is thrown there are no side-effects. The highest level
+ of exception safety, above the strong guarantee, is the nothrow guarantee
+ which disallows exceptions from being thrown entirely.
+ 
+
+ Within deferred updating, TBoost.STM can only afford to implement the
+ basic guarantee because if memory is partially committed and then a
+ user exception is thrown, no original state exists for the already
+ committed memory. Therefore, already committed memory in a deferred
+ updating system, must stay committed since no reverted original state
+ can be used to revert the changes. To implement such a system would
+ result in a substantial performance degradation to the overall system,
+ effectively doubling memory size and copy operations. Due to these
+ costs, a double-copy implementation is not performed and the basic
+ guarantee for deferred updating is deemed acceptable.
+ 
+
+ Within direct updating, memory updates are done immediately on global
+ memory, so transactions naturally achieve strong exception safety guarantees
+ for commits. Aborts within direct updating, however, invoke copy constructors
+ for restoration of the original global memory state. These copy constructors
+ can throw exceptions which then can lead to a partially restored global
+ state for aborted exceptions that are short-circuited by user-defined
+ copy constructor exceptions. As such, no exception safety guarantee
+ can be made for direct updating when used in C++, a downfall of the
+ updating policy.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h6 class="title">
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.why___boost_stm_s___cache_uses_now_memcpy_instead_of_copy_constructor_and_assignement.performances"></a><a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.why___boost_stm_s___cache_uses_now_memcpy_instead_of_copy_constructor_and_assignement.performances" title="Performances">Performances</a>
+</h6></div></div></div>
+
+ Another problem with the copy is that we will need to copy the whole
+ logical object when what we need is just the phisical part, e.g. if
+ copy is used to clone the transactional object, each time we modify
+ a linked list, we will copy the entire list, even if only one node
+ is modified.
+ 
+
+ A pure transactional object is a transactional object that do not points
+ to any non transactional object. For example, a transactional object
+ including a std::string, is not a pure transactional object, because
+ std::string has a pointer to a dynamically allocated memory which is
+ not a transactional object. For these non pure transactional objects
+ a copy will be needed. One way to limit this is to place every non
+ pure transactional object on a separated class and add a pointer to
+ it. So for example instead of doing
+ 
+
+ class X { std::string str; // ... other fields
+ 
+
+ };
+ 
+
+ which will make X non pure TO, we can do
+ 
+
+ class X { tx_ptr<std::string> str_ptr; / owned pointer
+ which is cloned when making a copy but not by the STM system. /
+ ... other fields
+ 
+
+ };
+ 
+
+ In this way X will be a pure TO poining to a non pure TO.
+ 
+</div>
+
+ If memcpy is not portable we can consider specializing the clone and
+ copy_state virtual functions.
+ 
+
+ The user must state explicitly the TO that are not pure by overloading
+ the cacheclone, cache ... . We
+ can also define a trait.
 
</div>
<div class="section" lang="en">
@@ -792,9 +2082,10 @@
 semantics</a>
</h5></div></div></div>

- We solve the problem of commit-time and abort-time exceptions by using
- move semantics in place of copy semantics. The idea of moving is new
- to C++ and will be available in the next version of the standard.
+ When copying is needed we solve the problem of commit-time and abort-time
+ exceptions by using move semantics in place of copy semantics when the
+ class provided it. The idea of moving is new to C++ and will be available
+ in the next version of the standard.
 
</div>
<div class="section" lang="en">
@@ -814,8 +2105,8 @@
 on the other hand, reduces type-safety to some degree, but gains run-time
 flexibility unachievable with C++ templates alone. Other mechanisms also
 exist to create general purpose code, such as void pointers or preprocessor
- macros, but are considered unsafe and error-prone [8] and thusly, not
- used in TBoost.STM.
+ macros, but are considered unsafe and error-prone and thusly, not used
+ in TBoost.STM.
 

 TBoost.STM uses both parametric and subtype polymorphism throughout its
@@ -832,10 +2123,243 @@
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h5 class="title">
-<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_atomic_transaction_macro_blocks"></a><a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_atomic_transaction_macro_blocks" title="Language-like atomic transaction macro blocks">Language-like
- atomic transaction macro blocks</a>
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks"></a><a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks" title="Language-like macro blocks">Language-like
+ macro blocks</a>
</h5></div></div></div>

+ The synchronization primitives supported in TBoost.STM's programming
+ model are mutual exclusion locks, timed locks and transactions. Mutual
+ exclusion locks have architectural support in all modern instruction
+ set architectures and are widely considered the most common synchronization
+ primitive [11]. Transactions, a parallel programming abstraction by Herlihy
+ and Moss [10], are currently implemented in software with potential hardware
+ support in the near future [4].
+ 
+<div class="table">
+<a name="id4908020"></a>Table 1.4. Comparaison with other STM systems
+<div class="table-contents"><table class="table" summary="Comparaison with other STM systems">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Keyword
+ 
+ </th>
+<th>
+ 
+ Behavior
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ use_lock(L)
+ 
+ </td>
+<td>
+ 
+ Acquires lock L and executes critical section.
+ Supports single operations without {} scope construction such as,
+ use_lock(L) foo()
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ use_timed_lock(MS, L)
+ 
+ </td>
+<td>
+ 
+ Acquires timed lock L and executes a critical
+ section based on MS millisecond timer. If the timer expires without
+ obtaining lock L, an exception is thrown. This extension allows
+ the exception to escape the parallel construct scope. Supports
+ single operations without {} scope construction such as, use_timed_lock(1,
+ L) foo()
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ try_timed_lock(MS, L)
+ 
+ </td>
+<td>
+ 
+ Same as use_timed_lock(L), but exceptions
+ are caught locally. Requires catch_lock_timeout(L) or lock_timeout
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ catch_lock_timeout(E)
+ 
+ </td>
+<td>
+ 
+ Catches timed lock exception E thrown from
+ try_timed_lock(L). Required to follow all try_timed_lock(L), unless
+ followed by lock_timeout
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ lock_timeout
+ 
+ </td>
+<td>
+ 
+ Catches and discards failed timer exception
+ thrown from try_timed_lock(L). Required to follow all try_timed_lock(L),
+ unless followed by catch_lock_timeout(E)
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ 
+ Table 1. TBoost.STM Mutual Exclusion Locking Parallel Constructs.
+ 
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.library_based_lock_implementations"></a><h6>
+<a name="id4908228"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.library_based_lock_implementations">Library-based
+ Lock Implementations</a>
+ </h6>
+
+ Mutual exclusion locks, or just locks, ensure a programmerspecified set
+ of operations are limited to one thread of execution [7, 11]. Lock-guarded
+ operations, also known as pessimistic critical sections, require that
+ all threads obtain a single-ownership flag before executing the guarded
+ operations. If N threads simultaneously attempt to execute the same pessimistic
+ critical section, one thread is allowed forward progress while the remaining
+ N ?? 1 threads are stalled. An example of three distinct types of locking
+ is shown in Figure 1.
+ 
+<pre class="programlisting">1 // mutual exclusion with lock()/unlock().
+2 pthread_mutex_lock(l);
+3 int ret = foo();
+4 pthread_mutex_unlock(l);
+5 return ret;
+</pre>
+
+ or
+ 
+<pre class="programlisting">1 // mutual exclusion with automatic objects.
+2 {
+3 scoped_lock<pthread_mutex_t> lock(l);
+4 return foo(); // lock released
+5 }
+</pre>
+
+ or
+ 
+<pre class="programlisting">1 // language-like mutual exclusion.
+2 use_lock(l) return foo(); // lock released
+
+Figure 1. Library-based Lock Implementations.
+</pre>
+
+ In Figure 1, the automatic object and language-like mutual exclusion
+ interfaces are safer than the pthread_mutex_lock() and pthread_mutex_unlock()
+ interfaces. If an exception is thrown from foo() after pthread_mutex_lock()
+ is called, its corresponding pthread_mutex_unlock() will not be called
+ causing the application to deadlock. Both the automatic object and language-like
+ implementations avoid deadlock in the event of an exception thrown from
+ foo(). However, these implementations have notable differences in programmatic
+ scoping and programmer error.
+ 
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.pitfalls_in_scoping_of_automatic_object_locks"></a><h6>
+<a name="id4908625"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.pitfalls_in_scoping_of_automatic_object_locks">Pitfalls
+ in Scoping of Automatic Object Locks</a>
+ </h6>
+
+ A closer examination of the automatic object and language-like approaches
+ to locking reveal differences in potential programmerinduced error. Figure
+ 2 demonstrates a sequential locking order example, a common solution
+ to complex fine-grained locking implementations, in which locks must
+ be obtained in a specific sequential order to avoid deadlocking. If the
+ scope ({}) operators are removed from Figure 2 the behavior of both the
+ scoped_locks and the use_locks are changed. In the case of the scoped_locks,
+ the automatic objects will no longer be terminated after operation_C()
+ and they will thereby retain any locks acquired upon construction until
+ the next immediate scope is terminated. In the case of the use_locks,
+ the locks remain locked only for operation_A() and are then released.
+ Both locking structures are changed to behave incorrectly when the scope
+ operators ({}) are removed, but we believe programmers are less likely
+ to accidentally remove the scope from the use_lock idiom than the scoped_lock.
+ 
+<pre class="programlisting">1 // mutual exclusion with automatic objects.
+2 {
+3 scoped_lock<pthread_mutex_t> lock1(L1);
+4 scoped_lock<pthread_mutex_t> lock2(L2);
+5 scoped_lock<pthread_mutex_t> lock3(L3);
+6 operation_A();
+7 operation_B();
+8 operation_C();
+9 }
+</pre>
+
+ or 1 // language-like mutual exclusion. 2 use_lock(L1) use_lock(L2) use_lock(L3)
+ 3 { 4 operation_A(); 5 operation_B(); 6 operation_C(); 7 }
+ 
+<pre class="programlisting">Figure 2. A Required Sequential Locking Order.
+</pre>
+
+ The reason why programmers are less likely to accidentally remove the
+ scope from use_lock as opposed to scoped_lock is because the programming
+ structure of use_lock is native to C++ in many ways. For example, the
+ code structure shown below is found throughout C, C++ and Java:
+ 
+<pre class="programlisting">1 grammatical-phrase
+2 {
+3 operations ...
+4 }
+</pre>
+
+ A number of control structures, specifically in C++, follow this format,
+ such as, if statements, for loops, switches, classes, structs and so
+ forth. While the use_lock structure follows this common practice, scoped
+ automatic objects (e.g., scoped_locks) do not. Because scoped_locks unavoidably
+ deviate from the above common code structure, due to their automatic
+ object basis, their scope is more likely to be accidentally removed by
+ novice programmers as unnecessary.
+ 
+
+ The side-effect of accidental scope removal for automatic objects is
+ that resources obtained by these objects are not released until the following
+ scope closure is reached. In some cases, such as file closing, it may
+ be acceptable for automatic objects to delay the release of resources.
+ However, in other cases, such as the case with locks, it is unacceptable
+ for automatic objects to delay the release of resources. In particular,
+ if locks are not released when the programmer intended, the resulting
+ behavior can temporarily or permanently stall all other threads from
+ making forward progress. If threads are temporarily suspended from forward
+ progress, program performance is degraded, yet if threads are permanently
+ suspended from making forward progress, the program results in a deadlock.
+ Both cases are unacceptable for locks because locks are used as a tool
+ to optimize program performance and in both cases the delayed release
+ of locks results in unoptimized performance.
+ 
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.library_based_transaction_implementations"></a><h6>
+<a name="id4909080"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.library_based_transaction_implementations">Library-based
+ Transaction Implementations</a>
+ </h6>
+
 Transactions allow an unlimited number of threads to execute their optimistic
 critical sections. Transactions can perform their writes off to the side,
 ensuring global memory is preserved until the transaction's atomic operations
@@ -847,26 +2371,29 @@
 for transactions from a library-based approach where x is shared memory
 that must be synchronized.
 
-
- transaction with begin()/end():
- 
<pre class="programlisting">begin_transaction(t);
tx_write(t, x) = val;
end_transaction(t);
+
+transaction with begin()/end():
</pre>

- transaction with automatic object:
+ or
 
-<pre class="programlisting">{
+<pre class="programlisting">{
 transaction t;
 t.write(x) = val;
 t.end();
}
+
+transaction with automatic object:
</pre>

- language transaction:
+ or
 
-<pre class="programlisting">atomic { x = val; }
+<pre class="programlisting">atomic { x = val; }
+
+language transaction:
</pre>

 Inspection of the above code reveals that begin_transaction() and end_transaction()
@@ -881,9 +2408,9 @@
 complexity for transactional retry mechanics and composed transactional
 behaviors.
 
-<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_atomic_transaction_macro_blocks.pitfalls_in_transactional_execution_of_automatic_objects"></a><h6>
-<a name="id4888966"></a>
- <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_atomic_transaction_macro_blocks.pitfalls_in_transactional_execution_of_automatic_objects">Pitfalls
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.pitfalls_in_transactional_execution_of_automatic_objects"></a><h6>
+<a name="id4909452"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.pitfalls_in_transactional_execution_of_automatic_objects">Pitfalls
 in Transactional Execution of Automatic Objects</a>
 </h6>

@@ -893,22 +2420,23 @@
 The code below illustrates the client code necessary to implement a basic
 retry behavior for automatic objects and language-like transactions.
 
-
- automatic object transaction with retry:
- 
<pre class="programlisting">for (transaction t; !t.committed(); t.restart()) {
 try {
 t.write(x) = val;
 t.end();
 } catch (...) {}
}
+
+automatic object transaction with retry
</pre>

- language-like transaction with retry:
+ and
 
-<pre class="programlisting">atomic(t) {
- t.write(x) = val;
+<pre class="programlisting">atomic(t) {
+ t.write(x) = val;
} end_atom
+
+language-like transaction with retry
</pre>

 To complicate matters, some transactions must not implement a retry.
@@ -921,9 +2449,6 @@
 The code above shows the differences between an automatic object and
 language-like implementation for parent and child transactions.
 
-
- automatic object:
- 
<pre class="programlisting">// parent tx with automatic object:
for (transaction t; !t.committed(); t.restart()) {
 try {
@@ -939,9 +2464,11 @@
 t.write(y) += val;
 t.end();
}
+
+automatic object:
</pre>

- language-like transaction:
+ and
 
<pre class="programlisting">// parent tx with language-like transaction.
atomic(t) {
@@ -951,10 +2478,12 @@

// child tx with language-like transaction.
void foo(int val) {
- atomic(t) {
- t.write(y) += val;
+ atomic(t) {
+ t.write(y) += val;
 } end_atom
}
+
+language-like transaction:
</pre>

 The retry mechanics' syntactic overhead for automatic objects is nearly
@@ -974,9 +2503,9 @@
 errors. For these reasons, a number of TM researchers have been in favor
 of direct language integration of TM instead of API-only approaches.
 
-<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_atomic_transaction_macro_blocks.disadvantages_of_language_based_transactional_integration"></a><h6>
-<a name="id4889874"></a>
- <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_atomic_transaction_macro_blocks.disadvantages_of_language_based_transactional_integration">Disadvantages
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.disadvantages_of_language_based_transactional_integration"></a><h6>
+<a name="id4910450"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.disadvantages_of_language_based_transactional_integration">Disadvantages
 of Language Based Transactional Integration</a>
 </h6>

@@ -1011,6 +2540,260 @@
 provides such a solution for C++ that neither library-based automatic
 objects nor language-based parallel abstractions alone can provide.
 
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.parallel_constructs_for_mutually_exclusive_locks"></a><h6>
+<a name="id4910527"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.parallel_constructs_for_mutually_exclusive_locks">Parallel
+ Constructs for Mutually Exclusive Locks</a>
+ </h6>
+
+ In this section we describe the behavior, and give examples, of the TBoost.STM
+ language-like parallel constructs for mutually exclusive locks. The TBoost.STM
+ mutual exclusion locking constructs are shown in Table 1. Each of these
+ constructs allow any type of nesting, ordering and intermixing. Examples
+ of the TBoost.STM locking constructs are shown in Figure 9.
+ 
+<pre class="programlisting">1 // single-line sequential locking
+2 use_lock(L1) use_lock(L2) use_lock(L3) foo();
+1 // multi-line sequential locking
+2 use_lock(L1) use_lock(L2) use_lock(L3) {
+3 foo();
+4 }
+1 // multi-line sequential single 100 ms timed lock
+2 while (polling)
+3 try_timed_lock(100, L1) {
+4 use_lock(L2) use_lock(L3)
+5 {
+6 foo();
+7 polling = false;
+8 }
+9 } lock_timeout { execute_on_failed(); }
+
+Figure 9. Mutual Exclusion Locks with TBoost.STM.
+</pre>
+
+ As demonstrated in Figure 9, a number of locking models can be implemented
+ using a mixture of the use_lock(L), use_timed_lock(MS, L) and try_timed_lock(MS,
+ L) parallel constructs. Each locking interface addresses a unique requirement
+ in client code.
+ 
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.exception_based_timed_locks"></a><h6>
+<a name="id4911030"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.exception_based_timed_locks">Exception-based
+ Timed Locks</a>
+ </h6>
+
+ A notable feature of our TBoost.STM language-like extensions is the use
+ of exceptions in conjunction with timed locks. It is our belief that
+ timed locks are used primarily for polling models and generally require
+ two distinct paths of execution. One path of execution is taken when
+ the lock is obtained before the timeout. The other path of execution
+ is taken when the lock is not obtained before the timeout. In light of
+ this, exceptions thrown when timed locks are not acquired can facilitate
+ a distinction between successful lock acquisition and failed lock acquisition.
+ Client code can become excessively unoptimized or complex if timed sequential
+ locking is necessary and non-throwing automatic objects are used. An
+ example of such unoptimized timed locking is demonstrated in Figure 10.
+ 
+<pre class="programlisting">1 // unoptimized timed locking
+2 while (polling) {
+3 timed_lock tl1(100, L1);
+4 timed_lock tl2(100, L2);
+5 timed_lock tl3(100, L3);
+6
+7 if (tl1.has_lock() && tl2.has_lock() &&
+8 tl3.has_lock()) {
+9 foo();
+10 polling = false;
+11 }
+12 else execute_on_failed();
+13 }
+
+Figure 10. Unoptimized Timed Locking with Automatic Objects.
+</pre>
+
+ Figure 10 illustrates how non-throwing automatic objects can hamper performance
+ if incorrectly implemented and demonstrates an unoptimized implementation
+ of timed locks. Delaying lock acquisition checks until after all timed
+ locks are constructed can result in an a substantial performance degradation
+ if neither L1 nor L2 are acquired. This performance degradation is caused
+ by performing additional unnecessary work after failing to acquire lock
+ L1 and L2.
+ 
+<pre class="programlisting">1 // optimized timed locking
+2 while (polling) {
+3 timed_lock tl1(100, L1);
+4 if (tl1.has_lock()) {
+5 timed_lock tl2(100, L2);
+6 if (tl2.has_lock()) {
+7 timed_lock tl3(100, L3);
+8 if (tl3.has_lock()) {
+9 foo();
+10 polling = false;
+11 }
+12 else execute_on_failed();
+13 }
+14 else execute_on_failed();
+15 }
+16 else execute_on_failed();
+17 }
+
+Figure 11. Optimized Timed Locking with Automatic Objects.
+</pre>
+
+ In order to optimize Figure 10's timed locks, a complex level of if nesting
+ is needed as shown in Figure 11. Figure 11 demonstrates an optimized
+ level of timed locking, but drastically increases the complexity of the
+ software structure. Figure 11 introduces a high level of software complexity
+ as a trade-off for performance. Intermixing the TBoost.STM try_timed_lock(MS,
+ L) and use_timed_lock(MS, L) constructs builds a software structure that
+ is simpler than either Figure 10 or 11 while achieving the same level
+ of performance found in Figure 11. An example of try_timed_lock(MS, L)
+ and use_timed_lock(MS, L) is shown in Figure 12.
+ 
+<pre class="programlisting">1 // multi-line sequential all 100 ms timed lock
+2 while (polling)
+3 try_timed_lock(100, L1) {
+4 use_timed_lock(100, L2)
+5 use_timed_lock(100, L3)
+6 {
+7 foo();
+8 polling = false;
+9 }
+10 } lock_timeout { execute_on_failed(); }
+
+Figure 12. Optimized Timed Locking with TBoost.STM.
+</pre>
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.parallel_constructs_for_transactional_memory"></a><h6>
+<a name="id4912318"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.parallel_constructs_for_transactional_memory">Parallel
+ Constructs for Transactional Memory</a>
+ </h6>
+
+ In this section we describe the behavior, and give examples, of the TBoost.STM
+ language-like parallel constructs for transactional memory. The TBoost.STM
+ transaction-based parallel constructs are shown in Table 2. These transactional
+ constructs enable open-ended transactional nesting behaviors that are
+ important to composition. Examples of the TBoost.STM transactions are
+ shown in Figure 13. Figure 13 demonstrates how transactions are used
+ in various ways. In some cases transactions are single operations, such
+ as in the inc_x() case. At other times transactions consist of
+ 
+<pre class="programlisting">1 void inc_x(int val)
+2 {
+3 atomic(t) { t.write(x) += val; } end_atom
+4 }
+1 void inc_y_and_z(int val)
+2 {
+3 atomic(t) {
+4 t.write(y) += val;
+5 t.write(z) += val;
+6 } end_atom
+7 }
+1 void transfer_x_to_y_z(int val)
+2 {
+3 atomic(t) {
+4 inc_x(-val);
+5 inc_y_and_z(val / 2);
+6 } end_atom
+7 }
+
+Figure 13. Transactions with TBoost.STM.
+</pre>
+
+ multiple operations, such as inc_y_and_z(). More cases exist when transactions
+ are made up of other transactions, such as transfer_x_to_y_z(). The last
+ case, often referred to as composition, is an important characteristic
+ of transactions that most (if not all) other synchronization primitives
+ do not exhibit (more on this later).
+ 
+
+ In the simple case, when no transactional nesting occurs, the transactional
+ retry behavior happens locally. For example, if two threads try to concurrently
+ execute the inc_x() function of Figure 13, only one thread will succeed
+ since both threads cannot simultaneously access and change the same shared
+ memory location. The failing thread will have to retry its transaction.
+ Since inc_x() is a single-level transaction, the failing thread can retry
+ the transaction locally (i.e., restarting at the top of the atomic structure
+ inside inc_x()).
+ 
+
+ Non-trivial cases exist when transactions may be nested and retrying
+ a transaction locally will cause an infinite loop. These cases use composed
+ transactions and (generally) require that a failed transaction be retried
+ from the parent transaction 1. An example of a composed transaction that,
+ if aborted, would require the transaction to be retried from the parent
+ is transfer_x_to_y_z(). This transaction must be retried from the parent,
+ rather than by either of its child transactions individually, (int_x()
+ and inc_y_and_z()) because the values within the shared memory x, y,
+ and z could have been altered by another interleaved transaction.
+ 
+
+ TBoost.STM handles the shifting of transactional retry mechanics from
+ child to parent dynamically and automatically. As demonstrated in Section
+ 3.2, the atomic macro makes numerous calls into the currently active
+ transaction to determine whether its failed commit should result in a
+ local retry or a thrown aborted_transaction exception. The correct path
+ of execution for the transactional retry is based on the run-time state.
+ For example, if int_x() has failed, but it is the only transaction currently
+ being executed by a thread, then it should be retried locally. However,
+ if int_x() has failed, but it is being executed from within transfer_x_to_y_z()
+ then transfer_x_to_y_z() should be re-executed. The re-execution of a
+ parent transaction is enabled by a child transaction identifying the
+ correct behavior and then throwing an exception upward.
+ 
+<a name="toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.transaction_nesting"></a><h6>
+<a name="id4912962"></a>
+ <a class="link" href="rationale.html#toward_boost_stm.appendices.rationale.c___and_library_specific_concepts.language_like_macro_blocks.transaction_nesting">Transaction
+ Nesting</a>
+ </h6>
+
+ While the retry behavior of nested transactions is important, the composed
+ behavior of independently designed transactions is even more important.
+ Transactional composition [8, 15] is the cornerstone of transactional
+ memory. In short, TM allows independently designed transactions to be
+ placed together under the umbrella of a single transaction. This single
+ transaction then behaves in an atomic, consistent and isolated fashion.
+ Furthermore, the single transaction that is composed of many individual
+ transactions is seen as a single indivisible operation to other transactions.
+ 
+
+ As such, an important aspect of transaction nesting is the construction
+ of a transaction without the need to specify it is nested. A similar
+ line of thinking is the construction of a function which is then used
+ inside of another function and so forth. In C++ these nested functions
+ are not created in any special way that describes their use in a given
+ nested structure. Transactions, therefore, should be programmatically
+ constructed in a similar way.
+ 
+
+ To the best of our knowledge, TBoost.STM is the first C++ STM library
+ to implement transactions under a single keyword (atomic) which behaves
+ correctly for both nested and non-nested transactions. While other correct
+ implementations exist at the languagelevel [24] and compiler-level [18],
+ no other library-based solution allows the programmer the practical freedom
+ to implement transactions under a single keyword for transactions at
+ any nesting level.
+ 
+
+ A more realistic example of the importance of nested and nonnested transactions
+ and a universal keyword for both, is shown in Figure 14. Here we implement
+ some basic list operations that are useful when used independently and
+ when used in an cooperative, nested fashion.
+ 
+
+ Figure 14 demonstrates how transactions are composed using TBoost.STM.
+ The goal of the code shown in Figure 14 is to transfer all of the elements
+ from list l to list j that do not already exist in list j. The entire
+ operation is done atomically using four core transactional operations,
+ insert, remove, transfer, and complete_transfer. The additional transactional
+ operation, priority_transfer, is added to demonstrate how client code
+ can wrap a composed transaction and alter its underlying performance
+ in relation to other transactions by modifying the transaction's priority.
+ Wrapping transactions with priority is useful in cases where the original
+ transaction was written in a priority-neutral manner, but now must be
+ used in an explicitly prioritized system. More details of prioritized
+ transactions can be found in [6, 20].
+ 
</div>
</div>
<div class="section" lang="en">
@@ -1019,7 +2802,7 @@
 with other STM systems</a>
</h4></div></div></div>
<div class="table">
-<a name="id4889966"></a>Table 1.3. Comparaison
+<a name="id4913083"></a>Table 1.5. Comparaison
 with other STM systems
<div class="table-contents"><table class="table" summary="Comparaison
 with other STM systems">

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/todo.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/todo.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/todo.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -40,7 +40,7 @@
 to do before review</a>
</h4></div></div></div>
<a name="toward_boost_stm.appendices.todo.tasks_to_do_before_review.interface"></a><h6>
-<a name="id4890886"></a>
+<a name="id4914141"></a>
 <a class="link" href="todo.html#toward_boost_stm.appendices.todo.tasks_to_do_before_review.interface">Interface</a>
 </h6>
<div class="itemizedlist"><ul type="disc">
@@ -59,7 +59,7 @@
 </li>
</ul></div>
<a name="toward_boost_stm.appendices.todo.tasks_to_do_before_review.boostifying_stm"></a><h6>
-<a name="id4890941"></a>
+<a name="id4914196"></a>
 <a class="link" href="todo.html#toward_boost_stm.appendices.todo.tasks_to_do_before_review.boostifying_stm">Boostifying
 STM</a>
 </h6>
@@ -135,7 +135,7 @@
 </li>
</ul></div>
<a name="toward_boost_stm.appendices.todo.tasks_to_do_before_review.implementation"></a><h6>
-<a name="id4891119"></a>
+<a name="id4914374"></a>
 <a class="link" href="todo.html#toward_boost_stm.appendices.todo.tasks_to_do_before_review.implementation">Implementation</a>
 </h6>
<div class="itemizedlist"><ul type="disc">
@@ -157,21 +157,21 @@
 </li>
</ul></div>
<a name="toward_boost_stm.appendices.todo.tasks_to_do_before_review.tests"></a><h6>
-<a name="id4891178"></a>
+<a name="id4914433"></a>
 <a class="link" href="todo.html#toward_boost_stm.appendices.todo.tasks_to_do_before_review.tests">Tests</a>
 </h6>
<div class="itemizedlist"><ul type="disc"><li>
 Add unit tests
 </li></ul></div>
<a name="toward_boost_stm.appendices.todo.tasks_to_do_before_review.benchmarks"></a><h6>
-<a name="id4891209"></a>
+<a name="id4914464"></a>
 <a class="link" href="todo.html#toward_boost_stm.appendices.todo.tasks_to_do_before_review.benchmarks">Benchmarks</a>
 </h6>
<div class="itemizedlist"><ul type="disc"><li>
 Add some specific benchmarks.
 </li></ul></div>
<a name="toward_boost_stm.appendices.todo.tasks_to_do_before_review.documentation"></a><h6>
-<a name="id4891240"></a>
+<a name="id4914495"></a>
 <a class="link" href="todo.html#toward_boost_stm.appendices.todo.tasks_to_do_before_review.documentation">Documentation</a>
 </h6>
<div class="itemizedlist"><ul type="disc">

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/overview.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/overview.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/overview.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -32,6 +32,9 @@
 <a class="link" href="overview.html#toward_boost_stm.overview.description">Description</a>
 </h4>

+ Toward An Industrial Strength C++ Software Transactional Memory Library.
+ 
+
 Transactional memory (TM) is a new parallel programming mechanism that reduces
 the complexity of parallel programming. TM reduces parallel programming complexity
 by abstracting away the necessary synchronization mechanisms from the parallel
@@ -93,7 +96,7 @@
 </li>
</ul></div>
<a name="toward_boost_stm.overview.how_to_use_this_documentation"></a><h4>
-<a name="id4810525"></a>
+<a name="id4810530"></a>
 <a class="link" href="overview.html#toward_boost_stm.overview.how_to_use_this_documentation">How
 to Use This Documentation</a>
 </h4>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/overview/intro.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/overview/intro.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/overview/intro.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -26,6 +26,797 @@
<div class="titlepage"><div><div><h3 class="title">
<a name="toward_boost_stm.overview.intro"></a><a class="link" href="intro.html" title="Introduction"> Introduction</a>
</h3></div></div></div>
+<a name="toward_boost_stm.overview.intro.transactional_memory"></a><h5>
+<a name="id4848945"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.transactional_memory">Transactional
+ Memory</a>
+ </h5>
+
+ Transactional memory is a modern type of concurrency control that uses transactions
+ as its synchronization mechanism. A transaction is a finite sequence of operations
+ that are executed in an atomic, isolated and consistent manner. The atomicity,
+ isolation and consistency (ACI) of transaction's are derived from the ACID
+ principle in the database community. TM does not exhibit the D (durability)
+ of ACID because unlike database transactions, TM transactions are not saved
+ to permanent storage (e.g., hard drives).
+ 
+
+ Transactions are executed speculatively (optimistically) and are checked
+ for consistency at various points in the transaction's lifetime. Programmers
+ specify the starting and ending points of a transaction. All of the operations
+ between those points make up the transaction's execution body. Transactions
+ are commonly represented using the atomic structure shown in the figure below.
+ 
+<pre class="programlisting">1 atomic
+2 {
+3 ++x;
+4 --y;
+5 }
+
+Simple Transaction Using the atomic Keyword
+</pre>
+
+ Once a transaction has started it either commits or aborts. A transaction's
+ operations are only seen once the transaction has committed, providing the
+ illusion that all of the operations occurred at a single instance in time.
+ The instructions of a committed transaction are viewed as if they occurred
+ as an indivisible event, not as a set of operations executed serially. The
+ operations of an aborted transaction are never seen by other threads, even
+ if such operations were executed within a transaction and then rolled back.
+ 
+
+ In the case of the above example, if the transaction was committed both operations
+ <code class="computeroutput">++x</code>
+ and <code class="computeroutput">--y</code>
+ would be made visible to other threads at the same instance in time. If the
+ transaction the above example was aborted, neither operation (<code class="computeroutput">++x</code> and
+ <code class="computeroutput">--y</code>)
+ would appear to have occurred even if the local transaction executed one
+ or both operations.
+ 
+
+ TM offers three distinct advantages over other parallel programming abstractions.
+ 
+<div class="orderedlist"><ol type="1">
+<li>
+ TM is simple; transactions, the synchronization mechanism of TM, are easier
+ to program than other synchronization mechanisms because they move shared
+ memory management into the underlying TM subsystem, removing its complexity
+ from the programmer's view. Moreover, TM exposes a simple programmer interface,
+ reducing (or in some cases, removing) the potential for deadlock, livelock
+ and priority inversion.
+ </li>
+<li>
+ TM is scalable; it achieves increased computational throughput when compared
+ to other parallel programming abstractions by allowing multiple threads
+ to speculatively execute the same critical section. When concurrently executing
+ threads do not exhibit shared data conflicts, they are guaranteed to make
+ forward progress.
+ </li>
+<li>
+ TM is modular; transactions can be nested to any depth and function as
+ a single unit. This behavior allows application programmers to extend atomic
+ library algorithms into atomic domain-specific algorithms without requiring
+ the application programmers to understand the implementation details of
+ the library algorithm.
+ </li>
+</ol></div>
+
+ For these reasons, transactions are considered an important synchronization
+ mechanism and TM is viewed as an important type of concurrency control. The
+ remainder of this section presents TM from a viewpoint of (1) simplicity,
+ (2) scalability and (3) modularity.
+ 
+<a name="toward_boost_stm.overview.intro.simplicity"></a><h5>
+<a name="id4849486"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.simplicity">Simplicity</a>
+ </h5>
+
+ Synchronization problems, such as deadlocks, livelocks and priority inversion
+ are common in software systems using mutual exclusion. TM avoids many of
+ these problems by providing a synchronization mechanism that does not expose
+ any of its implementation details to the programmer. The only interfaces
+ the programmer needs to use for TM is as follows:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ begin_tx() - the signaled start of the transaction.
+ </li>
+<li>
+ read(loc) - reads the specified memory location, storing its location in
+ the transaction's read set and returning its current value.
+ </li>
+<li>
+ write(loc, val) - writes the specified memory location to the supplied
+ val, storing its location in the transaction's write set.
+ </li>
+<li>
+ end_tx() - the signaled end of the transaction. end_tx() returns true if
+ the transaction commits, otherwise it returns false.
+ </li>
+</ul></div>
+
+ The above interfaces allow the programmer to create a transaction (using
+ begin_tx()), specify its memory operations (using read() and write()) and
+ terminate (using end_tx()()). Moreover, none of the interfaces specify details
+ of the TM subsystem's implementation. This leaves the TM system's implementation
+ disjoint from the interfaces it supplies, a key characteristic for TM's simplicity.
+ 
+
+ All TM implementations use some combination of the above interfaces. TMs
+ implemented within compilers tend to implicitly annotate transactional read()
+ and write() operations, whereas those implemented within software libraries
+ tend to require the programmer explicitly state which operations are transactional
+ reads and writes. An example of a transaction using the above interfaces
+ alongside an actual STM library implementation is shown in Figure 3.
+ 
+<pre class="programlisting">1 // TM interfaces // __Boost_STM__
+2 do { atomic(t)
+3 begin_tx(); {
+4 write(x, read(x)+1); ++t.write(x);
+5 write(y, read(y)-1); --t.write(y);
+6 } while (end_tx()); } before_retry {}
+
+Figure 3. Transaction Using (1) Explicit TM Interfaces and (2) TBoost.STM.
+</pre>
+
+ Figure 3 implements the same transaction as shown in Figure 2, except all
+ transactional memory accesses, including the transaction's retry behavior
+ (e.g., its loop), are demonstrated from a simple TM interface perspective
+ and an actual library implementation (TBoost.STM). While most TM systems
+ handle some portion of these interface calls implicitly, as is shown in the
+ TBoost.STM transaction, it is important to note that even when all operations
+ are made visible to the end programmer, transactions are still devoid of
+ many concurrency problems, such as data races and deadlocks (explained below),
+ that plague other types of concurrency control.
+ 
+
+ For example, as long as the programmer properly annotates the access to the
+ shared variables x and y as shown in Figure 3, it is impossible for race
+ conditions or deadlocks to occur. Furthermore, the programmer does not need
+ any program-specific knowledge to use shared data; he or she simply uses
+ the TM interfaces supplied by the system and the resulting behavior is guaranteed
+ to be consistent. This is explained in greater detail in Section 3.1.
+ 
+
+ Other types of concurrency control, such as mutual exclusion, cannot achieve
+ the same interface simplicity, because part of their implementation is associated
+ with, or exposed through, their interface. To demonstrate this, consider
+ the fine-grained locking example of Figure 1 as shown below.
+ 
+<pre class="programlisting">1 // fine-grained locking
+2 lock(mutexX);
+3 lock(mutexY);
+4 ++x;
+5 --y;
+6 unlock(mutexX);
+7 unlock(mutexY);
+</pre>
+
+ There is no universal interface that can be used to properly access the shared
+ data protected by the mutual exclusion in the above fine-grained locking
+ example. Instead, the programmer must be aware that mutexX and mutexY protect
+ shared data x and y and, therefore, the locks must be obtained before accessing
+ the shared data. In short, the programmer is responsible for knowing not
+ only that mutual exclusion is used, but also how it is used (e.g., which
+ locks protect which shared variables). In this case, mutexX must be obtained
+ before mutexY. If another section of code implements the following, a deadlock
+ scenario will eventually occur.
+ 
+<pre class="programlisting">1 // fine-grained locking
+2 lock(mutexY);
+3 lock(mutexX); // deadlock here
+4 --y;
+5 ++x;
+6 unlock(mutexY);
+7 unlock(mutexX);
+</pre>
+<a name="toward_boost_stm.overview.intro.understanding_concurrency_hazards"></a><h5>
+<a name="id4804185"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.understanding_concurrency_hazards">Understanding
+ Concurrency Hazards</a>
+ </h5>
+
+ Informally, a concurrency hazard is a condition existing in a set of operations
+ that, if executed with a specific concurrent interleaving, results in one
+ or many unwanted sideeffects. Most errors in parallel systems, such as deadlocks
+ and priority inversion, are the specific execution of concurrency hazards
+ resulting in the unwanted side-effect(s) they contain. If the concurrency
+ hazards are eliminated, the parallel system errors contained within the concurrency
+ hazards are also eliminated. Unfortunately, detecting existing concurrency
+ hazards is non-trivial and therefore eliminating them is also non-trivial.
+ 
+
+ Mutual exclusion exhibits more concurrency hazards than TM because its implementation
+ details (i.e., its locks) must be exposed and used by the end programmer.
+ While the locks used to enforce mutual exclusion by themselves are not concurrency
+ hazards, their use can lead to a number of hazards. As such, using locks
+ leads to concurrency hazards.
+ 
+
+ Because the mutual exclusion locking details are exposed to the programmer
+ and because the programmer must maintain a universal and informal contract
+ to use these locks, concurrency hazards can arise due to the number of possible
+ misuses that can be introduced by the programmer. In particular, if the programmer
+ accidentally deviates from the informal locking contract, he or she may inadvertently
+ introduce a concurrency hazard that can cause the program to deadlock, invert
+ priority or lead to inconsistent data.
+ 
+
+ In contrast, TM has no universal or informal contract between shared data
+ that the end programmer needs to understand and follow as is required in
+ mutual exclusion. Due to this, TM can hide its implementation details which
+ results in reduced concurrency hazards. In particular, each transaction tracks
+ the memory it uses in its read and write sets. When a transaction begins
+ its commit phase, it verifies its state is consistent and commits its changes.
+ If a transaction finds its state is inconsistent, it discards its changes
+ and restarts. All of this can be achieved using the basic TM interfaces shown
+ in Section 3 without exposing any implementation details. In order to use
+ TM, the end programmer only needs to know how to correctly create a transaction.
+ Once the transaction is executed, regardless of how it is executed, it results
+ in a program state that is guaranteed to be consistent.
+ 
+
+ Fundamentally, TM exhibits less concurrency hazards than mutual exclusion
+ because its implementation details are divorced from its interface and can
+ therefore be hidden within its subsystem. Any number of implementations can
+ be used in a TM subsystem using only the basic TM interfaces shown in Section
+ 3. The same is not true for mutual exclusion. Mutual exclusion, regardless
+ of how it is implemented, exposes details of its implementation to the programmer.
+ As demonstrated in Section 5, mutual exclusion does not provide software
+ modularity specifically because extending an existing module requires an
+ understanding and extension of that module's implementation. When such locking
+ implementations are hidden inside of software libraries, extending these
+ modules can range from difficult to impossible.
+ 
+<a name="toward_boost_stm.overview.intro.testing__race_conditions_and_interleavings"></a><h5>
+<a name="id4804299"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.testing__race_conditions_and_interleavings">Testing:
+ Race Conditions and Interleavings</a>
+ </h5>
+
+ A race condition is a common concurrency hazard that exists in parallel or
+ distributed software. As with all concurrency hazards, race conditions rely
+ on a specific interleaving of concurrent execution to cause their unwanted
+ side-effect. In this section we demonstrate that race conditions do not exist
+ in TM and therefore, software testing is greatly simplified because all possible
+ interleavings do not need to be tested to ensure correct system behavior.
+ In order to demonstrate that race conditions are absent from TM, we must
+ first show that they are present in other types of concurrency control.
+ 
+<pre class="programlisting">1 // Thread T1 // Thread T
+2 lock(L2);
+3 lock(L1);
+4 ...
+5 unlock(L1);
+6 unlock(L2);
+7 lock(L1);
+8 lock(L2);
+9 ...
+
+Figure 4. Mutual Exclusion Race Condition.
+</pre>
+
+ Consider the race condition present in the mutual exclusion example shown
+ in Figure 4. The race condition present in the example results in a deadlock
+ if thread T1 executes line 7 followed by thread T2 executing line 2. However,
+ if the program executes the lines in order (e.g., line 1, then line 2, then
+ line 3, etc.), the system will execute properly. The fundamental problem
+ in Figure 4 is that it contains a concurrency hazard; in particular, it contains
+ a race condition. To further complicate matters, the race condition can only
+ be observed in two of many possible concurrent executions. Those two executions
+ are: T1 executes line 7 followed by T2 executing line 2 or T2 executes line
+ 2 followed by T1 executing line 7. All other possible concurrent interleavings
+ of threads T1 and T2 avoid the deadlock race condition. More specifically,
+ as long as T1 executes lines 7-8 atomically or T2 executes line 2-3 atomically,
+ all remaining concurrent interleavings are free of the deadlock race condition.
+ 
+
+ Because it is unlikely that the deadlock race condition will occur, the programmer
+ may never observe it, no matter how many times the program is tested. Only
+ exhaustive testing, which tests all possible concurrent interleavings, is
+ guaranteed to identify the presence of the deadlock. Regrettably, exhaustive
+ testing is an unrealistic solution for most programs due to the time it would
+ take to execute all possible concurrent interleavings of the program.
+ 
+
+ An alternative to exhaustive testing is for programmers to use types of concurrency
+ control that are devoid of certain concurrency hazards. For example, if mutual
+ exclusion did not emit the race condition concurrency hazard, it would be
+ impossible for a program using it to deadlock. Therefore, exhaustive testing
+ would not be necessary. While this scenario is hypothetical, it illustrates
+ our larger argument: in order to avoid common parallel problems in a practical
+ fashion, programmers may need to only use types of concurrency control that
+ are devoid of certain concurrency hazards. By doing this, the program using
+ the specific type of concurrency control will be guaranteed to be free of
+ certain common parallel problems.
+ 
+
+ TMs are required to be devoid of race conditions within their implementations
+ because they must enforce the ACI (atomic, consistent and isolated) principles.
+ Transactions must execute as atomic and isolated and, therefore, TMs are
+ not capable of supporting concurrent interleavings between multiple transactions
+ as that would violate the atomic and isolated principles of ACI. Due to this,
+ programs only using TM are guaranteed to be free of deadlocks (i.e., deadlockfreedom).
+ Moreover, because TM implementations can guarantee freedom of race condition
+ concurrency hazards, programmers only need to verify their transactional
+ code is correct in a sequential (non-parallel) manner. Once the sequential
+ execution of the transactional code has been verified, no more testing is
+ required as the TM system is required to behave in a consistent manner for
+ all serial orders.
+ 
+<a name="toward_boost_stm.overview.intro.development__mutual_exclusion_and_tm"></a><h5>
+<a name="id4804665"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.development__mutual_exclusion_and_tm">Development:
+ Mutual Exclusion and TM</a>
+ </h5>
+
+ The development of fine-grained locking is notoriously difficult. Designing
+ such software is equally as hard. The difficulty in developing and designing
+ fine-grained locking systems is rooted in conflicting heuristics. A primary
+ goal of software design is to identify the most simplistic software solution
+ that exists for a particular problem. A primary goal of fine-grained locking
+ is the most efficient concurrent implementation of a software system. The
+ goals of software design and fine-grained locking are conflicting because
+ the most efficient fine-grained locking solution usually requires some of
+ the most complex software design implementations to achieve such performance.
+ 
+
+ TM achieves scalability by using optimistic concurrency that is implemented
+ within its subsystem (see Section 4). Since the TM subsystem is the efficiency
+ throttle for TM, which is unexposed to the programmer, the software architecture
+ and design never needs to be complicated (nor can it be) in order to achieve
+ increased parallelism when using transactions. As will be demonstrated in
+ the following section, transactions run efficiently using the interfaces
+ shown in this section and are never complicated in order to achieve improved
+ performance, as is commonly found in fine-grained mutual exclusion implementations.
+ 
+<a name="toward_boost_stm.overview.intro.scalability"></a><h5>
+<a name="id4804718"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.scalability">Scalability</a>
+ </h5>
+
+ In this section we analyze the scalability of TM compared to mutual exclusion.
+ We measure scalability by two metrics: consistency and performance. A concurrency
+ control type has consistent scalability if it guarantees correct behavior
+ for an arbitrarily large number of concurrently executing processes.4 Performance
+ scalability is measured by the maximum number of consistent processes supported
+ by a concurrency control type while executing concurrently.
+ 
+<a name="toward_boost_stm.overview.intro.pessimistic_and_optimistic_critical_sections"></a><h5>
+<a name="id4804741"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.pessimistic_and_optimistic_critical_sections">Pessimistic
+ and Optimistic Critical Sections</a>
+ </h5>
+
+ Critical sections can be pessimistic or optimistic. Pessimistic critical
+ sections limit their critical section execution to a single thread. Locks
+ are an example of a synchronization mechanism that use pessimistic critical
+ sections. Optimistic critical sections allow unlimited concurrent threaded
+ execution. Transactions are an example of a synchronization mechanism that
+ use optimistic critical sections.
+ 
+<a name="toward_boost_stm.overview.intro.truly_optimistic_critical_sections"></a><h5>
+<a name="id4804773"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.truly_optimistic_critical_sections">Truly
+ Optimistic Critical Sections</a>
+ </h5>
+
+ Truly optimistic critical sections are those critical sections which allow
+ multiple conflicting threads to simultaneously execute the same critical
+ section. A deferred update (or lazy acquire) TM system supports truly optimistic
+ critical section. A direct update (or eager acquire) TM system does not support
+ truly optimistic critical sections. More details on deferred and direct update
+ TM systems are presented in the subsequent sections.
+ 
+
+ Truly optimistic critical sections are important because they allow simultaneous
+ conflicting critical section execution, as opposed to disallowing such behavior.
+ It is important to allow conflicting critical section execution because prematurely
+ preventing concurrently executing threads pessimistically degrades performance.
+ To demonstrate this, consider two transactions, called T1 and T2, executing
+ the same critical section. Transaction T1 starts first and tentatively writes
+ to memory locationM. Transaction T2 then starts and tries to write to memory
+ locationM. In a truly optimistic TM system, T2 would be allowed to tentatively
+ write to location M while T1 is also writing to M. This behavior then allows
+ T2 to commit before T1 in the event T2 completes before T1.
+ 
+
+ In comparison, if the TM system is not truly optimistic, once T1 writes to
+ M, T2 must stall until T1 completes. This pessimistically degrades the performance
+ of the system by prematurely deciding that T1's transactional execution should
+ have higher priority than T2's.
+ 
+<pre class="programlisting">1 // global variables
+2 int g1 = 0; int g2 = 0;
+3
+4 void set1(int val) { atomic { g1 = val; } }
+5 void set2(int val) { atomic { g2 = val; } }
+6 int get1() { atomic { return g1; } }
+7 int get2() { atomic { return g2; } }
+
+Figure 5. Truly Optimistic Concurrency Diagram.
+</pre>
+
+ Furthermore, and perhaps more importantly, truly optimistic critical sections
+ allow readers and writers of the same memory location to execute concurrently.
+ This behavior is important because in many cases, both the readers and writers
+ of the same memory can commit with consistent views of memory.
+ 
+
+ An example of this is shown in Figure 5. As demonstrated in Figure 5 thread
+ 1 and thread 2, which we'll refer to as T1 and T2 respectively, operate on
+ the same memory locations (g1 and g2). Because the TM system supports optimistic
+ concurrency, T2 is allowed to execute concurrently alongside T1 even though
+ their memory accesses conflict. However, in this scenario, because T2 completes
+ its workload before T1, both transactions are allowed to commit. T2 captures
+ the state of g1=0,g2=0 while T1 sets the state of g1=1,g2=1. As the example
+ addresses, both g1=0,g2=0 and g1=1,g2=1 are legal states.
+ 
+<a name="toward_boost_stm.overview.intro.direct_and_deferred_update"></a><h5>
+<a name="id4805268"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.direct_and_deferred_update">Direct
+ and Deferred Update</a>
+ </h5>
+
+ Updating is the process of committing transactional writes to global memory
+ and is performed in either a direct or deferred manner. Figure 6 presents
+ a step-by-step analysis of direct and deferred updating.
+ 
+
+ Deferred update creates a local copy of global memory, performs modifications
+ to the local copy, and then writes those changes to global memory if the
+ transaction commits. If the transaction aborts, no additional work is done.
+ Direct update makes an original backup copy of global memory and then writes
+ directly to global memory. If the transaction commits, the transaction does
+ nothing. If the transaction aborts, the transaction restores global memory
+ with its backup copy. Some TM systems favor direct update due to its natural
+ optimization of commits (BSTM, McRTSTM and LogTM). However, other TM systems
+ favor deferred update due to its support for truly optimistic critical sections
+ (TBoost.STM and RingSTM).
+ 
+
+ Direct update enables greater TM throughput when aborts are relatively low
+ because it optimizes the common commit case. Deferred update enables greater
+ TM throughput when
+ 
+<div class="orderedlist"><ol type="1">
+<li>
+ aborts are relatively high or
+ </li>
+<li>
+ short running transactions (e.g., those that complete quickly) are executed
+ alongside long running transactions (e.g., those that do not complete quickly)
+ because long running transactions do not stall shorter running ones as
+ they would in direct update systems, and therefore the fastest transactions
+ can commit first.
+ </li>
+</ol></div>
+
+ It is important to note that deferred update supports truly optimistic critical
+ sections without special effort, while direct update does not. Truly optimistic
+ critical sections enable the speculative execution of transactions that arrive
+ after a memory location has already been tentatively written to by another
+ transaction. This allows the first transaction, of potentially many competing
+ transactions, to complete its commit, whether it be the later arriving transaction
+ or the earlier arriving writer. This scenario is not possible with direct
+ update without special effort.
+ 
+<a name="toward_boost_stm.overview.intro.scalability__mutual_exclusion_and_transactional_memory"></a><h5>
+<a name="id4805358"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.scalability__mutual_exclusion_and_transactional_memory">Scalability:
+ Mutual Exclusion and Transactional Memory</a>
+ </h5>
+
+ The scalability of mutual exclusion is limited to pessimistic concurrency.
+ By definition, mutual exclusion's critical sections must be pessimistic,
+ otherwise they would not be isolated to a single thread (i.e., they would
+ not be mutually exclusive). TM, however, is generally implemented using optimistic
+ concurrency, but it can enforce pessimistic concurrency amongst transactions
+ if that behavior is required for certain conditions. In certain cases, TMs
+ becomemore strict and execute pessimistically to enable inevitable or irrevocable
+ transactions. Such transactions have significant importance for handling
+ operations that, once started, must complete (e.g., I/O operations).
+ 
+
+ Since TM can execute optimistically and pessimistically, it is clear that
+ whatever benefits pessimistic concurrency has can be acquired by TM. However,
+ since mutual exclusion can only execute pessimistically, the advantages found
+ in optimistic concurrency can never be obtained by mutual exclusion.
+ 
+
+ When one first analyzes pessimistic and optimistic concurrency, it may seem
+ that the only benefit optimistic concurrency has over pessimistic concurrency
+ is that multiple critical sections, which conflict on the memory they access,
+ can execute concurrently. The simultaneous execution of such conflicting
+ critical sections allows the execution speed of such critical sections to
+ guide the system in deciding which execution should be allowed to commit
+ and which should be aborted. In particular, the first process to complete
+ the critical section can be allowed to abort the other process of the system.
+ The same scenario cannot be achieved by pessimistic critical sections and
+ is demonstrated in Section 4.1.1.
+ 
+
+ A counterargument to this scenario is that such optimistic concurrency only
+ allows one critical section to commit, while one must be aborted. Because
+ mutual exclusion only allows one conflicting critical section execution at
+ a time, and because mutual exclusion does not support failure atomicity (i.e.,
+ rollbacking of the critical section), mutual exclusion's pessimistic behavior
+ is superior in terms of energy and efficiency. Mutual exclusion, unlike TM,
+ suffers no wasted work because conflicting critical sections are limited
+ to a single thread of execution, reducing the energy it uses. Furthermore,
+ because mutual exclusion does not require original data to copied, as needed
+ for TM's direct or deferred update, it executes faster.
+ 
+
+ While there is merit to this counterargument, an important scenario is not
+ captured by it: truly optimistic critical sections can support multiple reader
+ / single write executions which, if executed so the readers commit before
+ the writer, all critical sections will succeed. This scenario is impossible
+ to achieve using pessimistic critical sections. Although mutual exclusion
+ can use read/write locking, as soon as a writer thread begins execution on
+ a conflicting critical section, all readers must be stalled. TM's truly optimistic
+ concurrency does not suffer from this overly pessimistic limitation of throughput
+ and is therefore capable of producing an immeasurable amount of concurrent
+ throughput under such conditions.
+ 
+
+ From a theoretical perspective, given L memory locations and P processes,
+ mutual exclusion can support the consistent concurrent execution of P*L number
+ of readers or L writers. TM can support the consistent concurrent execution
+ of P*L number of readers and L writers. Using the above variables, the mathematical
+ expression of the performance scalability of mutual exclusion (S(ME)) is:
+ 
+<pre class="programlisting">S(ME) = (P*L) + L
+</pre>
+
+ Using the same variables, the mathematical expression of the performance
+ scalability of transactional memory is:
+ 
+<pre class="programlisting">S(TM) = (P * L) + L
+</pre>
+
+ As should be clear from the above equations, mutual exclusion cannot achieve
+ the same performance scalability of TM. This is because TM supports truly
+ optimistic concurrency and mutual exclusion is confined to pessimistic concurrency.
+ While other examples exist that demonstrate optimistic concurrency can increase
+ throughput via contention management, the above equations capture the indisputable
+ mathematical limitations in mutual exclusion's performance scalability.
+ 
+<a name="toward_boost_stm.overview.intro.modularity"></a><h5>
+<a name="id4858700"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.modularity">Modularity</a>
+ </h5>
+
+ Software modularity is an important aspect of software that is necessary
+ for its reuse. Formally, software is modular if it can be composed in a new
+ system without altering its internal implementation. Informally, software
+ is modular if it can be used, in its entirety, through its interface.
+ 
+
+ By making software modular, it can be freely used in an unlimited number
+ of software systems. Without software modularity, software can only be used
+ in the original system where it was written. Clearly, without software modularity,
+ software cannot be reused. Because most software developments are based on
+ extensive library use, software reuse is an integral part of software development.
+ As such, limiting software reuse, would result in severely hampered development
+ capabilities and overall development time. For these reasons, software modularity
+ is vital for any software paradigm to be practical. Software paradigms that
+ do not support software modularity are, in short, impractical.
+ 
+<a name="toward_boost_stm.overview.intro.mutual_exclusion_and_software_modularity"></a><h5>
+<a name="id4858744"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.mutual_exclusion_and_software_modularity">Mutual
+ Exclusion and Software Modularity</a>
+ </h5>
+
+ In this section, we show that mutual exclusion, regardless of its implementation,
+ fails to deliver software modularity. We demonstrate this through a running
+ example started in Figure 7 which implements inc(), mult() and get(); these
+ functions use lock G to respectively implement an increment, multiply and
+ get operations for the shared data.
+ 
+<pre class="programlisting">1 void inc(int v) {
+2 lock(G); g += v; unlock(G);
+3 }
+4
+5 void mult(int v) {
+6 lock(G); g *= v; unlock(G);
+7 }
+8
+9 int get() {
+10 lock(G); int v = g; unlock(G);
+11 return v;
+12 }
+
+Figure 7. Mutual Exclusion for Increment, Multiply and Get of Shared Variable.
+</pre>
+
+ Now suppose a programmer wants to increment and multiply by some values within
+ the same atomic operation. The initial implementation may look like the following.
+ 
+<pre class="programlisting">1 inc(a);
+2 mult(-b);
+</pre>
+
+ An unwanted side-effect of such an implementation is the exposure of the
+ intermediate state of g between inc() and mult(). A second thread performing
+ a get() may read an inconsistent value of g; the value of g between inc()
+ and mult(). This is demonstrated in the timing diagram of Figure 8 .
+ 
+<pre class="programlisting">Figure 8. Example of Exposed State of Mutual Exclusion.
+</pre>
+
+ If the programmer needs the inc() and mult() operations to be executed together,
+ without an intermediate state being revealed, he or she could make lock G
+ reentrant. Reentrant locks are locks that can be obtained multiple times
+ by a single thread without deadlocking. If G is made reentrant, the following
+ code could be used to make inc(a) and mult(-b) atomic. A basic implementation
+ of a reentrant lock is to associate a counter with its lock and increment
+ the counter each time the lock() interface is called and to decrement the
+ counter each time the unlock() interface is called. The reentrant lock is
+ only truly locked when a call to lock() is made when its associated counter
+ is 0. Likewise, the reentrant lock is only truly unlocked when a call to
+ unlock() is made when its associated counter is 1.
+ 
+<pre class="programlisting">1 lock(G);
+2 inc(a);
+3 mult(-b);
+4 unlock(G);
+</pre>
+
+ If the above code uses reentrant locks, it will achieve the programmer's
+ intended atomicity for inc() and mult(), isolating the state between inc()
+ and mult(), which disallows the unwanted side-effect shown in Figure 8. While
+ the atomicity of the operations is achieved, it is only achieved by exposing
+ the implementation details of inc() and mult(). In particular, if the programmer
+ had not known that lock G was used within inc() and mult(), making an atomic
+ operation of inc() and mult() would be impossible.
+ 
+
+ An external atomic grouping of operations is impossible using embedded mutual
+ exclusion without exposing the implementation details because the heart of
+ mutual exclusion is based on named variables which the programmer specifies
+ to guard their critical sections. Because these variables are named, they
+ cannot be abstracted away and any programmer wishing to reuse the mutually
+ exclusive code must be able to access and extend the implementation details.
+ 
+<pre class="programlisting">1 void inc(int v) { atomic { g += v; } }
+2
+3 void mult(int v) { atomic { g *= v; } }
+4
+5 int get() { atomic { return g; } }
+
+Figure 9. TM of Increment, Multiply and Get of Shared Variable.
+</pre>
+<a name="toward_boost_stm.overview.intro.summary_of_mutual_exclusion_modularity"></a><h5>
+<a name="id4859757"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.summary_of_mutual_exclusion_modularity">Summary
+ of Mutual Exclusion Modularity</a>
+ </h5>
+
+ As we presented at the beginning of this section, software modularity can
+ be informally understood as a component's ability to be used entirely from
+ its interface. Therefore, components that cannot be used entirely from their
+ interface, components that must expose their implementation details to be
+ extended, are not modular. As such, the paradigm of mutual exclusion does
+ not support software modularity.
+ 
+<a name="toward_boost_stm.overview.intro.transactional_memory_and_software_modularity"></a><h5>
+<a name="id4859797"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.transactional_memory_and_software_modularity">Transactional
+ Memory and Software Modularity</a>
+ </h5>
+
+ Transactional memory works in a fundamentally different manner than mutual
+ exclusion, with regard to its interface and implementation. To begin, as
+ demonstrated in Section 3, TMs do not generally expose any of their implementation
+ details to client code. In fact, in many TMs, client code is more versatile
+ if it knows and assumes nothing about the active implementation of the TM.
+ By abstracting away details of TM implementation, a TM subsystem can adapt
+ its behavior to the most efficient configuration for the program's current
+ workload, much like the algorithms used for efficient operation of processes
+ controlled by operating systems. TM uses such abstractions to optimize the
+ performance of concurrent programs using various consistency checking methods,
+ conflict detection times, updating policies, and contention management schemes.
+ 
+<a name="toward_boost_stm.overview.intro.achieving_tm_software_modularity"></a><h5>
+<a name="id4859838"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.achieving_tm_software_modularity">Achieving
+ TM Software Modularity</a>
+ </h5>
+
+ TM achieves software modularity by allowing transactions to nest. With transactional
+ nesting, individual transactions can be wrapped inside of other transactions
+ which call the methods where they reside, resulting in a transaction composed
+ of both the parent and child transaction. Furthermore, this is achieved without
+ altering or understanding the child transaction's implementation. To best
+ demonstrate transactional nesting, we reuse the prior mutual exclusion example
+ shown in Figure 7 and implement it using transactions as shown in Figure
+ 9.
+ 
+
+ As before, the programmer's goal is to implement a combination of inc() and
+ mult() executed in an atomic fashion. The basic, and incorrect implementation
+ is demonstrated below:
+ 
+<pre class="programlisting">1 inc(a);
+2 mult(-b);
+</pre>
+
+ Even with transactions, this approach fails because the transactions within
+ inc() and mult() begin and end inside their respective functions. However,
+ to make the above operations atomic, the programmer need only make the following
+ modification shown in Figure 10.
+ 
+<pre class="programlisting">1 atomic { // atomic {
+2 inc(a); // atomic { g += a; }
+3 mult(-b); // atomic { g *= -b; }
+4 } // }
+
+Figure 10. Modularity: Transaction of Increment and Multiply.
+</pre>
+
+ In effect, the TM system subsumes the transactions that are nested inside
+ of the inc() and mult() operations. 6 The left side of Figure 10 shows the
+ actual code of the transaction, while the right side shows the child transactions
+ that are subsumed by the parent transaction.
+ 
+
+ Because transactions are isolated and atomic, the resulting state of g, from
+ operations inc() and mult(), is invisible to outside observers until the
+ transaction is committed. As such, outside threads cannot view any intermediate
+ state constructed by partial transaction execution. The result of such isolated
+ behavior is the guaranteed consistent concurrent execution of interleaved
+ accesses to shared memory from in-flight transactions. This is demonstrated
+ in Figure 11; let g=0 and assume deferred update is the active updating policy,
+ as explained in Section 4.2.
+ 
+<pre class="programlisting">Figure 11. Example of Isolated and Consistent State of TM.
+</pre>
+
+ As shown in Figure 11, multiple concurrently executing threads can read and
+ write to the same shared memory in a consistent and isolated fashion when
+ using TM. In the example, thread T2 performs x = get() after T1 has already
+ executed inc(a). However, since T1 has not yet committed its transaction,
+ T2's view of shared data g is consistent (g=0). When T2 begins the commit
+ phase of its transaction, the TM subsystem verifies that shared data g has
+ not been updated since it initially read it. Since no other transaction has
+ updated shared data g, T2's transaction is permitted to commit. Thread T1
+ then continues with its mult() operation and then enters its commit phase.
+ The TM subsystem also verifies the consistency of T1's transaction before
+ it is allowed to commit. Again, since no one transaction has updated shared
+ data g between its reads and writes to it, T1's transaction is permitted
+ to commit.
+ 
+
+ The above analysis demonstrates that software modularity can be achieved
+ in TM through transactional nesting (Figure 10). In this case, the specific
+ software modularity achieved is extension to an existing critical section.
+ Critical section extension was also possible with mutual exclusion, as demonstrated
+ in Section 5.1, but only through exposing the details behind the mutual exclusion
+ implementation. Due to this, mutual exclusion fails to deliver a practical
+ level of software modularity.
+ 
+<a name="toward_boost_stm.overview.intro.summary_of_transactional_memory_modularity"></a><h5>
+<a name="id4860198"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.summary_of_transactional_memory_modularity">Summary
+ of Transactional Memory Modularity</a>
+ </h5>
+
+ TM supports software modularity by allowing transactions to nest, to any
+ depth, while logically grouping the shared data accesses within the transactions
+ into an atomic, consistent and isolated (ACI) operation. Transactional nesting
+ is natural to the programmer because nested transactions behave in the same
+ manner as unnested transactions. TM's ACI support ensures transactions will
+ behave in a correct manner regardless of if the transaction is used by itself
+ or subsumed into a larger transaction.
+ 
+<a name="toward_boost_stm.overview.intro.c___library_language_like_solution"></a><h5>
+<a name="id4860232"></a>
+ <a class="link" href="intro.html#toward_boost_stm.overview.intro.c___library_language_like_solution">C++
+ library language-like solution</a>
+ </h5>

Research in parallel programming has recently seen a flurry of attention.
Among the active research is a push for high-level languages to offer native

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -43,36 +43,66 @@
 <code class="computeroutput">aborted_transaction_exception</code></a></dt></dl></dd>
<dt><a href="reference/transaction_hpp.html"> Header
 <code class="computeroutput"><boost/stm/transaction.hpp></code></a></dt>
-<dd><dl><dt><a href="reference/transaction_hpp.html#toward_boost_stm.reference.transaction_hpp.class__transaction_">Class
- <code class="computeroutput">transaction</code></a></dt></dl></dd>
-<dt><a href="reference/transaction_object_hpp.html"> Header
- <code class="computeroutput"><boost/stm/transaction_object.hpp></code></a></dt>
<dd><dl>
-<dt><a href="reference/transaction_object_hpp.html#toward_boost_stm.reference.transaction_object_hpp.abstract_class__base_transaction_object_">Abstract
+<dt><a href="reference/transaction_hpp.html#toward_boost_stm.reference.transaction_hpp.class__transaction_">Class
+ <code class="computeroutput">transaction</code></a></dt>
+<dt><a href="reference/transaction_hpp.html#toward_boost_stm.reference.transaction_hpp.struct__thread_initializer_">Struct
+ <code class="computeroutput">thread_initializer</code></a></dt>
+</dl></dd>
+<dt><a href="reference/base_transaction_hpp.html"> Header
+ <code class="computeroutput"><boost/stm/base_transaction.hpp></code></a></dt>
+<dd><dl>
+<dt><a href="reference/base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_">Abstract
 Class <code class="computeroutput">base_transaction_object</code></a></dt>
-<dt><a href="reference/transaction_object_hpp.html#toward_boost_stm.reference.transaction_object_hpp.template_class__transaction_object___">Template
+<dt><a href="reference/base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_function__cache_clone_____">Template
+ Function <code class="computeroutput">cache_clone<>()</code></a></dt>
+<dt><a href="reference/base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_function__cache_copy_____">Template
+ Function <code class="computeroutput">cache_copy<>()</code></a></dt>
+<dt><a href="reference/base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.function__cache_release_____">Function
+ <code class="computeroutput">cache_release<>()</code></a></dt>
+<dt><a href="reference/base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_function__cache_allocate_____">Template
+ Function <code class="computeroutput">cache_allocate<>()</code></a></dt>
+<dt><a href="reference/base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_function__cache_deallocate_____">Template
+ Function <code class="computeroutput">cache_deallocate<>()</code></a></dt>
+<dt><a href="reference/base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___">Template
 Class <code class="computeroutput">transaction_object<></code></a></dt>
-<dt><a href="reference/transaction_object_hpp.html#toward_boost_stm.reference.transaction_object_hpp.template_class__native_trans___">Template
+<dt><a href="reference/base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__native_trans___">Template
 Class <code class="computeroutput">native_trans<></code></a></dt>
-<dt><a href="reference/transaction_object_hpp.html#toward_boost_stm.reference.transaction_object_hpp.template_class__transactional_object___">Template
- Class <code class="computeroutput">transactional_object<></code></a></dt>
</dl></dd>
+<dt><a href="reference/transactional_object_hpp.html">
+ Header <code class="computeroutput"><boost/stm/transactional_object.hpp></code></a></dt>
+<dd><dl><dt><a href="reference/transactional_object_hpp.html#toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___">Template
+ Class <code class="computeroutput">transactional_object<></code></a></dt></dl></dd>
<dt> Header <boost/stm/tx_ptr.hpp></dt>
<dd><dl>
-<dt><a href="reference/tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__tx_obj___">Template
+<dt><a href="reference/tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__read_ptr___">Template
+ Class <code class="computeroutput">read_ptr<></code></a></dt>
+<dt><a href="reference/tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__write_ptr___">Template
+ Class <code class="computeroutput">write_ptr<></code></a></dt>
+</dl></dd>
+<dt><a href="reference/tx_smart_ptr_hpp.html"> Header
+ <code class="computeroutput"><boost/stm/tx_smart_ptr.hpp></code></a></dt>
+<dd><dl>
+<dt><a href="reference/tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__tx_obj___">Template
 Class <code class="computeroutput">tx_obj<></code></a></dt>
-<dt><a href="reference/tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__tx_ptr___">Template
+<dt><a href="reference/tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__tx_ptr___">Template
 Class <code class="computeroutput">tx_ptr<></code></a></dt>
-<dt><a href="reference/tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__rd_ptr___">Template
+<dt><a href="reference/tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__rd_ptr___">Template
 Class <code class="computeroutput">rd_ptr<></code></a></dt>
-<dt><a href="reference/tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__upgrd_ptr___">Template
+<dt><a href="reference/tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__upgrd_ptr___">Template
 Class <code class="computeroutput">upgrd_ptr<></code></a></dt>
-<dt><a href="reference/tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__wr_ptr___">Template
+<dt><a href="reference/tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__wr_ptr___">Template
+ Class <code class="computeroutput">wr_ptr<></code></a></dt>
+</dl></dd>
+<dt><a href="reference/non_tx_smart_ptr_hpp.html"> Header
+ <code class="computeroutput"><boost/stm/non_tx_smart_ptr.hpp></code></a></dt>
+<dd><dl>
+<dt><a href="reference/non_tx_smart_ptr_hpp.html#toward_boost_stm.reference.non_tx_smart_ptr_hpp.template_class__rd_ptr___">Template
+ Class <code class="computeroutput">rd_ptr<></code></a></dt>
+<dt><a href="reference/non_tx_smart_ptr_hpp.html#toward_boost_stm.reference.non_tx_smart_ptr_hpp.template_class__upgrd_ptr___">Template
+ Class <code class="computeroutput">upgrd_ptr<></code></a></dt>
+<dt><a href="reference/non_tx_smart_ptr_hpp.html#toward_boost_stm.reference.non_tx_smart_ptr_hpp.template_class__wr_ptr___">Template
 Class <code class="computeroutput">wr_ptr<></code></a></dt>
-<dt><a href="reference/tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__read_ptr___">Template
- Class <code class="computeroutput">read_ptr<></code></a></dt>
-<dt><a href="reference/tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__write_ptr___">Template
- Class <code class="computeroutput">write_ptr<></code></a></dt>
</dl></dd>
<dt><a href="reference/base_contention_manager_hpp.html">
 Header <code class="computeroutput"><boost/stm/base_contention_manager.hpp></code></a></dt>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/base_contention_manager_hpp.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/base_contention_manager_hpp.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/base_contention_manager_hpp.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -6,7 +6,7 @@
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
<link rel="start" href="../../index.html" title="Chapter 1. Toward.Boost.STM">
<link rel="up" href="../reference.html" title="Reference">
-<link rel="prev" href="tx_ptr_hpp.html" title="Header <boost/stm/tx_ptr.hpp>">
+<link rel="prev" href="non_tx_smart_ptr_hpp.html" title="Header <boost/stm/non_tx_smart_ptr.hpp>">
<link rel="next" href="language_like_hpp.html" title="Header <boost/stm/language_like.hpp>">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="tx_ptr_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="language_like_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+<a accesskey="p" href="non_tx_smart_ptr_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="language_like_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
@@ -281,7 +281,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="tx_ptr_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="language_like_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+<a accesskey="p" href="non_tx_smart_ptr_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="language_like_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>

Added: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/base_transaction_hpp.html
==============================================================================
--- (empty file)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/base_transaction_hpp.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -0,0 +1,542 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Header <boost/stm/base_transaction.hpp></title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
+<link rel="start" href="../../index.html" title="Chapter 1. Toward.Boost.STM">
+<link rel="up" href="../reference.html" title="Reference">
+<link rel="prev" href="transaction_hpp.html" title="Header <boost/stm/transaction.hpp>">
+<link rel="next" href="transactional_object_hpp.html" title="Header <boost/stm/transactional_object.hpp>">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="TowardBoostSTM" width="277" height="86" src="../../../image/Toward_Boost_STM.jpg"></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="transaction_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="transactional_object_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp"></a><a class="link" href="base_transaction_hpp.html" title="Header <boost/stm/base_transaction.hpp>"> Header
+ <code class="computeroutput"><boost/stm/base_transaction.hpp></code></a>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_">Abstract
+ Class <code class="computeroutput">base_transaction_object</code></a></dt>
+<dd><dl>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.constructor__base_transaction_object___">Constructor
+ <code class="computeroutput">base_transaction_object()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_destructor___base_transaction_object___">Virtual
+ Destructor <code class="computeroutput">~base_transaction_object()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_function__copy_state___">Virtual
+ function <code class="computeroutput">copy_state()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_function__move_state___">Virtual
+ function <code class="computeroutput">move_state()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.static_function__retrieve_mem___">Static
+ function <code class="computeroutput">retrieve_mem()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.static_function__return_mem___">Static
+ function <code class="computeroutput">return_mem()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.static_function__alloc_size___">Static
+ function <code class="computeroutput">alloc_size()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_function__cache_deallocate___">Virtual
+ function <code class="computeroutput">cache_deallocate()</code></a></dt>
+</dl></dd>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_function__cache_clone_____">Template
+ Function <code class="computeroutput">cache_clone<>()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_function__cache_copy_____">Template
+ Function <code class="computeroutput">cache_copy<>()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.function__cache_release_____">Function
+ <code class="computeroutput">cache_release<>()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_function__cache_allocate_____">Template
+ Function <code class="computeroutput">cache_allocate<>()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_function__cache_deallocate_____">Template
+ Function <code class="computeroutput">cache_deallocate<>()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___">Template
+ Class <code class="computeroutput">transaction_object<></code></a></dt>
+<dd><dl>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__clone___">Virtual
+ function <code class="computeroutput">clone()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__copy_state___">Virtual
+ function <code class="computeroutput">copy_state()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__move_state___">Virtual
+ function <code class="computeroutput">move_state()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__cache_deallocate___">Virtual
+ function <code class="computeroutput">cache_deallocate()</code></a></dt>
+</dl></dd>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__native_trans___">Template
+ Class <code class="computeroutput">native_trans<></code></a></dt>
+</dl></div>
+<pre class="programlisting">namespace boost { namespace stm {
+ class base_transaction_object;
+
+ template <class T> T* cache_clone(const T& val);
+ template <class T> void cache_copy(const T* const ori, T* target);
+ void cache_release(base_transaction_object* ptr);
+
+ template <class T> T* cache_allocate();
+ template <class T> void cache_deallocate(T*);
+
+
+ template <class Derived> class transaction_object;
+ template <typename T> class native_trans;
+}}
+</pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_" title="Abstract Class base_transaction_object">Abstract
+ Class <code class="computeroutput">base_transaction_object</code></a>
+</h4></div></div></div>
+<div class="toc"><dl>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.constructor__base_transaction_object___">Constructor
+ <code class="computeroutput">base_transaction_object()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_destructor___base_transaction_object___">Virtual
+ Destructor <code class="computeroutput">~base_transaction_object()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_function__copy_state___">Virtual
+ function <code class="computeroutput">copy_state()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_function__move_state___">Virtual
+ function <code class="computeroutput">move_state()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.static_function__retrieve_mem___">Static
+ function <code class="computeroutput">retrieve_mem()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.static_function__return_mem___">Static
+ function <code class="computeroutput">return_mem()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.static_function__alloc_size___">Static
+ function <code class="computeroutput">alloc_size()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_function__cache_deallocate___">Virtual
+ function <code class="computeroutput">cache_deallocate()</code></a></dt>
+</dl></div>
+
+ This is the base class of all the transactional objects. It tracks:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+<code class="computeroutput">transactionThread_</code>: the
+ thread identifier holding the write acces to this transactional object
+ </li>
+<li>
+<code class="computeroutput">transaction_</code>: the pointer
+ to the transaction
+ </li>
+<li>
+<code class="computeroutput">version_</code>: the version
+ when performing validation
+ </li>
+<li>
+<code class="computeroutput">newMemory_</code>: states whether
+ this object is a new object
+ </li>
+</ul></div>
+
+ Transactional objets must specialize the pure virtual functions
+ 
+<div class="itemizedlist"><ul type="disc">
+<li><code class="computeroutput">copy_state(base_transaction_object const
+ * const
+ rhs)</code></li>
+<li>
+<code class="computeroutput">move_state(base_transaction_object *
+ rhs)</code>
+ if <code class="computeroutput">BUILD_MOVE_SEMANTICS</code>
+</li>
+<li>
+<code class="computeroutput">cache_deallocate()</code>
+ if <code class="computeroutput">BOOST_STM_USE_UNASIGNED_COPY</code>
+</li>
+</ul></div>
+
+ <code class="computeroutput">copy_state</code> is used to copy
+ the backup/working copy to the shared transactional object when the roolback/commit
+ is done direct/defered policy is used.
+ 
+
+ <code class="computeroutput">move_state</code> is used to move
+ the backup/working copy to the shared transactional object when the roolback/commit
+ is done direct/defered policy is used.
+ 
+
+ <code class="computeroutput">cache_deallocate</code> is used
+ to release the backup/working copy when the transaction ends if direct/defered
+ policy is used.
+ 
+
+ When USE_STM_MEMORY_MANAGER is defined this class provides two functions
+ (<code class="computeroutput">retrieve_mem</code> and <code class="computeroutput">return_mem</code>) and to manage a pool of memory.
+ 
+<pre class="programlisting">class base_transaction_object
+{
+public:
+
+ base_transaction_object();
+ virtual ~base_transaction_object() {};
+
+ virtual base_transaction_object* clone() const = 0;
+ virtual void copy_state(base_transaction_object const * const rhs) = 0;
+ virtual void move_state(base_transaction_object * rhs) = 0;
+
+ void transaction_thread(thread_id rhs) const;
+ thread_id transaction_thread() const;
+
+ void new_memory(bool rhs)
+ bool new_memory() const;
+
+#if BOOST_STM_PERFORMING_VALIDATION
+ void version(std::size_t rhs);
+ std::size_t version() const;
+#endif
+
+#if BOOST_STM_USE_MEMORY_MANAGER
+ static void return_mem(void *mem, size_t size);
+ static void* retrieve_mem(size_t size);
+ static void alloc_size(size_t size);
+#endif
+
+#ifdef BOOST_STM_USE_UNASIGNED_COPY
+ virtual void cache_deallocate()=0;
+#endif
+
+};
+</pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.constructor__base_transaction_object___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.constructor__base_transaction_object___" title="Constructor base_transaction_object()">Constructor
+ <code class="computeroutput">base_transaction_object()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">base_transaction_object();
+</pre>
+
+ Default constructor (ctor) with no parameters allows derived base_transaction_objects
+ to implicitly construct the base_transaction_object base class for easier
+ integration.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_destructor___base_transaction_object___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_destructor___base_transaction_object___" title="Virtual Destructor ~base_transaction_object()">Virtual
+ Destructor <code class="computeroutput">~base_transaction_object()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">virtual ~base_transaction_object() {};
+</pre>
+
+ Virtual destructor (dtor) ensures correct destructors are called in the
+ inheritance hierarchy for delete operations invoked on base_transaction_object
+ pointers, which occur in numerous places throughout the internal transaction
+ code.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_function__copy_state___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_function__copy_state___" title="Virtual function copy_state()">Virtual
+ function <code class="computeroutput">copy_state()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">virtual void copy_state(base_transaction_object const * const rhs) = 0;
+</pre>
+
+ The <code class="computeroutput">copy_state()</code>
+ method is called each time global memory is updated, for either direct
+ or deferred updating policies. With this in mind, it is vital that the
+ this object be set to the exact state of the input parameter.
+ 
+
+ Derived classes usually simply override this method and perform an <code class="computeroutput">operator=()</code>
+ function call for the specific derived type.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_function__move_state___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_function__move_state___" title="Virtual function move_state()">Virtual
+ function <code class="computeroutput">move_state()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">virtual void move_state(base_transaction_object * rhs) = 0;
+</pre>
+
+ The move_state() method is internally called at deferred updating commit
+ time and at direct updating abort time and invokes the user-defined derived
+ transaction class's move assignment (e.g. operator=(type &&)).
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.static_function__retrieve_mem___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.static_function__retrieve_mem___" title="Static function retrieve_mem()">Static
+ function <code class="computeroutput">retrieve_mem()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">static void* retrieve_mem(size_t size);
+</pre>
+
+ Static interface into TBoost.STM's memory management system for retrieving
+ memory. The supplied parameter is the requested block size, the return
+ parameter is a void* to the allocated block. Usually access to this interface
+ is done by overloading operator new in the derived base_transaction_object
+ class. Void pointers are the natural and preferred manner to handle memory
+ allocations and deallocations and are therefore safe in this context.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.static_function__return_mem___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.static_function__return_mem___" title="Static function return_mem()">Static
+ function <code class="computeroutput">return_mem()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">static void return_mem(void *mem, size_t size);
+</pre>
+
+ Static interface into TBoost.STM's memory management system for returning
+ memory. The first parameter points to the memory block being returned,
+ the second parameter specifies its size. Usually access to this interface
+ is done by overloading operator delete in the derived transaction object
+ class. Void pointers are the natural and preferred manner to handle memory
+ allocations and deallocations and are therefore safe in this context.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.static_function__alloc_size___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.static_function__alloc_size___" title="Static function alloc_size()">Static
+ function <code class="computeroutput">alloc_size()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">static void alloc_size(size_t size);
+</pre>
+
+ Static interface into TBoost.STM's memory management system which allows
+ the user to specify the allocation chunk size for the memory manager.
+ The input parameter specifies the number of transactional objects that
+ should be allocated at startup and with each subsequent buffer increase.
+ If no size is specified, the allocation chunk size uses TBoost.STM's
+ default value, currently 8192. The alloc_size() interface can be reconfigured
+ at runtime and is used upon the next buffer increase.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_function__cache_deallocate___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.abstract_class__base_transaction_object_.virtual_function__cache_deallocate___" title="Virtual function cache_deallocate()">Virtual
+ function <code class="computeroutput">cache_deallocate()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">virtual void cache_deallocate()=0;
+</pre>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.template_function__cache_clone_____"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_function__cache_clone_____" title="Template Function cache_clone<>()">Template
+ Function <code class="computeroutput">cache_clone<>()</code></a>
+</h4></div></div></div>
+<pre class="programlisting">template <class T>
+T* cache_clone(const T& val);
+</pre>
+
+ Makes a new copy of the parameter. Allocates an object of type T using
+ the <code class="computeroutput">cache_allocate</code> function
+ and copy from the given parameter <code class="computeroutput">val</code>
+ using the free function <code class="computeroutput">cache_copy</code>.
+ 
+
+ The user can overload this function, as TBoost.STM uses ADL to access it.
+ 
+
+ When <code class="computeroutput">BOOST_STM_NO_PARTIAL_SPECIALIZATION</code>
+ is defined, i.e. on compilers not supporting partial template specialization,
+ the function calls to <code class="computeroutput">partial_specialization_workaround::cache_clone<T>::apply(val)</code>. So the user will need to overload the
+ class <code class="computeroutput">partial_specialization_workaround::cache_clone<T></code> defining the function
+ 
+<pre class="programlisting">static T* apply(const T& val);
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.template_function__cache_copy_____"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_function__cache_copy_____" title="Template Function cache_copy<>()">Template
+ Function <code class="computeroutput">cache_copy<>()</code></a>
+</h4></div></div></div>
+<pre class="programlisting">template <class T>
+void cache_copy(const T* const source, T* target);
+</pre>
+
+ Copy from souce to target using memcpy by default.
+ 
+
+ The user can overload this function, as TBoost.STM uses ADL to access it.
+ 
+
+ When <code class="computeroutput">BOOST_STM_NO_PARTIAL_SPECIALIZATION</code>
+ is defined, i.e. on compilers not supporting partial template specialization,
+ the function calls to <code class="computeroutput">partial_specialization_workaround::cache_copy<T>::apply(source, target)</code>. So the user will need to overload the
+ class <code class="computeroutput">partial_specialization_workaround::cache_copy<T></code> defining the function
+ 
+<pre class="programlisting">static T* apply(const T* const source, T* target);
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.function__cache_release_____"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.function__cache_release_____" title="Function cache_release<>()">Function
+ <code class="computeroutput">cache_release<>()</code></a>
+</h4></div></div></div>
+<pre class="programlisting">void cache_release(base_transaction_object* ptr) {
+</pre>
+
+ Release the given base_transaction_object by calling to the virtual function
+ <code class="computeroutput">cache_dealocate</code>.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.template_function__cache_allocate_____"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_function__cache_allocate_____" title="Template Function cache_allocate<>()">Template
+ Function <code class="computeroutput">cache_allocate<>()</code></a>
+</h4></div></div></div>
+<pre class="programlisting">template <class T>
+T* cache_allocate();
+</pre>
+
+ Allocates an instance of calls T. Depending on whether BOOST_STM_CACHE_USE_MEMORY_MANAGER,
+ BOOST_STM_CACHE_USE_MALLOC or BOOST_STM_CACHE_USE_TSS_MONOTONIC_MEMORY_MANAGER
+ are defined this function will use the static pool of the class T, malloc
+ or the thread specific monotonic allocator.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.template_function__cache_deallocate_____"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_function__cache_deallocate_____" title="Template Function cache_deallocate<>()">Template
+ Function <code class="computeroutput">cache_deallocate<>()</code></a>
+</h4></div></div></div>
+<pre class="programlisting">template <class T>
+void cache_deallocate(T*ptr) {
+</pre>
+
+ Deallocates an instance of calls T. Depending on whether BOOST_STM_CACHE_USE_MEMORY_MANAGER,
+ BOOST_STM_CACHE_USE_MALLOC or BOOST_STM_CACHE_USE_TSS_MONOTONIC_MEMORY_MANAGER
+ are defined this function will use the static pool of the class T, free
+ or the no-op.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___" title="Template Class transaction_object<>">Template
+ Class <code class="computeroutput">transaction_object<></code></a>
+</h4></div></div></div>
+<div class="toc"><dl>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__clone___">Virtual
+ function <code class="computeroutput">clone()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__copy_state___">Virtual
+ function <code class="computeroutput">copy_state()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__move_state___">Virtual
+ function <code class="computeroutput">move_state()</code></a></dt>
+<dt><a href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__cache_deallocate___">Virtual
+ function <code class="computeroutput">cache_deallocate()</code></a></dt>
+</dl></div>
+
+ To further simplify the usage of TBoost.STM, an intermediate template class
+ was built which is meant to sit between the base_transaction_object and
+ the user-defined transaction objects. The purpose of this intermediate
+ class is to reduce the code overhead needed for user-defined transaction
+ objects. To do this, the curiously recurring template pattern developed
+ by James Coplien was used.
+ 
+
+ With the templatized transaction_object, client-side transaction objects
+ need only to derive from it and pass their class type as its template parameter.
+ At compile-time the transaction_object generates the necessary code to
+ override copy_state() and implement operator new and operator delete using
+ TBoost.STM's memory manager for all user-defined types derived from it.
+ 
+<pre class="programlisting">template <class Derived>
+class transaction_object : public base_transaction_object {
+public:
+
+ virtual base_transaction_object* clone() const;
+ virtual void copy_state(base_transaction_object const * const rhs);
+ virtual void move_state(base_transaction_object * rhs);
+};
+</pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__clone___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__clone___" title="Virtual function clone()">Virtual
+ function <code class="computeroutput">clone()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">virtual base_transaction_object* clone() const;
+</pre>
+
+ The clone() method calls to the free function cache_new_copy which allocates
+ enough memory for the new object and then do a memcpy by default.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__copy_state___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__copy_state___" title="Virtual function copy_state()">Virtual
+ function <code class="computeroutput">copy_state()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">virtual void copy_state(base_transaction_object const * const rhs);
+</pre>
+
+ The copy_state() method call to the free function cache_copy which do
+ a memcpy by default.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__move_state___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__move_state___" title="Virtual function move_state()">Virtual
+ function <code class="computeroutput">move_state()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">virtual void move_state(base_transaction_object * rhs);
+</pre>
+
+ The move_state() method call to the free function cache_copy which do
+ a memcpy by default.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__cache_deallocate___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__transaction_object___.virtual_function__cache_deallocate___" title="Virtual function cache_deallocate()">Virtual
+ function <code class="computeroutput">cache_deallocate()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">virtual void cache_deallocate();
+</pre>
+
+ The cache_deallocate() method call to the free function cache_deallocate
+ which do a memcpy by default.
+ 
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.base_transaction_hpp.template_class__native_trans___"></a><a class="link" href="base_transaction_hpp.html#toward_boost_stm.reference.base_transaction_hpp.template_class__native_trans___" title="Template Class native_trans<>">Template
+ Class <code class="computeroutput">native_trans<></code></a>
+</h4></div></div></div>
+<pre class="programlisting">template <typename T> class native_trans : public transaction_object< native_trans<T> > {
+public:
+ native_trans(){}
+ native_trans(T const &rhs);
+ native_trans(native_trans const &rhs);
+ native_trans(native_trans &&rhs);
+ native_trans& operator=(native_trans &&rhs);
+
+ native_trans& operator=(T const &rhs);
+
+ native_trans& operator--();
+ native_trans operator--(int);
+ native_trans& operator++();
+ native_trans operator++(int);
+ native_trans& operator+=(T const &rhs);
+ native_trans operator+(native_trans const &rhs);
+
+ operator T() const;
+ T& value();
+ T const & value() const;
+};
+</pre>
+</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 © 2009 Justin E. Gottchlich Copyright © 2009 Vicente J. Botet Escriba
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="transaction_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="transactional_object_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/language_like_hpp.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/language_like_hpp.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/language_like_hpp.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -45,12 +45,16 @@
 The complexity behind the <code class="computeroutput">atomic</code>
 macro is needed to guarantee two fundamental goals.
 
-<div class="itemizedlist"><ul type="disc"><li>
- First, transactions must start and end correctly. Second, transactions
- must change their retry behavior based on whether they are a child or parent
- transaction to ensure proper closed nesting, flattened transaction behavior
- is performed.
- </li></ul></div>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ First, transactions must start and end correctly.
+ </li>
+<li>
+ Second, transactions must change their retry behavior based on whether
+ they are a child or parent transaction to ensure proper closed nesting,
+ flattened transaction behavior is performed.
+ </li>
+</ul></div>

 The <code class="computeroutput">atomic</code> preprocessor behaves
 as follows. When the transactional for loop is entered, a transaction automatic

Added: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/non_tx_smart_ptr_hpp.html
==============================================================================
--- (empty file)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/non_tx_smart_ptr_hpp.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -0,0 +1,193 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Header <boost/stm/non_tx_smart_ptr.hpp></title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
+<link rel="start" href="../../index.html" title="Chapter 1. Toward.Boost.STM">
+<link rel="up" href="../reference.html" title="Reference">
+<link rel="prev" href="tx_smart_ptr_hpp.html" title="Header <boost/stm/tx_smart_ptr.hpp>">
+<link rel="next" href="base_contention_manager_hpp.html" title="Header <boost/stm/base_contention_manager.hpp>">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="TowardBoostSTM" width="277" height="86" src="../../../image/Toward_Boost_STM.jpg"></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="tx_smart_ptr_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="base_contention_manager_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="toward_boost_stm.reference.non_tx_smart_ptr_hpp"></a><a class="link" href="non_tx_smart_ptr_hpp.html" title="Header <boost/stm/non_tx_smart_ptr.hpp>"> Header
+ <code class="computeroutput"><boost/stm/non_tx_smart_ptr.hpp></code></a>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><a href="non_tx_smart_ptr_hpp.html#toward_boost_stm.reference.non_tx_smart_ptr_hpp.template_class__rd_ptr___">Template
+ Class <code class="computeroutput">rd_ptr<></code></a></dt>
+<dt><a href="non_tx_smart_ptr_hpp.html#toward_boost_stm.reference.non_tx_smart_ptr_hpp.template_class__upgrd_ptr___">Template
+ Class <code class="computeroutput">upgrd_ptr<></code></a></dt>
+<dt><a href="non_tx_smart_ptr_hpp.html#toward_boost_stm.reference.non_tx_smart_ptr_hpp.template_class__wr_ptr___">Template
+ Class <code class="computeroutput">wr_ptr<></code></a></dt>
+</dl></div>
+<pre class="programlisting">namespace boost { namespace stm { namespace non_tx {
+ template <typename T> class rd_ptr;
+ template <typename T> rd_ptr<T> make_rd_ptr(transaction& tx, T* ptr);
+ template <typename T> rd_ptr<T> make_rd_ptr(transaction& tx, T& ref);
+ template <typename T> rd_ptr<T> make_rd_ptr(T* ptr);
+ template <typename T> rd_ptr<T> make_rd_ptr(T& ref);
+ template <typename T> void delete_ptr(rd_ptr<T> ptr);
+
+ template <typename T> class upgrd_ptr;
+ template <typename T> void delete_ptr(upgrd_ptr<T> const& ptr);
+ template <typename T> void delete_ptr(transaction& tx, upgrd_ptr<T> const& ptr);
+
+ template <typename T> class wr_ptr;
+}}}
+</pre>
+
+ These smart pointers points to an unspecified cache type which inherits from
+ base_transactional object. This cache is obtained from an internal thread
+ safe cache map.
+ 
+
+ As the the non_tx smart pointers need to lookup on a cache they must be used
+ only when you need to access to a non transactional variable on the context
+ of a transaction. Otherwise, please use tx_ptr<> or the mixin transaction_object<>.
+ 
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.non_tx_smart_ptr_hpp.template_class__rd_ptr___"></a><a class="link" href="non_tx_smart_ptr_hpp.html#toward_boost_stm.reference.non_tx_smart_ptr_hpp.template_class__rd_ptr___" title="Template Class rd_ptr<>">Template
+ Class <code class="computeroutput">rd_ptr<></code></a>
+</h4></div></div></div>
+
+ A rd_ptr<T> ("read pointer") points to an cache that the
+ current transaction has opened for read only access. You can only call
+ a const method through a read pointer.
+ 
+
+ A rd_ptr<T> is constructed from an T pointer or reference. Once a
+ rd_ptr<T> has been constructed, the associated cache is opened for
+ reading.
+ 
+
+ It is not safe to derreference a rd_ptr<T> after having assigned
+ the same T to a wr_ptr<T>. If this is the case the readen value do
+ not match the writen one. If it is possible to write on the same transaction
+ use upgrd_ptr instead which is safe.
+ 
+<pre class="programlisting">template <typename T>
+class rd_ptr {
+public:
+ rd_ptr(transaction &t, T const * ptr);
+
+ rd_ptr(transaction &t, T const & obj);
+
+ template<class Y>
+ explicit rd_ptr & operator=(Y const* ptr);
+
+ template<class Y>
+ explicit rd_ptr & operator=(Y const& ref);
+
+ const T* get() const;
+
+ const T & operator*() const;
+ const T* operator->() const;
+
+ operator unspecified_bool_type() const;
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.non_tx_smart_ptr_hpp.template_class__upgrd_ptr___"></a><a class="link" href="non_tx_smart_ptr_hpp.html#toward_boost_stm.reference.non_tx_smart_ptr_hpp.template_class__upgrd_ptr___" title="Template Class upgrd_ptr<>">Template
+ Class <code class="computeroutput">upgrd_ptr<></code></a>
+</h4></div></div></div>
+
+ A upgrd_ptr<T> ("upgradable pointer") points to an cache
+ that the current transaction has opened for read only access. You can only
+ call const method of the wrapped type through a upgradable pointer.
+ 
+
+ A upgrd_ptr<T> is constructed from an T pointer or reference through
+ a constructor having also the transaction as parameter. Once a upgrd_ptr<T>
+ has been constructed, an a cache of T can is opened for reading.
+ 
+
+ It is safe to derreference a upgrd_ptr<T> after having assigned the
+ same T to a wr_ptr<T>.
+ 
+
+ A upgrd_ptr<T> can be upgraded to a wr_ptr<T> through a constructor.
+ 
+<pre class="programlisting">template <typename T>
+class upgrd_ptr {
+public:
+ upgrd_ptr(transaction &t, T* ptr);
+ upgrd_ptr(transaction &t, T& ref);
+
+ template<class Y> upgrd_ptr & operator=(Y* ptr);
+
+ template<class Y> upgrd_ptr & operator=(Y& ref);
+
+ const T* get() const;
+ inline T const & operator*() const;
+ inline T const * operator->() const;
+
+ operator unspecified_bool_type() const;
+
+ void write_ptr(detail::cache<T>* ptr);
+ T* write_ptr();
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.non_tx_smart_ptr_hpp.template_class__wr_ptr___"></a><a class="link" href="non_tx_smart_ptr_hpp.html#toward_boost_stm.reference.non_tx_smart_ptr_hpp.template_class__wr_ptr___" title="Template Class wr_ptr<>">Template
+ Class <code class="computeroutput">wr_ptr<></code></a>
+</h4></div></div></div>
+
+ A wr_ptr<T> ("write pointer") points to a cache that the
+ current transaction has opened for writing.
+ 
+
+ A wr_ptr<T> is initialized explicitly from an T pointer or reference.
+ 
+
+ A wr_ptr<T> can also be explicitly constructed from a upgrd_ptr<T>
+ as an upgrade-to-writable operation.
+ 
+<pre class="programlisting">template <typename T>
+class wr_ptr {
+public:
+ wr_ptr(transaction &t, T* ptr);
+ wr_ptr(transaction &t, T& obj);
+
+ T* get();
+ inline T& operator*();
+ inline T* operator->();
+
+ operator unspecified_bool_type() const;
+};
+</pre>
+</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 © 2009 Justin E. Gottchlich Copyright © 2009 Vicente J. Botet Escriba
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tx_smart_ptr_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="base_contention_manager_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/transaction_hpp.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/transaction_hpp.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/transaction_hpp.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -7,7 +7,7 @@
<link rel="start" href="../../index.html" title="Chapter 1. Toward.Boost.STM">
<link rel="up" href="../reference.html" title="Reference">
<link rel="prev" href="exceptions_hpp.html" title="Header <boost/stm/exceptions.hpp>">
-<link rel="next" href="transaction_object_hpp.html" title="Header <boost/stm/transaction_object.hpp>">
+<link rel="next" href="base_transaction_hpp.html" title="Header <boost/stm/base_transaction.hpp>">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="exceptions_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="transaction_object_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+<a accesskey="p" href="exceptions_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="base_transaction_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
@@ -154,9 +154,12 @@
<dt><a href="transaction_hpp.html#toward_boost_stm.reference.transaction_hpp.class__transaction_.template__function__new_memory_copy___">Template
 Function <code class="computeroutput">new_memory_copy<></code></a></dt>
</dl></dd>
+<dt><a href="transaction_hpp.html#toward_boost_stm.reference.transaction_hpp.struct__thread_initializer_">Struct
+ <code class="computeroutput">thread_initializer</code></a></dt>
</dl></div>
<pre class="programlisting">namespace boost { namespace stm {
 class transaction;
+ struct thread_initializer;
}}
</pre>
<div class="section" lang="en">
@@ -1048,6 +1051,24 @@
 
</div>
</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.transaction_hpp.struct__thread_initializer_"></a><a class="link" href="transaction_hpp.html#toward_boost_stm.reference.transaction_hpp.struct__thread_initializer_" title="Struct thread_initializer">Struct
+ <code class="computeroutput">thread_initializer</code></a>
+</h4></div></div></div>
+
+ Scoped thread initializer calling transaction::initialize_thread() in the
+ constructor and transaction::terminate_thread() in the destructor.
+ 
+
+ Declare an object of this class on each thread participating on a transaction.
+ 
+<pre class="programlisting">struct thread_initializer {
+ thread_initializer();
+ ~thread_initializer();
+};
+</pre>
+</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
@@ -1059,7 +1080,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="exceptions_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="transaction_object_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+<a accesskey="p" href="exceptions_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="base_transaction_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>

Added: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/transactional_object_hpp.html
==============================================================================
--- (empty file)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/transactional_object_hpp.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -0,0 +1,177 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Header <boost/stm/transactional_object.hpp></title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
+<link rel="start" href="../../index.html" title="Chapter 1. Toward.Boost.STM">
+<link rel="up" href="../reference.html" title="Reference">
+<link rel="prev" href="base_transaction_hpp.html" title="Header <boost/stm/base_transaction.hpp>">
+<link rel="next" href="tx_ptr_hpp.html" title="Header <boost/stm/tx_ptr.hpp>">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="TowardBoostSTM" width="277" height="86" src="../../../image/Toward_Boost_STM.jpg"></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="base_transaction_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="tx_ptr_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="toward_boost_stm.reference.transactional_object_hpp"></a><a class="link" href="transactional_object_hpp.html" title="Header <boost/stm/transactional_object.hpp>">
+ Header <code class="computeroutput"><boost/stm/transactional_object.hpp></code></a>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><a href="transactional_object_hpp.html#toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___">Template
+ Class <code class="computeroutput">transactional_object<></code></a></dt>
+<dd><dl>
+<dt><a href="transactional_object_hpp.html#toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___.virtual_function__copy_state___">Virtual
+ function <code class="computeroutput">copy_state()</code></a></dt>
+<dt><a href="transactional_object_hpp.html#toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___.virtual_function__move_state___">Virtual
+ function <code class="computeroutput">move_state()</code></a></dt>
+<dt><a href="transactional_object_hpp.html#toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___.virtual_function__cache_deallocate___">Virtual
+ function <code class="computeroutput">cache_deallocate()</code></a></dt>
+</dl></dd>
+</dl></div>
+<pre class="programlisting">namespace boost { namespace stm {
+ template <class T> class transactional_object;
+
+ template <typename T>
+ static transactional_object<T>* tx_up_cast(T* ptr);
+
+ template <typename T, typename U>
+ static transactional_object<T>* tx_static_cast(transactional_object<U>* ptr);
+
+ template <typename T, typename U>
+ static transactional_object<T>* tx_dynamic_cast(transactional_object<U>* ptr);
+}}
+</pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___"></a><a class="link" href="transactional_object_hpp.html#toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___" title="Template Class transactional_object<>">Template
+ Class <code class="computeroutput">transactional_object<></code></a>
+</h4></div></div></div>
+<div class="toc"><dl>
+<dt><a href="transactional_object_hpp.html#toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___.virtual_function__copy_state___">Virtual
+ function <code class="computeroutput">copy_state()</code></a></dt>
+<dt><a href="transactional_object_hpp.html#toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___.virtual_function__move_state___">Virtual
+ function <code class="computeroutput">move_state()</code></a></dt>
+<dt><a href="transactional_object_hpp.html#toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___.virtual_function__cache_deallocate___">Virtual
+ function <code class="computeroutput">cache_deallocate()</code></a></dt>
+</dl></div>
+
+ Transactional object wrapper. A <code class="computeroutput">transactional_object<T></code> is a base_transaction_object wrapping
+ an instance of type T. Provides the definition of the virtual functions
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ forward constructors to the wrapped type
+ </li>
+<li>
+<code class="computeroutput">copy_state</code>: relaying
+ on the cache_copy<T> generic function
+ </li>
+<li>
+<code class="computeroutput">move_state</code> and
+ </li>
+<li>
+<code class="computeroutput">cache_deallocate</code>: relaying
+ on the cache_copy<T> generic function
+ </li>
+</ul></div>
+
+ Defines in addition the functions <code class="computeroutput">new</code>
+ and <code class="computeroutput">delete</code> when <code class="computeroutput">BOOST_STM_USE_MEMORY_MANAGER</code> is defined
+ 
+
+ If a class D inherits from B we have that <code class="computeroutput">transactional_object<D></code> dont inherits from <code class="computeroutput">transactional_object<B></code>, but we can static/dynamic cast them
+ robustly.
+ 
+
+ Evidently the <code class="computeroutput">std::static_cast</code>/<code class="computeroutput">std::dynamic_cast</code>
+ do not works. We need to define the specific cast
+ 
+<pre class="programlisting">transactional_object<D>* d=...;
+transactional_object<B>* b=tx_static_cast<B>(d);
+
+transactional_object<B>* b=...;
+transactional_object<D>* d=tx_dynamic_cast<B>(b);
+</pre>
+
+ Synopsis
+ 
+<pre class="programlisting">template <typename T>
+class transactional_object : public base_transaction_object {
+public:
+ T value;
+
+ transactional_object();
+ transactional_object(const T*ptr);
+ transactional_object(transactional_object<T> const & r);
+ template <typename T1>
+ transactional_object(T1 const &p1);
+
+ template <typename T1, typename T2>
+ transactional_object(T1 const &p1, T2 const &p2);
+
+ transactional_object & operator=(transactional_object const & r);
+
+ virtual void copy_state(base_transaction_object const * const rhs);
+
+#ifdef BOOST_STM_USE_UNASIGNED_COPY
+ virtual void cache_deallocate();
+#endif
+
+#if BOST_STM_USE_MEMORY_MANAGER
+ void* operator new(size_t size) throw ();
+ void operator delete(void* mem);
+#endif
+
+};
+</pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___.virtual_function__copy_state___"></a><a class="link" href="transactional_object_hpp.html#toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___.virtual_function__copy_state___" title="Virtual function copy_state()">Virtual
+ function <code class="computeroutput">copy_state()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">virtual void copy_state(base_transaction_object const * const rhs);
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___.virtual_function__move_state___"></a><a class="link" href="transactional_object_hpp.html#toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___.virtual_function__move_state___" title="Virtual function move_state()">Virtual
+ function <code class="computeroutput">move_state()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">virtual void move_state(base_transaction_object * rhs);
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h5 class="title">
+<a name="toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___.virtual_function__cache_deallocate___"></a><a class="link" href="transactional_object_hpp.html#toward_boost_stm.reference.transactional_object_hpp.template_class__transactional_object___.virtual_function__cache_deallocate___" title="Virtual function cache_deallocate()">Virtual
+ function <code class="computeroutput">cache_deallocate()</code></a>
+</h5></div></div></div>
+<pre class="programlisting">virtual void cache_deallocate()=0;
+</pre>
+</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 © 2009 Justin E. Gottchlich Copyright © 2009 Vicente J. Botet Escriba
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="base_transaction_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="tx_ptr_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/tx_ptr_hpp.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/tx_ptr_hpp.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/tx_ptr_hpp.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -6,8 +6,8 @@
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
<link rel="start" href="../../index.html" title="Chapter 1. Toward.Boost.STM">
<link rel="up" href="../reference.html" title="Reference">
-<link rel="prev" href="transaction_object_hpp.html" title="Header <boost/stm/transaction_object.hpp>">
-<link rel="next" href="base_contention_manager_hpp.html" title="Header <boost/stm/base_contention_manager.hpp>">
+<link rel="prev" href="transactional_object_hpp.html" title="Header <boost/stm/transactional_object.hpp>">
+<link rel="next" href="tx_smart_ptr_hpp.html" title="Header <boost/stm/tx_smart_ptr.hpp>">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@@ -20,299 +20,25 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="transaction_object_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="base_contention_manager_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+<a accesskey="p" href="transactional_object_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="tx_smart_ptr_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="toward_boost_stm.reference.tx_ptr_hpp"></a><a class="link" href="tx_ptr_hpp.html" title="Header <boost/stm/tx_ptr.hpp>"> Header <code class="computeroutput"><boost/stm/tx_ptr.hpp></code></a>
</h3></div></div></div>
<div class="toc"><dl>
-<dt><a href="tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__tx_obj___">Template
- Class <code class="computeroutput">tx_obj<></code></a></dt>
-<dt><a href="tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__tx_ptr___">Template
- Class <code class="computeroutput">tx_ptr<></code></a></dt>
-<dt><a href="tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__rd_ptr___">Template
- Class <code class="computeroutput">rd_ptr<></code></a></dt>
-<dt><a href="tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__upgrd_ptr___">Template
- Class <code class="computeroutput">upgrd_ptr<></code></a></dt>
-<dt><a href="tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__wr_ptr___">Template
- Class <code class="computeroutput">wr_ptr<></code></a></dt>
<dt><a href="tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__read_ptr___">Template
 Class <code class="computeroutput">read_ptr<></code></a></dt>
<dt><a href="tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__write_ptr___">Template
 Class <code class="computeroutput">write_ptr<></code></a></dt>
</dl></div>
<pre class="programlisting">namespace boost { namespace stm {
-
- template <typename T> class tx_obj;
- template <typename T, typename U>
- bool operator==(const tx_obj<T>& lhs, const tx_obj<U>& rhs);
- template <typename T, typename U>
- bool operator==(const T& lhs, const tx_obj<U>& rhs);
- template <typename T, typename U>
- bool operator==(const tx_obj<T>& lhs, const U& rhs);
- template <typename T, typename U>
- bool operator!=(const tx_obj<T>& lhs, const tx_obj<U>& rhs);
- template <typename T, typename U>
- bool operator!=(const tx_obj<T>& lhs, const tx_obj<U>& rhs);
- template<class T> inline void swap(tx_obj<T> & a, tx_obj<T> & b);
-
- template <typename T> class tx_ptr;
- template <typename T, typename U>
- bool operator==(const tx_ptr<T>& lhs, const tx_ptr<U>& rhs);
- template <typename T, typename U>
- bool operator!=(const tx_ptr<T>& lhs, const tx_ptr<U>& rhs);
- template<class T> inline void swap(tx_ptr<T> & a, tx_ptr<T> & b);
-
- template <typename T>
- void delete_ptr(tx_ptr<T> ptr);
- template <typename T>
- void delete_ptr(transaction& tx, tx_ptr<T> ptr);
-
- template <typename T, typename U>
- static tx_ptr<T> tx_static_cast(tx_ptr<U> ptr);
- template <typename T, typename U>
- static tx_ptr<T>* tx_dynamic_cast(tx_ptr<U> ptr);
-
- template <typename T> class rd_ptr;
- template <typename T>
- rd_ptr<T> make_rd_ptr(transaction& tx, tx_ptr<T> ptr);
- template <typename T>
- rd_ptr<T> make_rd_ptr(transaction& tx, tx_obj<T> const & ref);
-
- template <typename T>
- rd_ptr<T> make_rd_ptr(tx_ptr<T> ptr);
- template <typename T>
- rd_ptr<T> make_rd_ptr(tx_obj<T> const & ref);
- template <typename T>
- void delete_ptr(rd_ptr<T> ptr);
- template <typename T>
- void delete_ptr(transaction& tx, rd_ptr<T> ptr);
-
- template <typename T> class upgrd_ptr;
- template <typename T>
- void delete_ptr(upgrd_ptr<T> const& ptr);
- template <typename T>
- void delete_ptr(transaction& tx, upgrd_ptr<T> const& ptr);
-
- template <typename T> class wr_ptr;
- template <typename T>
- wr_ptr<T> make_wr_ptr(transaction& tx, tx_ptr<T>& ptr);
- template <typename T>
- wr_ptr<T> make_wr_ptr(tx_ptr<T>& ptr);
- template <typename T>
- void delete_ptr(wr_ptr<T> ptr);
- template <typename T>
- void delete_ptr(transaction& tx, wr_ptr<T> const& ptr);
-
 template <typename T> class read_ptr;
 template <typename T> class write_ptr;
}}
</pre>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
-<a name="toward_boost_stm.reference.tx_ptr_hpp.template_class__tx_obj___"></a><a class="link" href="tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__tx_obj___" title="Template Class tx_obj<>">Template
- Class <code class="computeroutput">tx_obj<></code></a>
-</h4></div></div></div>
-
- tx_obj is a kind of smart pointer to a wrapped transactional_object T providing
- builting operators
- 
-<pre class="programlisting">template <typename T> class tx_obj {
-public:
- tx_obj();
- template<ctypename Y> tx_obj(tx_obj<Y> const& r);
-
- template <typename T1> tx_obj(T1 p1);
-
- T* operator->();
- const T* operator->() const;
- T& operator*();
- const T& operator*() const;
- T* get();
- const T* get() const;
- T& ref();
- const T& ref() const;
-
- tx_obj& operator--();
- T operator--(int);
-
- tx_obj& operator++();
- T operator++(int);
-
- tx_obj& operator+=(T const &rhs);
- T operator+(T const &rhs) const;
-};
-</pre>
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="toward_boost_stm.reference.tx_ptr_hpp.template_class__tx_ptr___"></a><a class="link" href="tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__tx_ptr___" title="Template Class tx_ptr<>">Template
- Class <code class="computeroutput">tx_ptr<></code></a>
-</h4></div></div></div>
-
- a tx_ptr<T> is an smart pointer to a transactional_object<T>
- (which contains an instance of T). Reference fields in linked structures
- should always be tx_ptrs. The result of derreferencing it will be the pointer
- to the T instance When this pointer is derreference on a transaction the
- transactional_object<T> is set a written and the transaction specific
- storage will be used. Otherwise the shared storage is used.
- 
-
- Used to initialize a rd_ptr<T>, wr_ptr<T>, or upgrd_ptr<T>.
- 
-<pre class="programlisting">template <typename T>
-class tx_ptr {
-public:
- typedef tx_ptr<T> this_type;
-
- tx_ptr();
- template<class Y> explicit tx_ptr(Y * ptr);
- explicit tx_ptr(transactional_object<T>* ptr);
- tx_ptr(const tx_obj<T>& r);
-
- template<class Y> tx_ptr(tx_ptr<Y> const& r);
- template<class Y> tx_ptr(rd_ptr<Y> const & r);
- template<class Y> tx_ptr(wr_ptr<Y> const & r);
- template<class Y> tx_ptr(upgrd_ptr<Y> const & r);
-
- template<class Y> tx_ptr& operator=(transactional_object<Y>* ptr);
- template<class Y> tx_ptr & operator=(tx_ptr<Y> const & r);
-
- T* operator->() const;
- T& operator*() const;
- T* get() const;
-
- typedef transactional_object<T>* this_type::*unspecified_bool_type;
-
- operator unspecified_bool_type() const;
- void swap(tx_ptr & other);
-};
-</pre>
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="toward_boost_stm.reference.tx_ptr_hpp.template_class__rd_ptr___"></a><a class="link" href="tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__rd_ptr___" title="Template Class rd_ptr<>">Template
- Class <code class="computeroutput">rd_ptr<></code></a>
-</h4></div></div></div>
-
- A rd_ptr<T> ("read pointer") points to an object that the
- current transaction has opened for read only access. You can only call
- a const method through a read pointer.
- 
-
- A rd_ptr<T> is constructed from an tx_ptr<T> through an explicit
- constructor. Once a rd_ptr<T> has been constructed, an tx_ptr<T>
- can be opened for reading simply by assignment (operator=()) into the constructed
- rd_ptr<T>.
- 
-
- It is not safe to derreference a rd_ptr<T> after having assigned
- the same tx_ptr<T> to a wr_ptr<T>. If this is the case the
- readen value do not match the writen one. If it is possible to write on
- the same transaction use upgrd_ptr instead which is safe.
- 
-<pre class="programlisting">template <typename T>
-class rd_ptr {
-public:
- rd_ptr(transaction &t, tx_ptr<T> tx_obj);
- rd_ptr(transaction &t, tx_obj<T> const& tx_obj);
-
- template<class Y> rd_ptr & operator=(tx_ptr<Y> r);
-
- template<class Y> rd_ptr& operator=(tx_obj<Y> const & r);
-
- const T* get() const;
-
- inline const T & operator*() const;
- inline const T* operator->() const;
-
- operator unspecified_bool_type() const;
-
-};
-</pre>
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="toward_boost_stm.reference.tx_ptr_hpp.template_class__upgrd_ptr___"></a><a class="link" href="tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__upgrd_ptr___" title="Template Class upgrd_ptr<>">Template
- Class <code class="computeroutput">upgrd_ptr<></code></a>
-</h4></div></div></div>
-
- A upgrd_ptr<T> ("upgradable pointer") points to an object
- that the current transaction has opened for read only access.
- 
-
- You can only call const method of the wrapped type through a upgradable
- pointer.
- 
-
- A upgrd_ptr<T> is constructed from an tx_ptr<T> through a constructor
- having also the transaction as parameter. Once a rd_ptr<T> has been
- constructed, an tx_ptr<T> can be opened for reading simply by assignment
- (operator=()) into the constructed rd_ptr<T>.
- 
-
- It is safe to derreference a rd_ptr<T> after having assigned the
- same tx_ptr<T> to a wr_ptr<T>.
- 
-
- A upgrd_ptr<T> can be upgraded to a wr_ptr<T> through a constructor.
- 
-<pre class="programlisting">template <typename T>
-class upgrd_ptr {
-public:
-
- inline upgrd_ptr(transaction &t, tx_ptr<T> tx_obj);
- template<class Y>
- upgrd_ptr & operator=(tx_ptr<Y> const& r);
-
- const T* get() const;
-
- inline T const & operator*() const;
- inline T const * operator->() const;
-
- operator unspecified_bool_type() const;
-
- void write_ptr(transactional_object<T>* ptr);
- T* write_ptr();
-
-};
-</pre>
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
-<a name="toward_boost_stm.reference.tx_ptr_hpp.template_class__wr_ptr___"></a><a class="link" href="tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__wr_ptr___" title="Template Class wr_ptr<>">Template
- Class <code class="computeroutput">wr_ptr<></code></a>
-</h4></div></div></div>
-
- A wr_ptr<T> ("write pointer") points to a shared object
- that the current transaction has opened for writing.
- 
-
- A wr_ptr<T> is initialized explicitly from an tx_ptr<T>.
- 
-
- A wr_ptr<T> can also be explicitly constructed from a upgrd_ptr<T>
- as an upgrade-to-writable operation.
- 
-<pre class="programlisting">template <typename T>
-class wr_ptr {
-public:
- wr_ptr(transaction &t, tx_ptr<T> tx_obj);
-
- wr_ptr(transaction &t, upgrd_ptr<T> tx_obj);
-
- T* get();
-
- inline T& operator*();
- inline T* operator->();
-
- operator unspecified_bool_type() const;
-};
-</pre>
-</div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h4 class="title">
<a name="toward_boost_stm.reference.tx_ptr_hpp.template_class__read_ptr___"></a><a class="link" href="tx_ptr_hpp.html#toward_boost_stm.reference.tx_ptr_hpp.template_class__read_ptr___" title="Template Class read_ptr<>">Template
 Class <code class="computeroutput">read_ptr<></code></a>
</h4></div></div></div>
@@ -353,7 +79,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="transaction_object_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="base_contention_manager_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+<a accesskey="p" href="transactional_object_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="tx_smart_ptr_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>

Added: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/tx_smart_ptr_hpp.html
==============================================================================
--- (empty file)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/reference/tx_smart_ptr_hpp.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -0,0 +1,322 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Header <boost/stm/tx_smart_ptr.hpp></title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
+<link rel="start" href="../../index.html" title="Chapter 1. Toward.Boost.STM">
+<link rel="up" href="../reference.html" title="Reference">
+<link rel="prev" href="tx_ptr_hpp.html" title="Header <boost/stm/tx_ptr.hpp>">
+<link rel="next" href="non_tx_smart_ptr_hpp.html" title="Header <boost/stm/non_tx_smart_ptr.hpp>">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="TowardBoostSTM" width="277" height="86" src="../../../image/Toward_Boost_STM.jpg"></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="tx_ptr_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="non_tx_smart_ptr_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="toward_boost_stm.reference.tx_smart_ptr_hpp"></a><a class="link" href="tx_smart_ptr_hpp.html" title="Header <boost/stm/tx_smart_ptr.hpp>"> Header
+ <code class="computeroutput"><boost/stm/tx_smart_ptr.hpp></code></a>
+</h3></div></div></div>
+<div class="toc"><dl>
+<dt><a href="tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__tx_obj___">Template
+ Class <code class="computeroutput">tx_obj<></code></a></dt>
+<dt><a href="tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__tx_ptr___">Template
+ Class <code class="computeroutput">tx_ptr<></code></a></dt>
+<dt><a href="tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__rd_ptr___">Template
+ Class <code class="computeroutput">rd_ptr<></code></a></dt>
+<dt><a href="tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__upgrd_ptr___">Template
+ Class <code class="computeroutput">upgrd_ptr<></code></a></dt>
+<dt><a href="tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__wr_ptr___">Template
+ Class <code class="computeroutput">wr_ptr<></code></a></dt>
+</dl></div>
+<pre class="programlisting">namespace boost { namespace stm {
+
+ template <typename T> class tx_obj;
+ template <typename T, typename U>
+ bool operator==(const tx_obj<T>& lhs, const tx_obj<U>& rhs);
+ template <typename T, typename U>
+ bool operator==(const T& lhs, const tx_obj<U>& rhs);
+ template <typename T, typename U>
+ bool operator==(const tx_obj<T>& lhs, const U& rhs);
+ template <typename T, typename U>
+ bool operator!=(const tx_obj<T>& lhs, const tx_obj<U>& rhs);
+ template <typename T, typename U>
+ bool operator!=(const tx_obj<T>& lhs, const tx_obj<U>& rhs);
+ template<class T> inline void swap(tx_obj<T> & a, tx_obj<T> & b);
+
+ template <typename T> class tx_ptr;
+ template <typename T, typename U>
+ bool operator==(const tx_ptr<T>& lhs, const tx_ptr<U>& rhs);
+ template <typename T, typename U>
+ bool operator!=(const tx_ptr<T>& lhs, const tx_ptr<U>& rhs);
+ template<class T> inline void swap(tx_ptr<T> & a, tx_ptr<T> & b);
+
+ template <typename T>
+ void delete_ptr(tx_ptr<T> ptr);
+ template <typename T>
+ void delete_ptr(transaction& tx, tx_ptr<T> ptr);
+
+ template <typename T, typename U>
+ static tx_ptr<T> tx_static_cast(tx_ptr<U> ptr);
+ template <typename T, typename U>
+ static tx_ptr<T>* tx_dynamic_cast(tx_ptr<U> ptr);
+
+ template <typename T> class rd_ptr;
+ template <typename T>
+ rd_ptr<T> make_rd_ptr(transaction& tx, tx_ptr<T> ptr);
+ template <typename T>
+ rd_ptr<T> make_rd_ptr(transaction& tx, tx_obj<T> const & ref);
+
+ template <typename T>
+ rd_ptr<T> make_rd_ptr(tx_ptr<T> ptr);
+ template <typename T>
+ rd_ptr<T> make_rd_ptr(tx_obj<T> const & ref);
+ template <typename T>
+ void delete_ptr(rd_ptr<T> ptr);
+ template <typename T>
+ void delete_ptr(transaction& tx, rd_ptr<T> ptr);
+
+ template <typename T> class upgrd_ptr;
+ template <typename T>
+ void delete_ptr(upgrd_ptr<T> const& ptr);
+ template <typename T>
+ void delete_ptr(transaction& tx, upgrd_ptr<T> const& ptr);
+
+ template <typename T> class wr_ptr;
+ template <typename T>
+ wr_ptr<T> make_wr_ptr(transaction& tx, tx_ptr<T>& ptr);
+ template <typename T>
+ wr_ptr<T> make_wr_ptr(tx_ptr<T>& ptr);
+ template <typename T>
+ void delete_ptr(wr_ptr<T> ptr);
+ template <typename T>
+ void delete_ptr(transaction& tx, wr_ptr<T> const& ptr);
+}}
+</pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__tx_obj___"></a><a class="link" href="tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__tx_obj___" title="Template Class tx_obj<>">Template
+ Class <code class="computeroutput">tx_obj<></code></a>
+</h4></div></div></div>
+
+ tx_obj is a kind of smart pointer to a wrapped transactional_object T providing
+ builting operators
+ 
+<pre class="programlisting">template <typename T> class tx_obj {
+public:
+ tx_obj();
+ template<ctypename Y> tx_obj(tx_obj<Y> const& r);
+
+ template <typename T1> tx_obj(T1 p1);
+
+ T* operator->();
+ const T* operator->() const;
+ T& operator*();
+ const T& operator*() const;
+ T* get();
+ const T* get() const;
+ T& ref();
+ const T& ref() const;
+
+ tx_obj& operator--();
+ T operator--(int);
+
+ tx_obj& operator++();
+ T operator++(int);
+
+ tx_obj& operator+=(T const &rhs);
+ T operator+(T const &rhs) const;
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__tx_ptr___"></a><a class="link" href="tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__tx_ptr___" title="Template Class tx_ptr<>">Template
+ Class <code class="computeroutput">tx_ptr<></code></a>
+</h4></div></div></div>
+
+ a tx_ptr<T> is an smart pointer to a transactional_object<T>
+ (which contains an instance of T). Reference fields in linked structures
+ should always be tx_ptrs. The result of derreferencing it will be the pointer
+ to the T instance When this pointer is derreference on a transaction the
+ transactional_object<T> is set a written and the transaction specific
+ storage will be used. Otherwise the shared storage is used.
+ 
+
+ Used to initialize a rd_ptr<T>, wr_ptr<T>, or upgrd_ptr<T>.
+ 
+<pre class="programlisting">template <typename T>
+class tx_ptr {
+public:
+ typedef tx_ptr<T> this_type;
+
+ tx_ptr();
+ template<class Y> explicit tx_ptr(Y * ptr);
+ explicit tx_ptr(transactional_object<T>* ptr);
+ tx_ptr(const tx_obj<T>& r);
+
+ template<class Y> tx_ptr(tx_ptr<Y> const& r);
+ template<class Y> tx_ptr(rd_ptr<Y> const & r);
+ template<class Y> tx_ptr(wr_ptr<Y> const & r);
+ template<class Y> tx_ptr(upgrd_ptr<Y> const & r);
+
+ template<class Y> tx_ptr& operator=(transactional_object<Y>* ptr);
+ template<class Y> tx_ptr & operator=(tx_ptr<Y> const & r);
+
+ T* operator->() const;
+ T& operator*() const;
+ T* get() const;
+
+ typedef transactional_object<T>* this_type::*unspecified_bool_type;
+
+ operator unspecified_bool_type() const;
+ void swap(tx_ptr & other);
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__rd_ptr___"></a><a class="link" href="tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__rd_ptr___" title="Template Class rd_ptr<>">Template
+ Class <code class="computeroutput">rd_ptr<></code></a>
+</h4></div></div></div>
+
+ A rd_ptr<T> ("read pointer") points to an object that the
+ current transaction has opened for read only access. You can only call
+ a const method through a read pointer.
+ 
+
+ A rd_ptr<T> is constructed from an tx_ptr<T> through an explicit
+ constructor. Once a rd_ptr<T> has been constructed, an tx_ptr<T>
+ can be opened for reading simply by assignment (operator=()) into the constructed
+ rd_ptr<T>.
+ 
+
+ It is not safe to derreference a rd_ptr<T> after having assigned
+ the same tx_ptr<T> to a wr_ptr<T>. If this is the case the
+ readen value do not match the writen one. If it is possible to write on
+ the same transaction use upgrd_ptr instead which is safe.
+ 
+<pre class="programlisting">template <typename T>
+class rd_ptr {
+public:
+ rd_ptr(transaction &t, tx_ptr<T> tx_obj);
+ rd_ptr(transaction &t, tx_obj<T> const& tx_obj);
+
+ template<class Y> rd_ptr & operator=(tx_ptr<Y> r);
+
+ template<class Y> rd_ptr& operator=(tx_obj<Y> const & r);
+
+ const T* get() const;
+
+ inline const T & operator*() const;
+ inline const T* operator->() const;
+
+ operator unspecified_bool_type() const;
+
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__upgrd_ptr___"></a><a class="link" href="tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__upgrd_ptr___" title="Template Class upgrd_ptr<>">Template
+ Class <code class="computeroutput">upgrd_ptr<></code></a>
+</h4></div></div></div>
+
+ A upgrd_ptr<T> ("upgradable pointer") points to an object
+ that the current transaction has opened for read only access.
+ 
+
+ You can only call const method of the wrapped type through a upgradable
+ pointer.
+ 
+
+ A upgrd_ptr<T> is constructed from an tx_ptr<T> through a constructor
+ having also the transaction as parameter. Once a rd_ptr<T> has been
+ constructed, an tx_ptr<T> can be opened for reading simply by assignment
+ (operator=()) into the constructed rd_ptr<T>.
+ 
+
+ It is safe to derreference a rd_ptr<T> after having assigned the
+ same tx_ptr<T> to a wr_ptr<T>.
+ 
+
+ A upgrd_ptr<T> can be upgraded to a wr_ptr<T> through a constructor.
+ 
+<pre class="programlisting">template <typename T>
+class upgrd_ptr {
+public:
+
+ inline upgrd_ptr(transaction &t, tx_ptr<T> tx_obj);
+ template<class Y>
+ upgrd_ptr & operator=(tx_ptr<Y> const& r);
+
+ const T* get() const;
+
+ inline T const & operator*() const;
+ inline T const * operator->() const;
+
+ operator unspecified_bool_type() const;
+
+ void write_ptr(transactional_object<T>* ptr);
+ T* write_ptr();
+
+};
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__wr_ptr___"></a><a class="link" href="tx_smart_ptr_hpp.html#toward_boost_stm.reference.tx_smart_ptr_hpp.template_class__wr_ptr___" title="Template Class wr_ptr<>">Template
+ Class <code class="computeroutput">wr_ptr<></code></a>
+</h4></div></div></div>
+
+ A wr_ptr<T> ("write pointer") points to a shared object
+ that the current transaction has opened for writing.
+ 
+
+ A wr_ptr<T> is initialized explicitly from an tx_ptr<T>.
+ 
+
+ A wr_ptr<T> can also be explicitly constructed from a upgrd_ptr<T>
+ as an upgrade-to-writable operation.
+ 
+<pre class="programlisting">template <typename T>
+class wr_ptr {
+public:
+ wr_ptr(transaction &t, tx_ptr<T> tx_obj);
+
+ wr_ptr(transaction &t, upgrd_ptr<T> tx_obj);
+
+ T* get();
+
+ inline T& operator*();
+ inline T* operator->();
+
+ operator unspecified_bool_type() const;
+};
+</pre>
+</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 © 2009 Justin E. Gottchlich Copyright © 2009 Vicente J. Botet Escriba
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="tx_ptr_hpp.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="non_tx_smart_ptr_hpp.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -43,7 +43,15 @@
 Composable Transaction</a></dt>
<dt><a href="users_guide/tutorial.html#toward_boost_stm.users_guide.tutorial.a_dynamically_prioritized__composed_transaction">A
 Dynamically Prioritized, Composed Transaction</a></dt>
+<dt><a href="users_guide/tutorial.html#toward_boost_stm.users_guide.tutorial.can_a_transactional_object_embeed_another_transactional_object_">Can
+ a transactional object embeed another transactional object?</a></dt>
+<dt><a href="users_guide/tutorial.html#toward_boost_stm.users_guide.tutorial.returning_values_from_a_fucntion">Returning
+ values from a fucntion</a></dt>
+<dt><a href="users_guide/tutorial.html#toward_boost_stm.users_guide.tutorial.pointer_to_transactional_objects">Pointer
+ to transactional objects</a></dt>
<dt>Polymorphic</dt>
+<dt><a href="users_guide/tutorial.html#toward_boost_stm.users_guide.tutorial.can_non_transactional_objets_participate_in_a_transaction_">Can
+ non transactional objets participate in a transaction?</a></dt>
<dt><a href="users_guide/tutorial.html#toward_boost_stm.users_guide.tutorial.lock_aware">Lock
 aware</a></dt>
</dl></dd>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/ext_references.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/ext_references.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/ext_references.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -27,6 +27,20 @@
<a name="toward_boost_stm.users_guide.ext_references"></a><a class="link" href="ext_references.html" title="References"> References</a>
</h3></div></div></div>

+ For an introduction to TM, please refer to
+ 
+<div class="variablelist">
+
+<dl>
+<dt> Shifting the Parallel Programming Paradigm</dt>
+<dd>
+ Justin E. Gottschlich, Dwight Y. Winkler, Mark W. Holmes, Jeremy G. Siek,
+ and Manish Vachharajani - Raytheon Information Systems and
+ Computing Symposium (ISaCTN), March 2009
+ </dd>
+</dl>
+</div>
+
 For details on the underlying software architecture of TBoost.STM, including
 explanations of its API, please refer to our summary paper.
 
@@ -77,9 +91,10 @@
<div class="variablelist">

<dl>
-<dt> Lock-Aware Transactional Memory and Composable Locks</dt>
+<dt> An Intentional Library Approach to Lock-Aware Transactional Memory</dt>
<dd>
- Justin E. Gottschlich, Daniel A. Connors and Jeremy G. Siek -
+ Justin E. Gottschlich, Daniel A. Connors, Dwight Y. Winkler, Jeremy G.
+ Siek and Manish Vachharajani -
 </dd>
</dl>
</div>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/getting_started.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/getting_started.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/getting_started.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -61,7 +61,7 @@
 memory!
 
<a name="toward_boost_stm.users_guide.getting_started.install.getting_boost_stm"></a><h6>
-<a name="id4849300"></a>
+<a name="id4860391"></a>
 <a class="link" href="getting_started.html#toward_boost_stm.users_guide.getting_started.install.getting_boost_stm">Getting
 Boost.STM</a>
 </h6>
@@ -78,7 +78,7 @@
 Sandbox</a>.
 
<a name="toward_boost_stm.users_guide.getting_started.install.building_boost_stm"></a><h6>
-<a name="id4849354"></a>
+<a name="id4860444"></a>
 <a class="link" href="getting_started.html#toward_boost_stm.users_guide.getting_started.install.building_boost_stm">Building
 Boost.STM</a>
 </h6>
@@ -90,7 +90,7 @@
bjam
</pre>
<a name="toward_boost_stm.users_guide.getting_started.install.requirements"></a><h6>
-<a name="id4849418"></a>
+<a name="id4860506"></a>
 <a class="link" href="getting_started.html#toward_boost_stm.users_guide.getting_started.install.requirements">Requirements</a>
 </h6>

@@ -161,7 +161,7 @@
</dl>
</div>
<a name="toward_boost_stm.users_guide.getting_started.install.exceptions_safety"></a><h6>
-<a name="id4849670"></a>
+<a name="id4860771"></a>
 <a class="link" href="getting_started.html#toward_boost_stm.users_guide.getting_started.install.exceptions_safety">Exceptions
 safety</a>
 </h6>
@@ -170,7 +170,7 @@
 of exception safety as long as the underlying parameters provide it.
 
<a name="toward_boost_stm.users_guide.getting_started.install.thread_safety"></a><h6>
-<a name="id4849696"></a>
+<a name="id4860797"></a>
 <a class="link" href="getting_started.html#toward_boost_stm.users_guide.getting_started.install.thread_safety">Thread
 safety</a>
 </h6>
@@ -178,7 +178,7 @@
 All functions in the library are thread-unsafe except when noted explicitly.
 
<a name="toward_boost_stm.users_guide.getting_started.install.tested_compilers"></a><h6>
-<a name="id4849723"></a>
+<a name="id4860822"></a>
 <a class="link" href="getting_started.html#toward_boost_stm.users_guide.getting_started.install.tested_compilers">Tested
 compilers</a>
 </h6>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/glosary.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/glosary.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/glosary.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -39,33 +39,29 @@
 </dd>
<dt>LiT</dt>
<dd>
- Lock in transaction
+ Lock inside Transactions
 </dd>
<dt>LoT</dt>
<dd>
- Lock out of transaction
+ Lock outside Transactions
 </dd>
<dt>STM</dt>
<dd>
 Software Transaction Memory
 </dd>
-<dt>TX</dt>
-<dd>
- Transaction
- </dd>
<dt>TM</dt>
<dd>
 Transaction Memory
 </dd>
-<dt>in fligh transaction</dt>
+<dt>TX</dt>
<dd>
- .
+ Transaction
 </dd>
-<dt>Conflict Detection</dt>
+<dt>abort</dt>
<dd>
 .
 </dd>
-<dt>abort</dt>
+<dt>Conflict Detection</dt>
<dd>
 .
 </dd>
@@ -77,23 +73,27 @@
<dd>
 .
 </dd>
+<dt>Deferred Updating</dt>
+<dd>
+ .
+ </dd>
<dt>Direct Updating</dt>
<dd>
 .
 </dd>
-<dt>Deferred Updating</dt>
+<dt>Full-Lock protection</dt>
<dd>
 .
 </dd>
-<dt>Irrevocable transaction</dt>
+<dt>In fligh transaction</dt>
<dd>
 .
 </dd>
-<dt>Isolated transaction</dt>
+<dt>Irrevocable transaction</dt>
<dd>
 .
 </dd>
-<dt>Full-Lock protection</dt>
+<dt>Isolated transaction</dt>
<dd>
 .
 </dd>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/tutorial.html
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/tutorial.html (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/tutorial.html 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -33,7 +33,15 @@
 Composable Transaction</a></dt>
<dt><a href="tutorial.html#toward_boost_stm.users_guide.tutorial.a_dynamically_prioritized__composed_transaction">A
 Dynamically Prioritized, Composed Transaction</a></dt>
+<dt><a href="tutorial.html#toward_boost_stm.users_guide.tutorial.can_a_transactional_object_embeed_another_transactional_object_">Can
+ a transactional object embeed another transactional object?</a></dt>
+<dt><a href="tutorial.html#toward_boost_stm.users_guide.tutorial.returning_values_from_a_fucntion">Returning
+ values from a fucntion</a></dt>
+<dt><a href="tutorial.html#toward_boost_stm.users_guide.tutorial.pointer_to_transactional_objects">Pointer
+ to transactional objects</a></dt>
<dt>Polymorphic</dt>
+<dt><a href="tutorial.html#toward_boost_stm.users_guide.tutorial.can_non_transactional_objets_participate_in_a_transaction_">Can
+ non transactional objets participate in a transaction?</a></dt>
<dt><a href="tutorial.html#toward_boost_stm.users_guide.tutorial.lock_aware">Lock
 aware</a></dt>
</dl></div>
@@ -71,7 +79,7 @@
 calls.
 
<a name="toward_boost_stm.users_guide.tutorial.a_simple_transaction.client_invoked_inserts"></a><h6>
-<a name="id4803999"></a>
+<a name="id4861141"></a>
 <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.a_simple_transaction.client_invoked_inserts">Client
 Invoked Inserts</a>
 </h6>
@@ -94,7 +102,7 @@
 of TM solutions into algorithms of new and legacy systems.
 
<a name="toward_boost_stm.users_guide.tutorial.a_simple_transaction.linked_list_declaration"></a><h6>
-<a name="id4804232"></a>
+<a name="id4861371"></a>
 <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.a_simple_transaction.linked_list_declaration">Linked
 list declaration</a>
 </h6>
@@ -116,7 +124,7 @@
};
</pre>
<a name="toward_boost_stm.users_guide.tutorial.a_simple_transaction.insert_retry_transaction"></a><h6>
-<a name="id4804476"></a>
+<a name="id4861593"></a>
 <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.a_simple_transaction.insert_retry_transaction">Insert
 retry transaction</a>
 </h6>
@@ -147,7 +155,7 @@
 with its absorption of aborted transactions and only aborted transactions.
 
<a name="toward_boost_stm.users_guide.tutorial.a_simple_transaction.insert_specific"></a><h6>
-<a name="id4804764"></a>
+<a name="id4861843"></a>
 <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.a_simple_transaction.insert_specific">Insert
 specific</a>
 </h6>
@@ -403,14 +411,12 @@
 to abort the second transaction, the method returns true and the second
 transaction is aborted. If permission is not granted to abort the second
 transaction, the method returns false and upon returning the committing
- transaction aborts itself. All consistency checking for
- 
-
- deferred updating is performed prior to any updating operation and thus
- memory is still in a completely legal uncommitted state until all consistency
- is performed. For direct updating aborts, the system simply follows its
- normal semantics of aborting the transaction by restoring global memory
- to its original state. Similar to the prior example, overriding the permission_to_abort()
+ transaction aborts itself. All consistency checking for deferred updating
+ is performed prior to any updating operation and thus memory is still in
+ a completely legal uncommitted state until all consistency is performed.
+ For direct updating aborts, the system simply follows its normal semantics
+ of aborting the transaction by restoring global memory to its original
+ state. Similar to the prior example, overriding the permission_to_abort()
 method can be done in such a manner which prevents lower priority transaction
 from aborting a higher priority transaction as shown below:
 
@@ -473,8 +479,8 @@
 try {
 internal_insert(node, success);
 s = t.end_transaction();
- } catch (aborted_transaction_exception&) {
- t.restart_transaction();
+ } catch (aborted_transaction_exception&) {
+ t.restart_transaction();
 }
 if (!success) return false; // on list
 }
@@ -551,9 +557,11 @@
 }
}
</pre>
-
- Priority Inversion Allowed.
- 
+<a name="toward_boost_stm.users_guide.tutorial.a_dynamically_prioritized__composed_transaction.priority_inversion_allowed"></a><h6>
+<a name="id4866234"></a>
+ <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.a_dynamically_prioritized__composed_transaction.priority_inversion_allowed">Priority
+ Inversion Allowed</a>
+ </h6>

 From the above code examples, one may question why the default behavior
 implemented within TBoost.STM does not automatically integrate priority
@@ -577,9 +585,11 @@
 able to more correctly implement the right contention manager for their
 specific needs.
 
-
- The Future of Parallel Programming.
- 
+<a name="toward_boost_stm.users_guide.tutorial.a_dynamically_prioritized__composed_transaction.the_future_of_parallel_programming"></a><h6>
+<a name="id4866316"></a>
+ <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.a_dynamically_prioritized__composed_transaction.the_future_of_parallel_programming">The
+ Future of Parallel Programming</a>
+ </h6>

 An important distinction regarding priority within transactions versus
 priority within more classical synchronization mechanisms, like locks,
@@ -600,9 +610,259 @@
 memory.
 
</div>
-<div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title">
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.users_guide.tutorial.can_a_transactional_object_embeed_another_transactional_object_"></a><a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.can_a_transactional_object_embeed_another_transactional_object_" title="Can a transactional object embeed another transactional object?">Can
+ a transactional object embeed another transactional object?</a>
+</h4></div></div></div>
+
+ Let me show what happens when we emmend transactional objects: class C
+ : public transaction_object<C> {...};
+ 
+<pre class="programlisting">class E : public transaction_object<E> {
+ C c;
+ int i;
+};
+</pre>
+
+ E e;
+ 
+
+ When a thread T1 modifies e (and possibly the b part) on a transaction
+ another thread T2 can modify e.c on another transaction. When the two transactional
+ objects overlap the STM system is unable to detect this efficiently, having
+ as consequence an inconsistency.
+ 
+
+ The following pseudo-code shows the
+ 
+<pre class="programlisting"> T1 T2
+1 atomic { atomic {
+2 e.i=0; e.c=A;
+3 }
+4 }
+</pre>
+
+ When T2 commits on (3) e.c will be modified, but T1 will modify the complete
+ E independent of the e.c modification doen by T2, overwriting the e.c with
+ its old value. T1 will be coherent, but not T2. If we want to allow such
+ a scheme, we have several possibilities
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ implicit: take care of overlaping transactional objects, so we can detect
+ when T1 commits that an overlaping TO e.c has been modified, so the transaction
+ on T1 is aborted and retried.
+ </li>
+<li>
+ explicit: the developper of T1 must notify the STM system that the transactional
+ object e constains a transactional object e.c
+ </li>
+<li>
+ declarative: the developper of E would declare that it contains an emmbeed
+ transactional object C at E::c, so the STM system will use this explicit
+ information when an E is accesses using the STM interface.
+ </li>
+</ul></div>
+
+ The implicit approach is the more transparent for the user but it is also
+ the less efficient. It need to add a virtual function quering the size
+ of the class, and to modify the conflic detection algorithm (maybe the
+ write_list must be a write_set, ordered by the address)
+ 
+
+ The explit approach let the user with a lot of burden and risk of error
+ when access to an E is done on a transaction. This needs to add the size
+ and the algorithm which adds transactional object on the write_list (maybe
+ the write_list must be a write_interval_set, ordered by the address).
+ 
+
+ The declarative concentrate on a single place, so the user will be not
+ too concerned, and this open possible optimizations.
+ 
+
+ Supose now that we are able to embeed transactional objects. and that the
+ T1 not only opens for writing e, but also e.c either on the same block
+ on on a block (or nested transaction). The STM will see both address to
+ be written, and even if there should be no risk of incoherence the object
+ e.c will be copied twice.
+ 
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.users_guide.tutorial.returning_values_from_a_fucntion"></a><a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.returning_values_from_a_fucntion" title="Returning values from a fucntion">Returning
+ values from a fucntion</a>
+</h4></div></div></div>
+<a name="toward_boost_stm.users_guide.tutorial.returning_values_from_a_fucntion.returning_from_outside_the_transaction_context"></a><h6>
+<a name="id4866697"></a>
+ <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.returning_values_from_a_fucntion.returning_from_outside_the_transaction_context">Returning
+ from outside the transaction context</a>
+ </h6>
+
+ The simgle way consists is using a local variable declared outside the
+ transaction context.
+ 
+<pre class="programlisting">int inc_c() {
+ int res;
+ atomic(_) {
+ res = *(_.read(c))+i;
+ } end_atom;
+ return res;
+}
+</pre>
+<a name="toward_boost_stm.users_guide.tutorial.returning_values_from_a_fucntion.returning_from_inside"></a><h6>
+<a name="id4866874"></a>
+ <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.returning_values_from_a_fucntion.returning_from_inside">Returning
+ from inside</a>
+ </h6>
+
+ The following attempt does not work as the transaction will not be commited.
+ 
+<pre class="programlisting">int inc_c(int i) {
+ atomic(_) {
+ write_ptr<tx_int> tx_c(_,c);
+ return *(tx_c)+=i;
+ } end_atom;
+}
+</pre>
+
+ We need to commit before returning. SO we will need any way a local variable
+ storing the result before commiting.
+ 
+<pre class="programlisting">int inc_c(int i) {
+ atomic(_) {
+ write_ptr<tx_int> tx_c(_,c);
+ int res = *(tx_c)+=i;
+ _.commit();
+ return res;
+ } end_atom;
+}
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.users_guide.tutorial.pointer_to_transactional_objects"></a><a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.pointer_to_transactional_objects" title="Pointer to transactional objects">Pointer
+ to transactional objects</a>
+</h4></div></div></div>
+
+ Access to a pointer to a transaction object works, but this do not take
+ care of modifications of the pointer itself.
+ 
+<a name="toward_boost_stm.users_guide.tutorial.pointer_to_transactional_objects.using_the_mixin_transaction_object_lt__gt_"></a><h6>
+<a name="id4867276"></a>
+ <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.pointer_to_transactional_objects.using_the_mixin_transaction_object_lt__gt_">Using
+ the mixin transaction_object<></a>
+ </h6>
+
+ Let B the TO made using the mixin transaction_object.
+ 
+<pre class="programlisting">class B : public transaction_object<B> {
+public:
+ void virtaul fct();
+};
+</pre>
+
+ How a variable pointing to B must be declared. The fact that B is a transactional
+ object do not means that a pointer to it is one. We need a class that wraps
+ the pointer
+ 
+<pre class="programlisting">template <typename TO>
+class transaction_object_ptr : public transaction_object<transaction_object_ptr<TO> > {
+public:
+ TO* ptr_;
+ typedef transaction_object_ptr<TO> this_type;
+ typedef transaction_object<transaction_object_ptr<TO> > base_type;
+ transaction_object_ptr() : base_type(), ptr_(0) {
+ }
+ transaction_object_ptr(const transaction_object_ptr & rhs) : base_type(rhs), ptr_(rhs.ptr_) {
+ }
+ transaction_object_ptr(transaction_object_ptr & rhs) : base_type(rhs), ptr_(rhs.rhs) {
+ }
+ transaction_object_ptr(TO* ptr) : base_type(), ptr_(ptr) {
+ }
+ ~transaction_object_ptr() {
+ }
+ this_type& operator=(TO* rhs) {
+ ptr_=rhs;
+ return *this;
+ }
+
+ TO* get() const {
+ std::cout << "get" << std::endl;
+ return ptr_;
+ }
+
+ inline TO& operator*() const { return *get(); }
+ inline TO* operator->() const { return get(); }
+};
+</pre>
+
+ Let declare a pointer to B
+ 
+<pre class="programlisting">transaction_object_ptr<B> ptr_b;
+
+
+atomic(_) {
+ write_ptr< pointer<B> > tx_ptr_b_ptr(_, ptr_b);
+ *tx_ptr_b_ptr=BOOST_STM_NEW(_, B());
+}
+</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
<a name="toward_boost_stm.users_guide.tutorial.polymorphic"></a><a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.polymorphic" title="Polymorphic">Polymorphic</a>
-</h4></div></div></div></div>
+</h4></div></div></div>
+
+ How the user can defien a transactional class D inheriting from a transactional
+ class B
+ 
+<a name="toward_boost_stm.users_guide.tutorial.polymorphic.using_the_mixin_transaction_object_lt__gt_"></a><h6>
+<a name="id4868388"></a>
+ <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.polymorphic.using_the_mixin_transaction_object_lt__gt_">Using
+ the mixin transaction_object<></a>
+ </h6>
+
+ Let B the base class
+ 
+<pre class="programlisting">class B : public transaction_object<B> {
+public:
+ void virtaul fct();
+};
+</pre>
+
+ The derived class must declare D as follows:
+ 
+<pre class="programlisting">class D : public transaction_object<D,B> {
+ ...
+};
+</pre>
+
+ How a variable pointing to B must be declared. The fact that B is a transactional
+ object do not means that a pointer to it is one.
+ 
+<pre class="programlisting">pointer<B> ptr_b = 0
+</pre>
+
+ How can we assign a pointer to D?
+ 
+<pre class="programlisting">write_ptr<B*> tx_ptr_b_ptr(_,ptr_b);
+*ptr_b = BOOST_STM_NEW(_, D())
+</pre>
+<a name="toward_boost_stm.users_guide.tutorial.polymorphic.using_the_mixin_transaction_object_lt__gt_"></a><h6>
+<a name="id4868706"></a>
+ <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.polymorphic.using_the_mixin_transaction_object_lt__gt_">Using
+ the mixin transaction_object<></a>
+ </h6>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="toward_boost_stm.users_guide.tutorial.can_non_transactional_objets_participate_in_a_transaction_"></a><a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.can_non_transactional_objets_participate_in_a_transaction_" title="Can non transactional objets participate in a transaction?">Can
+ non transactional objets participate in a transaction?</a>
+</h4></div></div></div>
+
+ Non transactional objects are the objects that do not inherit from base_transaction_object.
+ 
+</div>
<div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title">
<a name="toward_boost_stm.users_guide.tutorial.lock_aware"></a><a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.lock_aware" title="Lock aware">Lock
 aware</a>

Modified: sandbox/stm/branches/vbe/libs/stm/doc/implementation.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/implementation.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/implementation.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,5 +1,5 @@
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
   (C) Copyright 2009 Vicente J. Botet Escriba
  /
  / Distributed under the Boost Software License, Version 1.0. (See accompanying
@@ -8,32 +8,34 @@

[section:implementation Appendix C: Implementation Notes]

-[section Why there is a `if (0 == rand()+1) {} else` preceding the for on the atomi macros?]
+[section Language-like macro blocks]

-The `if (0 == rand()+1) {} else` expression in the preprocessor atomic macros is used
-to prevent for loop errors in non-standard conforming C++ compilers.
-In these non-compliant compilers, automatic objects constructed
-as index variables for the for loop are leaked out beyond
-the scope of the for loop, incorrectly extending the liveness of
-these variables. In order to correct this behavior, the for loops that
-are not encapsulated within trys are wrapped within if statements.
-The if statements and for loops naturally nest without delineated
-scope (e.g., f, g) allowing programmers to execute single or multiple
-operations based on their preference.
-
-(0 == rand()+1) always returns false and cannot be
-optimized away by an optimizing compiler. By using an always
-false non-optimizable function inside an if statement, a variable
-scope is generated that guarantees automatic objects which are
-placed within these scopes are properly destroyed once the scope
-is exited. These scopes properly terminate variables which would
-otherwise be leaked in non-compliant for loop C++ compilers. The
-proper termination of automatic auto_locks and transactions
-is necessary to release acquired locks, terminate transactions and
-release transactional memory.
+Our language-like lock and transaction parallel constructs are implemented in __Boost_STM__ as automatic objects wrapped inside of preprocessor macros. Automatic objects are common in C++ and are helpful in ensuring correct lock and transaction behavior as they create deterministic termination points [5, 22]. These deterministic termination points are invoked when the scope containing the automatic object is exited, guaranteeing locks are released and transactions are terminated even in the event of uncaught exceptions. The preprocessor macros used for the locking and transaction constructs are shown in Figures 6 and 8, respectively.
+
+[heading Locking Macros]
+
+The lock macros use an unoptimized if statement to ensure the variables inside their local for loop are terminated for nonstandard conforming C++ compilers (more details to follow). Once the for loop is entered an auto_lock is constructed. Upon construction of the auto_lock, acquisition of the supplied lock is attempted if it has not already been acquired by the locking thread. For the use_lock macro, a blocking lock acquisition call is made which blocks forward progress until the lock is obtained. For the use_timed_lock and try_timed_lock calls, a non-blocking lock acquisition call is made which returns control to the calling thread via exception after MS milliseconds if the lock was not successfully obtained.
+
+The post_step() call within the lock macros releases any locks the auto_lock had acquired. The for loop conditional, done_post_step(), returns false until post_step() has been executed. This ensures the lock macro for loops are executed once and only once.
+
+[heading Transaction Macros]
+
+The preprocessor atomic macro for transactions is slightly more complex than the preprocessor locking macros. The additional complexity behind the atomic macro is needed to guarantee two fundamental goals. First, transactions must start and end correctly. Second, transactions must change their retry behavior based on whether they are a child or parent transaction to ensure proper closed nesting, flattened transaction behavior is performed.
+
+The atomic preprocessor behaves as follows. Like the lock macros, the atomic macro begins with an unoptimized if statement (details to follow). When the transactional for loop is entered, a transaction automatic object is constructed which initializes the transaction and puts it in-flight. The for loop conditional ensures the following conditions: (1) the transaction is uncommitted, (2) the transaction has the opportunity to throw an exception if necessary, and (3) the transaction is in-flight. Once a transaction commits, the check on (1) !T.committed() ensures the transaction is not executed again. If the transaction has been aborted but is a child transaction, the transaction must be restarted at the parent level. The call to (2) T.check_throw_before_restart() allows an aborted child transaction to throw an exception upward (before it is restarted) so the entire transaction can be restarted from the parent. The check_throw_before_restart() API checks the current run-time state of the thread to determine i
f another transaction is active above it. This behavior allows transactions to be used at any nesting level while dynamically ensuring the correct retry behavior. Finally, the call to restart_if_not_inflight() ensures the transaction is correctly restarted after each subsequent abort.
+
+Once all of the transactional operations within the for loop are executed, a call to no_throw_end() is made which ends the transaction. The no_throw_end() terminates the transaction by either committing or aborting it. Note, however, that no_throw_end() does not throw an exception if the transaction is aborted, whereas the prior __Boost_STM__ API end() does. This non-throwing behavior deviates from the prior __Boost_STM__ implementation of automatic objects when end() was invoked within the try / catch body. Furthermore, due to no_throw_end() not throwing an exception if the transaction is aborted, some cases may arise where catch_before_retry or before_retry operations are not invoked when a transaction is aborted. This is a current limitation of the system and is overcome by inserting a manual end() operation as the last operation in the atomic block. The explicit end() (Figure 14) ensures any operations within the before_retry block are executed if the transaction is aborted.
+
+
+[heading Correcting Non-Compliant Compilers]
+
+The `if (0 == rand()+1) {} else` expression in the preprocessor atomic macros is used to prevent for loop errors in non-standard conforming C++ compilers. In these non-compliant compilers, automatic objects constructed as index variables for the for loop are leaked out beyond the scope of the for loop, incorrectly extending the liveness of these variables. In order to correct this behavior, the for loops that are not encapsulated within trys are wrapped within if statements. The if statements and for loops naturally nest without delineated scope (e.g., f, g) allowing programmers to execute single or multiple operations based on their preference.
+
+(0 == rand()+1) always returns false and cannot be optimized away by an optimizing compiler. By using an always false non-optimizable function inside an if statement, a variable scope is generated that guarantees automatic objects which are placed within these scopes are properly destroyed once the scope is exited. These scopes properly terminate variables which would otherwise be leaked in non-compliant for loop C++ compilers. The proper termination of automatic auto_locks and transactions is necessary to release acquired locks, terminate transactions and release transactional memory.

[endsect]

+
[section Cache]

[heading Dispersed]

Modified: sandbox/stm/branches/vbe/libs/stm/doc/installation.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/installation.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/installation.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,5 +1,5 @@
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
   (C) Copyright 2009 Vicente J. Botet Escriba
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at
@@ -13,9 +13,9 @@

__Boost_STM__ is currently in an alpha release stage. This means our STM library is downloadable, but is undergoing some fundamental changes. Furthermore, our alpha release of TBoost.STM may exhibit some stability issues. While our internal tests have shown TBoost.STM to be fairly stable, your usage may vary.

-__Boost_STM_s__ current alpha download is mainly intended for other researchers who are curious about TBoost.STM's implementation and transactional memory. While we encourage non-TM experts to download the library and explore writing parallel code within its framework, we want such users know the system is in its early stages. As such, your usage of TBoost.STM may reveal some weaknesses or stability issues. Until we are into a fully released version, these issues are to be expected. However, please let us know if you encounter any problems using our library and we will do our best to resolve such issues immediately.
+__Boost_STM_s__ current alpha download is mainly intended for other researchers who are curious about TBoost.STM's implementation and transactional memory. While we encourage non-TM experts to download the library and explore writing parallel code within its framework, we want such users know the system is in its early stages. As such, your usage of TBoost.STM may reveal some weaknesses or stability issues. Until we are into a fully released version, these issues are to be expected. However, please let us know if you encounter any problems using our library and we will do our best to resolve such issues immediately.

-Thank you for considering __Boost_STM__ and we hope you enjoy exploring transactional memory!
+Thank you for considering __Boost_STM__ and we hope you enjoy exploring transactional memory!

[/=================================]
[heading Getting Boost.STM]
@@ -45,7 +45,7 @@
[/=========================]

-The POSIX threads (pthreads) library is needed to use __Boost_STM__. Pthreads is part of the standard deployment for almost all Unix / Linux flavors, however, it is not standard in Windows. If you are doing Windows development you can find the POSIX threads library at the below link:
+The POSIX threads (pthreads) library is needed to use __Boost_STM__. Pthreads is part of the standard deployment for almost all Unix / Linux flavors, however, it is not standard in Windows. If you are doing Windows development you can find the POSIX threads library at the below link:
[@http://sourceware.org/pthreads-win32/ POSIX threads (pthreads) for Windows]

@@ -66,7 +66,7 @@
]
]

-In addition __Boost_STM__ will uses the following libraries on the Boost Sandbox
+In addition __Boost_STM__ will uses the following libraries on the Boost Sandbox

[variablelist
[

Modified: sandbox/stm/branches/vbe/libs/stm/doc/introduction.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/introduction.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/introduction.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,5 +1,5 @@
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
   (C) Copyright 2009 Vicente J. Botet Escriba
  /
  / Distributed under the Boost Software License, Version 1.0. (See accompanying
@@ -8,44 +8,292 @@

[section:intro Introduction]

+[heading Transactional Memory]

-Research in parallel programming has recently seen a flurry of attention.
-Among the active research is a push for high-level languages
-to offer native support for parallel programming primitives. The next version of C++ will incorporate library support
-for threads, while numerous researchers are exploring ways to
-extend C++ to support transactional memory (TM).
-
-A strength of C++ is its support for automatic objects.
-Rather than requiring that parallel primitives be added directly to
-the language, automatic objects in C++ can be
-used to implement much of their necessary infrastructure.
-The automatic object approach is natural from a language perspective,
-provides full algorithmic control to the end programmer, and
-demonstrates C++'s linguistic elegance. The disadvantage of this
-approach is its added programmatic overhead. Using only automatic
-objects, certain programming errors, such as accidental scope
-removal and incorrectly programmed transactional retry behavior,
-can arise.
-
-In light of this, there are unique trade-offs between language based
-and library-based parallel primitives. Language-based solutions
-minimize syntactic clutter which reduce programmer related
-errors, but are seemingly irreversible and, if incorrect, can
-have crippling effects upon the language. Library-based solutions
-increase programmer control and flexibility, but place substantial
-pressure on the programmer to avoid minute programming errors.
-A good compromise is a solution that behaves like a language extension,
-but is implemented within a library. By implementing parallel
-primitives within a library that uses language-like interfaces,
-programmer pressure is reduced, implementation updates are seamless,
-and full programmer control is achieved through library extensibility.
+Transactional memory is a modern type of concurrency control that uses transactions as its synchronization mechanism. A transaction is a finite sequence of operations that are executed in an atomic, isolated and consistent manner. The atomicity, isolation and consistency (ACI) of transaction's are derived from the ACID principle in the database community. TM does not exhibit the D (durability) of ACID because unlike database transactions, TM transactions are not saved to permanent storage (e.g., hard drives).

+Transactions are executed speculatively (optimistically) and are checked for consistency at various points in the transaction's lifetime. Programmers specify the starting and ending points of a transaction. All of the operations between those points make up the transaction's execution body. Transactions are commonly represented using the atomic structure shown in the figure below.

+ 1 atomic
+ 2 {
+ 3 ++x;
+ 4 --y;
+ 5 }
+
+ Simple Transaction Using the atomic Keyword
+
+Once a transaction has started it either commits or aborts. A transaction's operations are only seen once the transaction has committed, providing the illusion that all of the operations occurred at a single instance in time. The instructions of a committed transaction are viewed as if they occurred as an indivisible event, not as a set of operations executed serially. The operations of an aborted transaction are never seen by other threads, even if such operations were executed within a transaction and then rolled back.
+
+In the case of the above example, if the transaction was committed both operations `++x` and `--y` would be made visible to other threads at the same instance in time. If the transaction the above example was aborted, neither operation (`++x` and `--y`) would appear to have occurred even if the local transaction executed one or both operations.
+
+TM offers three distinct advantages over other parallel programming abstractions.
+
+# TM is simple; transactions, the synchronization mechanism of TM, are easier to program than other synchronization mechanisms because they move shared memory management into the underlying TM subsystem, removing its complexity from the programmer's view. Moreover, TM exposes a simple programmer interface, reducing (or in some cases, removing) the potential for deadlock, livelock and priority inversion.
+
+# TM is scalable; it achieves increased computational throughput when compared to other parallel programming abstractions by allowing multiple threads to speculatively execute the same critical section. When concurrently executing threads do not exhibit shared data conflicts, they are guaranteed to make forward progress.
+
+# TM is modular; transactions can be nested to any depth and function as a single unit. This behavior allows application programmers to extend atomic library algorithms into atomic domain-specific algorithms without requiring the application programmers to understand the implementation details of the library algorithm.
+
+For these reasons, transactions are considered an important synchronization mechanism and TM is viewed as an important type of concurrency control. The remainder of this section presents TM from a viewpoint of (1) simplicity, (2) scalability and (3) modularity.
+
+[heading Simplicity]
+
+Synchronization problems, such as deadlocks, livelocks and priority inversion are common in software systems using mutual exclusion. TM avoids many of these problems by providing a synchronization mechanism that does not expose any of its implementation details to the programmer. The only interfaces the programmer needs to use for TM is as follows:
+
+* begin_tx() - the signaled start of the transaction.
+* read(loc) - reads the specified memory location, storing its location in the transaction's read set and returning its current value.
+* write(loc, val) - writes the specified memory location to the supplied val, storing its location in the transaction's write set.
+* end_tx() - the signaled end of the transaction. end_tx() returns true if the transaction commits, otherwise it returns false.
+
+The above interfaces allow the programmer to create a transaction (using begin_tx()), specify its memory operations (using read() and write()) and terminate (using end_tx()()). Moreover, none of the interfaces specify details of the TM subsystem's implementation. This leaves the TM system's implementation disjoint from the interfaces it supplies, a key characteristic for TM's simplicity.
+
+All TM implementations use some combination of the above interfaces. TMs implemented within compilers tend to implicitly annotate transactional read() and write() operations, whereas those implemented within software libraries tend to require the programmer explicitly state which operations are transactional reads and writes. An example of a transaction using the above interfaces alongside an actual STM library implementation is shown in Figure 3.
+
+ 1 // TM interfaces // __Boost_STM__
+ 2 do { atomic(t)
+ 3 begin_tx(); {
+ 4 write(x, read(x)+1); ++t.write(x);
+ 5 write(y, read(y)-1); --t.write(y);
+ 6 } while (end_tx()); } before_retry {}
+
+ Figure 3. Transaction Using (1) Explicit TM Interfaces and (2) __Boost_STM__.
+
+Figure 3 implements the same transaction as shown in Figure 2, except all transactional memory accesses, including the transaction's retry behavior (e.g., its loop), are demonstrated from a simple TM interface perspective and an actual library implementation (__Boost_STM__). While most TM systems handle some portion of these interface calls implicitly, as is shown in the __Boost_STM__ transaction, it is important to note that even when all operations are made visible to the end programmer, transactions are still devoid of many concurrency problems, such as data races and deadlocks (explained below), that plague other types of concurrency control.
+
+For example, as long as the programmer properly annotates the access to the shared variables x and y as shown in Figure 3, it is impossible for race conditions or deadlocks to occur. Furthermore, the programmer does not need any program-specific knowledge to use shared data; he or she simply uses the TM interfaces supplied by the system and the resulting behavior is guaranteed to be consistent. This is explained in greater detail in Section 3.1.
+
+Other types of concurrency control, such as mutual exclusion, cannot achieve the same interface simplicity, because part of their implementation is associated with, or exposed through, their interface. To demonstrate this, consider the fine-grained locking example of Figure 1 as shown below.
+
+ 1 // fine-grained locking
+ 2 lock(mutexX);
+ 3 lock(mutexY);
+ 4 ++x;
+ 5 --y;
+ 6 unlock(mutexX);
+ 7 unlock(mutexY);
+
+There is no universal interface that can be used to properly access the shared data protected by the mutual exclusion in the above fine-grained locking example. Instead, the programmer must be aware that mutexX and mutexY protect shared data x and y and, therefore, the locks must be obtained before accessing the shared data. In short, the programmer is responsible for knowing not only that mutual exclusion is used, but also how it is used (e.g., which locks protect which shared variables). In this case, mutexX must be obtained before mutexY. If another section of code implements the following, a deadlock scenario will eventually occur.
+
+ 1 // fine-grained locking
+ 2 lock(mutexY);
+ 3 lock(mutexX); // deadlock here
+ 4 --y;
+ 5 ++x;
+ 6 unlock(mutexY);
+ 7 unlock(mutexX);
+
+[heading Understanding Concurrency Hazards]
+
+Informally, a concurrency hazard is a condition existing in a set of operations that, if executed with a specific concurrent interleaving, results in one or many unwanted sideeffects. Most errors in parallel systems, such as deadlocks and priority inversion, are the specific execution of concurrency hazards resulting in the unwanted side-effect(s) they contain. If the concurrency hazards are eliminated, the parallel system errors contained within the concurrency hazards are also eliminated. Unfortunately, detecting existing concurrency hazards is non-trivial and therefore eliminating them is also non-trivial.
+
+Mutual exclusion exhibits more concurrency hazards than TM because its implementation details (i.e., its locks) must be exposed and used by the end programmer. While the locks used to enforce mutual exclusion by themselves are not concurrency hazards, their use can lead to a number of hazards. As such, using locks leads to concurrency hazards.
+
+Because the mutual exclusion locking details are exposed to the programmer and because the programmer must maintain a universal and informal contract to use these locks, concurrency hazards can arise due to the number of possible misuses that can be introduced by the programmer. In particular, if the programmer accidentally deviates from the informal locking contract, he or she may inadvertently introduce a concurrency hazard that can cause the program to deadlock, invert priority or lead to inconsistent data.
+
+In contrast, TM has no universal or informal contract between shared data that the end programmer needs to understand and follow as is required in mutual exclusion. Due to this, TM can hide its implementation details which results in reduced concurrency hazards. In particular, each transaction tracks the memory it uses in its read and write sets. When a transaction begins its commit phase, it verifies its state is consistent and commits its changes. If a transaction finds its state is inconsistent, it discards its changes and restarts. All of this can be achieved using the basic TM interfaces shown in Section 3 without exposing any implementation details. In order to use TM, the end programmer only needs to know how to correctly create a transaction. Once the transaction is executed, regardless of how it is executed, it results in a program state that is guaranteed to be consistent.
+
+Fundamentally, TM exhibits less concurrency hazards than mutual exclusion because its implementation details are divorced from its interface and can therefore be hidden within its subsystem. Any number of implementations can be used in a TM subsystem using only the basic TM interfaces shown in Section 3. The same is not true for mutual exclusion. Mutual exclusion, regardless of how it is implemented, exposes details of its implementation to the programmer. As demonstrated in Section 5, mutual exclusion does not provide software modularity specifically because extending an existing module requires an understanding and extension of that module's implementation. When such locking implementations are hidden inside of software libraries, extending these modules can range from difficult to impossible.
+
+[heading Testing: Race Conditions and Interleavings]
+
+A race condition is a common concurrency hazard that exists in parallel or distributed software. As with all concurrency hazards, race conditions rely on a specific interleaving of concurrent execution to cause their unwanted side-effect. In this section we demonstrate that race conditions do not exist in TM and therefore, software testing is greatly simplified because all possible interleavings do not need to be tested to ensure correct system behavior. In order to demonstrate that race conditions are absent from TM, we must first show that they are present in other types of concurrency control.
+
+ 1 // Thread T1 // Thread T
+ 2 lock(L2);
+ 3 lock(L1);
+ 4 ...
+ 5 unlock(L1);
+ 6 unlock(L2);
+ 7 lock(L1);
+ 8 lock(L2);
+ 9 ...
+
+ Figure 4. Mutual Exclusion Race Condition.
+
+Consider the race condition present in the mutual exclusion example shown in Figure 4. The race condition present in the example results in a deadlock if thread T1 executes line 7 followed by thread T2 executing line 2. However, if the program executes the lines in order (e.g., line 1, then line 2, then line 3, etc.), the system will execute properly. The fundamental problem in Figure 4 is that it contains a concurrency hazard; in particular, it contains a race condition. To further complicate matters, the race condition can only be observed in two of many possible concurrent executions. Those two executions are: T1 executes line 7 followed by T2 executing line 2 or T2 executes line 2 followed by T1 executing line 7. All other possible concurrent interleavings of threads T1 and T2 avoid the deadlock race condition. More specifically, as long as T1 executes lines 7-8 atomically or T2 executes line 2-3 atomically, all remaining concurrent interleavings are free of the deadlock race condition.
+
+Because it is unlikely that the deadlock race condition will occur, the programmer may never observe it, no matter how many times the program is tested. Only exhaustive testing, which tests all possible concurrent interleavings, is guaranteed to identify the presence of the deadlock. Regrettably, exhaustive testing is an unrealistic solution for most programs due to the time it would take to execute all possible concurrent interleavings of the program.
+
+An alternative to exhaustive testing is for programmers to use types of concurrency control that are devoid of certain concurrency hazards. For example, if mutual exclusion did not emit the race condition concurrency hazard, it would be impossible for a program using it to deadlock. Therefore, exhaustive testing would not be necessary. While this scenario is hypothetical, it illustrates our larger argument: in order to avoid common parallel problems in a practical fashion, programmers may need to only use types of concurrency control that are devoid of certain concurrency hazards. By doing this, the program using the specific type of concurrency control will be guaranteed to be free of certain common parallel problems.
+
+TMs are required to be devoid of race conditions within their implementations because they must enforce the ACI (atomic, consistent and isolated) principles. Transactions must execute as atomic and isolated and, therefore, TMs are not capable of supporting concurrent interleavings between multiple transactions as that would violate the atomic and isolated principles of ACI. Due to this, programs only using TM are guaranteed to be free of deadlocks (i.e., deadlockfreedom). Moreover, because TM implementations can guarantee freedom of race condition concurrency hazards, programmers only need to verify their transactional code is correct in a sequential (non-parallel) manner. Once the sequential execution of the transactional code has been verified, no more testing is required as the TM system is required to behave in a consistent manner for all serial orders.
+
+[heading Development: Mutual Exclusion and TM]
+
+The development of fine-grained locking is notoriously difficult. Designing such software is equally as hard. The difficulty in developing and designing fine-grained locking systems is rooted in conflicting heuristics. A primary goal of software design is to identify the most simplistic software solution that exists for a particular problem. A primary goal of fine-grained locking is the most efficient concurrent implementation of a software system. The goals of software design and fine-grained locking are conflicting because the most efficient fine-grained locking solution usually requires some of the most complex software design implementations to achieve such performance.
+
+TM achieves scalability by using optimistic concurrency that is implemented within its subsystem (see Section 4). Since the TM subsystem is the efficiency throttle for TM, which is unexposed to the programmer, the software architecture and design never needs to be complicated (nor can it be) in order to achieve increased parallelism when using transactions. As will be demonstrated in the following section, transactions run efficiently using the interfaces shown in this section and are never complicated in order to achieve improved performance, as is commonly found in fine-grained mutual exclusion implementations.
+
+[heading Scalability]
+
+In this section we analyze the scalability of TM compared to mutual exclusion. We measure scalability by two metrics: consistency and performance. A concurrency control type has consistent scalability if it guarantees correct behavior for an arbitrarily large number of concurrently executing processes.4 Performance scalability is measured by the maximum number of consistent processes supported by a concurrency control type while executing concurrently.
+
+[heading Pessimistic and Optimistic Critical Sections]
+
+Critical sections can be pessimistic or optimistic. Pessimistic critical sections limit their critical section execution to a single thread. Locks are an example of a synchronization mechanism that use pessimistic critical sections. Optimistic critical sections allow unlimited concurrent threaded execution. Transactions are an example of a synchronization mechanism that use optimistic critical sections.
+
+[heading Truly Optimistic Critical Sections]
+
+Truly optimistic critical sections are those critical sections which allow multiple conflicting threads to simultaneously execute the same critical section. A deferred update (or lazy acquire) TM system supports truly optimistic critical section. A direct update (or eager acquire) TM system does not support truly optimistic critical sections. More details on deferred and direct update TM systems are presented in the subsequent sections.
+
+Truly optimistic critical sections are important because they allow simultaneous conflicting critical section execution, as opposed to disallowing such behavior. It is important to allow conflicting critical section execution because prematurely preventing concurrently executing threads pessimistically degrades performance. To demonstrate this, consider two transactions, called T1 and T2, executing the same critical section. Transaction T1 starts first and tentatively writes to memory locationM. Transaction T2 then starts and tries to write to memory locationM. In a truly optimistic TM system, T2 would be allowed to tentatively write to location M while T1 is also writing to M. This behavior then allows T2 to commit before T1 in the event T2 completes before T1.
+
+In comparison, if the TM system is not truly optimistic, once T1 writes to M, T2 must stall until T1 completes. This pessimistically degrades the performance of the system by prematurely deciding that T1's transactional execution should have higher priority than T2's.
+
+ 1 // global variables
+ 2 int g1 = 0; int g2 = 0;
+ 3
+ 4 void set1(int val) { atomic { g1 = val; } }
+ 5 void set2(int val) { atomic { g2 = val; } }
+ 6 int get1() { atomic { return g1; } }
+ 7 int get2() { atomic { return g2; } }
+
+ Figure 5. Truly Optimistic Concurrency Diagram.
+
+Furthermore, and perhaps more importantly, truly optimistic critical sections allow readers and writers of the same memory location to execute concurrently. This behavior is important because in many cases, both the readers and writers of the same memory can commit with consistent views of memory.
+
+An example of this is shown in Figure 5. As demonstrated in Figure 5 thread 1 and thread 2, which we'll refer to as T1 and T2 respectively, operate on the same memory locations (g1 and g2). Because the TM system supports optimistic concurrency, T2 is allowed to execute concurrently alongside T1 even though their memory accesses conflict. However, in this scenario, because T2 completes its workload before T1, both transactions are allowed to commit. T2 captures the state of g1=0,g2=0 while T1 sets the state of g1=1,g2=1. As the example addresses, both g1=0,g2=0 and g1=1,g2=1 are legal states.
+
+[heading Direct and Deferred Update]
+
+Updating is the process of committing transactional writes to global memory and is performed in either a direct or deferred manner. Figure 6 presents a step-by-step analysis of direct and deferred updating.
+
+Deferred update creates a local copy of global memory, performs modifications to the local copy, and then writes those changes to global memory if the transaction commits. If the transaction aborts, no additional work is done. Direct update makes an original backup copy of global memory and then writes directly to global memory. If the transaction commits, the transaction does nothing. If the transaction aborts, the transaction restores global memory with its backup copy. Some TM systems favor direct update due to its natural optimization of commits (BSTM, McRTSTM and LogTM). However, other TM systems favor deferred update due to its support for truly optimistic critical sections (__Boost_STM__ and RingSTM).
+
+Direct update enables greater TM throughput when aborts are relatively low because it optimizes the common commit case. Deferred update enables greater TM throughput when
+
+# aborts are relatively high or
+# short running transactions (e.g., those that complete quickly) are executed alongside long running transactions (e.g., those that do not complete quickly) because long running transactions do not stall shorter running ones as they would in direct update systems, and therefore the fastest transactions can commit first.
+
+It is important to note that deferred update supports truly optimistic critical sections without special effort, while direct update does not. Truly optimistic critical sections enable the speculative execution of transactions that arrive after a memory location has already been tentatively written to by another transaction. This allows the first transaction, of potentially many competing transactions, to complete its commit, whether it be the later arriving transaction or the earlier arriving writer. This scenario is not possible with direct update without special effort.
+
+[heading Scalability: Mutual Exclusion and Transactional Memory]
+
+The scalability of mutual exclusion is limited to pessimistic concurrency. By definition, mutual exclusion's critical sections must be pessimistic, otherwise they would not be isolated to a single thread (i.e., they would not be mutually exclusive). TM, however, is generally implemented using optimistic concurrency, but it can enforce pessimistic concurrency amongst transactions if that behavior is required for certain conditions. In certain cases, TMs becomemore strict and execute pessimistically to enable inevitable or irrevocable transactions. Such transactions have significant importance for handling operations that, once started, must complete (e.g., I/O operations).
+
+Since TM can execute optimistically and pessimistically, it is clear that whatever benefits pessimistic concurrency has can be acquired by TM. However, since mutual exclusion can only execute pessimistically, the advantages found in optimistic concurrency can never be obtained by mutual exclusion.
+
+When one first analyzes pessimistic and optimistic concurrency, it may seem that the only benefit optimistic concurrency has over pessimistic concurrency is that multiple critical sections, which conflict on the memory they access, can execute concurrently. The simultaneous execution of such conflicting critical sections allows the execution speed of such critical sections to guide the system in deciding which execution should be allowed to commit and which should be aborted. In particular, the first process to complete the critical section can be allowed to abort the other process of the system. The same scenario cannot be achieved by pessimistic critical sections and is demonstrated in Section 4.1.1.
+
+A counterargument to this scenario is that such optimistic concurrency only allows one critical section to commit, while one must be aborted. Because mutual exclusion only allows one conflicting critical section execution at a time, and because mutual exclusion does not support failure atomicity (i.e., rollbacking of the critical section), mutual exclusion's pessimistic behavior is superior in terms of energy and efficiency. Mutual exclusion, unlike TM, suffers no wasted work because conflicting critical sections are limited to a single thread of execution, reducing the energy it uses. Furthermore, because mutual exclusion does not require original data to copied, as needed for TM's direct or deferred update, it executes faster.
+
+While there is merit to this counterargument, an important scenario is not captured by it: truly optimistic critical sections can support multiple reader / single write executions which, if executed so the readers commit before the writer, all critical sections will succeed. This scenario is impossible to achieve using pessimistic critical sections. Although mutual exclusion can use read/write locking, as soon as a writer thread begins execution on a conflicting critical section, all readers must be stalled. TM's truly optimistic concurrency does not suffer from this overly pessimistic limitation of throughput and is therefore capable of producing an immeasurable amount of concurrent throughput under such conditions.
+
+From a theoretical perspective, given L memory locations and P processes, mutual exclusion can support the consistent concurrent execution of P*L number of readers or L writers. TM can support the consistent concurrent execution of P*L number of readers and L writers. Using the above variables, the mathematical expression of the performance scalability of mutual exclusion (S(ME)) is:
+
+ S(ME) = (P*L) + L
+
+Using the same variables, the mathematical expression of the performance scalability of transactional memory is:
+
+ S(TM) = (P * L) + L
+
+As should be clear from the above equations, mutual exclusion cannot achieve the same performance scalability of TM. This is because TM supports truly optimistic concurrency and mutual exclusion is confined to pessimistic concurrency. While other examples exist that demonstrate optimistic concurrency can increase throughput via contention management, the above equations capture the indisputable mathematical limitations in mutual exclusion's performance scalability.
+
+[heading Modularity]
+
+Software modularity is an important aspect of software that is necessary for its reuse. Formally, software is modular if it can be composed in a new system without altering its internal implementation. Informally, software is modular if it can be used, in its entirety, through its interface.
+
+By making software modular, it can be freely used in an unlimited number of software systems. Without software modularity, software can only be used in the original system where it was written. Clearly, without software modularity, software cannot be reused. Because most software developments are based on extensive library use, software reuse is an integral part of software development. As such, limiting software reuse, would result in severely hampered development capabilities and overall development time. For these reasons, software modularity is vital for any software paradigm to be practical. Software paradigms that do not support software modularity are, in short, impractical.
+
+[heading Mutual Exclusion and Software Modularity]
+
+In this section, we show that mutual exclusion, regardless of its implementation, fails to deliver software modularity. We demonstrate this through a running example started in Figure 7 which implements inc(), mult() and get(); these functions use lock G to respectively implement an increment, multiply and get operations for the shared data.
+
+ 1 void inc(int v) {
+ 2 lock(G); g += v; unlock(G);
+ 3 }
+ 4
+ 5 void mult(int v) {
+ 6 lock(G); g *= v; unlock(G);
+ 7 }
+ 8
+ 9 int get() {
+ 10 lock(G); int v = g; unlock(G);
+ 11 return v;
+ 12 }
+
+ Figure 7. Mutual Exclusion for Increment, Multiply and Get of Shared Variable.
+
+Now suppose a programmer wants to increment and multiply by some values within the same atomic operation. The initial implementation may look like the following.
+
+ 1 inc(a);
+ 2 mult(-b);
+
+An unwanted side-effect of such an implementation is the exposure of the intermediate state of g between inc() and mult(). A second thread performing a get() may read an inconsistent value of g; the value of g between inc() and mult(). This is demonstrated in the timing diagram of Figure 8 .
+
+ Figure 8. Example of Exposed State of Mutual Exclusion.
+
+If the programmer needs the inc() and mult() operations to be executed together, without an intermediate state being revealed, he or she could make lock G reentrant. Reentrant locks are locks that can be obtained multiple times by a single thread without deadlocking. If G is made reentrant, the following code could be used to make inc(a) and mult(-b) atomic. A basic implementation of a reentrant lock is to associate a counter with its lock and increment the counter each time the lock() interface is called and to decrement the counter each time the unlock() interface is called. The reentrant lock is only truly locked when a call to lock() is made when its associated counter is 0. Likewise, the reentrant lock is only truly unlocked when a call to unlock() is made when its associated counter is 1.
+
+ 1 lock(G);
+ 2 inc(a);
+ 3 mult(-b);
+ 4 unlock(G);
+
+If the above code uses reentrant locks, it will achieve the programmer's intended atomicity for inc() and mult(), isolating the state between inc() and mult(), which disallows the unwanted side-effect shown in Figure 8. While the atomicity of the operations is achieved, it is only achieved by exposing the implementation details of inc() and mult(). In particular, if the programmer had not known that lock G was used within inc() and mult(), making an atomic operation of inc() and mult() would be impossible.
+
+An external atomic grouping of operations is impossible using embedded mutual exclusion without exposing the implementation details because the heart of mutual exclusion is based on named variables which the programmer specifies to guard their critical sections. Because these variables are named, they cannot be abstracted away and any programmer wishing to reuse the mutually exclusive code must be able to access and extend the implementation details.
+
+ 1 void inc(int v) { atomic { g += v; } }
+ 2
+ 3 void mult(int v) { atomic { g *= v; } }
+ 4
+ 5 int get() { atomic { return g; } }
+
+ Figure 9. TM of Increment, Multiply and Get of Shared Variable.
+
+
+[heading Summary of Mutual Exclusion Modularity]
+
+As we presented at the beginning of this section, software modularity can be informally understood as a component's ability to be used entirely from its interface. Therefore, components that cannot be used entirely from their interface, components that must expose their implementation details to be extended, are not modular. As such, the paradigm of mutual exclusion does not support software modularity.
+
+[heading Transactional Memory and Software Modularity]
+
+Transactional memory works in a fundamentally different manner than mutual exclusion, with regard to its interface and implementation. To begin, as demonstrated in Section 3, TMs do not generally expose any of their implementation details to client code. In fact, in many TMs, client code is more versatile if it knows and assumes nothing about the active implementation of the TM. By abstracting away details of TM implementation, a TM subsystem can adapt its behavior to the most efficient configuration for the program's current workload, much like the algorithms used for efficient operation of processes controlled by operating systems. TM uses such abstractions to optimize the performance of concurrent programs using various consistency checking methods, conflict detection times, updating policies, and contention management schemes.
+
+[heading Achieving TM Software Modularity]
+
+TM achieves software modularity by allowing transactions to nest. With transactional nesting, individual transactions can be wrapped inside of other transactions which call the methods where they reside, resulting in a transaction composed of both the parent and child transaction. Furthermore, this is achieved without altering or understanding the child transaction's implementation. To best demonstrate transactional nesting, we reuse the prior mutual exclusion example shown in Figure 7 and implement it using transactions as shown in Figure 9.
+
+As before, the programmer's goal is to implement a combination of inc() and mult() executed in an atomic fashion. The basic, and incorrect implementation is demonstrated below:
+
+ 1 inc(a);
+ 2 mult(-b);
+
+Even with transactions, this approach fails because the transactions within inc() and mult() begin and end inside their respective functions. However, to make the above operations atomic, the programmer need only make the following modification shown in Figure 10.
+
+ 1 atomic { // atomic {
+ 2 inc(a); // atomic { g += a; }
+ 3 mult(-b); // atomic { g *= -b; }
+ 4 } // }
+
+ Figure 10. Modularity: Transaction of Increment and Multiply.
+
+In effect, the TM system subsumes the transactions that are nested inside of the inc() and mult() operations. 6 The left side of Figure 10 shows the actual code of the transaction, while the right side shows the child transactions that are subsumed by the parent transaction.
+
+Because transactions are isolated and atomic, the resulting state of g, from operations inc() and mult(), is invisible to outside observers until the transaction is committed. As such, outside threads cannot view any intermediate state constructed by partial transaction execution. The result of such isolated behavior is the guaranteed consistent concurrent execution of interleaved accesses to shared memory from in-flight transactions. This is demonstrated in Figure 11; let g=0 and assume deferred update is the active updating policy, as explained in Section 4.2.
+
+ Figure 11. Example of Isolated and Consistent State of TM.
+
+As shown in Figure 11, multiple concurrently executing threads can read and write to the same shared memory in a consistent and isolated fashion when using TM. In the example, thread T2 performs x = get() after T1 has already executed inc(a). However, since T1 has not yet committed its transaction, T2's view of shared data g is consistent (g=0). When T2 begins the commit phase of its transaction, the TM subsystem verifies that shared data g has not been updated since it initially read it. Since no other transaction has updated shared data g, T2's transaction is permitted to commit. Thread T1 then continues with its mult() operation and then enters its commit phase. The TM subsystem also verifies the consistency of T1's transaction before it is allowed to commit. Again, since no one transaction has updated shared data g between its reads and writes to it, T1's transaction is permitted to commit.
+
+The above analysis demonstrates that software modularity can be achieved in TM through transactional nesting (Figure 10). In this case, the specific software modularity achieved is extension to an existing critical section. Critical section extension was also possible with mutual exclusion, as demonstrated in Section 5.1, but only through exposing the details behind the mutual exclusion implementation. Due to this, mutual exclusion fails to deliver a practical level of software modularity.
+
+[heading Summary of Transactional Memory Modularity]
+
+TM supports software modularity by allowing transactions to nest, to any depth, while logically grouping the shared data accesses within the transactions into an atomic, consistent and isolated (ACI) operation. Transactional nesting is natural to the programmer because nested transactions behave in the same manner as unnested transactions. TM's ACI support ensures transactions will behave in a correct manner regardless of if the transaction is used by itself or subsumed into a larger transaction.
+
+
+[heading C++ library language-like solution]
+
+Research in parallel programming has recently seen a flurry of attention. Among the active research is a push for high-level languages to offer native support for parallel programming primitives. The next version of C++ will incorporate library support for threads, while numerous researchers are exploring ways to extend C++ to support transactional memory (TM).
+
+A strength of C++ is its support for automatic objects. Rather than requiring that parallel primitives be added directly to the language, automatic objects in C++ can be used to implement much of their necessary infrastructure. The automatic object approach is natural from a language perspective, provides full algorithmic control to the end programmer, and demonstrates C++'s linguistic elegance. The disadvantage of this approach is its added programmatic overhead. Using only automatic objects, certain programming errors, such as accidental scope removal and incorrectly programmed transactional retry behavior, can arise.
+
+In light of this, there are unique trade-offs between language based and library-based parallel primitives. Language-based solutions minimize syntactic clutter which reduce programmer related errors, but are seemingly irreversible and, if incorrect, can have crippling effects upon the language. Library-based solutions increase programmer control and flexibility, but place substantial pressure on the programmer to avoid minute programming errors. A good compromise is a solution that behaves like a language extension, but is implemented within a library. By implementing parallel primitives within a library that uses language-like interfaces, programmer pressure is reduced, implementation updates are seamless, and full programmer control is achieved through library extensibility.
+
+__Boost_STM__ present such a language-like solution for C++ using generic library coupled with a deliberate use of the preprocessor. The culmination of these components facilitate a simple, yet powerful, parallel programming interface in C++.

-__Boost_STM__ present such a language-like solution for C++
-using generic library coupled with a deliberate use of the
-preprocessor. The culmination of these components facilitate a
-simple, yet powerful, parallel programming interface in C++.

Modified: sandbox/stm/branches/vbe/libs/stm/doc/overview.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/overview.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/overview.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,5 +1,5 @@
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
 (C) Copyright 2009 Vicente J. Botet Escriba
 Distributed under the Boost Software License, Version 1.0.
 (See accompanying file LICENSE_1_0.txt or copy at
@@ -14,27 +14,28 @@
[heading Description]
[/==================]

+Toward An Industrial Strength C++ Software Transactional Memory Library.
+
Transactional memory (TM) is a new parallel programming mechanism that reduces the complexity of parallel programming. TM reduces parallel programming complexity by abstracting away the necessary synchronization mechanisms from the parallel code, allowing the programmer to write parallel applications without worry of deadlocks, livelocks or race conditions.

Transactional memory is an active research interest for many academic and industry institutions with many open questions about its behavior.

__Boost_STM__ is a C++ lock-based software transactional memory (STM) library. Our approach to STM is to use only native language semantics while implementing the least intrusive, most type-safe object oriented solution possible.

-
[*__Boost_STM__] provides:

-* Optimistic concurrency
-* ACI transactions
- * Atomic: all operations execute or none do
- * Consistent: only legal memory states
- * Isolated: other txes cannot see until committed
-* Language-like atomic transaction macro blocks
-* Closed, flattened composable transactions
-* Direct and deferred updating run-time policies
-* Validation and invalidation conflict detection policies
+* Optimistic concurrency
+* ACI transactions
+ * Atomic: all operations execute or none do
+ * Consistent: only legal memory states
+ * Isolated: other txes cannot see until committed
+* Language-like atomic transaction macro blocks
+* Closed, flattened composable transactions
+* Direct and deferred updating run-time policies
+* Validation and invalidation conflict detection policies
* Lock-aware transactions
-* Programmable contention management, enabling programmers to specify forward progress mechanisms
-* Isolated and irrevocable transactions for transactions that must commit (i.e., I/O transactions)
+* Programmable contention management, enabling programmers to specify forward progress mechanisms
+* Isolated and irrevocable transactions for transactions that must commit (i.e., I/O transactions)

[/====================================]
@@ -45,11 +46,9 @@

* Code is in `fixed width font` and is syntax-highlighted.
* Replaceable text that you will need to supply is in [~italics].
-* If a name refers to a free function, it is specified like this:
- `free_function()`; that is, it is in code font and its name is followed by `()` to indicate that it is a free function.
-* If a name refers to a class template, it is specified like this: `class_template<>`; that is, it is in code font and its name is followed by `<>` to indicate that it is a class template.
-* If a name refers to a function-like macro, it is specified like this: `MACRO()`;
- that is, it is uppercase in code font and its name is followed by `()` to indicate that it is a function-like macro. Object-like macros appear without the trailing `()`.
+* If a name refers to a free function, it is specified like this: `free_function()`; that is, it is in code font and its name is followed by `()` to indicate that it is a free function.
+* If a name refers to a class template, it is specified like this: `class_template<>`; that is, it is in code font and its name is followed by `<>` to indicate that it is a class template.
+* If a name refers to a function-like macro, it is specified like this: `MACRO()`; that is, it is uppercase in code font and its name is followed by `()` to indicate that it is a function-like macro. Object-like macros appear without the trailing `()`.
* Names that refer to /concepts/ in the generic programming sense are specified in CamelCase.

[note In addition, notes such as this one specify non-essential information that provides additional background or rationale.]

Modified: sandbox/stm/branches/vbe/libs/stm/doc/rationale.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/rationale.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/rationale.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,5 +1,5 @@
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
 (C) Copyright 2009 Vicente J. Botet Escriba
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
@@ -15,11 +15,10 @@

[section ACI transactions]

-Transactional memory was founded on the database ACID principle (atomic, consistent, isolated and durable), except without the
-D [24].
+Transactional memory was founded on the database ACID principle (atomic, consistent, isolated and durable), except without the D (durability) because unlike database transactions, TM transactions are not saved to permanent storage (e.g., hard drives).

-* Transactions are atomic; the operations all commit or none of them do.
-* Transactions are consistent; transactions must begin and end in legal memory states.
+* Transactions are atomic; the operations all commit or none of them do.
+* Transactions are consistent; transactions must begin and end in legal memory states.
* Transactions are isolated; memory changes made within a transaction are invisible until committed.

The below example gives a basic introduction into __Boost_STM_s__ transactional framework and demonstrates __Boost_STM_s__ ACI conformance.
@@ -32,7 +31,7 @@
 } end_atom
 return val;
 }
-
+
In the above example, (A) both the t.write() and t.read() operations function atomically or neither operations are performed.
In addition, (C) the transaction begins and ends in legal memory states, meaning global int is guaranteed to be read correctly, preventing thread data races from causing inconsistent results. Lastly, (I) the intermediate state of the incremented global int is isolated until the transaction commits. These three attributes fulfill __Boost_STM_s__
conformance to the ACI principles. The above example also gives a basic introduction into __Boost_STM_s__ transactional
@@ -42,26 +41,26 @@

[section STM Synchronization Types]

-There are two ways STM systems synchronize memory:
+There are two ways STM systems synchronize memory:

-# using non-blocking mechanisms (lock-free) or
-# using lock-based (or blocking) mechanisms.
+# using non-blocking mechanisms (lock-free) or
+# using lock-based (or blocking) mechanisms.

Non-blocking STM systems use atomic primitives, such as, compare-and-swap (CAS) or load-linked and store-conditional (LL-SC), that do not lock the STM system to perform their transactional operations. Lock-based STM systems use locks, such as mutual exclusion locks, which lock the STM system to perform some portion of their transactional operations.

__Boost_STM__ is a lock-based STM system. At its core, __Boost_STM__ uses one lock per thread to implement transactional reads and writes. This allows multiple transactions to simultaneously read and write without blocking other transactions' progress. When a transaction is committing, a global locking strategy is used to temporarily block forward progress on all transactions except the committing one. Once the committing transaction completes, other transactions are allowed to resume their work. __Boost_STM_s__ lockbased strategy allows it to gain the performance benefits of a nonblocking system, such that when transactions are not committing, the transactions do not block each other and are guaranteed to make forward progress. Yet __Boost_STM__ maintains the benefits of a lockbased system, enabling it to perform commit-time invalidation, its primary consistency model mechanism.

Recent research shows lock-based STM systems outperform non-blocking systems. Our own research shows that through
-__Boost_STM_s__ design, scaling concerns and other lock-based specific problems, such as deadlocking and priority inversion, can be overcome with specific contention management and conflict detection policies.
+__Boost_STM_s__ design, scaling concerns and other lock-based specific problems, such as deadlocking and priority inversion, can be overcome with specific contention management and conflict detection policies.

[endsect]

[section Updating policies]

-In any STM system, an updating protocol must be used to perform transactional commits for writes. Updating policies determine how a transaction commits its memory updates to global memory. Two general ways exist to perform updating:
+In any STM system, an updating protocol must be used to perform transactional commits for writes. Updating policies determine how a transaction commits its memory updates to global memory. Two general ways exist to perform updating:

-# direct updating, which copies the original global memory state off to the side and then writes directly to global memory, and
-# deferred updating, which copies the original global memory off to the side and the writes to the local copy.
+# direct updating, which copies the original global memory state off to the side and then writes directly to global memory, and
+# deferred updating, which copies the original global memory off to the side and the writes to the local copy.

When a transaction of a direct updating system commits its changes, no changes to global memory are made as the STM system has written directly to global memory. When a transaction of a deferred updating system commits its changes, it writes the local changes to global memory. When a direct updating system aborts, it uses the original copy of memory to update global memory, restoring it to its original state. When a deferred updating system aborts, no changes to global memory are made as the STM system has not written anything to global memory. One of __Boost_STM_s__ novel features is its implementation of both direct and deferred updating.

@@ -69,7 +68,7 @@

[section Conflict Detection]

-Conflict detection is the process of identifying when two or more transactions conflict. Conflicts can exist when a transaction writes to memory that another transaction then reads or writes (write after write, write after read), or when a transaction reads memory that is then used in another transaction's write (read after write). Unlimited readers, on the other hand, can read the same piece of memory without any conflict (read after read).
+Conflict detection is the process of identifying when two or more transactions conflict. Conflicts can exist when a transaction writes to memory that another transaction then reads or writes (write after write, write after read), or when a transaction reads memory that is then used in another transaction's write (read after write). Unlimited readers, on the other hand, can read the same piece of memory without any conflict (read after read).

[table Comparaison with other STM systems
 [
@@ -84,12 +83,12 @@
]

-Before determining how to handle a conflict, STM systems must determine when they will detect conflicts. There are two primary ways to detect conflicts:
+Before determining how to handle a conflict, STM systems must determine when they will detect conflicts. There are two primary ways to detect conflicts:

* Early conflict detection attempts to identify conflicts as soon as a transaction reads or writes to memory.
* Late conflict detection attempts to identify conflicts some time after the initial read or write.

-For direct updating, __Boost_STM__ implements a run-time configurable early and late conflict detection mechanism. For deferred updating, __Boost_STM__ only implements late conflict detection. The decision to have __Boost_STM__ only support late conflict detection for deferred updating was made after identifying numerous lost optimizations using early conflict detection with deferred updating.
+For direct updating, __Boost_STM__ implements a run-time configurable early and late conflict detection mechanism. For deferred updating, __Boost_STM__ only implements late conflict detection. The decision to have __Boost_STM__ only support late conflict detection for deferred updating was made after identifying numerous lost optimizations using early conflict detection with deferred updating.

Future work may lead to the implementation of early conflict detection for deferred updating simply for symmetry.

@@ -97,23 +96,23 @@

[section Consistency checking policies]

-An STM system can identify a conflict in two principal ways: through validation or invalidation.
+An STM system can identify a conflict in two principal ways: through validation or invalidation.

-* Validation is the process a transaction performs on its own read and write set to check itself for consistency.
+* Validation is the process a transaction performs on its own read and write set to check itself for consistency.
* Invalidation is the process a transaction performs on other transaction's read and write sets to check them for consistency.

Validation strategies usually have the the transaction abort itself if an inconsistency is found. Invalidation strategies usually do just the opposite, aborting the other transactions if an inconsistency is found. In addition, STM systems can use contention managers to determine how best to behave when inconsistent transactions are identified.

__Boost_STM__ currently implements consistency checking only through invalidation. One of the next goals of __Boost_STM__ is to build run-time configuration of consistency checking for both invalidation and validation, as it is believed that both may be necessary for varying problems. This aside, __Boost_STM__ is unique in that it is the first STM system to implement commit-time invalidation. While other systems, such as __RSTM__, have implemented invalidation, no other system implements commit-time invalidation.

-We believe __Boost_STM__ is the first commit-time invalidating system due to commit-time invalidation being seemingly only possible in lock-based STM systems and as lock-based STM systems are relatively new, other lock-based systems not being far enough along to implement it yet. The two key differences we focus on in this work between invalidation and validation are;
+We believe __Boost_STM__ is the first commit-time invalidating system due to commit-time invalidation being seemingly only possible in lock-based STM systems and as lock-based STM systems are relatively new, other lock-based systems not being far enough along to implement it yet. The two key differences we focus on in this work between invalidation and validation are;

-# invalidation can save many wasted operations by early notification of doomed transactions, whereas validation cannot and
-# invalidation can detect true priority inversion, whereas validation cannot
+# invalidation can save many wasted operations by early notification of doomed transactions, whereas validation cannot and
+# invalidation can detect true priority inversion, whereas validation cannot

(other significant differences exist, but are not discussed here).

-* Fully validating systems must iterate through all transactional operations and determine consistency only at commit-time. Thus, each transaction must fully execute its transactional operations. A substantial amount of work can be saved by an invalidating system which can flag doomed transactions early, as shown in table 1. Table 1 details 4, 8 and 12 threaded runs for red-black trees, linked lists and hash tables in __Boost_STM__. While the percentage of operational savings decreases for each benchmark as the structure size increases, the actual operational savings improves. For example, if a linked list is inserting at the end of a 1600 node list and receives an early termination notification saving 50% of its operations, the savings gained is an 800 node iteration and insert. Likewise, performing a 90% operations savings in a linked list insert operation of size 100, saves only a 90 node iteration and insert.
+* Fully validating systems must iterate through all transactional operations and determine consistency only at commit-time. Thus, each transaction must fully execute its transactional operations. A substantial amount of work can be saved by an invalidating system which can flag doomed transactions early, as shown in table 1. Table 1 details 4, 8 and 12 threaded runs for red-black trees, linked lists and hash tables in __Boost_STM__. While the percentage of operational savings decreases for each benchmark as the structure size increases, the actual operational savings improves. For example, if a linked list is inserting at the end of a 1600 node list and receives an early termination notification saving 50% of its operations, the savings gained is an 800 node iteration and insert. Likewise, performing a 90% operations savings in a linked list insert operation of size 100, saves only a 90 node iteration and insert.

Furthermore, not shown in the tables here, due to space limitations, is that abort percentages grow for each benchmark as the data structure size increases. Thus, the number of aborts increases, resulting in an even high amount of abort savings per benchmark. The increasing number of aborts as the data structure grows is quite intuitive as longer running transactions are more likely to incur collisions, especially while operating on the same data structure.

@@ -149,13 +148,13 @@

[section Memory Rollback Capability]

-STM systems must implement memory rollback capabilities for aborted transactions. Memory rollbacking restores the original state of memory in the event a transaction aborts. There are three rollbacking aspects any STM system must handle when implemented in an unmanaged language;
+STM systems must implement memory rollback capabilities for aborted transactions. Memory rollbacking restores the original state of memory in the event a transaction aborts. There are three rollbacking aspects any STM system must handle when implemented in an unmanaged language;

-* updates to global,
-* allocated memory and
-* deallocated memory.
+* updates to global,
+* allocated memory and
+* deallocated memory.

-__Boost_STM__ handles rollbacking to global memory internally for both direct and deferred updating, requiring no programmer-based code. However, allocated and deallocated memory rollbacking require programmer-specific interfaces to be used. These interfaces handle C++ memory operations in their native capacity - new and delete - as well as their transactional memory capacity, ensuring no memory is leaked nor deleted prematurely.
+__Boost_STM__ handles rollbacking to global memory internally for both direct and deferred updating, requiring no programmer-based code. However, allocated and deallocated memory rollbacking require programmer-specific interfaces to be used. These interfaces handle C++ memory operations in their native capacity - new and delete - as well as their transactional memory capacity, ensuring no memory is leaked nor deleted prematurely.

Examples of this are presented in the following section.

@@ -163,7 +162,7 @@

[section Composable transactions]

-Composition is the process of taking separate transactions and adding them together to compose a larger single transaction. Composition is a very important aspect of transactions as, unlike locks, transactions can compose. Without a composable TM system, nested transactions each act independently committing their state as they complete. This is highly problematic if an outer transaction then aborts, as there may be no way to rollback the state of a nested (and already committed) transaction. Therefore, implementation of composable transactions is paramount to any TM system which hopes to build large transactions.
+Composition is the process of taking separate transactions and adding them together to compose a larger single transaction. Composition is a very important aspect of transactions as, unlike locks, transactions can compose. Without a composable TM system, nested transactions each act independently committing their state as they complete. This is highly problematic if an outer transaction then aborts, as there may be no way to rollback the state of a nested (and already committed) transaction. Therefore, implementation of composable transactions is paramount to any TM system which hopes to build large transactions.

__Boost_STM__ implements composition via subsumption and is a closed nested system. Composition via subsumption merges all nested transactional memory of a single thread into the outer most active transaction of that same thread. The outer transaction subsumes all the inner transactions' changes. Once the outer transaction completes, all the transactional memory from the nested transactions and their parent either commit or abort. __Boost_STM_s__ closed nesting system enables each nested transaction visibility into its parent's transactional memory and vice versa, but does not allow other transactions to see this intermediate state.

@@ -173,12 +172,376 @@

[section Contention management]

-[endsect]
-[section Unrecoverable transactions to manage with I/O]
+[heading Priority-Based Tasks]
+
+Real-time systems or systems that have strict requirements for task behavior, such as deadline-drive systems, usually guarantee such behavior through priority scheduling. While significant prior TM contention management (CM) research has been done, its attention has been primarily focused on preventing starvation through fairness. In many systems preventing starvation may be sufficient, yet some systems (e.g. deadline-driven or real-time systems) require stronger behavioral guarantees. In these cases, user-defined priority-based transactions are necessary.
+
+[heading Approach]
+
+This work extends the prior TM contention management research by concretely implementing user-defined contention managers as determined consequential. We approach this by first presenting a brief background of TM aspects important to understanding the complexities of contention management. Next, we review and expand upon prior contention management work. We then show how consistency models play a significant role in the correctness and capability of priority-based transactional scheduling. We then build user-defined priority-based transactions with __Boost_STM__, demonstrating how contention management frameworks work with different consistency checking models. Last, we present our experimental results.
+
+[heading Attacking & Victim Transactions]
+
+We refer to transactions which can identify a memory conflict in another in-flight transaction as attacking transactions. Transactions which are targeted by attacking transactions are referred to as victim transactions. The attacking and victim transaction terms help simplify the invalidation process. An example of attacking and victim transactions is as follows. Consider transaction Tv, a victim transaction and transaction Ta, an attacking transaction. Tv writes to memory location L0. Ta then tries to write to L0. If our STM system only allows single-writers, both Ta and Tv cannot write to L0 at the same time. As Ta is the second transaction attempting to write to L0, the single-writer semantics require it to deal with the conflict located at L0. Handling this conflict makes Ta the attacking transaction as it decides if Tv is aborted. Tv is the victim transaction since Ta may abort it.
+
+[heading User-Defined Priority-Based Transactions]
+
+Validation and invalidation
+
+consistency checking are both practical solutions to transactional memory for different classes of problems. When inflight transactions are low and memory usage is high, invalidation may be preferred. When transactional traffic is high and transactions are small, validation may be preferred. Neither type of consistency checking seems to perform universally better than the other. Though certain classes of problems perform better under different consistency checking models, the ramifications of these consistency checking schemes performing within strict user-defined priority-based transactional systems is unclear from prior research. Our work clarifies the advantages and disadvantages of validation and invalidation in user-defined priority-based transactional environments.
+
+[heading Extensible Polymorphic Contention Management Interface]
+
+Due to the innumerable possibilities of consistency checking model combinations, for the remainder of this work, we narrow our scope of consistency checking to commit-time validation and committime invalidation. We do this for a number of reasons. First, validation and invalidation are near opposites and commit-time consistency checking is straight forward in that it is only performed once per transaction. Due to this, we can see the two primary views of consistency checking in an understandable fashion. Second, early TM systems tended toward validation while newer TM systems tend toward invalidation. This makes considering both viewpoints practical. Third, both validation and invalidation perform well under different circumstances. By considering both types, we can help extend their current understanding to user-defined priority-based systems as well. Finally, __Boost_STM__ supports both commit-time validation and commit-time invalidation.
+
+__Boost_STM__ extensible contention manager supports two types of management: abort behavior management and conflict resolution management. The abort behavior interfaces are somewhat novel compared to prior work, in that they allow __Boost_STM_s__ contention manager to decide how the system should behave when a transaction must abort. These interfaces, shown in bellow, were added as it was determined that not all aborted transactions should behave in the same manner. For example, some transactions which have extremely large read and write sets, should perhaps sleep for some period of time before running again. Other transactions which have already high priorities, should perhaps receive larger priority boosts.
+
+ class base_contention_manager {
+ public:
+ virtual void abort_on_new(transaction const &t) = 0;
+ virtual void abort_on_delete(transaction const &t, base_transaction_object const &in) = 0;
+ virtual void abort_on_read(transaction const &t, base_transaction_object const &in) = 0;
+ virtual void abort_on_write(transaction &t, base_transaction_object const &in) = 0;
+ // conflict interfaces removed
+ };
+
+The interfaces shown above do not manage any memory contention, instead they only handle how required aborts behave.
+
+The second type of __Boost_STM__ contention management interfaces is shown in below.
+
+ class base_contention_manager
+ {
+ public:
+ // abort interfaces removed
+ virtual bool abort_before_commit(transaction const &t) = 0;
+ virtual bool permission_to_abort(transaction const &lhs, transaction const &rhs) = 0;
+ };
+
+These interfaces implement true management of memory conflicts. The two interfaces shown: abort_before_commit() and permission_to_abort() enable two fundamentally different types of consistency checking. abort_before_commit() is called when __Boost_STM__ is performing validating consistency checking, while permission_to_abort() is called when __Boost_STM__ is performing invalidating consistency checking. Both APIs are called internally at different points in the transaction's commit phase.

[endsect]
+
[section Lock-aware transaction]

+Transactional memory (TM) has garnered significant interest as an alternative to existing concurrency methods due to its simplified programming model, natural composition characteristics and native support of optimistic concurrency. Yet, mutual exclusion locks are ubiquitous in existing parallel software due to their fast execution, inherent property for irreversible operations and long-standing underlying support in modern instruction set architectures (ISAs). For transactions to become practical, lock-based and TM-based concurrency methods must be unified into a single model.
+
+__Boost_STM__ presents a lock-aware transactional memory (LATM) solution with a deliberate library-based approach. Our LATM system supports locks inside of transactions (LiT) and locks outside of transactions (LoT) while preserving the original programmer-intended locking structure. Our solution provides three policies with varying degrees of performance and required programming. The most basic LATM policy enables transactionlock correctness without any programming overhead, while improved performance can be achieved by programmer-specified conflicts between locks and transactions. The differences in LATM policy performance are presented through a number of experimental benchmarks on .
+
+[heading Introduction]
+
+Yet, for all of the benefits of transactional programming, its native inoperability with mutual exclusion locks is a major obstacle to its adoption as a practical solution. Mutual exclusion (implemented through locks) is arguably the most predominant form of thread synchronization used in parallel software, yet its native incompatibility with transactions places a considerable restriction on the practical use of TM in real-world software.
+
+A TM system that is cooperative with locks can extend the lifetime and improve the behavior of previously generated parallel programs. __Boost_STM__ C++ library is a lock-aware transactional memory (LATM) system supporting the simultaneous execution of transactions and locks. Of critical importance is that the extended __Boost_STM__ LATM system naturally supports lock-based composition for locks placed inside of transactions (LiT), a characteristic previously unavailable in locks. The LATM policies present in __Boost_STM__ are implemented with software library limitations as a central concern. While novel operating system (OS)-level and language-based transaction-lock cooperative models have been previously found, these implementations use constructs not available in library-based STM systems. While useful, the previously identified OS-level and language-based solutions do not address the critical need for a transaction-lock unified model expressed entirely within the limitations of a software library. In l
anguages that are unlikely to be extended, such as C++, and development environments bound to specific constraints, such as a particular compiler or OS, library based solutions are paramount as they present practical solutions within industry-based constraints. Our approach presents a novel library-based LATM solution aimed at addressing these concerns. __Boost_STM__ makes the following contributions:
+
+# Extension of the __Boost_STM__ library for support of locks outside of transactions (LoT) and locks inside of transactions (LiT).
+
+# Proof that an LATM LiT system naturally enables lock composition. Analytical examples are examined that show LiT composable locks demonstrating atomicity, isolation and consistency as well as deadlock avoidance.
+
+# Introduction of three novel LATM policies: full lock protection, TM-lock protection, and TX-lock protection. Each LATM policy provides different programming / performance trade offs. Experimental results are provided which highlight the performance and programming differences of the three LATM policies.
+
+[heading Background]
+
+Transaction-lock interaction does not natively exhibit shared memory consistency and correctness due to differences in underlying critical section semantics. Strongly and weakly isolated transactional memory systems are susceptible to incorrect execution when used with pessimistic critical sections.
+
+Mutual exclusion locks use pessimistic critical section semantics; execution of a lock-controlled critical section is limited to one thread and guarantees the executing thread has mutually exclusive (isolated) access to the critical section code region. Transactions use optimistic critical section semantics; transaction controlled critical sections support unlimited concurrent thread execution. Shared memory conflicts arising from simultaneous transaction execution are handled by the TM system during the commit phase of the transaction. Optimistic critical sections and pessimistic critical sections are natively inoperable due to their contradictive semantics as demonstrated in the below example:
+
+Lock and transaction violation (code).
+
+ 1 native_trans<int> x;
+ 2
+ 3 int lock_dec() {
+ 4 lock(L1);
+ 5 int val = --x;
+ 6 unlock(L1);
+ 7 return val;
+ 8 }
+ 9
+ 10 void tx_inc() {
+ 11 for (transaction t;;t.restart())
+ 12 try {
+ 13 ++t.write(x);
+ 14 t.end(); break;
+ 15 } catch (aborted_tx &) {}
+ 16 }
+
+Without an intervening system, thread T1 executing lock_dec() and thread T2 executing tx_inc() are not guaranteed to operate consistently, as they would if each function were run in a lock-only or transaction-only system, respectively. The following example demonstrates how the correctness of the above code is violated from a deferred update and direct update standpoint.
+
+Deferred Update Lock/Transaction Violation. A deferred update TM system stores transactional writes off to the side, updating global memory once the transaction commits. A deferred update system can exhibit an inconsistency in the above code in the following way. Given: x = 0, thread T1 executes lock_dec() and thread T2 executes tx_inc(). T2 executes line 10 - the first half of line 13 (storing a transactional value for x = 0, but not performing the increment). T1 executes lines 3-5 (global x = -1). T2 executes the remainder of line 13 and line 14 (++x on its stored reference of 0, setting its local x = 1) and then commits. T1 executes lines 6-7. The resulting global state of x = 1 is incorrect; x = 0 is correct as one thread has incremented it and one thread has decremented it.
+
+Direct Update Lock/Transaction Violation. A direct update TM system stores transactional writes directly in global memory, storing an original backup copy off to the side in the event the transaction must be unwound. In a direct update system, threads T1 and T2 can exhibit inconsistencies using the code shown above in a variety of ways; T1 executes line 3 - the first half of line 5 (decrementing x, but not setting val). T2 executes lines 10-13 (incrementing the global x and creating a restore point of x = -1). T1 executes the remainder of line 5 (val = 0). T2 executes line 14, but is required to abort, restoring x to -1. T1 completes and returns val = 0 which is incorrect. T2 never committed its x = 0 and has not successfully committed, therefore, x has never correctly been set to 0.
+
+Overcoming Transaction-Lock Inoperability
+
+In order for transactions and locks to cooperate, transactions must adhere to a single mutual exclusion rule: Mutual exclusion semantics require that instructions within a mutex guarded critical section be limited to <=1 simultaneous thread of execution.
+
+Our LATM implementation adheres to this rule and is discussed in two high-level views:
+
+# locks outside of transactions (LoT) and
+# locks inside of transactions (LiT).
+
+__Boost_STM__ supports lock-aware transactions by supplying a pass-through interface that is used in place of prior locking calls.
+
+The __Boost_STM__ locking API is used to perform the additional transaction-lock communication before or after the pthreads interface is called. In all cases, the __Boost_STM__ pass-through interface results in at least one corresponding call to the appropriated interface to lock, try to lock or unlock the mutual exclusion lock. Further details are provided in later sections.
+
+[heading Locks Outside of Transactions (LoT)]
+
+Locks outside of transactions (LoT) are scenarios where a pessimistic critical section of a lock is executed in a thread T1 while an optimistic critical section of a transaction is executed in a thread T2, simultaneously. Thread T1's lock-based pessimistic critical section is entirely outside of thread T2's transaction, thus the term locks outside of transactions or LoT. Figure 5 sets up a running LoT example, used throughout this section, by constructing six functions which are simultaneously executed by six threads. Three of the functions in the below example, tx1(), tx2() and tx3(), are transaction-based, while the other three functions, lock1(), lock2() and lock3(), are lock-based. The functions tx1(), tx2() and lock3() do not have any memory conflict with any other transaction-based or lock-based function and should therefore be able to run concurrently with any of the other functions. However, certain LoT policies inhibit the execution of these nonconflicting functions; details of such inhibited behav
ior is explained in the following subsections. The below example is used throughout this section to illustrate the differences in the LoT policies.
+
+ 1 native_trans<int> arr1[99], arr2[99];
+ 2
+ 3 void tx1() { /* no conflict */ }
+ 4 void tx2() { /* no conflict */ }
+ 5 void tx3() {
+ 6 for (transaction t;;t.restart())
+ 7 try {
+ 8 for (int i = 0; i < 99; ++i)
+ 9 {
+ 10 ++t.w(arr1[i]).value();
+ 11 ++t.w(arr2[i]).value();
+ 12 }
+ 13 t.end(); break;
+ 14 } catch (aborted_tx&) {}
+ 15 }
+ 16
+ 17 int lock1() {
+ 18 transaction::lock(L1); int sum = 0;
+ 19 for (int i = 0; i < 99; ++i) sum += arr1[i];
+ 20 transaction::unlock(L1); return sum;
+ 21 }
+ 22 int lock2() {
+ 23 transaction::lock(L2); int sum = 0;
+ 24 for (int i = 0; i < 99; ++i) sum += arr2[i];
+ 25 transaction::unlock(L2); return sum;
+ 26 }
+ 27 int lock3() { /* no conflict */ }
+
+[heading LoT Full Lock Protection]
+
+The most basic implementation of transaction-lock cooperation, what we call full lock protection, is to enforce all transactions to commit or abort before a lock's critical section is executed. All locks outside of transactions are protected from transactions violating their critical section execution by disallowing transactions to run in conjunction with locks. Transactions are stalled until all LoT critical sections are complete and their corresponding locks are released.
+
+An example of full lock protection is shown in Figure 6 using the previously described six threaded model. Full lock protection has no programmer requirements; no new code is required, aside from alteration of existing locking code to use the LATM passthrough interfaces. Additionally, an understanding of how the locks behave within the system to enable transaction-lock cooperation is also not needed. However, full lock protection suffers some performance penalties. As seen in Figure 6, T1 ?? T3 are blocked for the entire duration of the critical sections obtained in T4 ?? T6, since full lock protection prevents any transactions from running while LoTs are obtained. Although T3 does conflict with T4 ?? T5, T6's critical section does not interfere with any of the transactions and should therefore not prevent any transactions from running concurrently; TM-lock protection, the next level of lock protection, is able to avoid such unnecessary stalling.
+
+[heading LoT TM-Lock Protection]
+
+TM-lock protection is slightly more complex than full lock protection, yet it can yield better overall system performance. TMlock protection works in the following way: locks which can conflict with transactions are identified by the programmer at startup. Once a conflicting LoT is acquired, all in-flight transactions are either committed or aborted. Transactions are then blocked until the conflicting lock-based critical sections are completed and released. Locks that do not conflict with transactions do not cause any transactions to stall.
+
+The identification of locks that can conflict with transactions requires the programmer to (1) write new code and (2) have a basic understanding of the software system. Due to this, the requirements of TM-lock protection are greater on the end programmer. The trade-off for higher programmer requirements is greater overall system performance.
+
+TM-lock protection addresses the problem of transactions unnecessarily stalled when T6 is executing. When using TM-lock protection, the end programmer must explicitly express which locks can conflict with the TM system. In this example, locks L1 and L2 from threads T4 and T5 conflict with tx3 in thread T3. The end programmer would explicitly label these locks as conflicting in the following way:
+
+ 1 transaction::do_tm_conflicting_lock_protection();
+ 2 transaction::add_tm_conflicting_lock(L1);
+ 3 transaction::add_tm_conflicting_lock(L2);
+
+As shown in the six threaded example, TM-lock protection shortens the overall TM run-time by allowing T1 ?? T3 to restart their transactions as soon as L2's critical section is completed. Yet, there still exists unnecessary stalls in threads T1 and T2 as their associated transactions do not conflict with any of the lock-based critical sections of T4 ??T6. The remaining unnecessary stalls are resolved by using TX-lock protection, the third lock protection policy.
+
+[heading LoT TX-Lock Protection]
+
+TX-lock protection enables maximum performance throughput by identifying only true conflicts as they exist per transaction. TXlock protection is similar to TM-lock protection except rather than requiring conflicting locks be identified at a general TM-level, conflicting locks are identified at a transaction-level. While this level of protection yields the highest level of performance, it also requires the greatest level of familiarity of the locks within the system and the most hand-crafted code.
+
+An example of TX-lock protection is in Figure 8. By using TX-lock protection and explicitly identifying conflicting locks per transaction, the system only stalls for true conflicts, increasing overall system performance. The code required for correct TX-lock protection in the prior six threaded example is shown below by extending the original tx3() implementation:
+
+ 1 void tx3() {
+ 2 for (transaction t;;t.restart())
+ 3 try {
+ 4 // identify conflicting locks
+ 5 t.add_tx_conflicting_lock(L1);
+ 6 t.add_tx_conflicting_lock(L2);
+ 7 for (int i = 0; i < 99; ++i)
+ 8 {
+ 9 ++t.w(arr1[i]).value();
+ 10 ++t.w(arr2[i]).value();
+ 11 }
+ 12 t.end(); break;
+ 13 } catch (aborted_tx&) {}
+ 14 }
+
+Using TX-lock protection, threads T1 and T2 are no longer stalled when threads T4 and T5 lock their associated locks, L1 and L2. In fact, only thread T3 (the only true conflict) is stalled while the critical sections created by L1 and L2 are executing, resulting in the highest transaction-lock cooperative performance while still adhering to the rule.
+
+
+[heading Locks Inside of Transactions (LiT)]
+
+Locks inside of transactions (LiT) are scenarios where a lock-based pessimistic critical section is executed partially or completely inside a transaction. Only two of the three possible LiT scenarios are supported by our work: (1) pessimistic critical sections are encapsulated entirely within a transaction or (2) pessimistic critical sections start inside a transaction but end after the transaction has terminated.We do not support LiT scenarios where pessimistic critical sections start before a transaction begins, having the front-end of the transaction encapsulated by the pessimistic critical section. The reason to disallow such behavior is to avoid deadlocks.
+
+Consider the following scenario. Thread T1 has an in-flight irrevocable transaction Tx1 and thread T2, after obtaining lock L2, starts a transaction Tx2. Tx2 is not allowed to make forward progress until it is made irrevocable (details to follow). Tx1 is already in-flight and irrevocable. Since two irrevocable transactions cannot run simultaneously as they are not guaranteed to be devoid of conflicts with one another, Tx2 must stall until Tx1 completes. If irrevocable transaction Tx1 requires lock L2 to complete its work the system will deadlock. Tx1 cannot make forward progress due to its dependency upon L2 (currently held by Tx2) and Tx2 cannot make forward progress as it requires Tx1 to complete before it can run. As such, LiT scenarios where locks encapsulate the front-end of a transaction are disallowed; our implementation immediately throws an exception when this behavior is detected.
+
+Irrevocable and Isolated Transactions
+
+The LiT algorithms use the same policies as the LoT algorithms: full lock protection, TM-lock protection and TX-lock protection. Locks inside of transactions have the same characteristics as normal mutual exclusion locks, and Lemma 1 must be followed in order to ensure correctness. Since the LiT algorithms use locks acquired inside of transactions and these locks are not guaranteed to have failure atomicity as transactions do, the containing transactions must become irrevocable (see Lemma 2). Irrevocable transactions, characterized by T(irrevocable) = true, are transactions that cannot be aborted. The concept of irrevocable (or inevitable) transactions is not new; Welc et al. and Spear et al. have shown these types of transactions to be of significant importance as well as having a variety of practical uses [17, 19]. We extend the prior work of Welc et al. and Spear et al. by using irrevocable transactions to enable pessimistic critical sections within transactions, as well as to create composable locks wit
hin transactions. In addition to irrevocable transactions, the LiT full lock protection and TM-lock protection require a new type of transaction, one that we term as an isolated transaction. Isolated transactions, characterized by T(isolated) = true, are transactions that cannot be aborted and require that no other type of transaction run along side it simultaneously. Isolated transactions can be viewed as a superset of irrevocable transactions; isolated transactions have the properties of irrevocable transactions and must be run in isolation. To demonstrate how the LiT algorithms work, consider the six threaded example shown in Figure 12.
+
+3 LiT Transaction Threads, 3 Locking Threads.
+
+ 1 native_trans<int> g1, g2, g3, g4;
+ 2
+ 3 void tx1() { /* no conflict */ }
+ 4 void tx2() {
+ 5 transaction::add_tm_conflicting_lock(L2);
+ 6 for (transaction t;;t.restart())
+ 7 try {
+ 8 t.add_tx_conflicting_lock(L2);
+ 9 inc2();
+ 10 t.end(); break;
+ 11 } catch (aborted_tx&) {}
+ 12 }
+ 13 void tx3() {
+ 14 transaction::add_tm_conflicting_lock(L3);
+ 15 for (transaction t;;t.restart())
+ 16 try {
+ 17 t.add_tx_conflicting_lock(L3);
+ 18 inc3();
+ 19 t.end(); break;
+ 20 } catch (aborted_tx&) {}
+ 21 }
+ 22
+ 23 void inc2() {
+ 24 lock(L2); ++g2.value(); unlock(L2);
+ 25 }
+ 26 void inc3() {
+ 27 lock(L3); ++g3.value(); unlock(L3);
+ 28 }
+ 29 void inc4() { /* no conflict */ }
+
+In Figure 12 thread T1 executes tx1(), T2 executes tx2(), T3 executes tx3(), T4 executes inc2(), T5 executes inc3() and T6 executes inc4(). Threads T1 (tx1()) and T6 (inc4()) do not conflict with any other thread, yet their execution can be inhibited by other threads based on the LiT policy employed. Thread T2 has a true conflict with thread T4 (both threads call inc2()) and thread T3 has a true conflict with thread T5 (both threads call inc3()). A staggered start time is used in the coming diagrams: T1 starts, followed by T2, T3, T4, T5 and finally T6.We label the LiT threads based on the locks they acquire: tx1 acquires lock L1, thread tx2 acquires lock L2 and thread tx3 acquires lock L3. The same taxonomy is used for locking threads: thread lockL2 acquires lock L2, thread lockL3 acquires lock L3 and thread lockL4 acquires lock L4.
+
+In Figure 12, both add_tm_conflicting_lock() and add_tx_conflicting_lock() are present. If the system is using TM-lock protection only the add_tm_conflicting_lock() is necessary, whereas if the system is using TX-lock protection only the add_tx_conflicting_lock() is necessary. If neither TMlock or TX-lock protection is in use, neither call is needed. These interfaces are supplied for the completeness of the example.
+
+[heading LiT Full-Lock Protection]
+
+Figure 13 demonstrates how the six threads interact using the full lock protection policy, as well as showing policy conflicts in comparison to true conflicts. The LiT full lock protection algorithm requires that any transaction that has a lock inside of it be run as an isolated transaction. Prior to a lock inside the transaction being obtained, all other in-flight transactions are aborted or committed and all currently held locks must execute through release. Future attempts to obtain locks outside of the isolated transaction are prevented until the transaction commits. This behavior is required as the system must assume (1) all external locks can conflict with the isolated transaction, so no external locks can be obtained; and (2) all external transactions can conflict with the LiT transaction, and therefore no external transactions can execute.
+
+For Figure 13, once tx2 begins, tx1 is stalled as tx2 must run as an isolated transaction. Due to tx2's isolation, tx3 is also stalled. Both lockL2 and lockL3 are also stalled because full lock protection disallows transactions from running while LoT locks are obtained; as tx2 is an isolated transaction, the threads attempting to lock L2 and L3 are stalled until tx2 completes. When tx2 completes, tx3 is started as it has stalled for the longest amount of time. The thread executing lockL4 is stalled until tx3 completes. When tx3 completes, tx1, lockL2, lockL3 and lockL4 are all allowed to resume.
+
+[heading LiT TM-Lock Protection]
+
+Like full lock protection, LiT TM-lock protection runs transactions encapsulating locks in isolation. However, LiT TM-lock protection also requires the end programmer to identify locks obtained within any transaction prior to transaction execution (just as LoT TM-lock protection). Unlike LiT full lock protection, TM-lock protection allows non-conflicting LoT locks to execute along side LiT locks, increasing overall system throughput.
+
+As shown in Figure 14 TM-lock protection reduces the overall policy-induced conflicting time to a range closer to the true conflicting time. Since tx2 and tx3 are true conflicts with lockL2 and lockL3, lockL2 and lockL3 must stall while tx2 and tx3 are executing. However, lockL4 does not conflict with either tx2 or tx3 and as such, should not be stalled while the LiT transactions are inflight. TM-lock protection correctly identifies this conflict as false, allowing lockL4's execution to be unimpeded by tx2 and tx3's execution.
+
+Three problems still exist in the LiT example: (1) tx1 is stalled by tx2 and tx3, (2) lockL2 is stalled by tx3 and (3) lockL3 is stalled by tx2. Ideally, none of these stalls should occur as none represent true conflicts. All three false conflicts are avoided by using the following LiT protection policy, LiT TX-lock protection.
+
+[heading LiT TX-Lock Protection]
+
+Like LoT TX-lock protection, the Lit TX-lock protection algorithm allows for the highest throughput of both transactions and locks while requiring the highest level of programmer involvement and system understanding. Unlike both prior LiT algorithms, TX-lock protection allows LiT transactions to run as irrevocable transactions, rather than isolated transactions. This optimization can increase overall system throughput substantially if other revocable transactions can be run along side the LiT transaction.
+
+With LiT TX-lock protection, the programmer specifies locking conflicts for each transaction. In Figure 12's case, the programmer would specify that tx2 conflicts with L2 and tx3 conflicts with L3. By specifying true transactional conflicts with locks, the TM system can relax the requirement of running LiT transactions in isolation and instead run them as irrevocable. While no two irrevocable transactions can be run simultaneously, as they may conflict with each other (resulting in a violation of their irrevocable characteristic), other non-irrevocable transactions can be run along side them, improving overall system throughput.
+
+The run-time result of using LiT TX-lock protection is shown in Figure 15. Transaction tx1 is able to run without being stalled as it has no conflicts with other transactions or locks. Transaction tx2 is run as an irrevocable transaction, rather than as an isolated transaction, allowing tx1 to run along side it. Irrevocable transaction tx3 is prevented from starting as irrevocable transaction tx2 is already in-flight. Likewise, lockL2 cannot lock L2 since tx2 conflicts with L2 and allowing lockL2 to proceed would require tx2 to abort. Since tx2 is irrevocable (e.g. unabortable), lockL2 is stalled. However, lockL3 and lockL4 start immediately, since neither conflict with any in-flight transaction. When tx2 completes, both tx3 and lockL2 can try to proceed. Transaction tx3 is stalled by lockL3, but lockL2 executes immediately as its conflict with tx2 has passed. When lockL3 completes tx3 begins and runs through to completion.
+
+
+[heading Lock Composition]
+
+Any TM system that supports locks inside of transactions must ensure the pessimistic critical sections of the locks inside of transactions are not violated. This is achieved by making the containing transactions either isolated or irrevocable once the lock inside the transaction is obtained. Lemma 2 proves the necessity of the irrevocability characteristic for LiT transactions.
+
+Locks Inside of Transactions Lemma 2. Any lock L obtained during an in-flight transaction Tif requires Tif be immediately and permanently promoted to an irrevocable transaction, characterized by Tif (irrevocable) = true, which cannot be aborted.
+
+Proof. (Contradiction) Given: threads T1 and T2 execute inc() and get() from Figure 19, respectively and variables x = 0, y = 0. ++x and ++y operations within inc() are unguarded direct access variable operations that perform no transactional undo or redo logging operation; these operations are irreversible (e.g. normal pessimistic critical section operations). The atomic property of any transaction T requires all memory operations of T are committed or none are committed.
+
+Execution: T1 starts transaction Tx1 (Tx1(irrevocable) = false) and completely executes lines 3-7, setting x = 1. T2 executes 13- 14, obtains lock L1, released by Tx1 and flags Tx1 to abort due to its identified lock conflict. T2 reads x = 1 and y = 0, unlocks L1 and returns. Tx1 tries to lock L1, but instead is required to abort, causing the atomic transactional property of Tx1 to be violated since ++x has been performed and will not be undone when Tx1 is aborted.
+
+ 1 int x = 0, y = 0;
+ 2
+ 3 void inc() {
+ 4 for (transaction t;;t.restart())
+ 5 try {
+ 6 t.add_conflicting_lock(L1);
+ 7 lock(L1); ++x; unlock(L1);
+ 8 lock(L1); ++y; unlock(L1);
+ 9 t.end(); break;
+ 10 } catch (aborted_tx&) {}
+ 11 }
+ 12
+ 13 void get(int &retX, int &retY) {
+ 14 lock(L1);
+ 15 retX = x; retY = y;
+ 16 unlock(L1);
+ 17 }
+
+ Figure 19. Violating LiT Lemma 2.
+
+Referring again to Figure 19, now consider the correct execution (following Lemma 2) of threads T1 and T2 of inc() and get(), respectively, with variables x = 0, y = 0. T1 starts transaction Tx1 and executes lines 3-7, setting x = 1 and Tx1(irrevocable) = true. T2 executes 13-14, but fails to obtain lock L1 even though it is released by Tx1. T2 fails to obtain lock L1 because in order to do so would require Tx1 be aborted as it has flagged itself as conflicting with lock L1 via t.add_conflicting_lock(L1). Yet, Tx1 cannot be aborted since Tx1(irrevocable) = true. T2 stalls until Tx1 completes, setting x = 1, y = 1. T2 then executes, obtaining the necessary locks and returning x = 1 and y = 1 the atomically correct values for x and y (equivalent values) given transaction Tx1.
+
+By incorporating both Lemma 1 and 2, locks inside of transactions naturally compose and emit database ACI characteristics; atomic, consistent and isolated. They are atomic (all operations commit): once a lock is obtained inside a transaction, the transaction becomes irrevocable. This ensures that all operations will commit, irrespective of how many locks are obtained within the LiT transaction. They are consistent: no conflicting locks or transactions can run along side the irrevocable LiT transaction, ensuring memory correctness. They are isolated: conflicting locks or transactions are disallowed from running in conjunction with an LiT transaction, preventing its state from being visible before it commits. Even when a lock is released inside an LiT transaction, other threads remain unable to obtain the lock until the transaction commits.
+
+[heading Criticality of LiT Lock Composition]
+
+The composable nature of LiT locks is critical to the incremental adoption of transactions into pre-existing, lock-based parallel software. To understand this, consider a multi-threaded linked list implemented using mutual exclusion locks. The linked list software is mature, thoroughly tested and contains lookup(), insert() and remove() methods. A software designer wishes to extend the linked list's behavior to include a move() operation. The move() operation behaves in the following way: if element A exists in the list and element B does not exist in the list, element A is removed from the list and element B is inserted into the list.With LiT lock composition, the move() operation could be implemented entirely from the previously built locking implementation. Figure 20 demonstrates how this is achieved within the __Boost_STM__ LATM extension.
+
+ 1 bool move(node const &A, node const &B) {
+ 2 // compose locking operations: lookup(), remove()
+ 3 // & insert() in an irrevocable & indivisible tx
+ 4 // to make a new transaction-based move() method
+ 5 for (transaction t;;t.restart())
+ 6 try {
+ 7 t.add_tx_conflicting_lock(list_lock_);
+ 8 // lookup() uses lock list_lock_
+ 9 if (lookup(A) && !lookup(B)) {
+ 10 remove(A); // uses lock list_lock_
+ 11 insert(B); // uses lock list_lock_
+ 12 }
+ 13 else return false;
+ 14
+ 15 t.end(); return true;
+ 16 } catch (aborted_tx&) {}
+ 17 }
+
+ Figure 20. Move Implemented with LiT Lock Composition.
+
+The move() method in Figure 20 is viewed by other threads as an indivisible operation whose intermediate state is isolated from other threads, even though it contains four disjoint pessimistic critical section invocations (e.g. two lookups, a remove and an insert). Even when list_lock_ is released intermittently during the transaction execution, other threads are prevented from obtaining it until the transaction commits. This behavior ensures each pessimistic critical section within the transaction is prevented from being viewed independently. Once the transaction commits other threads can obtain list_lock_ and view the cumulative affects of the move() operation.
+
+[heading Understanding LiT Lock Composition]
+
+Figure 21 shows a transfer function implemented using LiT lock composition. This example was chosen because the code sample is small enough to be presented in full (not possible with the prior linked list move() example). Figure 21 uses LiT TX-lock protection and contains two locks inside of the same transaction that are subsumed by the transaction. The transaction composes the two separate lock-based critical sections into an atomically viewed and isolated operation.
+
+Consider threads T1 executing lit_transfer(1), T2 executing get1() and T3 executing get2() with x1 = 0 and x2 = 0 in the time line shown in Figure 22. The dotted vertical lines in the conflicting lock time in Figure 22 demonstrate when T1's transaction tx1 obtains and releases locks L1 and L2 with regard to T2 and T3. Thread T1 starts transaction tx1 and adds L1 and L2 to tx1's conflicting lock list. Next, tx1 locks L2 and becomes irrevocable (Lemma 2). Thread T2 then attempts to lock L1, however, since L1 conflicts with tx1 and tx1 is irrevocable, thread T2 is disallowed from aborting tx1 and is therefore prevented from obtaining L1, stalling instead. After tx1 sets x2 = ??1 and unlocks L2, thread T3 tries to lock L1, however, it is disallowed because L1 is on tx1's conflicting lock list and tx1 is irrevocable. Thus, thread T3 is stalled. Transaction tx1 then locks L1, sets x1 = 1 and unlocks
+
+ 1 int x1 = 0, x2 = 0;
+ 2
+ 3 void lit_transfer(int transfer) {
+ 4 for (transaction t;;t.restart())
+ 5 try {
+ 6 t.add_tx_conflicting_lock(L1);
+ 7 t.add_tx_conflicting_lock(L2);
+ 8
+ 9 lock(L2); x2 -= transfer; unlock(L2);
+ 10 lock(L1); x1 += transfer; unlock(L1);
+ 11
+ 12 t.end(); break;
+ 13 } catch (aborted_tx&) {}
+ 14 }
+ 15
+ 16 void get1and2(int& val1, int& val2) {
+ 17 lock(L1); lock(L2);
+ 18 val1 = x1; val2 = x2;
+ 19 unlock(L2); unlock(L1);
+ 20 }
+ 21 void get1(int& val) {
+ 22 lock(L1); val = x1; unlock(L1);
+ 23 }
+ 24 void get2(int& val) {
+ 25 lock(L2); val = x2; unlock(L2);
+ 26 }
+
+ Figure 21. LiT Transaction and Two Locking Getters.
+
+L1. When tx1 commits, threads T2 and T3 are unstalled and read x1 = 1 and x2 = ??1, respectively, the correct atomic values for the lit_transfer(1) operation with lock composition.
+
+Figure 22. Composed LiT Example using TX-Lock Protection.
+
+In the above scenario, both T2 and T3 tried to acquire the unlocked locks L1 and L2 but failed due to tx1's irrevocability even though the locks themselves were available. The characteristic of disallowing lock acquisition even when locks are available is a primary attribute of LiT transactions. This characteristic is not present in systems which use locks alone, and is a key attribute to enabling lock composition. As demonstrated earlier with LoT transactions, a lock and a transaction conflicting with the same lock cannot both execute simultaneously. LiT transactions use this same behavior and extend it to favor transactions over locks once a lock is obtained inside of a transaction, making it irrevocable. By restricting access of locks to in-flight LiT transactions which have acquired (and then released) them, the system ensures any remaining behavior not yet performed by the transaction will occur prior to other threads obtaining such released locks. This ensures
+
+all the pessimistic critical sections within an LiT transaction are executed in isolation and consistently without memory interference from outside locking threads. Note that this was the case when T3 tried to acquire lock L2 even after transaction tx1 had completed
+its operations on its shared memory x2.
+
+[heading LiT Lock Identification]
+
+LiT TX-lock protection requires that all transaction conflicting locks, those locks used directly inside of transactions, be identified prior to any lock being obtained within the transaction; failure to do so can lead to deadlocks. A simple example of how adding conflicting locks as they are obtained inside of transactions can lead to deadlocks can be derived from Figure 21. If lit_transfer() is executed without adding conflicting locks (e.g. no calls to add_conflicting_lock()), the following deadlock is possible. Thread T1 executes lines 3-5, skips lines 6-7 (the conflict calls) and executes line 9 locking L2 and adding it to its conflicting lock list. Thread T2 then executes lines 16 and part of line 17 of get1and2(), locking L1.Without the transactional code identifying L1 as a conflict, the TM system would not disallow T2 from locking L1. The system is now deadlocked. T2 cannot proceed with locking L2 as L2 has been added to T1 conflicting lock list, yet T1 cannot proceed as lock L1 is held by T2.
+
+These deadlocks scenarios are overcome by requiring the LiT TM-lock or TX-lock protection to list all conflicting locks prior to obtaining any locks within transactions. Attempting to use locks inside of transactions without first identifying them as conflicts causes __Boost_STM__ to throw an exception informing the programmer of the missed conflicting lock and how to correct the error. Recycling the same scenario as above with conflicting locks identified at the start of the transaction avoids deadlocks. For example, thread T1 adds locks L1 and L2 to its conflicting lock list. It then executes lines 3-8 and part of line 9, locking L2 (but not unlocking it). Thread T2 executes lines 16 and part of 17, trying to lock L1, and sees T1's transaction as conflicting. Thread T2 tries to abort T1's transaction, but is disallowed as the transaction is irrevocable (see Lemma 2). T2 is therefore stalled prior to obtaining lock L1. T1 continues and executes the remainder of line 9-12, obtaining and releasing lock L1 an
d finally committing. Once T1's transaction has committed, T2 is allowed to resume and runs to completion.
+
+[endsect]
+
+[section Unrecoverable transactions to manage with I/O]
+
[endsect]

[endsect]
@@ -192,7 +555,7 @@

Native Language Compatibility. Some existing STM systems require specific language extensions or compiler support for their proposed system to work. Other systems instead violate native language pragmatics by reducing or removing type-safety altogether. Yet other system's transactional functionality is significantly reliant on the preprocessor.

-__Boost_STM__ is built with native language compatibility as a top priority - as such, it does not require language extensions or violate natural language semantics. Native language compatibility is a foremost concern due to C++0x set to specifically resist language extensions [29]. While in other languages, such as Java, STM systems which require language extensions may be practical, within C++ this same approach seems unrealistic. Thus, there is a very practical need for a native language ready STM solution for C++.
+__Boost_STM__ is built with native language compatibility as a top priority - as such, it does not require language extensions or violate natural language semantics. Native language compatibility is a foremost concern due to C++0x set to specifically resist language extensions. While in other languages, such as Java, STM systems which require language extensions may be practical, within C++ this same approach seems unrealistic. Thus, there is a very practical need for a native language ready STM solution for C++.

[endsect]

@@ -217,9 +580,92 @@

[endsect]

+
+[section Mixin versus wrapper helpers]
+
+__Boost_STM_s__ provides some helper classes to make transactional objects. The user should use each one on a per case, taking in account the advantages and liabilities of each one.
+
+# mixin; transaction_object
+# intrinsic wrapper: transactional_object
+# extrinsic wrapper: transactional_reference_cache
+
+Next follows the features the user should question
+
+# Allows to use an existing class, for example std::pair class. Does the helper class allows the smart pointers to return an reference to an existing class?
+ * mixin: There is no mean
+ * intrinsic: the associated smart pointers to a transactional_object<std::pair> returns a std::pair reference
+ * extrinsic: This is exacly the role of the extrinsec approach
+# Allows to use an existing instance variable, for example a variable of type std::pair class. Does the helper class allows the smart pointers to return an reference to an existing class?
+ * mixin: There is no mean
+ * intrinsic: There is no mean
+ * extrinsic: This is exacly the role of the extrinsec approach
+# Works for class hierarchies. if D isa B, then helper<D> is a helper
+ * mixin: This is exactly the role of the extrinsec approach since we have added the base parameter (class B: mixin{} class D: mixin<D,B>{}).
+ * intrinsic: Not directly, we need to use some form of cast. clas D:B{}. intrinsic* ptr=new intrinsic<D>(); ????
+ * extrinsic: N/A because the helper is hidden
+# Allows to avoid the forwarding problem for base classes
+ * mixin: As the user defines its own class he can define the exact constructors avoiding the problem added the base parameter
+ * intrinsic: the wrapper must define generic constructors having the forwarding problem.
+ * extrinsic: N/A because the helper is hidden
+# Allows to avoid the forwarding problem for derived classes
+ * mixin: As the inheritance of the base class is done using the helper the base mixin must define generic constructors having the forwarding problem.
+ * intrinsic: the wrapper must define generic constructors having the forwarding problem.
+ * extrinsic: N/A because the helper is hidden
+# Performs optimally.
+ * mixin: optimal, only one allocation/copy
+ * intrinsic: optimal, only one allocation/copy
+ * extrinsic: instead of a single allocation/copy we need two, so no optimal
+
+The following table is a compilation of the preceding analysis:
+
+[table Comparaison with other STM systems
+ [
+ [[*feature]] [[*Mixin]] [[*Intrinsic Wrapper]] [[*Extrinsic Wrapper]]
+ ]
+ [
+ [[*existing class]] [[No]] [[*Yes]] [[*Yes]]
+ ]
+ [
+ [[*existing variable]] [[No]] [[No]] [[*Yes]]
+ ]
+ [
+ [[*existing class hierarchy]] [[No]] [[No]] [[*Yes]]
+ ]
+ [
+ [[*avoid the forwarding problem for base classes]] [[Yes]] [[No]] [[*Yes]]
+ ]
+ [
+ [[*avoid the forwarding problem for derived classes]] [[No]] [[No]] [[*Yes]]
+ ]
+ [
+ [[*Works for class hierarchies]] [[*Yes]] [[No]] [[*Yes]]
+ ]
+ [
+ [[*Performs optimaly]] [[*Yes]] [[*Yes]] [[No]]
+ ]
+]
+
+[endsect]
+
+[section Why __Boost_STM_s__ cache uses now memcpy instead of copy-constructor and assignement]
+
+Until version 0.3 __Boost_STM_s__ used the copy-constructor to clone a new object which will be used directly by the derreed update policy and as a backup by the direct update policy. This has some drawbacks:
+
+# Domain: Transactional object are limited to CopyConstructible objects
+# Exception safety: As the user copy-constructor and assignement can throw exceptions
+# Performances: Whole copy, either copy-constructor and assignement, of transactional objects could be expensive
+
+The following sections explain deeply this issues.
+
+[section Domain]
+
+It seems a hard limitation to force a STM user to make all its classes CopyConstructible and Assignable.
+
+[endsect]
+
[section Exception Safety]

-__Boost_STM__ fulfills Abrahams' basic exception safety guarantee for deferred updating, but cannot supply any exception safety guarantee for direct updating. The basic guarantee for exception safety states that if an exception is thrown, the operation may have side-effects but is in a consistent state. The basic guarantee is less strict than the strong guarantee which specifies if an exception is thrown there are no side-effects. The highest level of exception safety, above the strong guarantee, is the nothrow guarantee which disallows exceptions from being thrown entirely.
+With copy-constructor and assignement __Boost_STM__ fulfills Abrahams' basic exception safety guarantee for deferred updating, but cannot supply any exception safety guarantee for direct updating. The basic guarantee for exception safety states that if an exception is thrown, the operation may have side-effects but is in a consistent state. The basic guarantee is less strict than the strong guarantee which specifies if an exception is thrown there are no side-effects. The highest level of exception safety, above the strong guarantee, is the nothrow guarantee which disallows exceptions from being thrown entirely.

Within deferred updating, __Boost_STM__ can only afford to implement the basic guarantee because if memory is partially committed and then a user exception is thrown, no original state exists for the already committed memory. Therefore, already committed memory in a deferred updating system, must stay committed since no reverted original state can be used to revert the changes. To implement such a system would result in a substantial performance degradation to the overall system, effectively doubling memory size and copy operations. Due to these costs, a double-copy implementation is not performed and the basic guarantee for deferred updating is deemed acceptable.

@@ -227,46 +673,176 @@

[endsect]

+[section Performances]
+
+Another problem with the copy is that we will need to copy the whole logical object when what we need is just the phisical part, e.g. if copy is used to clone the transactional object, each time we modify a linked list, we will copy the entire list, even if only one node is modified.
+
+A pure transactional object is a transactional object that do not points to any non transactional object. For example, a transactional object including a std::string, is not a pure transactional object, because std::string has a pointer to a dynamically allocated memory which is not a transactional object. For these non pure transactional objects a copy will be needed. One way to limit this is to place every non pure transactional object on a separated class and add a pointer to it. So for example instead of doing
+
+class X {
+ std::string str;
+ // ... other fields
+
+};
+
+which will make X non pure TO, we can do
+
+class X {
+ tx_ptr<std::string> str_ptr; // owned pointer which is cloned when making a copy but not by the STM system.
+ // ... other fields
+
+};
+
+In this way X will be a pure TO poining to a non pure TO.
+
+[endsect]
+
+If memcpy is not portable we can consider specializing the clone and copy_state virtual functions.
+
+The user must state explicitly the TO that are not pure by overloading the cache_clone, cache_ ... . We can also define a trait.
+
+
+[endsect]
+
+
[section Move semantics]

-We solve the problem of commit-time and abort-time exceptions by using
-move semantics in place of copy semantics. The idea of moving is new to C++
-and will be available in the next version of the standard.
+When copying is needed we solve the problem of commit-time and abort-time exceptions by using move semantics in place of copy semantics when the class provided it. The idea of moving is new to C++ and will be available in the next version of the standard.

[endsect]

[section Parametric Polymorphism and Subtype Polymorphism]

Type
-abstraction in C++ to create general purpose code can be achieved in numerous ways. Some of these ways, such as the use of C++ template classes and template functions (parametric polymorphism), as well as inheritance (subtype polymorphism), are considered practical and robust ways to build general purpose functionality while still ensuring a certain degree of type-safety is maintained. C++ templates, also known as parametric polymorphism, exhibit the same type-safety as if the general purpose code was written specifically for the templated instantiated type. Inheritance, on the other hand, reduces type-safety to some degree, but gains run-time flexibility unachievable with C++ templates alone. Other mechanisms also exist to create general purpose code, such as void pointers or preprocessor macros, but are considered unsafe and error-prone [8] and thusly, not used in __Boost_STM__.
+abstraction in C++ to create general purpose code can be achieved in numerous ways. Some of these ways, such as the use of C++ template classes and template functions (parametric polymorphism), as well as inheritance (subtype polymorphism), are considered practical and robust ways to build general purpose functionality while still ensuring a certain degree of type-safety is maintained. C++ templates, also known as parametric polymorphism, exhibit the same type-safety as if the general purpose code was written specifically for the templated instantiated type. Inheritance, on the other hand, reduces type-safety to some degree, but gains run-time flexibility unachievable with C++ templates alone. Other mechanisms also exist to create general purpose code, such as void pointers or preprocessor macros, but are considered unsafe and error-prone and thusly, not used in __Boost_STM__.

__Boost_STM__ uses both parametric and subtype polymorphism throughout its internal implementation and exposed interfaces. In cases where strict type-safety can be achieved, C++ templates are used. In other cases where exact type-safety cannot be achieved without reducing __Boost_STM_s__ functionality, inheritance is used. All of these factors considered, __Boost_STM__ is a research library that requires type-safety to be a foremost concern, as its usage would hampered if type-safety was relaxed in areas where it could have been retained. As such, C++ templates are used due to their retention of full type information, in cases where inheritance would have also sufficed with a slight loss of type-safety.

[endsect]

-[section Language-like atomic transaction macro blocks]
+
+
+[section Language-like macro blocks]
+
+The synchronization primitives supported in __Boost_STM_s__ programming model are mutual exclusion locks, timed locks and transactions. Mutual exclusion locks have architectural support in all modern instruction set architectures and are widely considered the most common synchronization primitive [11]. Transactions, a parallel programming abstraction by Herlihy and Moss [10], are currently implemented in software with potential hardware support in the near future [4].
+
+
+[table Comparaison with other STM systems
+ [
+ [[*Keyword]] [[*Behavior]]
+ ]
+ [
+ [[*use_lock(L)]] [[*Acquires lock L and executes critical section. Supports single operations without {} scope construction such as, use_lock(L) foo()]]
+ ]
+ [
+ [[*use_timed_lock(MS, L)]] [[*Acquires timed lock L and executes a critical section based on MS millisecond timer. If the timer expires without obtaining lock L, an exception is thrown. This extension allows the exception to escape the parallel construct scope. Supports single operations without {} scope construction
+such as, use_timed_lock(1, L) foo()]]
+ ]
+ [
+ [[*try_timed_lock(MS, L)]] [[*Same as use_timed_lock(L), but exceptions are caught locally. Requires catch_lock_timeout(L) or lock_timeout]]
+ ]
+ [
+ [[*catch_lock_timeout(E)]] [[*Catches timed lock exception E thrown from try_timed_lock(L). Required to follow all try_timed_lock(L), unless followed by lock_timeout]]
+ ]
+ [
+ [[*lock_timeout]] [[*Catches and discards failed timer exception thrown from try_timed_lock(L). Required to follow all try_timed_lock(L), unless followed by catch_lock_timeout(E)]]
+ ]
+
+]
+
+Table 1. __Boost_STM__ Mutual Exclusion Locking Parallel Constructs.
+
+[heading Library-based Lock Implementations]
+
+Mutual exclusion locks, or just locks, ensure a programmerspecified set of operations are limited to one thread of execution [7, 11]. Lock-guarded operations, also known as pessimistic critical sections, require that all threads obtain a single-ownership flag before executing the guarded operations. If N threads simultaneously attempt to execute the same pessimistic critical section, one thread is allowed forward progress while the remaining N ?? 1 threads are stalled. An example of three distinct types of locking is shown in Figure 1.
+
+ 1 // mutual exclusion with lock()/unlock().
+ 2 pthread_mutex_lock(l);
+ 3 int ret = foo();
+ 4 pthread_mutex_unlock(l);
+ 5 return ret;
+
+or
+
+ 1 // mutual exclusion with automatic objects.
+ 2 {
+ 3 scoped_lock<pthread_mutex_t> lock(l);
+ 4 return foo(); // lock released
+ 5 }
+
+or
+
+ 1 // language-like mutual exclusion.
+ 2 use_lock(l) return foo(); // lock released
+
+ Figure 1. Library-based Lock Implementations.
+
+In Figure 1, the automatic object and language-like mutual exclusion interfaces are safer than the pthread_mutex_lock() and pthread_mutex_unlock() interfaces. If an exception is thrown from foo() after pthread_mutex_lock() is called, its corresponding pthread_mutex_unlock() will not be called causing the application to deadlock. Both the automatic object and language-like implementations avoid deadlock in the event of an exception thrown from foo(). However, these implementations have notable differences in programmatic scoping and programmer error.
+
+[heading Pitfalls in Scoping of Automatic Object Locks]
+
+A closer examination of the automatic object and language-like approaches to locking reveal differences in potential programmerinduced error. Figure 2 demonstrates a sequential locking order example, a common solution to complex fine-grained locking implementations, in which locks must be obtained in a specific sequential order to avoid deadlocking. If the scope ({}) operators are removed from Figure 2 the behavior of both the scoped_locks and the use_locks are changed. In the case of the scoped_locks, the automatic objects will no longer be terminated after operation_C() and they will thereby retain any locks acquired upon construction until the next immediate scope is terminated. In the case of the use_locks, the locks remain locked only for operation_A() and are then released. Both locking structures are changed to behave incorrectly when the scope operators ({}) are removed, but we believe programmers are less likely to accidentally remove the scope from the use_lock idiom than the scoped_lock.
+
+ 1 // mutual exclusion with automatic objects.
+ 2 {
+ 3 scoped_lock<pthread_mutex_t> lock1(L1);
+ 4 scoped_lock<pthread_mutex_t> lock2(L2);
+ 5 scoped_lock<pthread_mutex_t> lock3(L3);
+ 6 operation_A();
+ 7 operation_B();
+ 8 operation_C();
+ 9 }
+
+or
+ 1 // language-like mutual exclusion.
+ 2 use_lock(L1) use_lock(L2) use_lock(L3)
+ 3 {
+ 4 operation_A();
+ 5 operation_B();
+ 6 operation_C();
+ 7 }
+
+ Figure 2. A Required Sequential Locking Order.
+
+
+The reason why programmers are less likely to accidentally remove the scope from use_lock as opposed to scoped_lock is because the programming structure of use_lock is native to C++ in many ways. For example, the code structure shown below is found throughout C, C++ and Java:
+
+ 1 grammatical-phrase
+ 2 {
+ 3 operations ...
+ 4 }
+
+A number of control structures, specifically in C++, follow this format, such as, if statements, for loops, switches, classes, structs and so forth. While the use_lock structure follows this common practice, scoped automatic objects (e.g., scoped_locks) do not. Because scoped_locks unavoidably deviate from the above common code structure, due to their automatic object basis, their scope is more likely to be accidentally removed by novice programmers as unnecessary.
+
+The side-effect of accidental scope removal for automatic objects is that resources obtained by these objects are not released until the following scope closure is reached. In some cases, such as file closing, it may be acceptable for automatic objects to delay the release of resources. However, in other cases, such as the case with locks, it is unacceptable for automatic objects to delay the release of resources. In particular, if locks are not released when the programmer intended, the resulting behavior can temporarily or permanently stall all other threads from making forward progress. If threads are temporarily suspended from forward progress, program performance is degraded, yet if threads are permanently suspended from making forward progress, the program results in a deadlock. Both cases are unacceptable for locks because locks are used as a tool to optimize program performance and in both cases the delayed release of locks results in unoptimized performance.
+
+[heading Library-based Transaction Implementations]

Transactions allow an unlimited number of threads to execute their optimistic critical sections. Transactions can perform their writes off to the side, ensuring global memory is preserved until the transaction's atomic operations are complete. To ensure conflicting transactions are identified and prevented, transactions perform correctness verification immediately before committing. The consistency checking performed by transactions ensures that transactions that write to or read from the same memory are restricted in their concurrent execution. The code below demonstrates three different implementations for transactions from a library-based approach where x is shared memory that must be synchronized.

-transaction with begin()/end():

 begin_transaction(t);
 tx_write(t, x) = val;
 end_transaction(t);

+ transaction with begin()/end():

-transaction with automatic object:
+or

- {
+ {
 transaction t;
 t.write(x) = val;
 t.end();
 }

-language transaction:
+ transaction with automatic object:

- atomic { x = val; }
+or
+
+ atomic { x = val; }
+
+ language transaction:

Inspection of the above code reveals that begin_transaction() and end_transaction() are susceptible to the problem when a thrown exception can interfere with correct interface calls. As such, the begin_transaction() and end_transaction() approach can be immediately discarded from further consideration. The two remaining approaches, similar to the prior locking implementations, use automatic objects and a language-like approach. An initial observable difference between the two approaches is that the language approach has a smaller programmatic footprint than the automatic object approach. Furthermore, the automatic object approach introduces more programmatic complexity for transactional retry mechanics and composed transactional behaviors.

@@ -274,8 +850,6 @@

Transactions use optimistic critical sections which generally require transactions be retried if they do not commit. As such, transactions are usually implemented as loops which re-execute until they commit. The code below illustrates the client code necessary to implement a basic retry behavior for automatic objects and language-like transactions.

-automatic object transaction with retry:
-
 for (transaction t; !t.committed(); t.restart()) {
 try {
 t.write(x) = val;
@@ -283,15 +857,19 @@
 } catch (...) {}
 }

-language-like transaction with retry:
+ automatic object transaction with retry
+
+and

- atomic(t) {
- t.write(x) = val;
+ atomic(t) {
+ t.write(x) = val;
 } end_atom

+ language-like transaction with retry
+
To complicate matters, some transactions must not implement a retry. Failed subtransactions often require the entire transaction be re-executed from the beginning. While the methods used to perform transactional retries vary between TM implementations, __Boost_STM__ uses an exception-based approach for all transactional interfaces. These __Boost_STM__ interfaces throw exceptions if transactions are found to be inconsistent. Therefore, parent transactions should use retry mechanics while their child transactions should not. The code above shows the differences between an automatic object and language-like implementation for parent and child transactions.

-automatic object:
+

 // parent tx with automatic object:
 for (transaction t; !t.committed(); t.restart()) {
@@ -309,7 +887,9 @@
 t.end();
 }

-language-like transaction:
+ automatic object:
+
+and

 // parent tx with language-like transaction.
 atomic(t) {
@@ -319,11 +899,13 @@

 // child tx with language-like transaction.
 void foo(int val) {
- atomic(t) {
- t.write(y) += val;
+ atomic(t) {
+ t.write(y) += val;
 } end_atom
 }

+ language-like transaction:
+
The retry mechanics' syntactic overhead for automatic objects is nearly double that of the language-like semantics. The complexity of the additional retry code is significant and exhibits a number of locations where programmer-induced errors could be made. The key benefit of the language-like atomic syntax is that its structure is identical for parent and nested transactions and it behaves correctly when any transaction is used as a parent or child (details to follow).

While the automatic object syntax could also be created to be identical for parent and nested transactions, the impact of creating such identical behavior would result in an increase in the child transaction's code size by 266% for single instruction transactions. The resulting increased code size and complexity would increase the likelihood for programmer-induced errors. For these reasons, a number of TM researchers have been in favor of direct language integration of TM instead of API-only approaches.
@@ -336,6 +918,135 @@

The culmination of the above points illustrate the need for an extensible, simplified, parallel programming model today. Our language-like approach provides such a solution for C++ that neither library-based automatic objects nor language-based parallel abstractions alone can provide.

+
+[heading Parallel Constructs for Mutually Exclusive Locks]
+
+In this section we describe the behavior, and give examples, of the __Boost_STM__ language-like parallel constructs for mutually exclusive locks. The __Boost_STM__ mutual exclusion locking constructs are shown in Table 1. Each of these constructs allow any type of nesting, ordering and intermixing. Examples of the __Boost_STM__ locking constructs are shown in Figure 9.
+
+ 1 // single-line sequential locking
+ 2 use_lock(L1) use_lock(L2) use_lock(L3) foo();
+ 1 // multi-line sequential locking
+ 2 use_lock(L1) use_lock(L2) use_lock(L3) {
+ 3 foo();
+ 4 }
+ 1 // multi-line sequential single 100 ms timed lock
+ 2 while (polling)
+ 3 try_timed_lock(100, L1) {
+ 4 use_lock(L2) use_lock(L3)
+ 5 {
+ 6 foo();
+ 7 polling = false;
+ 8 }
+ 9 } lock_timeout { execute_on_failed(); }
+
+ Figure 9. Mutual Exclusion Locks with __Boost_STM__.
+
+As demonstrated in Figure 9, a number of locking models can be implemented using a mixture of the use_lock(L), use_timed_lock(MS, L) and try_timed_lock(MS, L) parallel constructs. Each locking interface addresses a unique requirement in client code.
+
+[heading Exception-based Timed Locks]
+
+A notable feature of our __Boost_STM__ language-like extensions is the use of exceptions in conjunction with timed locks. It is our belief that timed locks are used primarily for polling models and generally require two distinct paths of execution. One path of execution is taken when the lock is obtained before the timeout. The other path of execution is taken when the lock is not obtained before the timeout. In light of this, exceptions thrown when timed locks are not acquired can facilitate a distinction between successful lock acquisition and failed lock acquisition. Client code can become excessively unoptimized or complex if timed sequential locking is necessary and non-throwing automatic objects are used. An example of such unoptimized timed locking is demonstrated in Figure 10.
+
+ 1 // unoptimized timed locking
+ 2 while (polling) {
+ 3 timed_lock tl1(100, L1);
+ 4 timed_lock tl2(100, L2);
+ 5 timed_lock tl3(100, L3);
+ 6
+ 7 if (tl1.has_lock() && tl2.has_lock() &&
+ 8 tl3.has_lock()) {
+ 9 foo();
+ 10 polling = false;
+ 11 }
+ 12 else execute_on_failed();
+ 13 }
+
+ Figure 10. Unoptimized Timed Locking with Automatic Objects.
+
+Figure 10 illustrates how non-throwing automatic objects can hamper performance if incorrectly implemented and demonstrates an unoptimized implementation of timed locks. Delaying lock acquisition checks until after all timed locks are constructed can result in an a substantial performance degradation if neither L1 nor L2 are acquired. This performance degradation is caused by performing additional unnecessary work after failing to acquire lock L1 and L2.
+
+ 1 // optimized timed locking
+ 2 while (polling) {
+ 3 timed_lock tl1(100, L1);
+ 4 if (tl1.has_lock()) {
+ 5 timed_lock tl2(100, L2);
+ 6 if (tl2.has_lock()) {
+ 7 timed_lock tl3(100, L3);
+ 8 if (tl3.has_lock()) {
+ 9 foo();
+ 10 polling = false;
+ 11 }
+ 12 else execute_on_failed();
+ 13 }
+ 14 else execute_on_failed();
+ 15 }
+ 16 else execute_on_failed();
+ 17 }
+
+ Figure 11. Optimized Timed Locking with Automatic Objects.
+
+In order to optimize Figure 10's timed locks, a complex level of if nesting is needed as shown in Figure 11. Figure 11 demonstrates an optimized level of timed locking, but drastically increases the complexity of the software structure. Figure 11 introduces a high level of software complexity as a trade-off for performance. Intermixing the __Boost_STM__ try_timed_lock(MS, L) and use_timed_lock(MS, L) constructs builds a software structure that is simpler than either Figure 10 or 11 while achieving the same level of performance found in Figure 11. An example of try_timed_lock(MS, L) and use_timed_lock(MS, L) is shown in Figure 12.
+
+ 1 // multi-line sequential all 100 ms timed lock
+ 2 while (polling)
+ 3 try_timed_lock(100, L1) {
+ 4 use_timed_lock(100, L2)
+ 5 use_timed_lock(100, L3)
+ 6 {
+ 7 foo();
+ 8 polling = false;
+ 9 }
+ 10 } lock_timeout { execute_on_failed(); }
+
+ Figure 12. Optimized Timed Locking with __Boost_STM__.
+
+
+[ heading Parallel Constructs for Transactional Memory]
+
+In this section we describe the behavior, and give examples, of the __Boost_STM__ language-like parallel constructs for transactional memory. The __Boost_STM__ transaction-based parallel constructs are shown in Table 2. These transactional constructs enable open-ended transactional nesting behaviors that are important to composition. Examples of the __Boost_STM__ transactions are shown in Figure 13. Figure 13 demonstrates how transactions are used in various ways. In some cases transactions are single operations, such as in the inc_x() case. At other times transactions consist of
+
+ 1 void inc_x(int val)
+ 2 {
+ 3 atomic(t) { t.write(x) += val; } end_atom
+ 4 }
+ 1 void inc_y_and_z(int val)
+ 2 {
+ 3 atomic(t) {
+ 4 t.write(y) += val;
+ 5 t.write(z) += val;
+ 6 } end_atom
+ 7 }
+ 1 void transfer_x_to_y_z(int val)
+ 2 {
+ 3 atomic(t) {
+ 4 inc_x(-val);
+ 5 inc_y_and_z(val / 2);
+ 6 } end_atom
+ 7 }
+
+ Figure 13. Transactions with __Boost_STM__.
+
+multiple operations, such as inc_y_and_z(). More cases exist when transactions are made up of other transactions, such as transfer_x_to_y_z(). The last case, often referred to as composition, is an important characteristic of transactions that most (if not all) other synchronization primitives do not exhibit (more on this later).
+
+In the simple case, when no transactional nesting occurs, the transactional retry behavior happens locally. For example, if two threads try to concurrently execute the inc_x() function of Figure 13, only one thread will succeed since both threads cannot simultaneously access and change the same shared memory location. The failing thread will have to retry its transaction. Since inc_x() is a single-level transaction, the failing thread can retry the transaction locally (i.e., restarting at the top of the atomic structure inside inc_x()).
+
+Non-trivial cases exist when transactions may be nested and retrying a transaction locally will cause an infinite loop. These cases use composed transactions and (generally) require that a failed transaction be retried from the parent transaction 1. An example of a composed transaction that, if aborted, would require the transaction to be retried from the parent is transfer_x_to_y_z(). This transaction must be retried from the parent, rather than by either of its child transactions individually, (int_x() and inc_y_and_z()) because the values within the shared memory x, y, and z could have been altered by another interleaved transaction.
+
+__Boost_STM__ handles the shifting of transactional retry mechanics from child to parent dynamically and automatically. As demonstrated in Section 3.2, the atomic macro makes numerous calls into the currently active transaction to determine whether its failed commit should result in a local retry or a thrown aborted_transaction exception. The correct path of execution for the transactional retry is based on the run-time state. For example, if int_x() has failed, but it is the only transaction currently being executed by a thread, then it should be retried locally. However, if int_x() has failed, but it is being executed from within transfer_x_to_y_z() then transfer_x_to_y_z() should be re-executed. The re-execution of a parent transaction is enabled by a child transaction identifying the correct behavior and then throwing an exception upward.
+
+[heading Transaction Nesting]
+
+While the retry behavior of nested transactions is important, the composed behavior of independently designed transactions is even more important. Transactional composition [8, 15] is the cornerstone of transactional memory. In short, TM allows independently designed transactions to be placed together under the umbrella of a single transaction. This single transaction then behaves in an atomic, consistent and isolated fashion. Furthermore, the single transaction that is composed of many individual transactions is seen as a single indivisible operation to other transactions.
+
+As such, an important aspect of transaction nesting is the construction of a transaction without the need to specify it is nested. A similar line of thinking is the construction of a function which is then used inside of another function and so forth. In C++ these nested functions are not created in any special way that describes their use in a given nested structure. Transactions, therefore, should be programmatically constructed in a similar way.
+
+To the best of our knowledge, __Boost_STM__ is the first C++ STM library to implement transactions under a single keyword (atomic) which behaves correctly for both nested and non-nested transactions. While other correct implementations exist at the languagelevel [24] and compiler-level [18], no other library-based solution allows the programmer the practical freedom to implement transactions under a single keyword for transactions at any nesting level.
+
+A more realistic example of the importance of nested and nonnested transactions and a universal keyword for both, is shown in Figure 14. Here we implement some basic list operations that are useful when used independently and when used in an cooperative, nested fashion.
+
+Figure 14 demonstrates how transactions are composed using __Boost_STM__. The goal of the code shown in Figure 14 is to transfer all of the elements from list l to list j that do not already exist in list j. The entire operation is done atomically using four core transactional operations, insert, remove, transfer, and complete_transfer. The additional transactional operation, priority_transfer, is added to demonstrate how client code can wrap a composed transaction and alter its underlying performance in relation to other transactions by modifying the transaction's priority. Wrapping transactions with priority is useful in cases where the original transaction was written in a priority-neutral manner, but now must be used in an explicitly prioritized system. More details of prioritized transactions can be found in [6, 20].
+
+
[endsect]

[endsect]

Modified: sandbox/stm/branches/vbe/libs/stm/doc/reference/language_like.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/reference/language_like.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/reference/language_like.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -10,53 +10,20 @@
[section:language_like_hpp Header `<boost/stm/language_like.hpp>`]
[/==========================================================================================]

-The complexity behind the `atomic` macro is needed to guarantee two
-fundamental goals.
+The complexity behind the `atomic` macro is needed to guarantee two fundamental goals.

-*First, transactions must start and end correctly.
-Second, transactions must change their retry behavior based on
-whether they are a child or parent transaction to ensure proper
-closed nesting, flattened transaction behavior is performed.
-
-The `atomic` preprocessor behaves as follows. When the transactional for loop is entered,
-a transaction automatic object is constructed which initializes
-the transaction and puts it in-flight. The for loop conditional
-ensures the following conditions:
-
-# the transaction is uncommitted,
-# the transaction has the opportunity to throw an exception if necessary, and
-# the transaction is in-flight.
-
-Once a transaction commits, the check on (1) `!T.committed()` ensures
-the transaction is not executed again. If the transaction has been
-aborted but is a child transaction, the transaction must be restarted
-at the parent level. The call to (2) `T.check_throw_before_restart()`
-allows an aborted child transaction to throw an exception upward
-(before it is restarted) so the entire transaction can be restarted from
-the parent. The `check_throw_before_restart()` API checks
-the current run-time state of the thread to determine if another
-transaction is active above it. This behavior allows transactions to
-be used at any nesting level while dynamically ensuring the correct
-retry behavior. Finally, the call to `restart_if_not_inflight()`
-ensures the transaction is correctly restarted after each subsequent
-abort.
-
-Once all of the transactional operations within the for loop are
-executed, a call to no_throw_end() is made which ends the transaction.
-The `no_throw_end()` terminates the transaction by either
-committing or aborting it. Note, however, that `no_throw_end()`
-does not throw an exception if the transaction is aborted, whereas
-the prior __Boost_STM_s__ API end() does. This non-throwing behavior
-deviates from the prior __Boost_STM__ implementation of automatic
-objects when end() was invoked within the try / catch
-body. Furthermore, due to `no_throw_end()` not throwing an exception
-if the transaction is aborted, some cases may arise where
-`catch_before_retry` or `before_retry` operations are not invoked
-when a transaction is aborted. This is a current limitation of
-the system and is overcome by inserting a manual end() operation
-as the last operation in the atomic block. The explicit end()
-ensures any operations within the before_retry block are
-executed if the transaction is aborted.
+* First, transactions must start and end correctly.
+* Second, transactions must change their retry behavior based on whether they are a child or parent transaction to ensure proper closed nesting, flattened transaction behavior is performed.
+
+The `atomic` preprocessor behaves as follows. When the transactional for loop is entered, a transaction automatic object is constructed which initializes the transaction and puts it in-flight. The for loop conditional ensures the following conditions:
+
+# the transaction is uncommitted,
+# the transaction has the opportunity to throw an exception if necessary, and
+# the transaction is in-flight.
+
+Once a transaction commits, the check on (1) `!T.committed()` ensures the transaction is not executed again. If the transaction has been aborted but is a child transaction, the transaction must be restarted at the parent level. The call to (2) `T.check_throw_before_restart()` allows an aborted child transaction to throw an exception upward (before it is restarted) so the entire transaction can be restarted from the parent. The `check_throw_before_restart()` API checks the current run-time state of the thread to determine if another transaction is active above it. This behavior allows transactions to be used at any nesting level while dynamically ensuring the correct retry behavior. Finally, the call to `restart_if_not_inflight()` ensures the transaction is correctly restarted after each subsequent abort.
+
+Once all of the transactional operations within the for loop are executed, a call to no_throw_end() is made which ends the transaction. The `no_throw_end()` terminates the transaction by either committing or aborting it. Note, however, that `no_throw_end()` does not throw an exception if the transaction is aborted, whereas the prior __Boost_STM_s__ API end() does. This non-throwing behavior deviates from the prior __Boost_STM__ implementation of automatic objects when end() was invoked within the try / catch body. Furthermore, due to `no_throw_end()` not throwing an exception if the transaction is aborted, some cases may arise where `catch_before_retry` or `before_retry` operations are not invoked when a transaction is aborted. This is a current limitation of the system and is overcome by inserting a manual end() operation as the last operation in the atomic block. The explicit end() ensures any operations within the before_retry block are executed if the transaction is aborted.

@@ -70,9 +37,7 @@

[section Macro `atomic`]

-Use atomic transaction T for optimistic critical section. Supports single-depth and multiple-depth (nested)
-transactions. Performs automatic retry when T is a parent transaction, throws exception when T is a
-child transaction. This automatic switch enables correctly behaved nested and non-nested transactions
+Use atomic transaction T for optimistic critical section. Supports single-depth and multiple-depth (nested) transactions. Performs automatic retry when T is a parent transaction, throws exception when T is a child transaction. This automatic switch enables correctly behaved nested and non-nested transactions

 #define atomic(T) \
 for (transaction T; \
@@ -108,10 +73,7 @@

 #define catch_before_retry(E) catch (aborted_tx &E)

-Catches exception when transaction is aborted. This, before_retry, or end_atom must follow an
-atomic block. Once all operations within the catch_before_retry block are executed, control is
-returned to the local atomic where the transaction is retried (if it is the parent) or the atomic block
-is exited by exception (if it is a child).
+Catches exception when transaction is aborted. This, before_retry, or end_atom must follow an atomic block. Once all operations within the catch_before_retry block are executed, control is returned to the local atomic where the transaction is retried (if it is the parent) or the atomic block is exited by exception (if it is a child).

To be used pairwise with `try_atomic` or `atomic`.

Modified: sandbox/stm/branches/vbe/libs/stm/doc/reference/smart_pointers.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/reference/smart_pointers.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/reference/smart_pointers.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -11,6 +11,45 @@
[/==========================================================================================]

 namespace boost { namespace stm {
+ template <typename T> class read_ptr;
+ template <typename T> class write_ptr;
+ }}
+
+[section Template Class `read_ptr<>`]
+
+ template <typename T> class read_ptr {
+ public:
+ inline read_ptr(transaction &t, T const &tx_obj);
+ const T* get() const;
+ inline T const & operator*() const;
+ inline T const * operator->() const;
+
+ inline transaction &trans();
+ T* write_ptr();
+ };
+
+[endsect]
+[section Template Class `write_ptr<>`]
+
+ template <typename T> class write_ptr {
+ public:
+ inline write_ptr(transaction &t, T & tx_obj);
+
+ T* get() const;
+ inline T& operator*();
+ inline T* operator->();
+
+
+[endsect]
+
+[endsect]
+
+
+[/==========================================================================================]
+[section:tx_smart_ptr_hpp Header `<boost/stm/tx_smart_ptr.hpp>`]
+[/==========================================================================================]
+
+ namespace boost { namespace stm {

 template <typename T> class tx_obj;
 template <typename T, typename U>
@@ -72,9 +111,6 @@
 void delete_ptr(wr_ptr<T> ptr);
 template <typename T>
 void delete_ptr(transaction& tx, wr_ptr<T> const& ptr);
-
- template <typename T> class read_ptr;
- template <typename T> class write_ptr;
 }}

[section Template Class `tx_obj<>`]
@@ -248,32 +284,127 @@

[endsect]

-[section Template Class `read_ptr<>`]
+[endsect]

- template <typename T> class read_ptr {
+[/==========================================================================================]
+[section:non_tx_smart_ptr_hpp Header `<boost/stm/non_tx_smart_ptr.hpp>`]
+[/==========================================================================================]
+
+ namespace boost { namespace stm { namespace non_tx {
+ template <typename T> class rd_ptr;
+ template <typename T> rd_ptr<T> make_rd_ptr(transaction& tx, T* ptr);
+ template <typename T> rd_ptr<T> make_rd_ptr(transaction& tx, T& ref);
+ template <typename T> rd_ptr<T> make_rd_ptr(T* ptr);
+ template <typename T> rd_ptr<T> make_rd_ptr(T& ref);
+ template <typename T> void delete_ptr(rd_ptr<T> ptr);
+
+ template <typename T> class upgrd_ptr;
+ template <typename T> void delete_ptr(upgrd_ptr<T> const& ptr);
+ template <typename T> void delete_ptr(transaction& tx, upgrd_ptr<T> const& ptr);
+
+ template <typename T> class wr_ptr;
+ }}}
+
+These smart pointers points to an unspecified cache type which inherits from base_transactional object. This cache is obtained from an internal thread safe cache map.
+
+As the the non_tx smart pointers need to lookup on a cache they must be used only when you need to access to a non transactional variable on the context of a transaction. Otherwise, please use tx_ptr<> or the mixin transaction_object<>.
+
+[section Template Class `rd_ptr<>`]
+
+A rd_ptr<T> ("read pointer") points to an cache that the current transaction has opened for read only access. You can only call a const method through a read pointer.
+
+A rd_ptr<T> is constructed from an T pointer or reference.
+Once a rd_ptr<T> has been constructed, the associated cache is opened for
+reading.
+
+It is not safe to derreference a rd_ptr<T> after having assigned the same
+T to a wr_ptr<T>. If this is the case the readen value do not match
+the writen one. If it is possible to write on the same transaction use
+upgrd_ptr instead which is safe.
+
+ template <typename T>
+ class rd_ptr {
 public:
- inline read_ptr(transaction &t, T const &tx_obj);
- const T* get() const;
- inline T const & operator*() const;
- inline T const * operator->() const;
+ rd_ptr(transaction &t, T const * ptr);

- inline transaction &trans();
- T* write_ptr();
+ rd_ptr(transaction &t, T const & obj);
+
+ template<class Y>
+ explicit rd_ptr & operator=(Y const* ptr);
+
+ template<class Y>
+ explicit rd_ptr & operator=(Y const& ref);
+
+ const T* get() const;
+
+ const T & operator*() const;
+ const T* operator->() const;
+
+ operator unspecified_bool_type() const;
 };

[endsect]
-[section Template Class `write_ptr<>`]

- template <typename T> class write_ptr {
+[section Template Class `upgrd_ptr<>`]
+
+A upgrd_ptr<T> ("upgradable pointer") points to an cache that the current transaction has opened for read only access. You can only call const method of the wrapped type through a upgradable pointer.
+
+A upgrd_ptr<T> is constructed from an T pointer or reference through a constructor
+having also the transaction as parameter. Once a upgrd_ptr<T> has been constructed, an a cache of T can is opened for reading.
+
+It is safe to derreference a upgrd_ptr<T> after having assigned the same
+T to a wr_ptr<T>.
+
+A upgrd_ptr<T> can be upgraded to a wr_ptr<T> through a constructor.
+
+ template <typename T>
+ class upgrd_ptr {
 public:
- inline write_ptr(transaction &t, T & tx_obj);
+ upgrd_ptr(transaction &t, T* ptr);
+ upgrd_ptr(transaction &t, T& ref);

- T* get() const;
- inline T& operator*();
- inline T* operator->();
+ template<class Y> upgrd_ptr & operator=(Y* ptr);

+ template<class Y> upgrd_ptr & operator=(Y& ref);
+
+ const T* get() const;
+ inline T const & operator*() const;
+ inline T const * operator->() const;
+
+ operator unspecified_bool_type() const;
+
+ void write_ptr(detail::cache<T>* ptr);
+ T* write_ptr();
+ };
+
+
+[endsect]
+
+[section Template Class `wr_ptr<>`]
+
+A wr_ptr<T> ("write pointer") points to a cache that the current transaction has opened for writing.
+
+A wr_ptr<T> is initialized explicitly from an T pointer or reference.
+
+A wr_ptr<T> can also be explicitly constructed from a upgrd_ptr<T> as an upgrade-to-writable operation.
+
+
+ template <typename T>
+ class wr_ptr {
+ public:
+ wr_ptr(transaction &t, T* ptr);
+ wr_ptr(transaction &t, T& obj);
+
+ T* get();
+ inline T& operator*();
+ inline T* operator->();
+
+ operator unspecified_bool_type() const;
+ };

[endsect]
+
+
[endsect]

Modified: sandbox/stm/branches/vbe/libs/stm/doc/reference/transaction.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/reference/transaction.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/reference/transaction.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -12,15 +12,13 @@

     namespace boost { namespace stm {
         class transaction;
+ struct thread_initializer;
     }}

[section Class `transaction`]

-__Boost_STM__ defines transactions as stackbased
-objects using RAII. In addition to the static interfaces for
-direct and deferred updating described earlier in this section, the
-following interfaces are necessary for performing transactions.
+__Boost_STM__ defines transactions as stackbased objects using RAII. In addition to the static interfaces for direct and deferred updating described earlier in this section, the following interfaces are necessary for performing transactions.

     class transaction {
     public:
@@ -499,4 +497,18 @@
[endsect]

[endsect]
+
+[section Struct `thread_initializer`]
+
+Scoped thread initializer calling transaction::initialize_thread() in the constructor and transaction::terminate_thread() in the destructor.
+
+Declare an object of this class on each thread participating on a transaction.
+
+ struct thread_initializer {
+ thread_initializer();
+ ~thread_initializer();
+ };
+
+[endsect]
+
[endsect]

Modified: sandbox/stm/branches/vbe/libs/stm/doc/reference/transaction_object.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/reference/transaction_object.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/reference/transaction_object.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -8,23 +8,22 @@

[/==========================================================================================]
-[section:transaction_object_hpp Header `<boost/stm/transaction_object.hpp>`]
+[section:base_transaction_hpp Header `<boost/stm/base_transaction.hpp>`]
[/==========================================================================================]

 namespace boost { namespace stm {
 class base_transaction_object;
- template <class Derived> class transaction_object;
- template <typename T> class native_trans;
- template <class T> class transactional_object;

- template <typename T>
- static transactional_object<T>* tx_up_cast(T* ptr);
+ template <class T> T* cache_clone(const T& val);
+ template <class T> void cache_copy(const T* const ori, T* target);
+ void cache_release(base_transaction_object* ptr);

- template <typename T, typename U>
- static transactional_object<T>* tx_static_cast(transactional_object* ptr);
+ template <class T> T* cache_allocate();
+ template <class T> void cache_deallocate(T*);

- template <typename T, typename U>
- static transactional_object<T>* tx_dynamic_cast(transactional_object* ptr);
+
+ template <class Derived> class transaction_object;
+ template <typename T> class native_trans;
 }}

[section Abstract Class `base_transaction_object`]
@@ -37,6 +36,7 @@
* `newMemory_`: states whether this object is a new object

Transactional objets must specialize the pure virtual functions
+
* `copy_state(base_transaction_object const * const rhs)`
* `move_state(base_transaction_object * rhs)` if `BUILD_MOVE_SEMANTICS`
* `cache_deallocate()` if `BOOST_STM_USE_UNASIGNED_COPY`
@@ -57,6 +57,7 @@
 base_transaction_object();
 virtual ~base_transaction_object() {};

+ virtual base_transaction_object* clone() const = 0;
 virtual void copy_state(base_transaction_object const * const rhs) = 0;
 virtual void move_state(base_transaction_object * rhs) = 0;

@@ -76,20 +77,18 @@
 static void* retrieve_mem(size_t size);
 static void alloc_size(size_t size);
 #endif
-
+
 #ifdef BOOST_STM_USE_UNASIGNED_COPY
 virtual void cache_deallocate()=0;
 #endif
-
-};
+
+ };

[section Constructor `base_transaction_object()`]

 base_transaction_object();

-Default constructor (ctor) with no parameters allows derived
-base_transaction_objects to implicitly construct the
-base_transaction_object base class for easier integration.
+Default constructor (ctor) with no parameters allows derived base_transaction_objects to implicitly construct the base_transaction_object base class for easier integration.

[endsect]

@@ -97,10 +96,7 @@

 virtual ~base_transaction_object() {};

-Virtual destructor (dtor) ensures correct destructors are called
-in the inheritance hierarchy for delete operations invoked on
-base_transaction_object pointers, which occur in numerous
-places throughout the internal transaction code.
+Virtual destructor (dtor) ensures correct destructors are called in the inheritance hierarchy for delete operations invoked on base_transaction_object pointers, which occur in numerous places throughout the internal transaction code.

[endsect]

@@ -109,15 +105,9 @@
 virtual void copy_state(base_transaction_object const * const rhs) = 0;

-The `copy_state()`
-method is called each time global memory is updated, for either
-direct or deferred updating policies. With this in mind, it is
-vital that the this object be set to the exact state of the input
-parameter.
-
-Derived classes usually
-simply override this method and perform an `operator=()`
-function call for the specific derived type.
+The `copy_state()` method is called each time global memory is updated, for either direct or deferred updating policies. With this in mind, it is vital that the this object be set to the exact state of the input parameter.
+
+Derived classes usually simply override this method and perform an `operator=()` function call for the specific derived type.

[endsect]

@@ -134,14 +124,7 @@

 static void* retrieve_mem(size_t size);

-Static interface into __Boost_STM_s__ memory management system
-for retrieving memory. The supplied parameter is the requested
-block size, the return parameter is a void* to the allocated
-block. Usually access to this interface is done by overloading
-operator new in the derived base_transaction_object
-class. Void pointers are the natural and preferred manner to handle
-memory allocations and deallocations and are therefore safe
-in this context.
+Static interface into __Boost_STM_s__ memory management system for retrieving memory. The supplied parameter is the requested block size, the return parameter is a void* to the allocated block. Usually access to this interface is done by overloading operator new in the derived base_transaction_object class. Void pointers are the natural and preferred manner to handle memory allocations and deallocations and are therefore safe in this context.

[endsect]

@@ -150,27 +133,15 @@

 static void return_mem(void *mem, size_t size);

-Static interface into __Boost_STM_s__ memory management system
-for returning memory. The first parameter points to the memory
-block being returned, the second parameter specifies its size.
-Usually access to this interface is done by overloading operator
-delete in the derived transaction object class. Void pointers are
-the natural and preferred manner to handle memory allocations
-and deallocations and are therefore safe in this context.
+Static interface into __Boost_STM_s__ memory management system for returning memory. The first parameter points to the memory block being returned, the second parameter specifies its size. Usually access to this interface is done by overloading operator delete in the derived transaction object class. Void pointers are the natural and preferred manner to handle memory allocations and deallocations and are therefore safe in this context.
+
[endsect]

[section Static function `alloc_size()`]

 static void alloc_size(size_t size);

-Static interface into __Boost_STM_s__ memory management system
-which allows the user to specify the allocation chunk size for
-the memory manager. The input parameter specifies the number
-of transactional objects that should be allocated at startup and
-with each subsequent buffer increase. If no size is specified, the
-allocation chunk size uses __Boost_STM_s__ default value, currently
-8192. The alloc_size() interface can be reconfigured at runtime
-and is used upon the next buffer increase.
+Static interface into __Boost_STM_s__ memory management system which allows the user to specify the allocation chunk size for the memory manager. The input parameter specifies the number of transactional objects that should be allocated at startup and with each subsequent buffer increase. If no size is specified, the allocation chunk size uses __Boost_STM_s__ default value, currently 8192. The alloc_size() interface can be reconfigured at runtime and is used upon the next buffer increase.

[endsect]

@@ -183,36 +154,93 @@

[endsect]

+[section Template Function `cache_clone<>()`]
+
+ template <class T>
+ T* cache_clone(const T& val);
+
+Makes a new copy of the parameter. Allocates an object of type T using the `cache_allocate` function and copy from the given parameter `val` using the free function `cache_copy`.
+
+The user can overload this function, as __Boost_STM__ uses ADL to access it.
+
+When `BOOST_STM_NO_PARTIAL_SPECIALIZATION` is defined, i.e. on compilers not supporting partial template specialization, the function calls to `partial_specialization_workaround::cache_clone<T>::apply(val)`. So the user will need to overload the class `partial_specialization_workaround::cache_clone<T>` defining the function
+
+ static T* apply(const T& val);
+
+[endsect]
+
+
+[section Template Function `cache_copy<>()`]
+
+ template <class T>
+ void cache_copy(const T* const source, T* target);
+
+Copy from souce to target using memcpy by default.
+
+The user can overload this function, as __Boost_STM__ uses ADL to access it.
+
+When `BOOST_STM_NO_PARTIAL_SPECIALIZATION` is defined, i.e. on compilers not supporting partial template specialization, the function calls to `partial_specialization_workaround::cache_copy<T>::apply(source, target)`. So the user will need to overload the class `partial_specialization_workaround::cache_copy<T>` defining the function
+
+ static T* apply(const T* const source, T* target);
+
+[endsect]
+
+[section Function `cache_release<>()`]
+
+ void cache_release(base_transaction_object* ptr) {
+
+Release the given base_transaction_object by calling to the virtual function `cache_dealocate`.
+
+[endsect]
+
+
+[section Template Function `cache_allocate<>()`]
+
+ template <class T>
+ T* cache_allocate();
+
+Allocates an instance of calls T. Depending on whether BOOST_STM_CACHE_USE_MEMORY_MANAGER, BOOST_STM_CACHE_USE_MALLOC or BOOST_STM_CACHE_USE_TSS_MONOTONIC_MEMORY_MANAGER are defined this function will use the static pool of the class T, malloc or the thread specific monotonic allocator.
+
+[endsect]
+
+[section Template Function `cache_deallocate<>()`]
+
+ template <class T>
+ void cache_deallocate(T*ptr) {
+
+Deallocates an instance of calls T. Depending on whether BOOST_STM_CACHE_USE_MEMORY_MANAGER, BOOST_STM_CACHE_USE_MALLOC or BOOST_STM_CACHE_USE_TSS_MONOTONIC_MEMORY_MANAGER are defined this function will use the static pool of the class T, free or the no-op.
+
+[endsect]
+
[section Template Class `transaction_object<>`]

-To further simplify the usage of __Boost_STM__, an intermediate
-template class was built which is meant to sit between the
-base_transaction_object and the user-defined transaction
-objects. The purpose of this intermediate class is to reduce the
-code overhead needed for user-defined transaction objects. To do
-this, the curiously recurring template pattern developed by James
-Coplien was used.
-
-With the templatized transaction_object, client-side transaction
-objects need only to derive from it and pass their class type as
-its template parameter. At compile-time the transaction_object
-generates the necessary code to override copy_state() and implement
-operator new and operator delete using __Boost_STM_s__ memory
-manager for all user-defined types derived from it.
+To further simplify the usage of __Boost_STM__, an intermediate template class was built which is meant to sit between the base_transaction_object and the user-defined transaction objects. The purpose of this intermediate class is to reduce the code overhead needed for user-defined transaction objects. To do this, the curiously recurring template pattern developed by James Coplien was used.
+
+With the templatized transaction_object, client-side transaction objects need only to derive from it and pass their class type as its template parameter. At compile-time the transaction_object generates the necessary code to override copy_state() and implement operator new and operator delete using __Boost_STM_s__ memory manager for all user-defined types derived from it.

 template <class Derived>
 class transaction_object : public base_transaction_object {
 public:

- virtual void copy_state(base_transaction_object const * const rhs);
- virtual void move_state(base_transaction_object * rhs);
+ virtual base_transaction_object* clone() const;
+ virtual void copy_state(base_transaction_object const * const rhs);
+ virtual void move_state(base_transaction_object * rhs);
 };

+[section Virtual function `clone()`]
+
+ virtual base_transaction_object* clone() const;
+
+The clone() method calls to the free function cache_new_copy which allocates enough memory for the new object and then do a memcpy by default.
+
+[endsect]
+
+
[section Virtual function `copy_state()`]

 virtual void copy_state(base_transaction_object const * const rhs);

-The copy_state() method call to the free function cache_restore which do a unitialized_copy by default.
+The copy_state() method call to the free function cache_copy which do a memcpy by default.

[endsect]

@@ -220,17 +248,20 @@

 virtual void move_state(base_transaction_object * rhs);

-The move_state() method call to the free function cache_restore which do a unitialized_copy by default.
+The move_state() method call to the free function cache_copy which do a memcpy by default.

[endsect]

[section Virtual function `cache_deallocate()`]

- virtual void cache_deallocate()=0;
+ virtual void cache_deallocate();
+
+The cache_deallocate() method call to the free function cache_deallocate which do a memcpy by default.

[endsect]
[endsect]

+
[section Template Class `native_trans<>`]

 template <typename T> class native_trans : public transaction_object< native_trans<T> > {
@@ -257,14 +288,34 @@

[endsect]

+[endsect]
+
+
+[/==========================================================================================]
+[section:transactional_object_hpp Header `<boost/stm/transactional_object.hpp>`]
+[/==========================================================================================]
+
+ namespace boost { namespace stm {
+ template <class T> class transactional_object;
+
+ template <typename T>
+ static transactional_object<T>* tx_up_cast(T* ptr);
+
+ template <typename T, typename U>
+ static transactional_object<T>* tx_static_cast(transactional_object* ptr);
+
+ template <typename T, typename U>
+ static transactional_object<T>* tx_dynamic_cast(transactional_object* ptr);
+ }}
+
[section Template Class `transactional_object<>`]

Transactional object wrapper. A `transactional_object<T>` is a base_transaction_object wrapping an instance of type T. Provides the definition of the virtual functions

* forward constructors to the wrapped type
-* `copy_state`: relaying on the cache_restore<T> generic function
+* `copy_state`: relaying on the cache_copy<T> generic function
* `move_state` and
-* `cache_deallocate`: relaying on the cache_restore<T> generic function
+* `cache_deallocate`: relaying on the cache_copy<T> generic function

Defines in addition the functions `new` and `delete` when `BOOST_STM_USE_MEMORY_MANAGER` is defined

Modified: sandbox/stm/branches/vbe/libs/stm/doc/references.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/references.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/references.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,5 +1,5 @@
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
   (C) Copyright 2009 Vicente J. Botet Escriba
  /
  / Distributed under the Boost Software License, Version 1.0. (See accompanying
@@ -9,28 +9,38 @@

[section:ext_references References]

-For details on the underlying software architecture of __Boost_STM__, including explanations of its API, please refer to our summary paper.
+For an introduction to TM, please refer to
+[variablelist
+
+[
+ [ [@http://eces.colorado.edu/~gottschl/pubs/isac09.shift.pdf [*Shifting the Parallel Programming Paradigm]]]
+ [Justin E. Gottschlich, Dwight Y. Winkler, Mark W. Holmes, Jeremy G. Siek, and Manish Vachharajani -
+ ['Raytheon Information Systems and Computing Symposium (ISaCTN), March 2009] ]
+]
+]
+
+For details on the underlying software architecture of __Boost_STM__, including explanations of its API, please refer to our summary paper.

[variablelist

[
     [ [@http://eces.colorado.edu/~gottschl/tboostSTM/pubs/lcsd07-dracostm.pdf [*DracoSTM: A Practical C++ Approach to Software Transactional Memory]]]
- [Justin E. Gottschlich and Daniel A. Connors -
+ [Justin E. Gottschlich and Daniel A. Connors -
     ['Proceedings of the ACM SIGPLAN Symposium on Library-Centric Software Design (LCSD), October 2007] ]
]
]

-TBoost.STM uses a novel method of consistency checking called invalidation. Invalidation can assist in both high performance and strict contention management control. For more information on how invalidation can improve overall system performance and ensure true user-defined contention management policies, see our below research papers.
+TBoost.STM uses a novel method of consistency checking called invalidation. Invalidation can assist in both high performance and strict contention management control. For more information on how invalidation can improve overall system performance and ensure true user-defined contention management policies, see our below research papers.

[variablelist
[
     [ [@http://eces.colorado.edu/~gottschl/tboostSTM/pubs/podc08_full_paper.pdf [*A Consistency Checking Optimization Algorithm for Memory-Intensive Transactions]]]
- [Justin E. Gottschlich, Daniel A. Connors and Jeremy G. Siek -
+ [Justin E. Gottschlich, Daniel A. Connors and Jeremy G. Siek -
     ['Proceedings of the ACM SIGACT-SIGOPS Symposium on Principles of Distributed Computing (PODC) (brief announcement), August 2008] ] ]

[
     [ [@http://eces.colorado.edu/~gottschl/tboostSTM/pubs/epham08-stm.pdf [*Extending Contention Managers for User-Defined Priority Based Transactions]]]
- [Justin E. Gottschlich and Daniel A. Connors -
+ [Justin E. Gottschlich and Daniel A. Connors -
     ['Proceedings of the ACM Workshop on Exploiting Parallelism with Transactional Memory and other Hardware Assisted Methods (EPHAM), April 2008] ]
]
]
@@ -39,26 +49,26 @@

[variablelist
[
- [ [@http://eces.colorado.edu/~gottschl/tboostSTM/pubs/latm.pdf [*Lock-Aware Transactional Memory and Composable Locks]]]
- [Justin E. Gottschlich, Daniel A. Connors and Jeremy G. Siek -
+ [ [@http://eces.colorado.edu/~gottschl/tboostSTM/pubs/latm.pdf [*An Intentional Library Approach to Lock-Aware Transactional Memory]]]
+ [Justin E. Gottschlich, Daniel A. Connors, Dwight Y. Winkler, Jeremy G. Siek and Manish Vachharajani -
      ]
]

]

-__Boost_STM__ uses the last C++ features to provide a friendly and efficient interface. See the following papers to see how.
+__Boost_STM__ uses the last C++ features to provide a friendly and efficient interface. See the following papers to see how.

[variablelist
[
     [ [@http://eces.colorado.edu/~gottschl/pubs/boostcon.inter.2009.pdf [*Toward Simplified Parallel Support in C++]]]
- [Justin E. Gottschlich, Jeremy G. Siek, Paul J. Rogers, and Manish Vachharajani -
+ [Justin E. Gottschlich, Jeremy G. Siek, Paul J. Rogers, and Manish Vachharajani -
     ['BoostCon'09, the Third Boost Libraries Conference, May 2009] ]
]

[
     [ [@http://eces.colorado.edu/~gottschl/tboostSTM/pubs/icooolps08-exception.pdf [*C++ Move Semantics for Exception Safety and Optimization in Software Transactional Memory Libraries]]]
- [Justin E. Gottschlich, Jeremy G. Siek and Daniel A. Connors -
+ [Justin E. Gottschlich, Jeremy G. Siek and Daniel A. Connors -
     ['International Workshop on Implementation, Compilation, Optimization of Object-Oriented Languages, Programs and Systems (ICOOOLPS), July 2008]]
]
]

Modified: sandbox/stm/branches/vbe/libs/stm/doc/tests.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/tests.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/tests.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,5 +1,5 @@
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
   (C) Copyright 2009 Vicente J. Botet Escriba
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at

Modified: sandbox/stm/branches/vbe/libs/stm/doc/tickets.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/tickets.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/tickets.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,5 +1,5 @@
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
   (C) Copyright 2009 Vicente J. Botet Escriba
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at

Modified: sandbox/stm/branches/vbe/libs/stm/doc/tutorial.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/tutorial.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/tutorial.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -127,19 +127,9 @@

[section A Composable Transaction]

-The below example builds upon the previous example by adding
-a remove operation. We combine the insert and remove operations
-and build a transactional move operation that compose into a single
-transaction. Composition is a key aspect for TM systems. __Boost_STM_s__
-ability to compose transactions from pre-existing transactions
-is fundamental to its design.
-
-In the following example, the first section shows client code
-invoking the move operation. Next, the internal remove operation
-is shown, demonstrating its transactional independence. Last, the
-external move operation is explained, combining the internal insert
-and remove linked list operations resulting in a composed, single
-transaction.
+The below example builds upon the previous example by adding a remove operation. We combine the insert and remove operations and build a transactional move operation that compose into a single transaction. Composition is a key aspect for TM systems. __Boost_STM_s__ ability to compose transactions from pre-existing transactions is fundamental to its design.
+
+In the following example, the first section shows client code invoking the move operation. Next, the internal remove operation is shown, demonstrating its transactional independence. Last, the external move operation is explained, combining the internal insert and remove linked list operations resulting in a composed, single transaction.

Client Invoked Inserts / Moves.

@@ -154,11 +144,7 @@
 }
 }

-The client invoked inserts and moves are fairly straight forward.
-The insert operations are performed first then the original items are
-moved to a new location by inverting their value. Again, from a
-client programming perspective, there is no hint that this code is
-transactional, which is our intended goal.
+The client invoked inserts and moves are fairly straight forward. The insert operations are performed first then the original items are moved to a new location by inverting their value. Again, from a client programming perspective, there is no hint that this code is transactional, which is our intended goal.

Remove

@@ -183,13 +169,7 @@
 }
 }

-As was the case with the insert(), the above
-remove() method is almost identical to how a normal
-linked list remove operation would be implemented, with the
-exception of the atomic guard and a few __Boost_STM__ API calls.
-Again, this is ideal, as it leads to intuitive transactional programming,
-requiring only a minor learning curve for the algorithms
-developer.
+As was the case with the insert(), the above remove() method is almost identical to how a normal linked list remove operation would be implemented, with the exception of the atomic guard and a few __Boost_STM__ API calls. Again, this is ideal, as it leads to intuitive transactional programming, requiring only a minor learning curve for the algorithms developer.

Composed External Move

@@ -200,53 +180,17 @@
 }
 }

-The move() implementation do not requires any overhead
-required in non-transactional implementations, other than using the atomic guard.
-The remainder of the code is preserved.
+The move() implementation do not requires any overhead required in non-transactional implementations, other than using the atomic guard. The remainder of the code is preserved.

[endsect]

[section A Dynamically Prioritized, Composed Transaction]

-The following subsection discusses how priority inversion is handled
-within __Boost_STM__ using dynamic priority assignment. Two solutions
-are presented for the different consistency models, one for
-validation and one for invalidation. Following the two examples
-which detail how to override contention management interfaces,
-a dynamically prioritized transaction is presented, demonstrating
-how transactions interact with the prior implementations.
-Priority inversion in transactional memory occurs when a lower
-priority transaction causes a higher priority transaction to abort.
-With STM lock-based (and non-blocking) systems, priority inversion
-does not happen on the same scale as that of direct lock-based
-solutions. The different cases of priority inversion between direct
-locking solutions and TM solutions are due to TM's natural avoidance
-of critical sections. However, priority inversion in TM can easily
-occur if, for example, a long running transaction is continually
-preempted by shorter running transactions which always commit
-before the longer transaction.
-
-
-In order to prevent such priority inversion scenarios, two extensible
-contention manager (CM) virtual methods are provided
-to allow client-side implementations a way to handle different
-scenarios based on the consistency model currently in use. The
-first interface, abort_before_commit(), allows a user-defined
-contention manager mechanism to abort a transaction before it
-commits. Although __Boost_STM__ does not yet implement validation,
-once it becomes available, client-side validating algorithms
-which want to avoid priority inversion will need to override
-abort_before_commit() to iterate over in-flight transactions and
-abort the current in-process transaction if another in-flight transaction
-exists of higher priority. All in-flight transactions can be accessed
-by a call to in_flight_transactions() which returns
-the set of active transactions. As such, one could build an overridden
-abort_before_commit() which always caused lower priority
-committing transactions to abort in the event a higher priority
-transaction is currently in-flight. One possible implementation is
-shown below. For code simplicity, the following code has removed
-some static class accessors and namespaces.
+The following subsection discusses how priority inversion is handled within __Boost_STM__ using dynamic priority assignment. Two solutions are presented for the different consistency models, one for validation and one for invalidation. Following the two examples which detail how to override contention management interfaces, a dynamically prioritized transaction is presented, demonstrating how transactions interact with the prior implementations. Priority inversion in transactional memory occurs when a lower priority transaction causes a higher priority transaction to abort. With STM lock-based (and non-blocking) systems, priority inversion does not happen on the same scale as that of direct lock-based solutions. The different cases of priority inversion between direct locking solutions and TM solutions are due to TM's natural avoidance of critical sections. However, priority inversion in TM can easily occur if, for example, a long running transaction is continually preempted by shorter running transactions
which always commit before the longer transaction.
+
+
+In order to prevent such priority inversion scenarios, two extensible contention manager (CM) virtual methods are provided to allow client-side implementations a way to handle different scenarios based on the consistency model currently in use. The first interface, abort_before_commit(), allows a user-defined contention manager mechanism to abort a transaction before it commits. Although __Boost_STM__ does not yet implement validation, once it becomes available, client-side validating algorithms which want to avoid priority inversion will need to override abort_before_commit() to iterate over in-flight transactions and abort the current in-process transaction if another in-flight transaction exists of higher priority. All in-flight transactions can be accessed by a call to in_flight_transactions() which returns the set of active transactions. As such, one could build an overridden abort_before_commit() which always caused lower priority committing transactions to abort in the event a higher priority transac
tion is currently in-flight. One possible implementation is shown below. For code simplicity, the following code has removed some static class accessors and namespaces.

Priority Inversion for Validating Consistency.
@@ -266,41 +210,9 @@
 }
 };

-While the above approach is necessary for a validating system,
-it is largely a poor way to perform priority inversion checking.
-Firstly, it has the side-effect of causing unnecessary aborts for
-transactions which do not necessarily conflict, but simply have
-differing priority levels. Secondly, it is slow in that all transactions
-must be walked through each time a transaction commits.
-However, as an ad hoc solution for a validating system, the
-above priority inversion mechanism may be as close to correct
-as is possible. This solution is useful for validation, but should
-never be used for invalidation. Instead a second and more natural
-approach for invalidating systems to prevent priority inversion
-is to override the permission_to_abort() interface. The
-permission_to_abort() interface can only be used when __Boost_STM__
-is performing invalidation.
-
-The permission_to_abort() interface is called from __Boost_STM_s__
-end_transaction() method when a committing transaction
-has found a second transaction it needs to abort for consistency.
-As such, the method takes two parameters, an lhs (lefthand
-side), the committing transaction, and an rhs (right-hand side),
-the transaction requested to be aborted. If permission is granted to
-abort the second transaction, the method returns true and the second
-transaction is aborted. If permission is not granted to abort the
-second transaction, the method returns false and upon returning the
-committing transaction aborts itself. All consistency checking for
-
-
-deferred updating is performed prior to any updating operation and
-thus memory is still in a completely legal uncommitted state until
-all consistency is performed. For direct updating aborts, the system
-simply follows its normal semantics of aborting the transaction by
-restoring global memory to its original state. Similar to the prior
-example, overriding the permission_to_abort() method can be
-done in such a manner which prevents lower priority transaction
-from aborting a higher priority transaction as shown below:
+While the above approach is necessary for a validating system, it is largely a poor way to perform priority inversion checking. Firstly, it has the side-effect of causing unnecessary aborts for transactions which do not necessarily conflict, but simply have differing priority levels. Secondly, it is slow in that all transactions must be walked through each time a transaction commits. However, as an ad hoc solution for a validating system, the above priority inversion mechanism may be as close to correct as is possible. This solution is useful for validation, but should never be used for invalidation. Instead a second and more natural approach for invalidating systems to prevent priority inversion is to override the permission_to_abort() interface. The permission_to_abort() interface can only be used when __Boost_STM__ is performing invalidation.
+
+The permission_to_abort() interface is called from __Boost_STM_s__ end_transaction() method when a committing transaction has found a second transaction it needs to abort for consistency. As such, the method takes two parameters, an lhs (lefthand side), the committing transaction, and an rhs (right-hand side), the transaction requested to be aborted. If permission is granted to abort the second transaction, the method returns true and the second transaction is aborted. If permission is not granted to abort the second transaction, the method returns false and upon returning the committing transaction aborts itself. All consistency checking for deferred updating is performed prior to any updating operation and thus memory is still in a completely legal uncommitted state until all consistency is performed. For direct updating aborts, the system simply follows its normal semantics of aborting the transaction by restoring global memory to its original state. Similar to the prior example, overriding the permissio
n_to_abort() method can be done in such a manner which prevents lower priority transaction from aborting a higher priority transaction as shown below:

Priority Inversion for Invalidating Consistency.

@@ -314,43 +226,12 @@
 return lhs.priority() >= rhs.priority();
 }
 };
-
-With priority inversion preventable for both validating and invalidating
-consistency modes, transactions now need some mechanism
-to control their priority. __Boost_STM__ allows for such control
-through the raise_priority() interface. By iteratively calling
-raise_priority(), preempted transactions can raise their
-priority at each preemption ensuring their eventual commit. The
-raise_priority() interface is implemented using a size_t
-type. Additionally, __Boost_STM__ supplies a set_priority() interface
-taking a size_t parameter allowing client code to set the
-priority directly.
-
-In order for raise_priority() to function correctly, the affected
-transaction must not be destroyed upon transactional abort.
-If the prioritized transaction is destroyed at each transactional abort,
-raise_priority() will only raise the transaction's priority by
-one each time. In order to demonstrate how raise_priority()
-can be used in practice, we use a wrapper transaction around
-the internal_insert()'s transaction. However, in this case the
-wrapper transaction is not destroyed upon successive iterations.
-The restart_transaction() interface must be called for
-transactions that are not destroyed after being aborted. This necessary
-step clears the state from the previously failed transactional
-run. As shown in the below code, the restart_transaction()
-is only called when an aborted exception is caught. This is because
-end_transaction() throws an exception when the transaction
-is aborted. Following this implementation paradigm, handling
-aborted transactions is relatively straightforward as all aborted
-transactions follow the same exception-based path.
-
-The below example combines all of these aspects together into
-a dynamically prioritized composed transaction. The composition
-is slightly different than what has been shown previously - instead
-of using composition for wrapping two methods into a larger transaction,
-we use composition to override the internal transaction's
-implementation to improve the richness of its behavior, a relatively
-novel concept for composition.
+
+With priority inversion preventable for both validating and invalidating consistency modes, transactions now need some mechanism to control their priority. __Boost_STM__ allows for such control through the raise_priority() interface. By iteratively calling raise_priority(), preempted transactions can raise their priority at each preemption ensuring their eventual commit. The raise_priority() interface is implemented using a size_t type. Additionally, __Boost_STM__ supplies a set_priority() interface taking a size_t parameter allowing client code to set the priority directly.
+
+In order for raise_priority() to function correctly, the affected transaction must not be destroyed upon transactional abort. If the prioritized transaction is destroyed at each transactional abort, raise_priority() will only raise the transaction's priority by one each time. In order to demonstrate how raise_priority() can be used in practice, we use a wrapper transaction around the internal_insert()'s transaction. However, in this case the wrapper transaction is not destroyed upon successive iterations. The restart_transaction() interface must be called for transactions that are not destroyed after being aborted. This necessary step clears the state from the previously failed transactional run. As shown in the below code, the restart_transaction() is only called when an aborted exception is caught. This is because end_transaction() throws an exception when the transaction is aborted. Following this implementation paradigm, handling aborted transactions is relatively straightforward as all aborted transact
ions follow the same exception-based path.
+
+The below example combines all of these aspects together into a dynamically prioritized composed transaction. The composition is slightly different than what has been shown previously - instead of using composition for wrapping two methods into a larger transaction, we use composition to override the internal transaction's implementation to improve the richness of its behavior, a relatively novel concept for composition.

Dynamically Prioritized Composed Transaction.

@@ -362,61 +243,23 @@
 try {
 internal_insert(node, success);
 s = t.end_transaction();
- } catch (aborted_transaction_exception&) {
- t.restart_transaction();
+ } catch (aborted_transaction_exception&) {
+ t.restart_transaction();
 }
 if (!success) return false; // on list
 }
 return true;
 }

-The above example demonstrates a number of important concepts
-with __Boost_STM_s__ extensible contention manager and its implementation
-of composition. First, it shows how to avoid priority
-inversion, using dynamically prioritize transactions, in conjunction
-with a prioritized overridden contention manager for both validation
-and invalidation consistency schemes. Second, it demonstrates
-how transactions which are aborted but not destroyed can be
-restarted with the aborted transaction catch clause. Third, the example
-explains how ordinary transactions can be enriched by layering
-composed transactions on top of them without changing the underlying
-original code. Lastly, it reveals some of __Boost_STM_s__ internal
-priority processing which requires a additional amount of explanation,
-as follows.
-
-__Boost_STM_s__ Internal Write-Write Abort Process.
-
-As the above priority assigned transaction demonstrates, the outer transaction
-has increasing priority while the inner transaction, the one
-within internal_insert(), does not. Yet, the inner transaction
-is not aborted due to the outer transaction's priority. This is handled
-internally via __Boost_STM_s__ abort process by two fundamental
-ideas.
-
-# As previously explained, all transactions of the same
-thread share transactional memory, this allows the outer transaction
-to be seen as using the same memory as the inner transaction.
-Thus, when the inner transaction is flagged to be aborted, the outer
-transaction must also be flagged to be aborted as well, since it
-would have the same memory conflicts. However, when checking
-the outer transaction's priority, the contention manager's priority
-method would see the outer transaction as having higher priority
-than the committing transaction if it had already been aborted
-once and the committing transaction had not. The priority analysis
-of the outer transaction compared to the committing transaction
-would thereby force the committing transaction to abort instead of
-the outer transaction.
-
-# __Boost_STM_s__ abort mechanism does not
-abort any transactions until it has walked all transactions, passing
-all the permission_to_abort() checks. Therefore, even if the
-inner transaction is flagged to be aborted, since all transactions
-must be successfully walked in order to abort any transaction, the
-outer transaction's priority will cause the committing transaction
-to abort, thereby saving the inner transaction from being affected.
-An example of this, taken directly from __Boost_STM_s__ implementation,
-is shown below (some code has been removed or shorted to
-simplify the example):
+The above example demonstrates a number of important concepts with __Boost_STM_s__ extensible contention manager and its implementation of composition. First, it shows how to avoid priority inversion, using dynamically prioritize transactions, in conjunction with a prioritized overridden contention manager for both validation and invalidation consistency schemes. Second, it demonstrates how transactions which are aborted but not destroyed can be restarted with the aborted transaction catch clause. Third, the example explains how ordinary transactions can be enriched by layering composed transactions on top of them without changing the underlying original code. Lastly, it reveals some of __Boost_STM_s__ internal priority processing which requires a additional amount of explanation, as follows.
+
+__Boost_STM_s__ Internal Write-Write Abort Process.
+
+As the above priority assigned transaction demonstrates, the outer transaction has increasing priority while the inner transaction, the one within internal_insert(), does not. Yet, the inner transaction is not aborted due to the outer transaction's priority. This is handled internally via __Boost_STM_s__ abort process by two fundamental ideas.
+
+# As previously explained, all transactions of the same thread share transactional memory, this allows the outer transaction to be seen as using the same memory as the inner transaction. Thus, when the inner transaction is flagged to be aborted, the outer transaction must also be flagged to be aborted as well, since it would have the same memory conflicts. However, when checking the outer transaction's priority, the contention manager's priority method would see the outer transaction as having higher priority than the committing transaction if it had already been aborted once and the committing transaction had not. The priority analysis of the outer transaction compared to the committing transaction would thereby force the committing transaction to abort instead of the outer transaction.
+
+# __Boost_STM_s__ abort mechanism does not abort any transactions until it has walked all transactions, passing all the permission_to_abort() checks. Therefore, even if the inner transaction is flagged to be aborted, since all transactions must be successfully walked in order to abort any transaction, the outer transaction's priority will cause the committing transaction to abort, thereby saving the inner transaction from being affected. An example of this, taken directly from __Boost_STM_s__ implementation, is shown below (some code has been removed or shorted to simplify the example):

 void abort_conflicting_writes_on_write_set() {
 trans_list aborted;
@@ -439,60 +282,189 @@
 (*k)->forced_to_abort() = true;
 }
 }
-
-Priority Inversion Allowed.

-From the above code examples,
-one may question why the default behavior implemented within
-__Boost_STM__ does not automatically integrate priority into transactions,
-as it could be integrated within restart_transaction().
-First, each problem is different and integrating priority only into
-restart_transaction() would not cover all cases (e.g., when
-the outer transaction was terminated). Second, building an automatic
-priority inversion handling scheme would eliminate some of
-the natural optimizations granted from different updating policies.
-For example, deferred updating allows multiple writers of the same
-memory to execute simultaneously. This behavior enables deferred
-updating the ability to process the fastest completing transactions
-first. If a priority system was integrated directly into __Boost_STM__,
-this optimization would be lost. In addition, direct updating optimizes
-writes by writing directly to global memory. As such, direct
-updating suffers greater penalties for aborted transactions due to
-required restoration of global memory. In this case, more transactional
-aborts would occur if __Boost_STM__ built-in a default priority
-inversion handler. Considering these factors, as well as many others,
-__Boost_STM__ does not build transactional priority into its system.
-Instead, we leave this implementation up to client-side implementors,
-as they will have a better understanding of their problem domain
-and be able to more correctly implement the right contention
-manager for their specific needs.
-
-The Future of Parallel Programming.
-
-An important distinction
-regarding priority within transactions versus priority within
-more classical synchronization mechanisms, like locks, is that
-same functional units can be executed simultaneously by different
-threads yielding different priorities. For example, two threads
-can be executing the above insert transaction, one thread which
-has just begun its first run will have a priority of 0, while a second
-transaction which has attempted to run the insert operation 99 times
-previously, would have a priority of 99. The important distinction
-here is that classical critical section synchronization mechanisms
-can have only a single priority per functional unit (e.g., insert,
-remove, lookup operation) due to the innate limitations of single
-thread critical section execution. With transactions, this limitation
-is removed and new concepts of priority begin to emerge. Priority
-inversion can then extend beyond its traditional meaning and
-extend into a new category which incorporates differing priority
-within the same functional unit. These new concepts may reshape
-the way classical parallel problems are thought of in the future,
-especially in relation to transactional memory.
+[heading Priority Inversion Allowed]
+
+From the above code examples, one may question why the default behavior implemented within __Boost_STM__ does not automatically integrate priority into transactions, as it could be integrated within restart_transaction(). First, each problem is different and integrating priority only into restart_transaction() would not cover all cases (e.g., when the outer transaction was terminated). Second, building an automatic priority inversion handling scheme would eliminate some of the natural optimizations granted from different updating policies. For example, deferred updating allows multiple writers of the same memory to execute simultaneously. This behavior enables deferred updating the ability to process the fastest completing transactions first. If a priority system was integrated directly into __Boost_STM__, this optimization would be lost. In addition, direct updating optimizes writes by writing directly to global memory. As such, direct updating suffers greater penalties for aborted transactions due to requ
ired restoration of global memory. In this case, more transactional aborts would occur if __Boost_STM__ built-in a default priority inversion handler. Considering these factors, as well as many others, __Boost_STM__ does not build transactional priority into its system. Instead, we leave this implementation up to client-side implementors, as they will have a better understanding of their problem domain and be able to more correctly implement the right contention manager for their specific needs.
+
+[heading The Future of Parallel Programming]
+
+An important distinction regarding priority within transactions versus priority within more classical synchronization mechanisms, like locks, is that same functional units can be executed simultaneously by different threads yielding different priorities. For example, two threads can be executing the above insert transaction, one thread which has just begun its first run will have a priority of 0, while a second transaction which has attempted to run the insert operation 99 times previously, would have a priority of 99. The important distinction here is that classical critical section synchronization mechanisms can have only a single priority per functional unit (e.g., insert, remove, lookup operation) due to the innate limitations of single thread critical section execution. With transactions, this limitation is removed and new concepts of priority begin to emerge. Priority inversion can then extend beyond its traditional meaning and extend into a new category which incorporates differing priority within th
e same functional unit. These new concepts may reshape the way classical parallel problems are thought of in the future, especially in relation to transactional memory.
+
+[endsect]
+
+[section Can a transactional object embeed another transactional object?]
+
+Let me show what happens when we emmend transactional objects:
+ class C : public transaction_object<C> {...};
+
+ class E : public transaction_object<E> {
+ C c;
+ int i;
+ };
+
+E e;
+
+When a thread T1 modifies e (and possibly the b part) on a transaction another thread T2 can modify e.c on another transaction. When the two transactional objects overlap the STM system is unable to detect this efficiently, having as consequence an inconsistency.
+
+The following pseudo-code shows the
+
+ T1 T2
+ 1 atomic { atomic {
+ 2 e.i=0; e.c=A;
+ 3 }
+ 4 }
+
+
+When T2 commits on (3) e.c will be modified, but T1 will modify the complete E independent of the e.c modification doen by T2, overwriting the e.c with its old value. T1 will be coherent, but not T2. If we want to allow such a scheme, we have several possibilities
+
+* implicit: take care of overlaping transactional objects, so we can detect when T1 commits that an overlaping TO e.c has been modified, so the transaction on T1 is aborted and retried.
+* explicit: the developper of T1 must notify the STM system that the transactional object e constains a transactional object e.c
+* declarative: the developper of E would declare that it contains an emmbeed transactional object C at E::c, so the STM system will use this explicit information when an E is accesses using the STM interface.
+
+The implicit approach is the more transparent for the user but it is also the less efficient. It need to add a virtual function quering the size of the class, and to modify the conflic detection algorithm (maybe the write_list must be a write_set, ordered by the address)
+
+The explit approach let the user with a lot of burden and risk of error when access to an E is done on a transaction. This needs to add the size and the algorithm which adds transactional object on the write_list (maybe the write_list must be a write_interval_set, ordered by the address).
+
+The declarative concentrate on a single place, so the user will be not too concerned, and this open possible optimizations.
+
+
+Supose now that we are able to embeed transactional objects. and that the T1 not only opens for writing e, but also e.c either on the same block on on a block (or nested transaction). The STM will see both address to be written, and even if there should be no risk of incoherence the object e.c will be copied twice.
+
+[endsect]
+
+[section Returning values from a fucntion]
+
+[heading Returning from outside the transaction context]
+
+The simgle way consists is using a local variable declared outside the transaction context.
+
+ int inc_c() {
+ int res;
+ atomic(_) {
+ res = *(_.read(c))+i;
+ } end_atom;
+ return res;
+ }
+
+[heading Returning from inside]
+
+The following attempt does not work as the transaction will not be commited.
+
+ int inc_c(int i) {
+ atomic(_) {
+ write_ptr<tx_int> tx_c(_,c);
+ return *(tx_c)+=i;
+ } end_atom;
+ }
+
+We need to commit before returning. SO we will need any way a local variable storing the result before commiting.
+
+ int inc_c(int i) {
+ atomic(_) {
+ write_ptr<tx_int> tx_c(_,c);
+ int res = *(tx_c)+=i;
+ _.commit();
+ return res;
+ } end_atom;
+ }
+
+[endsect]
+
+[section Pointer to transactional objects]
+
+Access to a pointer to a transaction object works, but this do not take care of modifications of the pointer itself.
+
+[heading Using the mixin transaction_object<>]
+
+Let B the TO made using the mixin transaction_object.
+
+ class B : public transaction_object {
+ public:
+ void virtaul fct();
+ };
+
+How a variable pointing to B must be declared. The fact that B is a transactional object do not means that a pointer to it is one. We need a class that wraps the pointer
+
+ template <typename TO>
+ class transaction_object_ptr : public transaction_object<transaction_object_ptr<TO> > {
+ public:
+ TO* ptr_;
+ typedef transaction_object_ptr<TO> this_type;
+ typedef transaction_object<transaction_object_ptr<TO> > base_type;
+ transaction_object_ptr() : base_type(), ptr_(0) {
+ }
+ transaction_object_ptr(const transaction_object_ptr & rhs) : base_type(rhs), ptr_(rhs.ptr_) {
+ }
+ transaction_object_ptr(transaction_object_ptr & rhs) : base_type(rhs), ptr_(rhs.rhs) {
+ }
+ transaction_object_ptr(TO* ptr) : base_type(), ptr_(ptr) {
+ }
+ ~transaction_object_ptr() {
+ }
+ this_type& operator=(TO* rhs) {
+ ptr_=rhs;
+ return *this;
+ }
+
+ TO* get() const {
+ std::cout << "get" << std::endl;
+ return ptr_;
+ }
+
+ inline TO& operator*() const { return *get(); }
+ inline TO* operator->() const { return get(); }
+ };
+
+Let declare a pointer to B
+
+ transaction_object_ptr ptr_b;
+
+
+ atomic(_) {
+ write_ptr< pointer > tx_ptr_b_ptr(_, ptr_b);
+ *tx_ptr_b_ptr=BOOST_STM_NEW(_, B());
+ }
+

[endsect]

[section Polymorphic]

+How the user can defien a transactional class D inheriting from a transactional class B
+
+[heading Using the mixin transaction_object<>]
+
+Let B the base class
+
+ class B : public transaction_object {
+ public:
+ void virtaul fct();
+ };
+
+The derived class must declare D as follows:
+
+ class D : public transaction_object<D,B> {
+ ...
+ };
+
+How a variable pointing to B must be declared. The fact that B is a transactional object do not means that a pointer to it is one.
+
+ pointer ptr_b = 0
+
+How can we assign a pointer to D?
+
+ write_ptr<B*> tx_ptr_b_ptr(_,ptr_b);
+ *ptr_b = BOOST_STM_NEW(_, D())
+
+[heading Using the mixin transaction_object<>]
+
+[endsect]
+
+[section Can non transactional objets participate in a transaction?]
+
+Non transactional objects are the objects that do not inherit from base_transaction_object.
+
[endsect]

[section Lock aware]

Modified: sandbox/stm/branches/vbe/libs/stm/doc/users_guide.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/users_guide.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/users_guide.qbk 2009-09-20 19:20:26 EDT (Sun, 20 Sep 2009)
@@ -1,6 +1,6 @@
[/
[/
- (C) Copyright 2009 Justin E. Gottchlich.
+ (C) Copyright 2009 Justin E. Gottchlich.
   (C) Copyright 2009 Vicente J. Botet Escriba
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at
@@ -25,24 +25,26 @@

[[ACI] [Atomic, Consistent and Isolated]]
[[LATM] [lock aware transaction memory]]
-[[LiT] [Lock in transaction]]
-[[LoT] [Lock out of transaction]]
+[[LiT] [Lock inside Transactions]]
+[[LoT] [Lock outside Transactions]]
[[STM] [Software Transaction Memory]]
-[[TX] [Transaction]]
[[TM] [Transaction Memory]]
+[[TX] [Transaction]]

-[[in fligh transaction] [.]]
-[[Conflict Detection] [.]]
[[abort] [.]]
+[[Conflict Detection] [.]]
[[commit] [.]]
[[Consistency Checking] [.]]
-[[Direct Updating] [.]]
[[Deferred Updating] [.]]
+[[Direct Updating] [.]]
+[[Full-Lock protection] [.]]
+[[In fligh transaction] [.]]
[[Irrevocable transaction] [.]]
[[Isolated transaction] [.]]
-[[Full-Lock protection] [.]]
[[TM-Lock protection] [.]]
[[TX-Lock protection] [.]]
+
+
[[commit] [.]]
[[commit] [.]]
[[commit] [.]]

Next message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r56334 - sandbox/stm/branches/vbe/libs/stm/test"
Previous message: jeff_at_[hidden]: "[Boost-commit] svn:boost r56332 - in sandbox/explore: boost boost/explore libs/explore/doc"

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