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

Subject: [Boost-commit] svn:boost r81130 - trunk/libs/thread/doc
From: vicente.botet_at_[hidden]
Date: 2012-10-31 17:17:50

Author: viboes
Date: 2012-10-31 17:17:49 EDT (Wed, 31 Oct 2012)
New Revision: 81130
URL: http://svn.boost.org/trac/boost/changeset/81130

Log:
Thread: update doc with warnigs for deprecated features + history
Text files modified: 
   trunk/libs/thread/doc/changes.qbk        |    25 ++++++++--                              
   trunk/libs/thread/doc/future_ref.qbk     |    20 ++++++++                                
   trunk/libs/thread/doc/mutex_concepts.qbk |    86 +++++++++++++++++++++++++++++++++++---- 
   trunk/libs/thread/doc/mutexes.qbk        |     4                                         
   trunk/libs/thread/doc/thread_ref.qbk     |    79 ++++++++++++++++++++++++++++++++----    
   5 files changed, 185 insertions(+), 29 deletions(-)

Modified: trunk/libs/thread/doc/changes.qbk
==============================================================================
--- trunk/libs/thread/doc/changes.qbk	(original)
+++ trunk/libs/thread/doc/changes.qbk	2012-10-31 17:17:49 EDT (Wed, 31 Oct 2012)
@@ -20,25 +20,38 @@
 
 * packaged_task<R> is deprecated, use instead packaged_task<R()>. See BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK and BOOST_THREAD_DONT_PROVIDE_SIGNATURE_PACKAGED_TASK
 
+* [@http://svn.boost.org/trac/boost/ticket/7537 #7537] deprecate Mutex::scoped_lock and scoped_try_lock and boost::condition
+
 New Features:
 
-* [@http://svn.boost.org/trac/boost/ticket/7281 #7281] C++11 compliance: Add ArgTypes to packaged_task template. 
-Provided when BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK is defined (Default value from Boost 1.55).
-See BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK and BOOST_THREAD_DONT_PROVIDE_SIGNATURE_PACKAGED_TASK.
 
 
 * [@http://svn.boost.org/trac/boost/ticket/6270 #6270] c++11 compliance: Add thread constructor from movable callable and movable arguments
 Provided when BOOST_THREAD_PROVIDES_VARIADIC_THREAD is defined (Default value from Boost 1.55):
 See BOOST_THREAD_PROVIDES_VARIADIC_THREAD and BOOST_THREAD_DONT_PROVIDE_VARIADIC_THREAD.
 
+* [@http://svn.boost.org/trac/boost/ticket/7281 #7281] C++11 compliance: Add ArgTypes to packaged_task template. 
+Provided when BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK is defined (Default value from Boost 1.55).
+See BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK and BOOST_THREAD_DONT_PROVIDE_SIGNATURE_PACKAGED_TASK.
+
 * [@http://svn.boost.org/trac/boost/ticket/7412 #7412] c++11 compliance: Add async from movable callable and movable arguments
 Provided when BOOST_THREAD_PROVIDES_VARIADIC_THREAD and BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK are defined (Default value from Boost 1.55):
 See BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK and BOOST_THREAD_DONT_PROVIDE_SIGNATURE_PACKAGED_TASK, BOOST_THREAD_PROVIDES_VARIADIC_THREAD and BOOST_THREAD_DONT_PROVIDE_VARIADIC_THREAD.
 
-* [@http://svn.boost.org/trac/boost/ticket/7414 #7414] c++11 compliance: future::get post-condition should be valid()==false
-* [@http://svn.boost.org/trac/boost/ticket/7414 #7444] Async: Add make_future/make_shared_future
-
 [/* [@http://svn.boost.org/trac/boost/ticket/7413 #7413] c++11 compliance: Add async when the launch policy is deferred.]
+* [@http://svn.boost.org/trac/boost/ticket/7414 #7414] c++11 compliance: future::get post-condition should be valid()==false.
+* [@http://svn.boost.org/trac/boost/ticket/7414 #7444] Async: Add make_future/make_shared_future.
+* [@http://svn.boost.org/trac/boost/ticket/7445 #7445] Async: Add future<>.then.
+* [@http://svn.boost.org/trac/boost/ticket/7449 #7449] Synchro: Add a synchronized value class.
+* [@http://svn.boost.org/trac/boost/ticket/7540 #7540] Add a helper class that join a thread on destruction.
+* [@http://svn.boost.org/trac/boost/ticket/7541 #7541] Add a thread wrapper class that joins on destruction.
+* [@http://svn.boost.org/trac/boost/ticket/7587 #7587] Add strict_lock and nested_strict_lock
+* [@http://svn.boost.org/trac/boost/ticket/7588 #7588] Split the locks.hpp in several files to limit depedencies
+* [@http://svn.boost.org/trac/boost/ticket/7589 #7589] Add polymorphic lockables
+* [@http://svn.boost.org/trac/boost/ticket/7590 #7590] Add lockable concept checkers based on Boost.ConceptCheck
+* [@http://svn.boost.org/trac/boost/ticket/7592 #7592] Add a null_mutex that is a no-op and that is a model of UpgardeLockable
+* [@http://svn.boost.org/trac/boost/ticket/7593 #7593] Add a externally_locked class
+* [@http://svn.boost.org/trac/boost/ticket/7590 #7594] Allow to disable thread interruptions
 
 Fixed Bugs:
 

Modified: trunk/libs/thread/doc/future_ref.qbk
==============================================================================
--- trunk/libs/thread/doc/future_ref.qbk	(original)
+++ trunk/libs/thread/doc/future_ref.qbk	2012-10-31 17:17:49 EDT (Wed, 31 Oct 2012)
@@ -289,7 +289,7 @@
       template <class Clock, class Duration>
       future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
 
-    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
+    #if defined BOOST_THREAD_USES_DATE_TIME || defined BOOST_THREAD_DONT_USE_CHRONO
       template<typename Duration>
       bool timed_wait(Duration const& rel_time) const; // DEPRECATED SINCE V3.0.0
       bool timed_wait_until(boost::system_time const& abs_time) const; // DEPRECATED SINCE V3.0.0
@@ -444,6 +444,14 @@
     template<typename Duration>
     bool timed_wait(Duration const& wait_duration);
 
+[warning
+DEPRECATED since 3.00.
+ 
+Available only up to Boost 1.56. 
+
+Use instead __wait_for.  
+]
+
 [variablelist
 
 [[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready, or the time specified by
@@ -470,6 +478,14 @@
 
     bool timed_wait(boost::system_time const& wait_timeout);
 
+[warning
+DEPRECATED since 3.00.
+ 
+Available only up to Boost 1.56. 
+
+Use instead __wait_until.  
+]
+
 [variablelist
 
 [[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready, or the time point specified by
@@ -733,7 +749,7 @@
       template <class Clock, class Duration>
       future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
 
-    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
+    #if defined BOOST_THREAD_USES_DATE_TIME || defined BOOST_THREAD_DONT_USE_CHRONO
       template<typename Duration>
       bool timed_wait(Duration const& rel_time) const;  // DEPRECATED SINCE V3.0.0
       bool timed_wait_until(boost::system_time const& abs_time) const;  // DEPRECATED SINCE V3.0.0

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-31 17:17:49 EDT (Wed, 31 Oct 2012)
@@ -20,6 +20,16 @@
 
 [section:basic_lockable `BasicLockable` Concept]
 
+  // #include <boost/thread/lockable_concepts.hpp> 
+
+  namespace boost 
+  {
+
+    template<typename L>
+    class BasicLockable;
+  }
+
+
 The __BasicLockable concept models exclusive ownership. 
 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`):
 
@@ -73,6 +83,15 @@
 [endsect]
 [section:lockable `Lockable` Concept]
 
+  // #include <boost/thread/lockable_concepts.hpp> 
+
+  namespace boost 
+  {
+    template<typename L>
+    class Lockable;
+  }
+
+
 A type `L` meets the __Lockable requirements if it meets the __BasicLockable requirements and the following expressions are well-formed and have the specified semantics (`m` denotes a value of type `L`):
 
 * `m.__try_lock()`
@@ -100,6 +119,14 @@
 
 [section:timed_lockable `TimedLockable` Concept]
 
+  // #include <boost/thread/lockable_concepts.hpp> 
+
+  namespace boost 
+  {
+    template<typename L>
+    class TimedLockable;
+  }
+
 The __timed_lockable_concept__ refines the __lockable_concept__ to add support for
 timeouts when trying to acquire the lock.
 
@@ -142,9 +169,14 @@
 ]
 [endsect]
 
-[heading Deprecated V3.0.0]
+[warning
+DEPRECATED since 3.00. The following expressions were required on version 2, but are now deprecated.
+ 
+Available only up to Boost 1.56. 
+
+Use instead __try_lock_for, __try_lock_until.  
+]
 
-The following expressions were required on version 2, but are now deprecated.
 
 [*Variables:]
 
@@ -188,6 +220,15 @@
 
 [section:shared_lockable `SharedLockable` Concept]
 
+  // #include <boost/thread/lockable_concepts.hpp> 
+
+  namespace boost 
+  {
+    template<typename L>
+    class SharedLockable;
+  }
+
+
 The __shared_lockable_concept__ is a refinement of the __timed_lockable_concept__ that
 allows for ['shared ownership] as well as ['exclusive ownership]. This is the
 standard multiple-reader / single-write model: at most one thread can have
@@ -290,9 +331,13 @@
 ]
 [endsect]
 
-[heading Deprecated V3]
+[warning
+DEPRECATED since 3.00. The following expressions were required on version 2, but are now deprecated.
+ 
+Available only up to Boost 1.56. 
 
-The following expressions were required on version 1, but are now deprecated.
+Use instead __try_lock_shared_for, __try_lock_shared_until.  
+]
 
 [*Variables:]
 
@@ -327,6 +372,15 @@
 
 [section:upgrade_lockable `UpgradeLockable` Concept]
 
+  // #include <boost/thread/lockable_concepts.hpp> 
+
+  namespace boost 
+  {
+    template<typename L>
+    class UpgradeLockable;
+  }
+
+
 The __upgrade_lockable_concept__ is a refinement of the __shared_lockable_concept__ that allows for ['upgradable ownership] as well
 as ['shared ownership] and ['exclusive ownership]. This is an extension to the multiple-reader / single-write model provided by the
 __shared_lockable_concept__: a single thread may have ['upgradable ownership] at the same time as others have ['shared
@@ -907,18 +961,30 @@
 [section:lock_concepts Lock Concepts]
 [section:StrictLock StrictLock]
 
+  // #include <boost/thread/lock_concepts.hpp> 
+
+  namespace boost 
+  {
+
+    template<typename Lock>
+    class 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();`
+* `is_strict_lock<L>`
+* `cl.owns_lock(m);`
 
-where
+and BasicLockable<L::mutex_type>
 
-* `cl` denotes a value of type `const L`,
+where
 
+* `cl` denotes a value of type `L const&`,
+* `m` denotes a value of type `L::mutex_type const*`,
 
 [section: mutex_type `L::mutex_type`]
 
@@ -1045,7 +1111,7 @@
 
         Lockable* mutex() const noexcept;
 
-    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
+    #if defined BOOST_THREAD_USE_DATE_TIME || defined BOOST_THREAD_DONT_USE_CHRONO
         unique_lock(Lockable& m_,system_time const& target_time);
         template<typename TimeDuration>
         bool timed_lock(TimeDuration const& relative_time);
@@ -1405,7 +1471,7 @@
         bool owns_lock() const;
         mutex_type mutex() const;
 
-    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
+    #if defined BOOST_THREAD_USE_DATE_TIME || defined BOOST_THREAD_DONT_USE_CHRONO
         shared_lock(Lockable& m_,system_time const& target_time);
         bool timed_lock(boost::system_time const& target_time);
     #endif

Modified: trunk/libs/thread/doc/mutexes.qbk
==============================================================================
--- trunk/libs/thread/doc/mutexes.qbk	(original)
+++ trunk/libs/thread/doc/mutexes.qbk	2012-10-31 17:17:49 EDT (Wed, 31 Oct 2012)
@@ -89,7 +89,7 @@
         typedef unspecified-type scoped_try_lock;
         typedef scoped_timed_lock scoped_lock;
 
-    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
+    #if defined BOOST_THREAD_PROVIDES_DATE_TIME || defined BOOST_THREAD_DONT_USE_CHRONO
         bool timed_lock(system_time const & abs_time);
         template<typename TimeDuration>
         bool timed_lock(TimeDuration const & relative_time);
@@ -203,7 +203,7 @@
         typedef unspecified-type scoped_try_lock;
         typedef scoped_lock scoped_timed_lock;
 
-    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
+    #if defined BOOST_THREAD_PROVIDES_DATE_TIME || defined BOOST_THREAD_DONT_USE_CHRONO
         bool timed_lock(system_time const & abs_time); 
         template<typename TimeDuration>
         bool timed_lock(TimeDuration const & relative_time);

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-31 17:17:49 EDT (Wed, 31 Oct 2012)
@@ -532,6 +532,16 @@
 
     thread& operator=(thread&& other) noexcept;
 
+
+[warning
+DEPRECATED since 3.0.0: BOOST_THREAD_DONT_PROVIDE_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE behavior.  
+ 
+Available only up to Boost 1.56. 
+
+Join the thread before moving.
+]
+
+
 [variablelist
 
 [[Effects:] [Transfers ownership of the thread managed by `other` (if
@@ -548,6 +558,7 @@
 
 ]
 
+
 [endsect]
 
 [section:callable_constructor Thread Constructor]
@@ -695,6 +706,14 @@
 
     ~thread();
 
+[warning
+DEPRECATED since 3.0.0: BOOST_THREAD_DONT_PROVIDE_THREAD_DESTRUCTOR_CALLS_TERMINATE_IF_JOINABLE behavior.  
+ 
+Available only up to Boost 1.56. 
+
+Join the thread before destroying or use a scoped thread.
+]
+
 [variablelist
 
 [[Effects:] [
@@ -767,6 +786,14 @@
     template<typename TimeDuration>
     bool timed_join(TimeDuration const& rel_time);
 
+[warning
+DEPRECATED since 3.00.
+ 
+Available only up to Boost 1.56. 
+
+Use instead __try_join_for, __try_join_until.  
+]
+
 [variablelist
 
 [[Preconditions:] [the thread is joinable.]]
@@ -979,11 +1006,19 @@
 
     bool operator==(const thread& other) const;
 
+[warning
+DEPRECATED since 4.0.0.  
+ 
+Available only up to Boost 1.58. 
+
+Use `a.__get_id()==b.__get_id()` instead`.
+]
+
+
 [variablelist
 
 [[Returns:] [`get_id()==other.get_id()`]]
 
-[[See:] [Use `a.__get_id()==b.__get_id()` instead]]
 
 ]
 
@@ -993,12 +1028,18 @@
 
     bool operator!=(const thread& other) const;
 
+[warning
+DEPRECATED since 4.0.0.  
+ 
+Available only up to Boost 1.58. 
+
+Use `a.__get_id()!=b.__get_id()` instead`.
+]
+
 [variablelist
 
 [[Returns:] [`get_id()!=other.get_id()`]]
 
-[[See:] [Use `a.__get_id()!=b.__get_id()` instead`]]
-
 ]
 
 [endsect]
@@ -1007,6 +1048,15 @@
 
     void sleep(system_time const& abs_time);
 
+[warning
+DEPRECATED since 3.0.0.  
+ 
+Available only up to Boost 1.56. 
+
+Use `this_thread::__sleep_for()` or `this_thread::__sleep_until()`.
+]
+
+
 [variablelist
 
 [[Effects:] [Suspends the current thread until the specified time has been reached.]]
@@ -1015,8 +1065,6 @@
 
 [[Notes:] [`sleep()` is one of the predefined __interruption_points__.]]
 
-[[See:] [Use `this_thread::__sleep_for()` or `this_thread::__sleep_until()`]]
-
 ]
 
 [endsect]
@@ -1025,12 +1073,18 @@
 
     void yield();
 
+[warning
+DEPRECATED since 3.0.0.  
+ 
+Available only up to Boost 1.56. 
+
+Use `this_thread::__yield()`.
+]
+
 [variablelist
 
 [[Effects:] [See [link thread.thread_management.this_thread.yield `boost::this_thread::yield()`].]]
 
-[[See:] [Use `this_thread::__yield()`]]
-
 ]
 
 [endsect]
@@ -1412,6 +1466,15 @@
         void sleep(system_time const& abs_time)
     }
 
+[warning
+DEPRECATED since 3.0.0.  
+ 
+Available only up to Boost 1.56. 
+
+Use `__sleep_for()` and `__sleep_until()` instead.
+]
+
+
 [variablelist
 
 [[Effects:] [Suspends the current thread until the time period
@@ -1422,8 +1485,6 @@
 
 [[Notes:] [`sleep()` is one of the predefined __interruption_points__.]]
 
-[[See:] [Use `__sleep_for()` and `__sleep_until()` instead.]]
-
 ]
 
 [endsect]