Boost-Commit :

Date view	Thread view	Subject view	Author view

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

Author: viboes
Date: 2009-09-18 19:00:15 EDT (Fri, 18 Sep 2009)
New Revision: 56303
URL: http://svn.boost.org/trac/boost/changeset/56303

Log:
TBoost.Stm vbe
* Minor modifications

Text files modified:
   sandbox/stm/branches/vbe/libs/stm/doc/appendices.qbk | 39 ++++-
   sandbox/stm/branches/vbe/libs/stm/doc/getting_started.qbk | 2
   sandbox/stm/branches/vbe/libs/stm/doc/html/index.html | 2
   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 | 4
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/rationale.html | 10
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/appendices/todo.html | 105 ++++++++++++---
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/overview.html | 22 +-
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide.html | 3
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/getting_started.html | 64 ++++++--
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/glosary.html | 34 +++-
   sandbox/stm/branches/vbe/libs/stm/doc/html/toward_boost_stm/users_guide/tutorial.html | 94 +++++++++++--
   sandbox/stm/branches/vbe/libs/stm/doc/installation.qbk | 54 +++++--
   sandbox/stm/branches/vbe/libs/stm/doc/overview.qbk | 28 ++--
   sandbox/stm/branches/vbe/libs/stm/doc/reference/transaction_object.qbk | 270 ++++++++++++++++++++++++++++++++++++++-
   sandbox/stm/branches/vbe/libs/stm/doc/stm.qbk | 1
   sandbox/stm/branches/vbe/libs/stm/doc/tutorial.qbk | 61 +++++++-
   sandbox/stm/branches/vbe/libs/stm/doc/users_guide.qbk | 12 +
   18 files changed, 654 insertions(+), 155 deletions(-)

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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -70,20 +70,39 @@

* Add unit tests

+[heading Benchmarks]
+
+* Add some specific benchmarks.
+
[heading Documentation]

* [*DONE] Create the empty files and set the doc generation environement
-* Write the Motivation section
-* Write the Getting started section
-* [*DONE] Write the Installation section
-* Write the Tutorial section
-* Write the Example section
+* [*DONE] Write the Motivation section
+* Write the User'Guide section
+ * [*DONE] Write the Getting started section
+ * [*DONE] Write the Installation started section
+ * [*DONE] Write the Hello World example
+ * [*DONE] Write the Installation section
+ * Write the Tutorial section
+ * Write the Preamble/Initialization section
+ * [*DONE] Write the Simple transaction section
+ * [*DONE] Write the Composable transaction section
+ * [*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
* Write the Reference section
-* [*DONE] Write the Bibliography section
-* Write the Glossary section
-* Write the Rationale section
-* Write the Implementation notes section
-* Write the Acknowledgements section
+* Write the Appendix section
+ * Write the History section
+ * Write the Rationale section
+ * Write the Implementation notes section
+ * Write the Acknowledgements section
+ * Write the Tests section
+ * Write the Tickets section
+ * [*DONE] Write the Future plans section

[endsect]

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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -32,7 +32,7 @@
         return val;
     }

-In the above example, (A) both the write on global_int and the read operations function atomically or neither operations are performed. In addition, (C) the transaction begins and ends in legal memory
+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/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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -101,7 +101,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 17:16:32 GMT</td>
+<td align="left">Last revised: September 18, 2009 at 22:55:08 GMT</td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

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-18 19:00:15 EDT (Fri, 18 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="id4885927"></a>
+<a name="id4886949"></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="id4886000"></a>
+<a name="id4887022"></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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -70,11 +70,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="id4889557"></a>
+<a name="id4890531"></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="id4889578"></a>
+<a name="id4890552"></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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -256,7 +256,7 @@
 read).
 
<div class="table">
-<a name="id4886511"></a>Table 1.1. Comparaison with other STM systems
+<a name="id4887533"></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 +459,7 @@
 handle each specific problem with the most appropriate configuration.
 
<div class="table">
-<a name="id4886906"></a>Table 1.2. Consistency versus Updating policies composition
+<a name="id4887918"></a>Table 1.2. Consistency versus Updating policies composition
<div class="table-contents"><table class="table" summary="Consistency versus Updating policies composition">
<colgroup>
<col>
@@ -882,7 +882,7 @@
 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="id4887981"></a>
+<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
 in Transactional Execution of Automatic Objects</a>
 </h6>
@@ -975,7 +975,7 @@
 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="id4888889"></a>
+<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
 of Language Based Transactional Integration</a>
 </h6>
@@ -1019,7 +1019,7 @@
 with other STM systems</a>
</h4></div></div></div>
<div class="table">
-<a name="id4888980"></a>Table 1.3. Comparaison
+<a name="id4889966"></a>Table 1.3. 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-18 19:00:15 EDT (Fri, 18 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="id4889912"></a>
+<a name="id4890886"></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="id4889967"></a>
+<a name="id4890941"></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="id4890145"></a>
+<a name="id4891119"></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,14 +157,21 @@
 </li>
</ul></div>
<a name="toward_boost_stm.appendices.todo.tasks_to_do_before_review.tests"></a><h6>
-<a name="id4890204"></a>
+<a name="id4891178"></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 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="id4890235"></a>
+<a name="id4891240"></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">
@@ -173,38 +180,92 @@
 the doc generation environement
 </li>
<li>
- Write the Motivation section
+DONE Write the Motivation section
 </li>
<li>
- Write the Getting started section
- </li>
+ Write the User'Guide section
+ <div class="itemizedlist"><ul type="circle">
+<li>
+DONE Write the Getting started section
+ <div class="itemizedlist"><ul type="square">
+<li>
+DONE Write the Installation
+ started section
+ </li>
+<li>
+DONE Write the Hello World example
+ </li>
+</ul></div>
+</li>
<li>
DONE Write the Installation section
- </li>
+ </li>
<li>
- Write the Tutorial section
- </li>
+ Write the Tutorial section
+ <div class="itemizedlist"><ul type="square">
+<li>
+ Write the Preamble/Initialization section
+ </li>
+<li>
+DONE Write the Simple transaction
+ section
+ </li>
+<li>
+DONE Write the Composable transaction
+ section
+ </li>
+<li>
+DONE Write the A Dynamically
+ Prioritized, Composed Transaction section
+ </li>
+<li>
+ Write the Lock aware section
+ </li>
<li>
- Write the Example section
+ Write the Lock aware section
+ </li>
+</ul></div>
+</li>
+<li>
+DONE Write the References section
+ </li>
+<li>
+ Write the Glossary section
+ </li>
+</ul></div>
+</li>
+<li>
+ Write the Examples section
 </li>
<li>
 Write the Reference section
 </li>
<li>
-DONE Write the Bibliography section
- </li>
+ Write the Appendix section
+ <div class="itemizedlist"><ul type="circle">
<li>
- Write the Glossary section
- </li>
+ Write the History section
+ </li>
<li>
- Write the Rationale section
- </li>
+ Write the Rationale section
+ </li>
<li>
- Write the Implementation notes section
- </li>
+ Write the Implementation notes section
+ </li>
<li>
- Write the Acknowledgements section
- </li>
+ Write the Acknowledgements section
+ </li>
+<li>
+ Write the Tests section
+ </li>
+<li>
+ Write the Tickets section
+ </li>
+<li>
+DONE Write the Future plans section
+ </li>
+</ul></div>
+</li>
</ul></div>
</div>
<div class="section" lang="en">

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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -43,12 +43,12 @@
 institutions with many open questions about its behavior.
 

- Boost.STM is a C++ lock-based software transactional memory (STM) library.
+ TBoost.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:
+ TBoost.STM provides:
 
<div class="itemizedlist"><ul type="disc">
<li>
@@ -58,7 +58,7 @@
 ACI transactions
 <div class="itemizedlist"><ul type="circle">
<li>
- Atomic: all or nothing
+ Atomic: all operations execute or none do
 </li>
<li>
 Consistent: only legal memory states
@@ -72,26 +72,28 @@
 Language-like atomic transaction macro blocks
 </li>
<li>
- Open-nested composable transactions
+ Closed, flattened composable transactions
 </li>
<li>
- Direct/deffered updating policies
+ Direct and deferred updating run-time policies
 </li>
<li>
- Validation/invalidation consistency checking policies
+ Validation and invalidation conflict detection policies
 </li>
<li>
- Lock-aware transaction
+ Lock-aware transactions
 </li>
<li>
- Contention management: Mechanism for transaction forward progress
+ Programmable contention management, enabling programmers to specify forward
+ progress mechanisms
 </li>
<li>
- Unrecoverable transaction to manage with I/O
+ Isolated and irrevocable transactions for transactions that must commit (i.e.,
+ I/O transactions)
 </li>
</ul></div>
<a name="toward_boost_stm.overview.how_to_use_this_documentation"></a><h4>
-<a name="id4810523"></a>
+<a name="id4810525"></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/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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -43,6 +43,9 @@
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>Polymorphic</dt>
+<dt><a href="users_guide/tutorial.html#toward_boost_stm.users_guide.tutorial.lock_aware">Lock
+ aware</a></dt>
</dl></dd>
<dt> References</dt>
<dt> Glossary</dt>

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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -61,7 +61,7 @@
 memory!
 
<a name="toward_boost_stm.users_guide.getting_started.install.getting_boost_stm"></a><h6>
-<a name="id4849074"></a>
+<a name="id4849300"></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,18 +78,19 @@
 Sandbox</a>.
 
<a name="toward_boost_stm.users_guide.getting_started.install.building_boost_stm"></a><h6>
-<a name="id4849128"></a>
+<a name="id4849354"></a>
 <a class="link" href="getting_started.html#toward_boost_stm.users_guide.getting_started.install.building_boost_stm">Building
 Boost.STM</a>
 </h6>

- Boost.STM is not a header only library. You need to compile it before use.
+ TBoost.STM is not a header only library. You need to compile it before
+ use.
 
<pre class="programlisting">cd libs/stm/build
bjam
</pre>
<a name="toward_boost_stm.users_guide.getting_started.install.requirements"></a><h6>
-<a name="id4849192"></a>
+<a name="id4849418"></a>
 <a class="link" href="getting_started.html#toward_boost_stm.users_guide.getting_started.install.requirements">Requirements</a>
 </h6>

@@ -100,44 +101,67 @@
 threads (pthreads) for Windows</a>
 

- In order to be more portable Boost.STM
- is migrating to Boost. You should use either Boost version 1.39.x or the
- version in SVN trunk (even if Boost version 1.35.x should works also).
- In particular, Boost.STM will depends
+ In order to be more portable TBoost.STM is migrating to Boost. You should
+ use either Boost version 1.39.x or the version in SVN trunk (even if Boost
+ version 1.35.x should works also). In particular, TBoost.STM will depends
 on:
 
<div class="variablelist">

<dl>
-<dt>Boost.DynamicBitset</dt>
+<dt>Boost.DynamicBitset from Jeremy Siek and
+ Chuck Allison</dt>
<dd>
- dynamic_bitsets
+ dynamic_bitsets (replacement of the current bit_vector)
 </dd>
<dt>Boost.Thread from Anthony Williams</dt>
<dd>
- threads and synchronization primitives
+ threads and synchronization primitives (making the lib portable to
+ other platforms)
+ </dd>
+<dt>Boost.Pool from Stephen Cleary</dt>
+<dd>
+ Memory pool management (replacement of the current memory_pool)
 </dd>
</dl>
</div>

- In addition Boost.Stm will uses the following libraries on the Boost Sandbox
+ In addition TBoost.STM will uses the following libraries on the Boost Sandbox
 
<div class="variablelist">

<dl>
-<dt>Boost.Chrono from Vicente J. Botet Escriba</dt>
+<dt>Boost.BloomFilters from Dean Michael Berris</dt>
+<dd>
+ bloom_filters (replacement of the current bloom_filter)
+ </dd>
+<dt>Boost.Chrono from Beman Dawes</dt>
+<dd>
+ Standard Chrono library (making the lib portable to other platforms)
+ </dd>
+<dt>Boost.Containers from Ion Gaztanaga</dt>
+<dd>
+ flat containers (replacement of the current vector_map and vector_set)
+ </dd>
+<dt>Boost.InterThreads from Vicente J. Botet
+ Escriba</dt>
+<dd>
+ Thread specific shared pointer (replacement of the current maps having
+ thread_id as domain)
+ </dd>
+<dt>Boost.Move from Ion Gaztanaga</dt>
<dd>
- Standard Chrono library
+ Move semantics (replacement of the current Draco_move)
 </dd>
-<dt>Boost.Synchro from Vicente J. Botet Escriba</dt>
+<dt>Boost.Synchro from Vicente J. Botet Escriba</dt>
<dd>
 Exception based timed locks synchronization primitives & Language-like
- Synchronized Block
+ Synchronized Block (making the lib portable to other platforms)
 </dd>
</dl>
</div>
<a name="toward_boost_stm.users_guide.getting_started.install.exceptions_safety"></a><h6>
-<a name="id4849352"></a>
+<a name="id4849670"></a>
 <a class="link" href="getting_started.html#toward_boost_stm.users_guide.getting_started.install.exceptions_safety">Exceptions
 safety</a>
 </h6>
@@ -146,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="id4849378"></a>
+<a name="id4849696"></a>
 <a class="link" href="getting_started.html#toward_boost_stm.users_guide.getting_started.install.thread_safety">Thread
 safety</a>
 </h6>
@@ -154,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="id4849405"></a>
+<a name="id4849723"></a>
 <a class="link" href="getting_started.html#toward_boost_stm.users_guide.getting_started.install.tested_compilers">Tested
 compilers</a>
 </h6>
@@ -202,7 +226,7 @@
}
</pre>

- In the above example, (A) both the write on global_int and the read operations
+ 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

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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -29,18 +29,38 @@
<div class="variablelist">

<dl>
-<dt>in fligh transaction</dt>
+<dt>ACI</dt>
<dd>
- .
+ Atomic, Consistent and Isolated
 </dd>
-<dt>latm</dt>
+<dt>LATM</dt>
<dd>
 lock aware transaction memory
 </dd>
+<dt>LiT</dt>
+<dd>
+ Lock in transaction
+ </dd>
+<dt>LoT</dt>
+<dd>
+ Lock out of transaction
+ </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>
+<dd>
+ .
+ </dd>
<dt>Conflict Detection</dt>
<dd>
 .
@@ -65,14 +85,6 @@
<dd>
 .
 </dd>
-<dt>LiT</dt>
-<dd>
- .
- </dd>
-<dt>LoT</dt>
-<dd>
- .
- </dd>
<dt>Irrevocable transaction</dt>
<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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -33,6 +33,9 @@
 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>Polymorphic</dt>
+<dt><a href="tutorial.html#toward_boost_stm.users_guide.tutorial.lock_aware">Lock
+ aware</a></dt>
</dl></div>

 A number of example transactions are presented in this section using the
@@ -52,7 +55,7 @@

 While most of the examples are intuitive and a complete understanding of
 the TBoost.STM API is not needed for a high-level understanding of its functionality,
- a complete description of all interfaces used below can found in referenced
+ a complete description of all interfaces used below can be found in the referenced
 section.
 
<div class="section" lang="en">
@@ -68,14 +71,14 @@
 calls.
 
<a name="toward_boost_stm.users_guide.tutorial.a_simple_transaction.client_invoked_inserts"></a><h6>
-<a name="id4849752"></a>
+<a name="id4803999"></a>
 <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.a_simple_transaction.client_invoked_inserts">Client
 Invoked Inserts</a>
 </h6>
<pre class="programlisting">tx_ptr<linked_list<int> > llist;
...
-atomic(_) {
- for (int i = 0; i < 100; ++i) {
+for (int i = 0; i < 100; ++i) {
+ use_atomic(_) {
 llist->insert(i);
 }
}
@@ -84,19 +87,36 @@
 After inspecting the above client invoked insert code it is apparent that
 the code itself shows no deep signs of being transactional. The two exceptions
 are the declaration of the list using a tx_ptr smart pointer and the fact
- that the insertion of te 100 elements is atomic. This is our desired behavior.
+ that the insertion of the 100 elements is atomic. This is our desired behavior.
 As far as the client side programmer is concerned, there is no additional
 code needed to perform a transactional linked list insert over a non-transactional
 linked list insert. Obviously, this simplistic behavior eases the introduction
 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="id4803994"></a>
+<a name="id4804232"></a>
 <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.a_simple_transaction.linked_list_declaration">Linked
 list declaration</a>
 </h6>
+
+ A clasical linked list use a list node chained following the memer next_.
+ On a transactional context we nedd to state that the pointer to the next
+ node is a transactional one. This is reached using the smart pointer tx_ptr<>
+ 
+<pre class="programlisting">template <typename T>
+struct list_node {
+ tx_ptr<list_node<T> > next_;
+}
+
+template <typename T>
+class linked_list {
+// ...
+private:
+ tx_ptr<list_node<T> > head_;
+};
+</pre>
<a name="toward_boost_stm.users_guide.tutorial.a_simple_transaction.insert_retry_transaction"></a><h6>
-<a name="id4804016"></a>
+<a name="id4804476"></a>
 <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.a_simple_transaction.insert_retry_transaction">Insert
 retry transaction</a>
 </h6>
@@ -127,7 +147,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="id4804548"></a>
+<a name="id4804764"></a>
 <a class="link" href="tutorial.html#toward_boost_stm.users_guide.tutorial.a_simple_transaction.insert_specific">Insert
 specific</a>
 </h6>
@@ -155,18 +175,28 @@
 transactions small and easy to understand.
 

- One minor, but vital, detail is in way new objects are created on a transactional
- context. Rather than hide this difference, it is intentionally exposed
- here to draw out the memory access differences required for writes to new
- and existing memory. We explain this difference in detail later in this
- section.
+ upgrd_ptr is a read only smart pointer that can be upgraded to a read/write
+ smart pointer. Once the smart pointer is constructed (associating it to
+ the current transaction), the user can access any member as if it was non
+ transactional.
+ 
+
+ make_wr_ptr is a read/write smart pointer factory. The returned wr_ptr<>
+ allows to modify the pointee object.
+ 
+
+ One minor, but vital, detail is in the way new objects are created on a
+ transactional context. Rather than hide this difference, it is intentionally
+ exposed here to draw out the memory access differences required for writes
+ to new and existing memory. We explain this difference in detail later
+ in this section.
 

- In order to simplify the retry mechanism a macro is provided so the user
- can just write
+ In order to simplify the retry mechanism the macro <code class="computeroutput">use_atomic</code>
+ is provided so the user can just write
 
<pre class="programlisting">void insert(T const &val) {
- atomic(_) {
+ use_atomic(_) {
 upgrd_ptr<list_node<T> > prev(_, head_);
 upgrd_ptr<list_node<T> > curr(_, head_->next_);
 while (curr) {
@@ -182,6 +212,29 @@
 }
}
</pre>
+
+ We could also write the following, but this is less efficient as tx_ptr
+ is a smart pointer that associated the pointer to the current transaction
+ for writting. The use of the smart pointer upgrd_ptr and the smart pointer
+ factory function make_wr_ptr allows to make the difference kind of access.
+ 
+<pre class="programlisting">void insert(T const &val) {
+ use_atomic(_) {
+ tx_ptr<list_node<T> > prev(head_);
+ tx_ptr<list_node<T> > curr(head_->next_);
+ while (curr) {
+ if (curr->value_ == val) return;
+ else if (curr->value_ > val) break;
+ prev = curr;
+ curr = curr->next_;
+ }
+ if (!curr || (curr->value_ > val)) {
+ prev->next_ =
+ BOOST_STM_NEW(_,transactional_object<list_node<T> >(val, curr));
+ }
+ }
+}
+</pre>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
@@ -267,7 +320,7 @@

 The move() implementation do not requires any overhead required in non-transactional
 implementations, other than using the atomic guard. The remainder of the
- code
+ code is preserved.
 
</div>
<div class="section" lang="en">
@@ -547,6 +600,13 @@
 memory.
 
</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>
+<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>
+</h4></div></div></div></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>

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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -11,11 +11,11 @@
[section:install Installing STM]
[/======================================]

-TBoost.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__ 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.

-TBoost.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 TBoost.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]
@@ -35,7 +35,7 @@
[heading Building Boost.STM]
[/=================================]

-Boost.STM is not a header only library. You need to compile it before use.
+__Boost_STM__ is not a header only library. You need to compile it before use.

     cd libs/stm/build
     bjam
@@ -45,37 +45,59 @@
[/=========================]

-The POSIX threads (pthreads) library is needed to use TBoost.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]

-In order to be more portable [*Boost.STM] is migrating to Boost. You should use either Boost version 1.39.x
-or the version in SVN trunk (even if Boost version 1.35.x should works also).
-In particular, [*Boost.STM] will depends on:
+In order to be more portable __Boost_STM__ is migrating to Boost. You should use either Boost version 1.39.x or the version in SVN trunk (even if Boost version 1.35.x should works also). In particular, __Boost_STM__ will depends on:

[variablelist
[
- [[@http://www.boost.org/libs/dynamic_bitset [*Boost.DynamicBitset]]]
- [dynamic_bitsets]
+ [[@http://www.boost.org/libs/dynamic_bitset [*Boost.DynamicBitset]] from Jeremy Siek and Chuck Allison]
+ [dynamic_bitsets (replacement of the current bit_vector)]
]
[
     [[@http://www.boost.org/libs/thread [*Boost.Thread]] from Anthony Williams]
- [threads and synchronization primitives]
+ [threads and synchronization primitives (making the lib portable to other platforms)]
+]
+[
+ [[@http://www.boost.org/libs/pool [*Boost.Pool]] from Stephen Cleary]
+ [Memory pool management (replacement of the current memory_pool)]
]
]

-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
[
- [[@https://svn.boost.org/trac/boost/wiki/LibrariesUnderConstruction#Boost.Synchro [*Boost.Chrono]] from Vicente J. Botet Escriba]
- [Standard Chrono library]
+ [[@http://svn.boost.org/trac/boost/wiki/LibrariesUnderConstruction#Boost.BloomFilters [*Boost.BloomFilters]] from Dean Michael Berris]
+ [bloom_filters (replacement of the current bloom_filter)]
+]
+[
+ [[@http://svn.boost.org/trac/boost/wiki/LibrariesUnderConstruction#Boost.Chrono [*Boost.Chrono]] from Beman Dawes]
+ [Standard Chrono library (making the lib portable to other platforms)]
+]
+
+[
+ [[@http://svn.boost.org/trac/boost/wiki/LibrariesUnderConstruction#Boost.Containers [*Boost.Containers]] from Ion Gaztanaga]
+ [flat containers (replacement of the current vector_map and vector_set)]
]

[
- [[@https://svn.boost.org/trac/boost/wiki/LibrariesUnderConstruction#Boost.Synchro [*Boost.Synchro]] from Vicente J. Botet Escriba]
- [Exception based timed locks synchronization primitives & Language-like Synchronized Block]
+ [[@http://svn.boost.org/trac/boost/wiki/LibrariesUnderConstruction#Boost.InterThreads [*Boost.InterThreads]] from Vicente J. Botet Escriba]
+ [Thread specific shared pointer (replacement of the current maps having thread_id as domain)]
]
+
+[
+ [[@http://svn.boost.org/trac/boost/wiki/LibrariesUnderConstruction#Boost.Move [*Boost.Move]] from Ion Gaztanaga]
+ [Move semantics (replacement of the current Draco_move)]
+]
+
+[
+ [[@http://svn.boost.org/trac/boost/wiki/LibrariesUnderConstruction#Boost.Synchro [*Boost.Synchro]] from Vicente J. Botet Escriba]
+ [Exception based timed locks synchronization primitives & Language-like Synchronized Block (making the lib portable to other platforms)]
+]
+
]

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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -18,23 +18,23 @@

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__ 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:
+[*__Boost_STM__] provides:

-* Optimistic concurrency
-* ACI transactions
- * Atomic: all or nothing
- * Consistent: only legal memory states
- * Isolated: other txes cannot see until committed
-* Language-like atomic transaction macro blocks
-* Open-nested composable transactions
-* Direct/deffered updating policies
-* Validation/invalidation consistency checking policies
-* Lock-aware transaction
-* Contention management: Mechanism for transaction forward progress
-* Unrecoverable transaction to manage with I/O
+* 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)

[/====================================]

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-18 19:00:15 EDT (Fri, 18 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
@@ -14,38 +14,192 @@
 namespace boost { namespace stm {
 class base_transaction_object;
 template <class Derived> class transaction_object;
- template <typename T> class native_trans;
+ 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 <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 Abstract Class `base_transaction_object`]

+This is the base class of all the transactional objects. It tracks:
+
+* `transactionThread_`: the thread identifier holding the write acces to this transactional object
+* `transaction_`: the pointer to the transaction
+* `version_`: the version when performing validation
+* `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`
+
+`copy_state` is used to copy the backup/working copy to the shared transactional object when the roolback/commit is done direct/defered policy is used.
+
+`move_state` is used to move the backup/working copy to the shared transactional object when the roolback/commit is done direct/defered policy is used.
+
+`cache_deallocate` 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 (`retrieve_mem` and `return_mem`) and to manage a pool of memory.
+
+
 class base_transaction_object
 {
 public:

+ base_transaction_object();
+ virtual ~base_transaction_object() {};
+
+ 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
+
+};
+
+[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.
+
+[endsect]
+
+[section Virtual Destructor `~base_transaction_object()`]
+
 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.
+
+[endsect]
+
+[section Virtual function `copy_state()`]
+
 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.
+
+[endsect]
+
+
+[section Virtual function `move_state()`]
+
 virtual void move_state(base_transaction_object * rhs) = 0;

- void transaction_thread(thread_id rhs) const;
- thread_id transaction_thread() const;
+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 &&)).

- void new_memory(bool rhs)
- bool new_memory() const;
+[endsect]

- #if BOOST_STM_PERFORMING_VALIDATION
- void version(std::size_t rhs);
- std::size_t version() const;
- #endif
+[section Static function `retrieve_mem()`]
+
+ 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.
+
+[endsect]
+
+
+[section Static function `return_mem()`]
+
+ 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.
+[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.
+
+[endsect]
+
+[section Virtual function `cache_deallocate()`]
+
+ virtual void cache_deallocate()=0;
+
+[endsect]

- };

[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.
+
 template <class Derived>
 class transaction_object : public base_transaction_object {
 public:
@@ -54,6 +208,27 @@
 virtual void move_state(base_transaction_object * rhs);
 };

+[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.
+
+[endsect]
+
+[section Virtual function `move_state()`]
+
+ 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.
+
+[endsect]
+
+[section Virtual function `cache_deallocate()`]
+
+ virtual void cache_deallocate()=0;
+
+[endsect]
[endsect]

[section Template Class `native_trans<>`]
@@ -81,9 +256,80 @@
 };

[endsect]
-[section Class `base_transaction`]
+
+[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
+* `move_state` and
+* `cache_deallocate`: relaying on the cache_restore<T> generic function
+
+Defines in addition the functions `new` and `delete` when `BOOST_STM_USE_MEMORY_MANAGER` is defined
+
+If a class D inherits from B we have that `transactional_object<D>` dont inherits from `transactional_object`, but
+we can static/dynamic cast them robustly.
+
+Evidently the `std::static_cast`/`std::dynamic_cast` do not works. We need to define the specific cast
+
+ transactional_object<D>* d=...;
+ transactional_object* b=tx_static_cast(d);
+
+ transactional_object* b=...;
+ transactional_object<D>* d=tx_dynamic_cast(b);
+
+Synopsis
+
+ 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
+
+ };
+
+[section Virtual function `copy_state()`]
+
+ virtual void copy_state(base_transaction_object const * const rhs);
+
+[endsect]
+
+[section Virtual function `move_state()`]
+
+ virtual void move_state(base_transaction_object * rhs);
+
+[endsect]
+
+[section Virtual function `cache_deallocate()`]
+
+ virtual void cache_deallocate()=0;

[endsect]
+
+[endsect]
+
[endsect]

Modified: sandbox/stm/branches/vbe/libs/stm/doc/stm.qbk
==============================================================================
--- sandbox/stm/branches/vbe/libs/stm/doc/stm.qbk (original)
+++ sandbox/stm/branches/vbe/libs/stm/doc/stm.qbk 2009-09-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -28,6 +28,7 @@
[def __Boost_STM__ TBoost.STM]
[def __RSTM__ RSTM]
[def __TL2__ TL2]
+[def __use_atomic__ `use_atomic`]

[/

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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -12,7 +12,7 @@

A number of example transactions are presented in this section using the __Boost_STM__ library. The first example illustrates how to write a transactional linked list insert operation. The second example demonstrates composition, combining a transactional insert operation with a transactional remove operation which compose into a larger, single move transaction. Next, a minor but important detail regarding memory addresses within the transactional workspace is given. Finally, an example of how to handle priority inversion for validating and invalidating consistency schemes using __Boost_STM_s__ extensible contention manager and compositional framework is provided. The final example demonstrates a number of important aspects of __Boost_STM_s__ implementation, such as, differing priority inversion mechanics for different consistency models, transactional attribute enrichment via composition and threaded memory sharing amongst transactions.

-While most of the examples are intuitive and a complete understanding of the __Boost_STM__ API is not needed for a high-level understanding of its functionality, a complete description of all interfaces used below can found in referenced section.
+While most of the examples are intuitive and a complete understanding of the __Boost_STM__ API is not needed for a high-level understanding of its functionality, a complete description of all interfaces used below can be found in the referenced section.

@@ -24,16 +24,30 @@

 tx_ptr<linked_list<int> > llist;
 ...
- atomic(_) {
- for (int i = 0; i < 100; ++i) {
+ for (int i = 0; i < 100; ++i) {
+ use_atomic(_) {
 llist->insert(i);
 }
 }

-After inspecting the above client invoked insert code it is apparent that the code itself shows no deep signs of being transactional. The two exceptions are the declaration of the list using a tx_ptr smart pointer and the fact that the insertion of te 100 elements is atomic. This is our desired behavior. As far as the client side programmer is concerned, there is no additional code needed to perform a transactional linked list insert over a non-transactional linked list insert. Obviously, this simplistic behavior eases the introduction of TM solutions into algorithms of new and legacy systems.
+After inspecting the above client invoked insert code it is apparent that the code itself shows no deep signs of being transactional. The two exceptions are the declaration of the list using a tx_ptr smart pointer and the fact that the insertion of the 100 elements is atomic. This is our desired behavior. As far as the client side programmer is concerned, there is no additional code needed to perform a transactional linked list insert over a non-transactional linked list insert. Obviously, this simplistic behavior eases the introduction of TM solutions into algorithms of new and legacy systems.

[heading Linked list declaration]

+A clasical linked list use a list node chained following the memer next_. On a transactional context we nedd to state that the pointer to the next node is a transactional one. This is reached using the smart pointer tx_ptr<>
+
+ template <typename T>
+ struct list_node {
+ tx_ptr<list_node<T> > next_;
+ }
+
+ template <typename T>
+ class linked_list {
+ // ...
+ private:
+ tx_ptr<list_node<T> > head_;
+ };
+
[heading Insert retry transaction]

 void insert(T const &val) {
@@ -64,12 +78,17 @@

The above example illustrates the simplicity of __Boost_STM__ transactions and their interfaces. The transactional implementation is nearly identical to a non-transactional implementation with the exception of some annotations. The templatized functions within the transaction class ensure type-safety is maintained without any necessary type-casts. Due to exact type correctness, as demonstrated in the calls to make_wr_ptr(), daisy-chained method invocation can be performed allowing streamlined usage. These aspects help make __Boost_STM__ transactions small and easy to understand.

-One minor, but vital, detail is in way new objects are created on a transactional context. Rather than hide this difference, it is intentionally exposed here to draw out the memory access differences required for writes to new and existing memory. We explain this difference in detail later in this section.
+upgrd_ptr is a read only smart pointer that can be upgraded to a read/write smart pointer.
+Once the smart pointer is constructed (associating it to the current transaction), the user can access any member as if it was non transactional.
+
+make_wr_ptr is a read/write smart pointer factory. The returned wr_ptr<> allows to modify the pointee object.

-In order to simplify the retry mechanism a macro is provided so the user can just write
+One minor, but vital, detail is in the way new objects are created on a transactional context. Rather than hide this difference, it is intentionally exposed here to draw out the memory access differences required for writes to new and existing memory. We explain this difference in detail later in this section.
+
+In order to simplify the retry mechanism the macro __use_atomic__ is provided so the user can just write

 void insert(T const &val) {
- atomic(_) {
+ use_atomic(_) {
 upgrd_ptr<list_node<T> > prev(_, head_);
 upgrd_ptr<list_node<T> > curr(_, head_->next_);
 while (curr) {
@@ -85,6 +104,24 @@
 }
 }

+We could also write the following, but this is less efficient as tx_ptr is a smart pointer that associated the pointer to the current transaction for writting. The use of the smart pointer upgrd_ptr and the smart pointer factory function make_wr_ptr allows to make the difference kind of access.
+
+ void insert(T const &val) {
+ use_atomic(_) {
+ tx_ptr<list_node<T> > prev(head_);
+ tx_ptr<list_node<T> > curr(head_->next_);
+ while (curr) {
+ if (curr->value_ == val) return;
+ else if (curr->value_ > val) break;
+ prev = curr;
+ curr = curr->next_;
+ }
+ if (!curr || (curr->value_ > val)) {
+ prev->next_ =
+ BOOST_STM_NEW(_,transactional_object<list_node<T> >(val, curr));
+ }
+ }
+ }

[endsect]

@@ -165,7 +202,7 @@

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

[endsect]

@@ -454,4 +491,12 @@

[endsect]

+[section Polymorphic]
+
+[endsect]
+
+[section Lock aware]
+
+[endsect]
+
[endsect]

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-18 19:00:15 EDT (Fri, 18 Sep 2009)
@@ -23,17 +23,21 @@

[variablelist

-[[in fligh transaction] [.]]
-[[latm] [lock aware transaction memory]]
+[[ACI] [Atomic, Consistent and Isolated]]
+[[LATM] [lock aware transaction memory]]
+[[LiT] [Lock in transaction]]
+[[LoT] [Lock out of transaction]]
[[STM] [Software Transaction Memory]]
+[[TX] [Transaction]]
+[[TM] [Transaction Memory]]
+
+[[in fligh transaction] [.]]
[[Conflict Detection] [.]]
[[abort] [.]]
[[commit] [.]]
[[Consistency Checking] [.]]
[[Direct Updating] [.]]
[[Deferred Updating] [.]]
-[[LiT] [.]]
-[[LoT] [.]]
[[Irrevocable transaction] [.]]
[[Isolated transaction] [.]]
[[Full-Lock protection] [.]]

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