[Boost-commit] svn:boost r52071 - in sandbox/synchro/libs/synchro/doc: . tutorial

Subject: [Boost-commit] svn:boost r52071 - in sandbox/synchro/libs/synchro/doc: . tutorial
From: vicente.botet_at_[hidden]
Date: 2009-03-30 16:32:07

Author: viboes
Date: 2009-03-30 16:32:06 EDT (Mon, 30 Mar 2009)
New Revision: 52071
URL: http://svn.boost.org/trac/boost/changeset/52071

Log:
0.3.1 : Adding synchronize macros

Text files modified: 
   sandbox/synchro/libs/synchro/doc/history.qbk           |    10 +++++++++-                              
   sandbox/synchro/libs/synchro/doc/introduction.qbk      |    40 +++++++++++++++++++++-------------------
   sandbox/synchro/libs/synchro/doc/overview.qbk          |     9 +++++----                               
   sandbox/synchro/libs/synchro/doc/tutorial/lockable.qbk |     4 ++--                                    
   4 files changed, 37 insertions(+), 26 deletions(-)

Modified: sandbox/synchro/libs/synchro/doc/history.qbk
==============================================================================
--- sandbox/synchro/libs/synchro/doc/history.qbk	(original)
+++ sandbox/synchro/libs/synchro/doc/history.qbk	2009-03-30 16:32:06 EDT (Mon, 30 Mar 2009)
@@ -7,11 +7,19 @@
 
 [section:history Appendix A: History]
  
+[section [*Version 0.3.1, Mars 29, 2009] ['Language-like Synchronized Block Macros]]
+
+[*New Features:]
+
+* Language-like Synchronized Block Macros.
+
+[endsect]
+
 [section [*Version 0.3.0, Mars 19, 2009] ['Generic free operations on multiple lockables + Usage of Boost.Chrono]]
 
 [*New Features:]
 
-* Adding generic free functions on lockables: `lock`, `try_lock` 
+* Generic free functions on lockables: `lock`, `try_lock` 
 
 * Complete the generic free functions on multiple lockables in Boost.Thread `lock`, `try_lock` with:
     * `lock_until`, `lock_for`, `try_lock_until`, `try_lock_for`, `unlock`

Modified: sandbox/synchro/libs/synchro/doc/introduction.qbk
==============================================================================
--- sandbox/synchro/libs/synchro/doc/introduction.qbk	(original)
+++ sandbox/synchro/libs/synchro/doc/introduction.qbk	2009-03-30 16:32:06 EDT (Mon, 30 Mar 2009)
@@ -131,11 +131,11 @@
 
 The library defines some locker adapters which take care of naming differences and that can be used like
 
-        boost::synchro::unique_locker<boost::mutex> scoped(guard);
+        bsynchro::unique_locker<boost::mutex> scoped(guard);
 
 or        
 
-        boost::synchro::unique_locker<boost::interprocess::interprocess_mutex> scoped(guard);
+        bsynchro::unique_locker<boost::interprocess::interprocess_mutex> scoped(guard);
 
 [*Strict lockers]
 
@@ -211,7 +211,7 @@
 
 The library defines in a generic way a try_unique_locker adapter which takes care of naming differences and that can be used like
 
-        boost::synchro::unique_try_locker<Lockable> locker(mtx);
+        bsynchro::unique_try_locker<Lockable> locker(mtx);
 
 for any model of Lockable.
 
@@ -256,7 +256,7 @@
 To avoid this we can request the acquisition of all the locks toghether (letting the function to try several orders), as it does the function try_lock of Boost.Threads, but adding this time a expiration period parameter
 
     while (polling) {
-        if (boost::try_lock_for(100, m1, m2, m3)) {
+        if (bsynchro::try_lock_for(100, m1, m2, m3)) {
             foo();
             polling = false;
         } else execute_on_failed(); 
@@ -267,12 +267,12 @@
     while (polling)
         try {
             t=now()+100;
-            boost::unique_locker<boost::mutex> l1(t, m1);
-            boost::unique_locker<boost::mutex> l2(t, m2);
-            boost::unique_locker<boost::mutex> l3(t, m3);
+            bsynchro::unique_locker<boost::mutex> l1(t, m1);
+            bsynchro::unique_locker<boost::mutex> l2(t, m2);
+            bsynchro::unique_locker<boost::mutex> l3(t, m3);
             foo();
             polling = false;
-        } catch (timeout_exception& ex) {execute_on_failed(); }
+        } catch (bsynchro::timeout_exception& ex) {execute_on_failed(); }
 
 [*`locker_tuples` or `locker_array` of Locker containers]
 
@@ -282,7 +282,7 @@
 So the preceding code becomes without timeout exceptions
 
     while (polling) {
-        boost::synchro::array_unique_locker<boost::mutex, 3> lk(m1, m2, m3, 100);
+        bsynchro::array_unique_locker<boost::mutex, 3> lk(m1, m2, m3, 100);
         if (lk.owns_lock()) {
             foo();
             polling = false;
@@ -292,18 +292,18 @@
 which is exception safe or with exception based timed locks (Note that the time is given before the locks)
 
     while (polling) 
-    try { boost::synchro::array_locker<boost::mutex, 3> lk(100, m1, m2, m3);
+    try { bsynchro::array_locker<boost::mutex, 3> lk(100, m1, m2, m3);
         foo();
         polling = false;
-    } catch (boost::synchro::timed_exception& ex) { execute_on_failed(); }
+    } catch (bsynchro::timeout_exception& ex) { execute_on_failed(); }
 
 When the Locks locked by an `array_unique_locker` are not homogeneus we need some kind of tuple.
 
     while (polling) 
-    try { boost::synchro::tuple_unique_locker<T1, T2, T1> lk(100, m1, m2, m3);
+    try { bsynchro::tuple_unique_locker<T1, T2, T1> lk(100, m1, m2, m3);
         foo();
         polling = false;
-    } catch (boost::synchro::timed_exception& ex) { execute_on_failed(); }
+    } catch (bsynchro::timed_exception& ex) { execute_on_failed(); }
 
 
 [*`lock_until` and `lock_for` free functions]
@@ -312,10 +312,10 @@
 
     while (polling)
         try {
-            boost::lock_for(100, m1, m2, m3);
+            bsynchro::lock_for(100, m1, m2, m3);
             foo();
             polling = false;
-        } catch (timeout_exception& ex) {execute_on_failed(); }
+        } catch (bsynchro::timeout_exception& ex) {execute_on_failed(); }
 
 
 [*External lockers]
@@ -381,7 +381,7 @@
 
 With language-like mutual exclusion this results in:
 
-    synchronized(l) 
+    synchronize(l) 
     {
         foo();
         return bar(); 
@@ -393,10 +393,12 @@
 
 The library do not provides this directly because this can broke some user code. The library provideds other safer macros, using the BOOST prefix.
 
-    #define BOOST_SYNCHRONIZED_VAR(VARS_DECLARATION) if (bool stop_ = false) {} else \
-    for (VARS_DECLARATION; !stop_; stop_ = true)
+    #define BOOST_SYNCHRONIZED_VAR(VARS_DECLARATION) \
+        if (bool stop_ = false) {} else \
+        for (VARS_DECLARATION; !stop_; stop_ = true)
 
-    #define BOOST_SYNCHRONIZED(MUTEX) BOOST_SYNCHRONIZED_VAR(boost::scoped_guard<boost::mutex> __lock(MUTEX))
+    #define BOOST_SYNCHRONIZED(MUTEX) \
+        BOOST_SYNCHRONIZED_VAR(boost::scoped_guard<boost::mutex> __lock(MUTEX))
 
 [endsect]
 

Modified: sandbox/synchro/libs/synchro/doc/overview.qbk
==============================================================================
--- sandbox/synchro/libs/synchro/doc/overview.qbk	(original)
+++ sandbox/synchro/libs/synchro/doc/overview.qbk	2009-03-30 16:32:06 EDT (Mon, 30 Mar 2009)
@@ -30,7 +30,7 @@
 * A uniform usage of Boost.Thread and Boost.Interprocess synchronization mechanisms based on lockables(mutexes) concepts and locker(guards) concepts.
 
     * lockables traits and lock generators, 
-    * generic free functions on lockables as: `lock`, `try_lock` 
+    * generic free functions on lockables as: `lock`, `try_lock`, ... 
     * locker adapters of the Boost.Thread and Boost.Interprocess lockers models,
     * complete them with the corresponding models for single-threaded programms: `null_mutex` and `null_condition` classes,
     * locking families,
@@ -47,7 +47,7 @@
     * `locking_ptr`, `on_derreference_locking_ptr`,
     * `externally_locked`,
     
-* `array_locker` on multiple lockables.
+* `array_unique_locker` on multiple lockables.
 
 * Generic free functions on multiple lockables `lock`, `try_lock`, `lock_until`, `lock_for`, `try_lock_until`, `try_lock_for`, `unlock`    * lock adapters of the Boost.Thread and Boost.Interprocess lockable models,
     * `lock_until`, `lock_for`, `try_lock_until`, `try_lock_for`
@@ -55,10 +55,11 @@
 * A polymorphic lockable hierarchy.
 
 * High-level abstractions for handling more complicated synchronization problems, including
-    * `monitor` for guaranteeing exclusive access to an object, and
+    * `monitor` for guaranteeing exclusive access to an object.
 
 * A rendezvous mechanism for handling direct communication between objects `concurrent_components` via `ports` using an accept-synchronize protocol based on the design of the concurrency library in the Beta language.
 
+* Language-like Synchronized Block Macros
 
 [/====================================]
 [heading How to Use This Documentation]
@@ -79,7 +80,7 @@
 
 Finally, you can mentally add the following to any code fragments in this document:
 
-    // Include all of InterThreads
+    // Include all of Synchro files
     #include <boost/synchro/synchro.hpp>
 
     // Create a namespace aliases

Modified: sandbox/synchro/libs/synchro/doc/tutorial/lockable.qbk
==============================================================================
--- sandbox/synchro/libs/synchro/doc/tutorial/lockable.qbk	(original)
+++ sandbox/synchro/libs/synchro/doc/tutorial/lockable.qbk	2009-03-30 16:32:06 EDT (Mon, 30 Mar 2009)
@@ -55,8 +55,8 @@
 
 * boost::mutex: ExclusiveLock, non-recursive, has-not-timed-interface, multi-threaded
 * boost::shared_mutex: UpgradableLock, non-recursive, has-timed-interface, multi-threaded
-* bip::synchro::null_mutex: UpgradableLock, recursive, has-timed-interface, mono-threaded
-* bip::synchro::interprocess_recursive_mutex ExclusiveLock, recursive, has-timed-interface, multi_process.
+* bip::sync::null_mutex: UpgradableLock, recursive, has-timed-interface, mono-threaded
+* bip::sync::interprocess_recursive_mutex ExclusiveLock, recursive, has-timed-interface, multi_process.
 
 [*Lock traits]