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

Subject: [Boost-commit] svn:boost r81089 - trunk/libs/thread/doc
From: vicente.botet_at_[hidden]
Date: 2012-10-28 21:25:13

Author: viboes
Date: 2012-10-28 21:25:12 EDT (Sun, 28 Oct 2012)
New Revision: 81089
URL: http://svn.boost.org/trac/boost/changeset/81089

Log:
Thread: document the split of locks.hpp, StrictLock, strict_lock, null_mutex, configuration
Text files modified: 
   trunk/libs/thread/doc/configuration.qbk    |   136 ++++++++++++++++++++---                 
   trunk/libs/thread/doc/mutex_concepts.qbk   |   225 +++++++++++++++++++++++++++++++++------ 
   trunk/libs/thread/doc/shared_mutex_ref.qbk |    84 ++++++++++++++                          
   trunk/libs/thread/doc/thread.qbk           |    15 +                                       
   trunk/libs/thread/doc/thread_ref.qbk       |   171 ++++++++++++++++++++---------           
   5 files changed, 516 insertions(+), 115 deletions(-)

Modified: trunk/libs/thread/doc/configuration.qbk
==============================================================================
--- trunk/libs/thread/doc/configuration.qbk	(original)
+++ trunk/libs/thread/doc/configuration.qbk	2012-10-28 21:25:12 EDT (Sun, 28 Oct 2012)
@@ -11,21 +11,105 @@
 
 [section:chrono Boost.Chrono]
 
-Boost.Thread uses by default Boost.Chrono for the time related functions. For backward compatibility and also for compilers that don't work well with Boost.Chrono the user can define `BOOST_THREAD_DONT_USE_CHRONO`.
-
-`BOOST_THREAD_USES_CHRONO` is defined when Boost.Thread uses Boost.Chrono.
-
+Boost.Thread uses by default Boost.Chrono for the time related functions and define `BOOST_THREAD_USES_CHRONO` if `BOOST_THREAD_DONT_USE_CHRONO` is not defined. The user should define `BOOST_THREAD_DONT_USE_CHRONO` for compilers that don't work well with Boost.Chrono.
 
 [endsect]
 
 
-
 [section:move  Boost.Move]
 
 Boost.Thread uses by default an internal move semantic implementation. Since version 3.0.0 you can use the move emulation emulation provided by Boost.Move. 
 
 When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_USES_MOVE ` if you want to use Boost.Move interface.
-When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_USE_MOVE ` if you don't want to use Boost.Move interface.
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_USE_MOVE ` if you don't want to use Boost.Move interface.
+
+[endsect]
+
+[section:date_time  Boost.DateTime]
+
+The Boost.DateTime time related functions introduced in Boost 1.35.0, using the [link date_time Boost.Date_Time] library are deprecated. These include (but are not limited to):
+
+* __sleep__
+* __timed_join__
+* __cond_timed_wait__
+* __timed_lock_ref__
+
+
+When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_DONT_USE_DATETIME ` if you don't want to use Boost.DateTime related interfaces.
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_USES_DATETIME ` if you want to use Boost.DateTime related interfaces.
+
+[endsect]
+
+
+[section:thread_eq `boost::thread::oprator==` deprecated]
+
+The following nested typedefs are deprecated: 
+
+* `boost::thread::oprator==`
+* `boost::thread::oprator!=`
+
+When `BOOST_THREAD_PROVIDES_THREAD_EQ` is defined Boost.Thread provides these deprecated feature. 
+
+Use instead 
+
+* `boost::thread::id::oprator==`
+* `boost::thread::id::oprator!=`
+
+[warning This is a breaking change respect to version 1.x.]
+
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_PROVIDES_THREAD_EQ ` if you want this feature.
+When `BOOST_THREAD_VERSION<3` define `BOOST_THREAD_DONT_PROVIDE_THREAD_EQ ` if you don't want this feature.
+
+[endsect]
+
+[section:condition boost::condition deprecated]
+
+`boost::condition` is deprecated. When `BOOST_THREAD_PROVIDES_CONDITION` is defined Boost.Thread provides this deprecated feature. 
+
+Use instead `boost::condition_variable_any`.
+
+[warning This is a breaking change respect to version 1.x.]
+
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_PROVIDES_CONDITION` if you want this feature.
+When `BOOST_THREAD_VERSION<3` define `BOOST_THREAD_DONT_PROVIDE_CONDITION` if you don't want this feature.
+
+[endsect]
+
+[section:nested_lock Mutex nested lock types deprecated]
+
+
+The following nested typedefs are deprecated: 
+
+* `boost::mutex::scoped_lock`, 
+* `boost::mutex::scoped_try_lock`, 
+* `boost::timed_mutex::scoped_lock` 
+* `boost::timed_mutex::scoped_try_lock` 
+* `boost::timed_mutex::timed_scoped_timed_lock` 
+* `boost::recursive_mutex::scoped_lock`, 
+* `boost::recursive_mutex::scoped_try_lock`, 
+* `boost::recursive_timed_mutex::scoped_lock` 
+* `boost::recursive_timed_mutex::scoped_try_lock` 
+* `boost::recursive_timed_mutex::timed_scoped_timed_lock` 
+
+When `BOOST_THREAD_PROVIDES_NESTED_LOCKS` is defined Boost.Thread provides these deprecated feature. 
+
+
+Use instead
+* `boost::unique_lock<boost::mutex>`, 
+* `boost::unique_lock<boost::mutex>` with the `try_to_lock_t` constructor, 
+* `boost::unique_lock<boost::timed_mutex>` 
+* `boost::unique_lock<boost::timed_mutex>` with the `try_to_lock_t` constructor 
+* `boost::unique_lock<boost::timed_mutex>` 
+* `boost::unique_lock<boost::recursive_mutex>`, 
+* `boost::unique_lock<boost::recursive_mutex>` with the `try_to_lock_t` constructor, 
+* `boost::unique_lock<boost::recursive_timed_mutex>` 
+* `boost::unique_lock<boost::recursive_timed_mutex>` with the `try_to_lock_t` constructor 
+* `boost::unique_lock<boost::recursive_timed_mutex>` 
+
+[warning This is a breaking change respect to version 1.x.]
+
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_PROVIDES_NESTED_LOCKS` if you want these features.
+When `BOOST_THREAD_VERSION<3` define `BOOST_THREAD_DONT_PROVIDE_NESTED_LOCKS` if you don't want thes features.
 
 [endsect]
 
@@ -33,13 +117,16 @@
 
 Boost.Thread uses by default a thread::id on Posix based on the pthread type (BOOST_THREAD_PROVIDES_BASIC_THREAD_ID). For backward compatibility and also for compilers that don't work well with this modification the user can define `BOOST_THREAD_DONT_PROVIDE_BASIC_THREAD_ID`.
 
+When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_BASIC_THREAD_ID ` if you want these features.
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_BASIC_THREAD_ID ` if you don't want these features.
+
 [endsect]
 [section:shared_gen  Shared Locking Generic]
 
 The shared mutex implementation on Windows platform provides currently less functionality than the generic one that is used for PTheads based platforms. In order to have access to these functions, the user needs to define `BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN` to use the generic implementation, that while could be less efficient, provides all the functions.
 
 When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_GENERIC_SHARED_MUTEX_ON_WIN ` if you want these features.
-When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_GENERIC_SHARED_MUTEX_ON_WIN ` if you don't want these features.
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_GENERIC_SHARED_MUTEX_ON_WIN ` if you don't want these features.
 
 [endsect]
 
@@ -49,7 +136,7 @@
 These conversions need to be used carefully to avoid deadlock or livelock. The user need to define explicitly `BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION` to get these upwards conversions. 
 
 When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION ` if you want these features.
-When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_SHARED_MUTEX_UPWARDS_CONVERSION ` if you don't want these features.
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_SHARED_MUTEX_UPWARDS_CONVERSION ` if you don't want these features.
 
 [endsect]
 
@@ -69,7 +156,7 @@
 Since version 3.0.0 `boost::future` replaces `boost::unique_future` when `BOOST_THREAD_PROVIDES_FUTURE` is defined. The documentation doesn't contains anymore however `boost::unique_future`.
 
 When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_FUTURE` if you want to use boost::future.
-When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_FUTURE` if you want to use boost::unique_future.
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_FUTURE` if you want to use boost::unique_future.
 
 [endsect]
 
@@ -80,7 +167,7 @@
 Since version 3.0.0 this difference in behavior can be configured. When `BOOST_THREAD_PROVIDES_PROMISE_LAZY` is defined the backward compatible behavior is provided. 
 
 When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_DONT_PROVIDE_PROMISE_LAZY ` if you want to use boost::future.
-When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_PROVIDES_PROMISE_LAZY ` if you want to use boost::unique_future.
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_PROVIDES_PROMISE_LAZY ` if you want to use boost::unique_future.
 
 [endsect]
 
@@ -124,7 +211,7 @@
 which introduces a dependency on Boost.Container. This feature is provided only if  `BOOST_THREAD_PROVIDES_FUTURE_CTOR_ALLOCATORS` is defined. 
 
 When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_FUTURE_CTOR_ALLOCATORS ` if you want these features.
-When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_FUTURE_CTOR_ALLOCATORS ` if you don't want these features.
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_FUTURE_CTOR_ALLOCATORS ` if you don't want these features.
 
 [endsect]
 
@@ -133,10 +220,10 @@
 C++11 has a different semantic for the thread destructor and the move assignment. Instead of detaching the thread, calls to terminate() if the thread was joinable. When `BOOST_THREAD_PROVIDES_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE` and `BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE` is defined Boost.Thread provides the C++ semantic.
 
 When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE ` if you want these features.
-When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE ` if you don't want these features.
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE ` if you don't want these features.
 
 When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE ` if you want these features.
-When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE ` if you don't want these features.
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE ` if you don't want these features.
 
 [endsect]
 
@@ -151,7 +238,7 @@
   boost::once_flag once;
 
 When `BOOST_THREAD_VERSION==2` define `BOOST_THREAD_PROVIDES_ONCE_CXX11` if you want these features.
-When `BOOST_THREAD_VERSION==3` define `BOOST_THREAD_DONT_PROVIDE_ONCE_CXX11` if you don't want these features.
+When `BOOST_THREAD_VERSION>=3` define `BOOST_THREAD_DONT_PROVIDE_ONCE_CXX11` if you don't want these features.
 
 [endsect]
 
@@ -160,7 +247,7 @@
 
 C++11 packaged task class has a Signature template parameter. When `BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK ` is defined Boost.Thread provides this C++ feature. 
 
-[waring This is a breaking change respect to version 3.x.]
+[warning This is a breaking change respect to version 3.x.]
 
 When `BOOST_THREAD_VERSION<=3` define `BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK` if you want this feature.
 When `BOOST_THREAD_VERSION>4` define `BOOST_THREAD_DONT_PROVIDE_SIGNATURE_PACKAGED_TASK` if you don't want this feature.
@@ -185,13 +272,23 @@
 
 C++11 future<>::get() invalidates the future once its value has been obtained. When `BOOST_THREAD_PROVIDES_FUTURE_INVALID_AFTER_GET ` is defined Boost.Thread provides this C++ feature. 
 
-[waring This is a breaking change respect to version 3.x.]
+[warning This is a breaking change respect to version 3.x.]
 
 When `BOOST_THREAD_VERSION<=3` define `BOOST_THREAD_PROVIDES_FUTURE_INVALID_AFTER_GET` if you want this feature.
 When `BOOST_THREAD_VERSION>4` define `BOOST_THREAD_DONT_PROVIDE_FUTURE_INVALID_AFTER_GET` if you don't want this feature.
 
 [endsect]
 
+[section:intr Interruptions]
+
+Thread interruption, while useful, makes any interruption point less efficient than if the thread were not interruptible. 
+
+When `BOOST_THREAD_PROVIDES_INTERRUPTIONS` is defined Boost.Thread provides interruptions. 
+When `BOOST_THREAD_DONT_PROVIDE_INTERRUPTIONS` is defined Boost.Thread don't provide interruption. 
+
+Boost.Thread defines BOOST_THREAD_PROVIDES_INTERRUPTIONS if neither BOOST_THREAD_PROVIDES_INTERRUPTIONS nor BOOST_THREAD_DONT_PROVIDE_INTERRUPTIONS are defined, so that there is no compatibility break.
+
+[endsect]
 
 [section:version Version]
 
@@ -199,7 +296,6 @@
 The default version is 2. In this case the following breaking or extending macros are defined if the opposite is not requested: 
 
 * `BOOST_THREAD_PROVIDES_PROMISE_LAZY`
-* `BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0`
 
 The user can request the version 3 by defining `BOOST_THREAD_VERSION` to 3. In this case the following breaking or extending macros are defined if the opposite is not requested: 
 
@@ -213,7 +309,6 @@
 * Conformity & Breaking change `BOOST_THREAD_PROVIDES_ONCE_CXX11`
 
 * Breaking change `BOOST_THREAD_DONT_PROVIDE_PROMISE_LAZY`
-* Breaking change `BOOST_THREAD_DONT_PROVIDE_DEPRECATED_FEATURES_SINCE_V3_0_0`
 
 The default value for `BOOST_THREAD_VERSION` will be changed to 3 since Boost 1.53.
 
@@ -222,7 +317,11 @@
 * Conformity & Breaking change `BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK `
 * Conformity & Breaking change `BOOST_THREAD_PROVIDES_FUTURE_INVALID_AFTER_GET `
 * Conformity `BOOST_THREAD_PROVIDES_VARIADIC_THREAD`
+* Breaking change `BOOST_THREAD_DONT_PROVIDE_THREAD_EQ`
+* Breaking change `BOOST_THREAD_DONT_USE_DATETIME`
+
 
+The default value for `BOOST_THREAD_VERSION` will be changed to 4 since Boost 1.56.
 
 [endsect]
 
@@ -249,6 +348,7 @@
 If __IBMCPP__ < 1100 the library defines
 
 * `BOOST_THREAD_DONT_USE_CHRONO`
+* `BOOST_THREAD_USES_DATE`
 
 And Boost.Thread doesn't links with Boost.Chrono.
 

Modified: trunk/libs/thread/doc/mutex_concepts.qbk
==============================================================================
--- trunk/libs/thread/doc/mutex_concepts.qbk	(original)
+++ trunk/libs/thread/doc/mutex_concepts.qbk	2012-10-28 21:25:12 EDT (Sun, 28 Oct 2012)
@@ -21,7 +21,7 @@
 [section:basic_lockable `BasicLockable` Concept]
 
 The __BasicLockable concept models exclusive ownership. 
-A type `L` meets the __BasicLockable requiremets if the following expressions are well-formed and have the specified semantics (`m` denotes a value of type `L`):
+A type `L` meets the __BasicLockable requirements if the following expressions are well-formed and have the specified semantics (`m` denotes a value of type `L`):
 
 * `m.__lock();`
 * `m.__unlock();`
@@ -38,7 +38,7 @@
 
 [[Return type:] [`void`.]]
 
-[[Throws:] [__thread_resource_error__ if an error occurs.]]
+[[Throws:] [__lock_error__ if an error occurs.]]
 
 [[Error Conditions:] [
 
@@ -169,7 +169,7 @@
 
 [[Postcondition:] [If the call returns `true`, the current thread owns `m`.]]
 
-[[Throws:] [__thread_resource_error__ if an error occurs.]]
+[[Throws:] [__lock_error__ if an error occurs.]]
 ]
 [endsect]
 
@@ -221,7 +221,7 @@
 
 [[Postcondition:] [The current thread has shared ownership of `m`.]]
 
-[[Throws:] [__thread_resource_error__ if an error occurs.]]
+[[Throws:] [__lock_error__ if an error occurs.]]
 
 ]
 [endsect]
@@ -236,7 +236,7 @@
 
 [[Postcondition:] [If the call returns `true`, the current thread has shared ownership of `m`.]]
 
-[[Throws:] [__thread_resource_error__ if an error occurs.]]
+[[Throws:] [__lock_error__ if an error occurs.]]
 
 ]
 [endsect]
@@ -253,7 +253,7 @@
 [[Postcondition:] [If the call returns `true`, the current thread has shared
 ownership of `m`.]]
 
-[[Throws:] [__thread_resource_error__ if an error occurs.]]
+[[Throws:] [__lock_error__ if an error occurs.]]
 
 ]
 [endsect]
@@ -270,7 +270,7 @@
 [[Postcondition:] [If the call returns `true`, the current thread has shared
 ownership of `m`.]]
 
-[[Throws:] [__thread_resource_error__ if an error occurs.]]
+[[Throws:] [__lock_error__ if an error occurs.]]
 
 ]
 [endsect]
@@ -316,7 +316,7 @@
 [[Postcondition:] [If the call returns `true`, the current thread has shared
 ownership of `m`.]]
 
-[[Throws:] [__thread_resource_error__ if an error occurs.]]
+[[Throws:] [__lock_error__ if an error occurs.]]
 
 ]
 [endsect]
@@ -393,7 +393,7 @@
 
 [[Synchronization:] [Prior `__unlock_upgrade()` operations on the same object synchronize with this operation.]] 
 
-[[Throws:] [__thread_resource_error__ if an error occurs.]]
+[[Throws:] [__lock_error__ if an error occurs.]]
 
 ]
 [endsect]
@@ -787,9 +787,10 @@
 
 [endsect]
 
-[section:locks Lock Types]
+[section:lock_option Lock Options]
 
-  //#include <boost/thread/locks.hpp> 
+  // #include <boost/thread/locks.hpp> 
+  // #include <boost/thread/locks_options.hpp> 
 
   namespace boost 
   {
@@ -799,28 +800,11 @@
     constexpr defer_lock_t defer_lock; 
     constexpr try_to_lock_t try_to_lock; 
     constexpr adopt_lock_t adopt_lock;
- 
-    template<typename Lockable>
-    class lock_guard
-    template<typename Lockable>
-    class unique_lock;
-    template<typename Mutex>
-    void swap(unique_lock <Mutex>& lhs, unique_lock <Mutex>& rhs);
-    template<typename Lockable>
-    class shared_lock;
-    template<typename Mutex>
-    void swap(shared_lock<Mutex>& lhs,shared_lock<Mutex>& rhs);
-    template<typename Lockable>
-    class upgrade_lock;
-    template<typename Mutex>
-    void swap(upgrade_lock <Mutex>& lhs, upgrade_lock <Mutex>& rhs);
-    template <class Mutex>
-    class upgrade_to_unique_lock;
-  }
 
 [section:lock_tags Lock option tags] 
 
   #include <boost/thread/locks.hpp> 
+  #include <boost/thread/locks_options.hpp> 
 
   struct defer_lock_t {}; 
   struct try_to_lock_t {}; 
@@ -837,9 +821,24 @@
 
 [endsect] 
 
+[endsect]
+
+[section:lock_guard Lock Guard]
+
+  // #include <boost/thread/locks.hpp> 
+  // #include <boost/thread/lock_guard.hpp> 
+
+  namespace boost 
+  {
+
+    template<typename Lockable>
+    class lock_guard
+  }
+
 [section:lock_guard Class template `lock_guard`]
 
-    //#include <boost/thread/locks.hpp>
+    // #include <boost/thread/locks.hpp>
+    // #include <boost/thread/lock_guard.hpp> 
 
     template<typename Lockable>
     class lock_guard
@@ -856,7 +855,7 @@
 the constructor parameter. On destruction, the ownership is released. This
 provides simple RAII-style locking of a __lockable_concept_type__ object, to facilitate exception-safe
 locking and unlocking. In addition, the [link
-thread.synchronization.locks.lock_guard.constructor_adopt `lock_guard(Lockable &
+thread.synchronization.lock_guard.lock_guard.constructor_adopt `lock_guard(Lockable &
 m,boost::adopt_lock_t)` constructor] allows the __lock_guard__ object to
 take ownership of a lock already held by the current thread.
 
@@ -902,10 +901,97 @@
 [endsect]
 
 [endsect]
+  
+[endsect]
+
+[section:lock_concepts Lock Concepts]
+[section:StrictLock StrictLock]
+
+A StrictLock is a lock that ensures that the associated mutex is locked during the lifetime if the lock.
+
+A type `L` meets the StrictLock requirements if the following expressions are well-formed and have the specified semantics 
+
+* `L::mutex_type`
+* `is_strict_lock_sur_parolle<L>`
+* `cl.mutex();`
+
+where
+
+* `cl` denotes a value of type `const L`,
+
+
+[section: mutex_type `L::mutex_type`]
+
+The type L::mutex_type denotes the mutex that is locked by this lock.
+
+[endsect] [/ mutex_type]
+
+[section:is_strict_lock_sur_parolle `is_strict_lock_sur_parolle<L>`]
+
+As the semantic "ensures that the associated mutex is locked during the lifetime if the lock. " can not be described by syntactic requirements a `is_strict_lock_sur_parolle` trait must be specialized by the user defining the lock so that the following assertion is true:
+
+  is_strict_lock_sur_parolle<L>::value == true
+
+[endsect] [/ is_strict_lock_sur_parolle]
+
+[section:mutex `cl.mutex();`]
+
+[variablelist
+
+[[Return Type:] [`L::mutex_type`]]
+[[Returns:] [A pointer to the `L::mutex_type` object that this lock `l` is locking]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+
+[endsect] [/ mutex]
+
+[section Models]
+
+The following classes are models of `StrictLock`:
+
+* strict_lock: ensured by construction,
+* nested_strict_lock: ensured by construction,
+* __lock_guard__: "sur parolle" as the user could use adopt_lock_t constructor overload without having locked the mutex.
+
+[endsect] [/ Models]
+
+[endsect] [/ Strict Lock]
+
+[endsect] [/ Lock Concepts]
+
+[section:locks Lock Types]
+
+  // #include <boost/thread/locks.hpp> 
+  // #include <boost/thread/lock_types.hpp> 
+
+  namespace boost 
+  {
+
+    template<typename Lockable>
+    class unique_lock;
+    template<typename Mutex>
+    void swap(unique_lock <Mutex>& lhs, unique_lock <Mutex>& rhs);
+    template<typename Lockable>
+    class shared_lock;
+    template<typename Mutex>
+    void swap(shared_lock<Mutex>& lhs,shared_lock<Mutex>& rhs);
+    template<typename Lockable>
+    class upgrade_lock;
+    template<typename Mutex>
+    void swap(upgrade_lock <Mutex>& lhs, upgrade_lock <Mutex>& rhs);
+    template <class Mutex>
+    class upgrade_to_unique_lock;
+  }
+
+
 
 [section:unique_lock Class template `unique_lock`]
 
-    //#include <boost/thread/locks.hpp>
+    // #include <boost/thread/locks.hpp>
+    // #include <boost/thread/lock_types.hpp> 
 
     template<typename Lockable>
     class unique_lock
@@ -1269,7 +1355,8 @@
 
 [section:shared_lock Class template `shared_lock`]
 
-    //#include <boost/thread/locks.hpp>
+    // #include <boost/thread/locks.hpp>
+    // #include <boost/thread/lock_types.hpp> 
 
     template<typename Lockable>
     class shared_lock
@@ -1510,7 +1597,8 @@
 
 [section:upgrade_lock Class template `upgrade_lock`]
 
-    //#include <boost/thread/locks.hpp>
+    // #include <boost/thread/locks.hpp>
+    // #include <boost/thread/lock_types.hpp> 
 
     template<typename Lockable>
     class upgrade_lock
@@ -1591,7 +1679,8 @@
 
 [section:upgrade_to_unique_lock Class template `upgrade_to_unique_lock`]
 
-    #include <boost/thread/locks.hpp>
+    // #include <boost/thread/locks.hpp>
+    // #include <boost/thread/lock_types.hpp> 
 
     template <class Lockable>
     class upgrade_to_unique_lock
@@ -1694,6 +1783,69 @@
 
 [section:other_locks Other Lock Types]
 
+[section:strict_lock Strict Lock]
+
+  // #include <boost/thread/locks.hpp> 
+  // #include <boost/thread/strict_lock.hpp> 
+
+  namespace boost 
+  {
+
+    template<typename Lockable>
+    class strict_lock;
+  }
+
+[section:strict_lock Class template `strict_lock`]
+
+    // #include <boost/thread/locks.hpp>
+    // #include <boost/thread/strict_lock.hpp> 
+
+    template<typename BasicLockable>
+    class strict_lock
+    {
+    public:
+        typedef BasicLockable mutex_type;
+        explicit strict_lock(mutex_type& m_);
+        ~strict_lock();
+
+        mutex_type* mutex() const;
+    };
+
+__strict_lock is a model of __StrictLock.
+
+__strict_lock is the simplest __StrictLock: on construction it acquires ownership of the implementation of the __BasicLockable concept supplied as the constructor parameter. On destruction, the ownership is released. This provides simple RAII-style locking of a __BasicLockable object, to facilitate exception-safe locking and unlocking. 
+
+[heading See also __lock_guard__]
+
+[section:constructor `strict_lock(Lockable & m)`]
+
+[variablelist
+
+[[Effects:] [Stores a reference to `m`. Invokes [lock_ref_link `m.lock()`].]]
+
+[[Throws:] [Any exception thrown by the call to [lock_ref_link `m.lock()`].]]
+
+]
+
+[endsect]
+
+[section:destructor `~strict_lock()`]
+
+[variablelist
+
+[[Effects:] [Invokes [unlock_ref_link `m.unlock()`] on the __lockable_concept_type__
+object passed to the constructor.]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+
+[endsect]
+  
+[endsect]
+
 
 [section:shared_lock_guard Class template `shared_lock_guard`]
 
@@ -1814,7 +1966,7 @@
 [endsect]
 
 
-[endsect]
+[endsect] [/ reverse_lock<>]
 
 [endsect]
 
@@ -1824,6 +1976,7 @@
 [section:lock_multiple Non-member function `lock(Lockable1,Lockable2,...)`]
 
   // #include <boost/thread/locks.hpp>
+  // #include <boost/thread/lock_algorithms.hpp>
   namespace boost 
   {
 

Modified: trunk/libs/thread/doc/shared_mutex_ref.qbk
==============================================================================
--- trunk/libs/thread/doc/shared_mutex_ref.qbk	(original)
+++ trunk/libs/thread/doc/shared_mutex_ref.qbk	2012-10-28 21:25:12 EDT (Sun, 28 Oct 2012)
@@ -142,3 +142,87 @@
 
 
 [endsect]
+
+[section:null_mutex Class `null_mutex`]
+
+    #include <boost/thread/null_mutex.hpp>
+
+    class null_mutex
+    {
+    public:
+        null_mutex(null_mutex const&) = delete;
+        null_mutex& operator=(null_mutex const&) = delete;
+
+        null_mutex();
+        ~null_mutex();
+
+        void lock_shared();
+        bool try_lock_shared();
+     #ifdef BOOST_THREAD_USES_CHRONO
+        template <class Rep, class Period>
+        bool try_lock_shared_for(const chrono::duration<Rep, Period>& rel_time);
+        template <class Clock, class Duration>
+        bool try_lock_shared_until(const chrono::time_point<Clock, Duration>& abs_time);
+     #endif
+        void unlock_shared();
+
+        void lock();
+        bool try_lock();
+     #ifdef BOOST_THREAD_USES_CHRONO
+        template <class Rep, class Period>
+        bool try_lock_for(const chrono::duration<Rep, Period>& rel_time);
+        template <class Clock, class Duration>
+        bool try_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
+     #endif
+        void unlock();
+
+        void lock_upgrade();
+     #ifdef BOOST_THREAD_USES_CHRONO
+        template <class Rep, class Period>
+        bool try_lock_upgrade_for(const chrono::duration<Rep, Period>& rel_time);
+        template <class Clock, class Duration>
+        bool try_lock_upgrade_until(const chrono::time_point<Clock, Duration>& abs_time);
+     #endif
+        void unlock_upgrade();
+
+        // Shared <-> Exclusive
+
+        bool try_unlock_shared_and_lock();
+     #ifdef BOOST_THREAD_USES_CHRONO
+        template <class Rep, class Period>
+        bool try_unlock_shared_and_lock_for(const chrono::duration<Rep, Period>& rel_time);
+        template <class Clock, class Duration>
+        bool try_unlock_shared_and_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
+     #endif
+        void unlock_and_lock_shared();
+
+        // Shared <-> Upgrade
+
+        bool try_unlock_shared_and_lock_upgrade();
+     #ifdef BOOST_THREAD_USES_CHRONO
+        template <class Rep, class Period>
+        bool try_unlock_shared_and_lock_upgrade_for(const chrono::duration<Rep, Period>& rel_time);
+        template <class Clock, class Duration>
+        bool try_unlock_shared_and_lock_upgrade_until(const chrono::time_point<Clock, Duration>& abs_time);
+     #endif
+        void unlock_upgrade_and_lock_shared();
+
+        // Upgrade <-> Exclusive
+
+        void unlock_upgrade_and_lock();
+        bool try_unlock_upgrade_and_lock();
+     #ifdef BOOST_THREAD_USES_CHRONO
+        template <class Rep, class Period>
+        bool try_unlock_upgrade_and_lock_for(const chrono::duration<Rep, Period>& rel_time);
+        template <class Clock, class Duration>
+        bool try_unlock_upgrade_and_lock_until(const chrono::time_point<Clock, Duration>& abs_time);
+     #endif
+        void unlock_and_lock_upgrade();
+    };
+
+The class `boost::null_mutex` provides a no-op implementation of a multiple-reader / single-writer mutex. It is a model of the
+__UpgradeLockable concept.
+
+
+[endsect]
+

Modified: trunk/libs/thread/doc/thread.qbk
==============================================================================
--- trunk/libs/thread/doc/thread.qbk	(original)
+++ trunk/libs/thread/doc/thread.qbk	2012-10-28 21:25:12 EDT (Sun, 28 Oct 2012)
@@ -26,9 +26,9 @@
 [def __lockable_concept_type__ [lockable_concept_link `Lockable`]]
 [def __BasicLockable [link thread.synchronization.mutex_concepts.basic_lockable `BasicLockable`]]
 [def __Lockable [link thread.synchronization.mutex_concepts.lockable `Lockable`]]
-[def __TimedLockable [link thread.synchronization.mutex_concepts.timed_lockable `TimedLockable `]]
-[def __SharedLockable [link thread.synchronization.mutex_concepts.shared_lockable `SharedLockable `]]
-[def __UpgradeLockable [link thread.synchronization.mutex_concepts.upgrade_lockable `UpgradeLockable `]]
+[def __TimedLockable [link thread.synchronization.mutex_concepts.timed_lockable `TimedLockable`]]
+[def __SharedLockable [link thread.synchronization.mutex_concepts.shared_lockable `SharedLockable`]]
+[def __UpgradeLockable [link thread.synchronization.mutex_concepts.upgrade_lockable `UpgradeLockable`]]
 
 [template timed_lockable_concept_link[link_text] [link thread.synchronization.mutex_concepts.timed_lockable [link_text]]]
 [def __timed_lockable_concept__ [timed_lockable_concept_link `TimedLockable` concept]]
@@ -155,9 +155,12 @@
 [def __recursive_timed_mutex__ [link thread.synchronization.mutex_types.recursive_timed_mutex `boost::recursive_timed_mutex`]]
 [def __shared_mutex__ [link thread.synchronization.mutex_types.shared_mutex `boost::shared_mutex`]]
 
+
+[def __StrictLock [link thread.synchronization.lock_concepts.StrictLock `StrictLock`]]
+
 [template unique_lock_link[link_text] [link thread.synchronization.locks.unique_lock [link_text]]]
 
-[def __lock_guard__ [link thread.synchronization.locks.lock_guard `boost::lock_guard`]]
+[def __lock_guard__ [link thread.synchronization.lock_guard.lock_guard `boost::lock_guard`]]
 [def __unique_lock__ [unique_lock_link `boost::unique_lock`]]
 [def __unique_lock [unique_lock_link `boost::unique_lock`]]
 [def __shared_lock__ [link thread.synchronization.locks.shared_lock `boost::shared_lock`]]
@@ -167,6 +170,8 @@
 [def __shared_lock_guard [link thread.synchronization.other_locks.shared_lock_guard `shared_lock_guard`]]
 [def __shared_lock_guard_constructor_adopt [link thread.synchronization.other_locks.shared_lock_guard `shared_lock_guard`]]
 
+[def __strict_lock [link thread.synchronization.other_locks.strict_lock `strict_lock`]]
+
 
 [def __thread__ [link thread.thread_management.thread `boost::thread`]]
 [def __thread [link thread.thread_management.thread `thread`]]
@@ -177,7 +182,6 @@
 [def __try_join_for [link thread.thread_management.thread.try_join_for `try_join_for`]]
 [def __try_join_until [link thread.thread_management.thread.try_join_until `try_join_until`]]
 
-
 [template timed_join_link[link_text] [link thread.thread_management.thread.timed_join [link_text]]]
 [def __timed_join__ [timed_join_link `timed_join()`]]
 [def __detach__ [link thread.thread_management.thread.detach `detach()`]]
@@ -223,6 +227,7 @@
 [include changes.qbk]
 
 [include thread_ref.qbk]
+[include scoped_thread.qbk]
 
 [section:synchronization Synchronization]
 [include sync_tutorial.qbk]

Modified: trunk/libs/thread/doc/thread_ref.qbk
==============================================================================
--- trunk/libs/thread/doc/thread_ref.qbk	(original)
+++ trunk/libs/thread/doc/thread_ref.qbk	2012-10-28 21:25:12 EDT (Sun, 28 Oct 2012)
@@ -21,7 +21,7 @@
     {
       thread::id get_id() noexcept;
       template<typename TimeDuration>
-      void yield() noexcept;
+      void yield() noexcept; // DEPRECATED
       template <class Clock, class Duration>
       void sleep_until(const chrono::time_point<Clock, Duration>& abs_time); 
       template <class Rep, class Period>
@@ -36,9 +36,10 @@
       class disable_interruption; // EXTENSION
       class restore_interruption; // EXTENSION
 
-    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
-      void sleep(TimeDuration const& rel_time);
-      void sleep(system_time const& abs_time);
+    #if defined BOOST_THREAD_USES_DATETIME
+      template <TimeDuration>
+      void sleep(TimeDuration const& rel_time);  // DEPRECATED
+      void sleep(system_time const& abs_time); // DEPRECATED
     #endif
     }
     class thread_group; // EXTENSION
@@ -200,18 +201,81 @@
 
 [endsect]
 
-[section:join Joining and detaching]
+[section:detac Detaching thread]
+
+A thread can  be detached by explicitly invoking the __detach__ member function on the __thread__
+object. In this case, the __thread__ object ceases to represent the now-detached thread, and instead represents __not_a_thread__.
+
+  int main()
+  {
+    boost::thread t(my_func);
+    t.detach();
+  } 
+
+[endsect]
+
+[section:join Joining a thread]
+
+In order to wait for a thread of execution to finish, the __join__, __join_for or __join_until (__timed_join__ deprecated) member functions of the __thread__ object must be
+used. __join__ will block the calling thread until the thread represented by the __thread__ object has completed. 
+
+  int main()
+  {
+    boost::thread t(my_func);
+    t.join();
+  }
+
+
+If the thread of
+execution represented by the __thread__ object has already completed, or the __thread__ object represents __not_a_thread__, then __join__
+returns immediately. 
+
+  int main()
+  {
+    boost::thread t;
+    t.join(); // do nothing
+  }
+
+Timed based join are similar, except that a call to __join_for or __join_until will also return if the thread being waited for
+does not complete when the specified time has elapsed or reached respectively.
+
+  int main()
+  {
+    boost::thread t;
+    if ( t.join_for(boost::chrono::milliseconds(500)) ) 
+      // do something else
+    t.join(); // join anyway
+  }
+
+[endsect]
+
+[section:destructor1 Destructor V1]
 
 When the __thread__ object that represents a thread of execution is destroyed the thread becomes ['detached]. Once a thread is
 detached, it will continue executing until the invocation of the function or callable object supplied on construction has completed,
 or the program is terminated. A thread can also be detached by explicitly invoking the __detach__ member function on the __thread__
 object. In this case, the __thread__ object ceases to represent the now-detached thread, and instead represents __not_a_thread__.
 
-In order to wait for a thread of execution to finish, the __join__ or __timed_join__ member functions of the __thread__ object must be
-used. __join__ will block the calling thread until the thread represented by the __thread__ object has completed. If the thread of
-execution represented by the __thread__ object has already completed, or the __thread__ object represents __not_a_thread__, then __join__
-returns immediately. __timed_join__ is similar, except that a call to __timed_join__ will also return if the thread being waited for
-does not complete when the specified time has elapsed.
+[endsect]
+
+[section:destructor2 Destructor V2]
+
+When the __thread__ object that represents a thread of execution is destroyed the program terminates if the thread is __joinable__. 
+
+  int main()
+  {
+    boost::thread t(my_func);
+  } // calls std::terminate()
+
+You can use a thread_joiner to ensure that the thread has been joined at the thread destructor.
+
+
+  int main()
+  {
+    boost::thread t(my_func);
+    boost::thread_joiner g(t);
+    // do someting else
+  } // here the thread_joiner destructor will join the thread before it is destroyed.
 
 [endsect]
 
@@ -359,6 +423,8 @@
     class thread
     {
     public:
+        class attributes; // EXTENSION
+
         thread() noexcept;
         thread(const thread&) = delete;
         thread& operator=(const thread&) = delete;
@@ -374,15 +440,15 @@
 
         template <class F,class A1,class A2,...>
         thread(F f,A1 a1,A2 a2,...);
-        // template <class F, class ...Args> 
-        // explicit thread(F&& f, Args&&... args); // NOT YET IMPLEMENTED
+        template <class F, class ...Args> 
+        explicit thread(F&& f, Args&&... args);
 
         template <class F>
         explicit thread(attributes& attrs, F f); // EXTENSION
         template <class F>
         thread(attributes& attrs, F &&f); // EXTENSION
-        // template <class F, class ...Args> 
-        // explicit thread(attributes& attrs, F&& f, Args&&... args); // NOT YET IMPLEMENTED
+        template <class F, class ...Args> 
+        explicit thread(attributes& attrs, F&& f, Args&&... args);
 
         // move support
         thread(thread && x) noexcept;
@@ -391,7 +457,6 @@
         void swap(thread& x) noexcept;
 
         class id;
-        class attributes; // EXTENSION
 
         id get_id() const noexcept;
 
@@ -413,19 +478,19 @@
         bool interruption_requested() const noexcept; // EXTENSION
 
 
-    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
-        bool timed_join(const system_time& wait_until);
+    #if defined BOOST_THREAD_USES_DATETIME
+        bool timed_join(const system_time& wait_until); // DEPRECATED
         template<typename TimeDuration>
-        bool timed_join(TimeDuration const& rel_time); 
+        bool timed_join(TimeDuration const& rel_time); // DEPRECATED
+        static void sleep(const system_time& xt);// DEPRECATED
     #endif
 
-    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
-        bool operator==(const thread& other) const;
-        bool operator!=(const thread& other) const;
+    #if defined BOOST_THREAD_PROVIDES_THREAD_EQ
+        bool operator==(const thread& other) const; // DEPRECATED
+        bool operator!=(const thread& other) const; // DEPRECATED
 
-        static void yield();
-        static void sleep(const system_time& xt);
     #endif
+        static void yield() noexcept; // DEPRECATED
 
     };
 
@@ -470,8 +535,12 @@
 [variablelist
 
 [[Effects:] [Transfers ownership of the thread managed by `other` (if
-any) to `*this`. Version 2: If there was a thread previously associated with
-`*this` then that thread is detached, Version 3: If the thread is joinable calls to std::terminate.]]
+any) to `*this`. 
+
+_ if defined BOOST_THREAD_DONT_PROVIDE_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE: If there was a thread previously associated with `*this` then that thread is detached, DEPRECATED
+
+- if defined BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE: If the thread is joinable calls to std::terminate.
+]]
 
 [[Postconditions:] [`other->get_id()==thread::id()` and `get_id()` returns the value of `other.get_id()` prior to the assignment.]]
 
@@ -628,32 +697,19 @@
 
 [variablelist
 
-[[Effects:] [Version 2: If `*this` has an associated thread of execution, calls __detach__, Version 3: If the thread is joinable calls to std::terminate. Destroys `*this`.]]
-
-[[Throws:] [Nothing.]]
+[[Effects:] [
+- if defined BOOST_THREAD_DONT_PROVIDE_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE: If `*this` has an associated thread of execution, calls __detach__, DEPRECATED
 
-]
-
-[endsect]
+- BOOST_THREAD_PROVIDES_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE: If the thread is joinable calls to std::terminate. Destroys `*this`.]]
 
-[/
-[section:v2_destructor V3 Thread Destructor]
-
-    ~thread();
-
-[variablelist
-
-[[Effects:] [If `*this` has an associated thread of execution, calls terminate. Destroys `*this`.]]
+[[Throws:] [Nothing.]]
 
 [[Note:] [Either implicitly detaching or joining a `joinable()` thread in its destructor could result in difficult to debug correctness (for `detach`) or performance (for `join`) bugs encountered only when an exception is raised. Thus the programmer must ensure that the destructor is never executed while the thread is still joinable.]]
 
-
-[[Throws:] [Nothing.]]
-
 ]
 
 [endsect]
-]
+
 
 [section:joinable Member function `joinable()`]
 
@@ -704,7 +760,7 @@
 
 [endsect]
 
-[section:timed_join Member function `timed_join()`]
+[section:timed_join Member function `timed_join()` DEPRECATED]
 
     bool timed_join(const system_time& wait_until);
 
@@ -871,7 +927,7 @@
 
 [endsect]
 
-[section:interrupt Member function `interrupt()`]
+[section:interrupt Member function `interrupt()` EXTENSION]
 
     void interrupt();
 
@@ -919,7 +975,7 @@
 
 [endsect]
 
-[section:equals `operator==` DEPRECATED V3]
+[section:equals `operator==` DEPRECATED]
 
     bool operator==(const thread& other) const;
 
@@ -933,7 +989,7 @@
 
 [endsect]
 
-[section:not_equals `operator!=` DEPRECATED V3]
+[section:not_equals `operator!=` DEPRECATED]
 
     bool operator!=(const thread& other) const;
 
@@ -947,7 +1003,7 @@
 
 [endsect]
 
-[section:sleep Static member function `sleep()`]
+[section:sleep Static member function `sleep()` DEPRECATED]
 
     void sleep(system_time const& abs_time);
 
@@ -965,7 +1021,7 @@
 
 [endsect]
 
-[section:yield Static member function `yield()`]
+[section:yield Static member function `yield()` DEPRECATED]
 
     void yield();
 
@@ -1262,9 +1318,9 @@
       class disable_interruption; // EXTENSION
       class restore_interruption; // EXTENSION
 
-    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
-      void sleep(TimeDuration const& rel_time);
-      void sleep(system_time const& abs_time) 
+    #if defined BOOST_THREAD_USES_DATETIME
+      void sleep(TimeDuration const& rel_time); // DEPRECATED
+      void sleep(system_time const& abs_time);  // DEPRECATED
     #endif
     }
   }
@@ -1345,7 +1401,7 @@
 
 [endsect]
 
-[section:sleep Non-member function `sleep()`]
+[section:sleep Non-member function `sleep()` DEPRECATED]
 
     #include <boost/thread/thread.hpp>
 
@@ -1584,14 +1640,17 @@
 
 [endsect]
 
-[section:threadgroup Class `thread_group`]
+[section:threadgroup Class `thread_group` EXTENSION]
 
     #include <boost/thread/thread.hpp>
+    #include <boost/thread/thread_group.hpp>
 
-    class thread_group:
-        private noncopyable
+    class thread_group
     {
     public:
+        thread_group(const thread_group&) = delete;
+        thread_group& operator=(const thread_group&) = delete;
+
         thread_group();
         ~thread_group();