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

Subject: [Boost-commit] svn:boost r82283 - trunk/libs/thread/doc
From: vicente.botet_at_[hidden]
Date: 2012-12-30 13:24:02

Author: viboes
Date: 2012-12-30 13:24:01 EST (Sun, 30 Dec 2012)
New Revision: 82283
URL: http://svn.boost.org/trac/boost/changeset/82283

Log:
Thread: update doc
Text files modified: 
   trunk/libs/thread/doc/condition_variables.qbk |     4 +-                                      
   trunk/libs/thread/doc/mutex_concepts.qbk      |    25 +++++++++++++++++++--                   
   trunk/libs/thread/doc/scoped_thread.qbk       |    46 +++++++++++++++------------------------ 
   trunk/libs/thread/doc/shared_mutex_ref.qbk    |     2                                         
   trunk/libs/thread/doc/thread_ref.qbk          |     9 ++++++-                                 
   5 files changed, 50 insertions(+), 36 deletions(-)

Modified: trunk/libs/thread/doc/condition_variables.qbk
==============================================================================
--- trunk/libs/thread/doc/condition_variables.qbk	(original)
+++ trunk/libs/thread/doc/condition_variables.qbk	2012-12-30 13:24:01 EST (Sun, 30 Dec 2012)
@@ -131,7 +131,7 @@
                 const chrono::duration<Rep, Period>& d,
                 Predicate pred);
 
-        #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
+        #if defined BOOST_THREAD_USES_DATETIME
             bool timed_wait(boost::unique_lock<boost::mutex>& lock,boost::system_time const& abs_time);
             template<typename duration_type>
             bool timed_wait(boost::unique_lock<boost::mutex>& lock,duration_type const& rel_time);
@@ -482,7 +482,7 @@
                 const chrono::duration<Rep, Period>& d,
                 Predicate pred);
 
-        #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
+        #if defined BOOST_THREAD_USES_DATETIME
             template<typename lock_type>
             bool timed_wait(lock_type& lock,boost::system_time const& abs_time);
             template<typename lock_type,typename duration_type>

Modified: trunk/libs/thread/doc/mutex_concepts.qbk
==============================================================================
--- trunk/libs/thread/doc/mutex_concepts.qbk	(original)
+++ trunk/libs/thread/doc/mutex_concepts.qbk	2012-12-30 13:24:01 EST (Sun, 30 Dec 2012)
@@ -44,6 +44,8 @@
 
 [[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. ]]
+
 [[Postcondition:] [The current thread owns `m`.]]
 
 [[Return type:] [`void`.]]
@@ -71,6 +73,8 @@
 
 [[Requires:] [The current thread owns `m`.]]
 
+[[Synchronization:] [This operation synchronizes with subsequent lock operations that obtain ownership on the same object.]]
+
 [[Effects:] [Releases a lock on `m` by the current thread.]]
 
 [[Return type:] [`void`.]]
@@ -119,6 +123,12 @@
 
 [[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.]]
+
+[[Note:] [Since `lock()` does not synchronize with a failed subsequent
+`try_lock()`, the visibility rules are weak enough that little would be known about the state after a
+failure, even in the absence of spurious failures.]]
+
 [[Return type:] [`bool`.]]
 
 [[Returns:] [`true` if ownership was obtained for the current thread, `false` otherwise.]]
@@ -213,6 +223,10 @@
 [[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__.]]
 
+[[Synchronization:] [If `try_lock_until()` returns true, prior `unlock()` operations on the same object synchronize with this operation.]]
+
+[[Return type:] [`bool`.]]
+
 [[Returns:] [`true` if ownership was obtained for the current thread, `false` otherwise.]]
 
 [[Postcondition:] [If the call returns `true`, the current thread owns `m`.]]
@@ -227,13 +241,15 @@
 
 [[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.]]
+
 ]
 [endsect]
 
 [warning
-DEPRECATED since 3.00. The following expressions were required on version 2, but are now deprecated.
+DEPRECATED since 4.00. The following expressions were required on version 2, but are now deprecated.
  
-Available only up to Boost 1.56. 
+Available only up to Boost 1.58. 
 
 Use instead __try_lock_for, __try_lock_until.  
 ]
@@ -2415,6 +2431,7 @@
 
 An instance of __reverse_lock doesn't ['own] the lock never.
 
+
 [section:constructor `reverse_lock(Lock & m)`]
 
 [variablelist
@@ -2436,7 +2453,9 @@
 
 [[Effects:] [Let be mtx the stored mutex*. If not 0 Invokes `mtx->__lock()` and gives again the `mtx` to the `Lock` using the `adopt_lock_t` overload.]]
 
-[[Throws:] [Nothing.]]
+[[Throws:] [Any exception thrown by `mtx->__lock()`.]]
+
+[[Remarks:] [Note that if `mtx->__lock()` throws an exception while unwinding the program will terminate, so don't use reverse_lock if an exception can be thrown.]]
 
 ]
 

Modified: trunk/libs/thread/doc/scoped_thread.qbk
==============================================================================
--- trunk/libs/thread/doc/scoped_thread.qbk	(original)
+++ trunk/libs/thread/doc/scoped_thread.qbk	2012-12-30 13:24:01 EST (Sun, 30 Dec 2012)
@@ -111,14 +111,14 @@
   };
 
 
-RAI @c thread wrapper adding a specific destroyer allowing to master what can be done at destruction time.
+RAI __thread wrapper adding a specific destroyer allowing to master what can be done at destruction time.
 
-CallableThread: A callable void(thread&) .
+CallableThread: A callable `void(thread&)`.
 
-The default is a join_if_joinable.
+The default is a `join_if_joinable`.
 
 
-thread std/boost::thread destructor terminates the program if the thread is not joinable.
+`std/boost::thread` destructor terminates the program if the __thread is not joinable.
 This wrapper can be used to join the thread before destroying it seems a natural need.
 
 [heading Example]
@@ -131,7 +131,7 @@
 
 [variablelist
 
-[[Effects:] [move the thread to own @c t]]
+[[Effects:] [move the thread to own `t_`]]
 
 [[Throws:] [Nothing]]
 
@@ -147,7 +147,8 @@
 
 [[Effects:] [Equivalent to `CallableThread()(t_)`.  ]]
 
-[[Throws:] [Nothing]]
+[[Throws:] [Nothing: The `CallableThread()(t_)` should not throw when joining the thread as the scoped variable is on a scope outside the thread function.]]
+
 
 ]
 
@@ -161,12 +162,13 @@
 
     class scoped_thread
     {
+      thread t_; // for exposition purposes only
     public:
         scoped_thread() noexcept;
         scoped_thread(const scoped_thread&) = delete;
         scoped_thread& operator=(const scoped_thread&) = delete;
 
-        explicit scoped_thread(thread&& th);
+        explicit scoped_thread(thread&& th) noexcept;
 
         ~scoped_thread();
 
@@ -182,10 +184,12 @@
 
         bool joinable() const noexcept;
         void join();
+    #ifdef BOOST_THREAD_USES_CHRONO
         template <class Rep, class Period>
         bool try_join_for(const chrono::duration<Rep, Period>& rel_time);
         template <class Clock, class Duration>
         bool try_join_until(const chrono::time_point<Clock, Duration>& t);
+    #endif
 
         void detach();
 
@@ -194,23 +198,11 @@
         typedef thread::native_handle_type native_handle_type;
         native_handle_type native_handle();
 
+    #if defined BOOST_THREAD_PROVIDES_INTERRUPTIONS
         void interrupt();
         bool interruption_requested() const noexcept;
-
-
-    #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); // DEPRECATED
-        static void sleep(const system_time& xt);// DEPRECATED
     #endif
 
-    #if defined BOOST_THREAD_PROVIDES_THREAD_EQ
-        bool operator==(const scoped_thread& other) const; // DEPRECATED
-        bool operator!=(const scoped_thread& other) const; // DEPRECATED
-
-    #endif
-        static void yield() noexcept; // DEPRECATED
 
     };
 
@@ -225,9 +217,9 @@
 thread std::thread destructor terminates the program if the thread is not joinable.
 Having a wrapper that can join the thread before destroying it seems a natural need.
 
-Remark: scoped_thread is not a @c thread as @c thread is not designed to be derived from as a polymorphic type.
+Remark: `scoped_thread` is not a __thread as __thread is not designed to be derived from as a polymorphic type.
 
-Anyway scoped_thread can be used in most of the contexts a @c thread could be used as it has the
+Anyway `scoped_thread` can be used in most of the contexts a __thread could be used as it has the
 same non-deprecated interface with the exception of the construction.
 
 [heading Example]
@@ -277,9 +269,9 @@
 [[Effects:] [Transfers ownership of the scoped_thread managed by `other` (if
 any) to `*this`. 
 
-_ if defined BOOST_THREAD_DONT_PROVIDE_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE: If there was a scoped_thread previously associated with `*this` then that scoped_thread is detached, DEPRECATED
+- if defined `BOOST_THREAD_DONT_PROVIDE_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE`: If there was a `scoped_thread` previously associated with `*this` then that `scoped_thread` is detached, DEPRECATED
 
-- if defined BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE: If the scoped_thread is joinable calls to std::terminate.
+- if defined `BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE`: If the `scoped_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.]]
@@ -296,7 +288,7 @@
 
 [variablelist
 
-[[Effects:] [move the thread to own @c t.]]
+[[Effects:] [move the thread to own `t_`.]]
 
 [[Postconditions:] [`*this.t_` refers to the newly created thread of execution and `this->get_id()!=thread::id()`.]]
 
@@ -315,7 +307,7 @@
 
 [[Effects:] [Equivalent to `CallableThread()(t_)`.  ]]
 
-[[Throws:] [Nothing]]
+[[Throws:] [Nothing: The `CallableThread()(t_)` should not throw when joining the thread as the scoped variable is on a scope outside the thread function.]]
 
 ]
 
@@ -345,8 +337,6 @@
 
 [[Effects:] [Equivalent to t_.join().]]
 
-]]
-
 ]
 
 [endsect]

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-12-30 13:24:01 EST (Sun, 30 Dec 2012)
@@ -45,7 +45,7 @@
         void unlock_upgrade_and_lock_shared();
     #endif
 
-    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
+    #if defined BOOST_THREAD_USES_DATETIME
         bool timed_lock_shared(system_time const& timeout);
         bool timed_lock(system_time const& timeout);
     #endif

Modified: trunk/libs/thread/doc/thread_ref.qbk
==============================================================================
--- trunk/libs/thread/doc/thread_ref.qbk	(original)
+++ trunk/libs/thread/doc/thread_ref.qbk	2012-12-30 13:24:01 EST (Sun, 30 Dec 2012)
@@ -547,7 +547,7 @@
 [[Effects:] [Transfers ownership of the thread managed by `other` (if
 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_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.
 ]]
@@ -755,13 +755,18 @@
 
 [[Effects:] [If `*this` refers to a thread of execution, waits for that thread of execution to complete.]]
 
+[[Synchronization:] [The completion of the thread represented by `*this` synchronizes with the
+corresponding successful `join()` return. ]]
+[[Note:] [Operations on *this are not synchronized.
+ ]]
+
 [[Postconditions:] [If `*this` refers to a thread of execution on entry, that thread of execution has completed. `*this` no longer refers to any thread of execution.]]
 
 [[Throws:] [__thread_interrupted__ if the current thread of execution is interrupted or `system_error`]]
 
 [[Error Conditions:] [
 
-[*resource_deadlock_would_occur]: if deadlock is detected or `this->get_id() == boost::this_thread::get_id()` and `BOOST_THREAD_TRHOW_IF_PRECONDITION_NOT_SATISFIED` is defined..
+[*resource_deadlock_would_occur]: if deadlock is detected or `this->get_id() == boost::this_thread::get_id()`.
 
 [*invalid_argument]: if the thread is not joinable and `BOOST_THREAD_TRHOW_IF_PRECONDITION_NOT_SATISFIED` is defined.