[Boost-commit] svn:boost r83534 - trunk/libs/thread/doc

Subject: [Boost-commit] svn:boost r83534 - trunk/libs/thread/doc
From: vicente.botet_at_[hidden]
Date: 2013-03-23 14:05:11

Author: viboes
Date: 2013-03-23 14:05:10 EDT (Sat, 23 Mar 2013)
New Revision: 83534
URL: http://svn.boost.org/trac/boost/changeset/83534

Log:
Thread: update doc addin the missing traits is_recursive_lockable and is_recursive_basic_lockable; Added lock/try_lock requires clause; Added call_once restrictions.
Text files modified: 
   trunk/libs/thread/doc/future_ref.qbk       |     2                                         
   trunk/libs/thread/doc/internal_locking.qbk |     2                                         
   trunk/libs/thread/doc/mutex_concepts.qbk   |    53 ++++++++++++++++++++++++++++++++++++++- 
   trunk/libs/thread/doc/once.qbk             |     8 ++++++                                  
   4 files changed, 61 insertions(+), 4 deletions(-)

Modified: trunk/libs/thread/doc/future_ref.qbk
==============================================================================
--- trunk/libs/thread/doc/future_ref.qbk	(original)
+++ trunk/libs/thread/doc/future_ref.qbk	2013-03-23 14:05:10 EDT (Sat, 23 Mar 2013)
@@ -1621,7 +1621,7 @@
 
 [warning `async(launch::deferred, F)` is NOT YET IMPLEMENTED!]
 
-[warning the variadic prototype is provided only on C++11 compilers supporting rvalue references, variadic templates, decltype and a standard library providing <tuple>, and BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK is defined.]
+[warning the variadic prototype is provided only on C++11 compilers supporting rvalue references, variadic templates, decltype and a standard library providing <tuple> (waiting for a boost::tuple that is move aware), and BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK is defined.]
 
 [heading Non-Variadic variant]
 

Modified: trunk/libs/thread/doc/internal_locking.qbk
==============================================================================
--- trunk/libs/thread/doc/internal_locking.qbk	(original)
+++ trunk/libs/thread/doc/internal_locking.qbk	2013-03-23 14:05:10 EDT (Sat, 23 Mar 2013)
@@ -78,7 +78,7 @@
           mtx_.lock();
           int b = balance_;
           mtx_.unlock();
-          return balance_;
+          return b;
       }
   };
 

Modified: trunk/libs/thread/doc/mutex_concepts.qbk
==============================================================================
--- trunk/libs/thread/doc/mutex_concepts.qbk	(original)
+++ trunk/libs/thread/doc/mutex_concepts.qbk	2013-03-23 14:05:10 EDT (Sat, 23 Mar 2013)
@@ -42,6 +42,8 @@
 
 [variablelist
 
+[[Requires:] [The calling thread doesn't owns the mutex if the mutex is not recursive.]]
+
 [[Effects:] [The current thread blocks until ownership can be obtained for the current thread.]]
 
 [[Synchronization:] [Prior `unlock()` operations on the same object synchronizes with this operation. ]]
@@ -97,7 +99,12 @@
     }
   }
 
-Some of the algorithms on mutexes use this trait via SFINAE. If BOOST_THREAD_NO_AUTO_DETECT_MUTEX_TYPES is defined you will need to specialize this traits for the models of BasicLockable you could build. 
+
+Some of the algorithms on mutexes use this trait via SFINAE. 
+
+This trait is true_type if the parameter L meets the __Lockable requirements.
+
+[warning If BOOST_THREAD_NO_AUTO_DETECT_MUTEX_TYPES is defined you will need to specialize this traits for the models of BasicLockable you could build.] 
 
 [endsect]
 [endsect]
@@ -121,6 +128,9 @@
 
 [variablelist
 
+
+[[Requires:] [The calling thread doesn't owns the mutex if the mutex is not recursive.]]
+
 [[Effects:] [Attempt to obtain ownership for the current thread without blocking.]]
 
 [[Synchronization:] [If `try_lock()` returns true, prior `unlock()` operations on the same object synchronize with this operation.]]
@@ -152,7 +162,11 @@
     }
   }
 
-Some of the algorithms on mutexes use this trait via SFINAE. If BOOST_THREAD_NO_AUTO_DETECT_MUTEX_TYPES is defined you will need to specialize this traits for the models of Lockable you could build. 
+Some of the algorithms on mutexes use this trait via SFINAE. 
+
+This trait is true_type if the parameter L meets the __Locable requirements.
+
+[warning If BOOST_THREAD_NO_AUTO_DETECT_MUTEX_TYPES is defined you will need to specialize this traits for the models of Lockable you could build.] 
 
 [endsect]
 [endsect]
@@ -185,6 +199,37 @@
 
 [endsect]
 
+[section:is_recursive_basic_lockable `is_recursive_basic_lockable` trait -- EXTENSION]
+
+  // #include <boost/thread/lockable_traits.hpp> 
+  namespace boost 
+  {
+    namespace sync 
+    {
+      template<typename L>
+      class is_recursive_basic_lockable;// EXTENSION
+    }
+  }
+
+This traits is true_type if is_basic_lockable and is_recursive_mutex_sur_parolle.
+
+[endsect]
+[section:is_recursive_lockable `is_recursive_lockable` trait -- EXTENSION]
+
+  // #include <boost/thread/lockable_traits.hpp> 
+  namespace boost 
+  {
+    namespace sync 
+    {
+      template<typename L>
+      class is_recursive_lockable;// EXTENSION
+    }
+  }
+
+This traits is true_type if is_lockable and is_recursive_mutex_sur_parolle.
+
+[endsect]
+
 [endsect]
 
 
@@ -220,6 +265,8 @@
 
 [variablelist
 
+[[Requires:] [The calling thread doesn't owns the mutex if the mutex is not recursive.]]
+
 [[Effects:] [Attempt to obtain ownership for the current thread. Blocks until ownership can be obtained, or the specified time is
 reached. If the specified time has already passed, behaves as __try_lock_ref__.]]
 
@@ -239,6 +286,8 @@
 
 [variablelist
 
+[[Requires:] [The calling thread doesn't owns the mutex if the mutex is not recursive.]]
+
 [[Effects:] [As-if `__try_lock_until(chrono::steady_clock::now() + rel_time)`.]]
 
 [[Synchronization:] [If `try_lock_for()` returns true, prior `unlock()` operations on the same object synchronize with this operation.]]

Modified: trunk/libs/thread/doc/once.qbk
==============================================================================
--- trunk/libs/thread/doc/once.qbk	(original)
+++ trunk/libs/thread/doc/once.qbk	2013-03-23 14:05:10 EDT (Sat, 23 Mar 2013)
@@ -21,6 +21,11 @@
 
   }
 
+[warning the variadic prototype is provided only on C++11 compilers supporting variadic templates, otherwise the interface is limited up to 3 parameters.]
+
+[warning the move semantics is ensured only on C++11 compilers supporting SFINAE expression, decltype N3276 and auto. Waiting for a boost::bind that is move aware.]
+
+
 `boost::call_once` provides a mechanism for ensuring that an initialization routine is run exactly once without data races or deadlocks.
 
 [section:once_flag Typedef `once_flag`]
@@ -71,6 +76,9 @@
 function, in which case it could also avoid calling `call_once`
 recursively.]]
 
+
+[[Note:] [On some compilers this function has some restrictions, e.g. if variadic templates are not supported the number of arguments is limited to 3; .]]
+
 ]
 
     void call_once(void (*func)(),once_flag& flag);