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

Subject: [Boost-commit] svn:boost r75790 - trunk/libs/thread/doc
From: vicente.botet_at_[hidden]
Date: 2011-12-03 09:28:18

Author: viboes
Date: 2011-12-03 09:28:17 EST (Sat, 03 Dec 2011)
New Revision: 75790
URL: http://svn.boost.org/trac/boost/changeset/75790

Log:
Thread: 2639 documentation should be extended(defer_lock, try_to_lock, ...) + 3885 document about mix usage of boost.thread and native thread api. + 3975 Incorrect precondition for promise::set_wait_callback() + 4819 boost.thread's documentation misprints.
Text files modified: 
   trunk/libs/thread/doc/changes.qbk        |    19 ++++++++++++++++++-                     
   trunk/libs/thread/doc/future_ref.qbk     |     2 +-                                      
   trunk/libs/thread/doc/mutex_concepts.qbk |    19 +++++++++++++++++++                     
   trunk/libs/thread/doc/thread_ref.qbk     |    40 +++++++++++++++++++++++++++++++++++++++-
   4 files changed, 77 insertions(+), 3 deletions(-)

Modified: trunk/libs/thread/doc/changes.qbk
==============================================================================
--- trunk/libs/thread/doc/changes.qbk	(original)
+++ trunk/libs/thread/doc/changes.qbk	2011-12-03 09:28:17 EST (Sat, 03 Dec 2011)
@@ -5,7 +5,24 @@
   http://www.boost.org/LICENSE_1_0.txt).
 ]
 
-[section:changes Changes since boost 1.40]
+[section:changes Changes since]
+
+[heading Changes since boost 1.41]
+
+Fixed Bugs:
+
+* [@http://svn.boost.org/trac/boost/ticket/2639 #2639] documentation should be extended(defer_lock, try_to_lock, ...).
+* [@http://svn.boost.org/trac/boost/ticket/3885 #3885] document about mix usage of boost.thread and native thread api.
+* [@http://svn.boost.org/trac/boost/ticket/3762 #3762] Thread can't be compiled with winscw (Codewarrior by Nokia).
+* [@http://svn.boost.org/trac/boost/ticket/3975 #3975] Incorrect precondition for promise::set_wait_callback().
+* [@http://svn.boost.org/trac/boost/ticket/4480 #4480] OpenVMS patches for compiler issues workarounds.
+* [@http://svn.boost.org/trac/boost/ticket/4819 #4819] boost.thread's documentation misprints.
+* [@http://svn.boost.org/trac/boost/ticket/5423 #5423] thread issues with C++0x.
+* [@http://svn.boost.org/trac/boost/ticket/5739 #5739] set-but-not-used warnings with gcc-4.6
+* [@http://svn.boost.org/trac/boost/ticket/6168 #6168] recursive_mutex is using wrong config symbol (possible typo).
+* [@http://svn.boost.org/trac/boost/ticket/6200 #6200] patch to have condition_variable and mutex error better handle EINTR. 
+
+[heading Changes since boost 1.40]
 
 The 1.41.0 release of Boost adds futures to the thread library. There are also a few minor changes.
 

Modified: trunk/libs/thread/doc/future_ref.qbk
==============================================================================
--- trunk/libs/thread/doc/future_ref.qbk	(original)
+++ trunk/libs/thread/doc/future_ref.qbk	2011-12-03 09:28:17 EST (Sat, 03 Dec 2011)
@@ -701,7 +701,7 @@
 
 [variablelist
 
-[[Preconditions:] [The expression `f(t)` where `t` is a lvalue of type __packaged_task__ shall be well-formed. Invoking a copy of
+[[Preconditions:] [The expression `f(t)` where `t` is a lvalue of type __promise__ shall be well-formed. Invoking a copy of
 `f` shall have the same effect as invoking `f`]]
 
 [[Effects:] [Store a copy of `f` with the asynchronous result associated with `*this` as a ['wait callback]. This will replace any

Modified: trunk/libs/thread/doc/mutex_concepts.qbk
==============================================================================
--- trunk/libs/thread/doc/mutex_concepts.qbk	(original)
+++ trunk/libs/thread/doc/mutex_concepts.qbk	2011-12-03 09:28:17 EST (Sat, 03 Dec 2011)
@@ -310,6 +310,25 @@
 
 [section:locks Lock Types]
 
+[section:lock_tags Lock option tags] 
+
+  #include <boost/thread/locks.hpp> 
+
+  struct defer_lock_t {}; 
+  struct try_to_lock_t {}; 
+  struct adopt_lock_t {}; 
+  const defer_lock_t defer_lock; 
+  const try_to_lock_t try_to_lock; 
+  const adopt_lock_t adopt_lock; 
+
+These tags are used in scoped locks constructors to specify a specific behavior. 
+
+*`defer_lock_t`: is used to construct the scoped lock without locking it. 
+*`try_to_lock_t`: is used to construct the scoped lock trying to lock it. 
+*`adopt_lock_t`: is used to construct the scoped lock without locking it but adopting ownership. 
+
+[endsect] 
+
 [section:lock_guard Class template `lock_guard`]
 
     #include <boost/thread/locks.hpp>

Modified: trunk/libs/thread/doc/thread_ref.qbk
==============================================================================
--- trunk/libs/thread/doc/thread_ref.qbk	(original)
+++ trunk/libs/thread/doc/thread_ref.qbk	2011-12-03 09:28:17 EST (Sat, 03 Dec 2011)
@@ -163,6 +163,44 @@
 compare equal to each other, but not equal to any instances that refer to an actual thread of execution. The comparison operators on
 __thread_id__ yield a total order for every non-equal thread ID.
 
+[heading Using native interfaces with Boost.Thread resources] 
+
+
+__thread__ class has members `native_handle_type` and `native_handle` providing access to the underlying native handle.  
+	 
+This native handle can be used to change for example the scheduling. 
+
+
+In general, it is not safe to use this handle with operations that can conflict with the ones provided by Boost.Thread. An example of bad usage could be detaching a thread directly as it will not change the internals of the __thread__ instance, so for example the joinable function will continue to return true, while the native thread is no more joinable. 
+
+  thread t(fct); 
+  thread::native_handle_type hnd=t.native_handle(); 
+  pthread_detach(hnd); 
+  assert(t.joinable()); 
+
+[heading Using Boost.Thread interfaces in a native thread] 
+ 
+
+Any thread of execution created using the native interface is called a native thread in this documentation. 
+
+The first example of a native thread of execution is the main thread.  
+
+The user can access to some synchronization functions related to the native current thread using the `boost::this_thread` `yield`, `sleep`, functions. 
+
+
+  int main() { 
+    // ... 
+    boost::this_thread::sleep(); 
+    // ... 
+  } 
+
+
+Of course all the synchronization facilities provided by Boost.Thread are also available on native threads. 
+
+The `boost::this_thread` interrupt related functions behave in a degraded mode when called from a thread created using the native interface, i.e. `boost::this_thread::interruption_enabled()` returns false. As consequence the use of `boost::this_thread::disable_interruption` and `boost::this_thread::restore_interruption` will do nothing and calls to `boost::this_thread::interrupt_point()` will be just ignored.  
+
+As the single way to interrupt a thread is through a __thread__ instance, `interruption_request()` wiil returns false for the native threads. 
+
 [section:thread Class `thread`]
 
     #include <boost/thread/thread.hpp>
@@ -675,7 +713,7 @@
 
 [endsect]
 
-[section:less_than_or_equal `operator>=`]
+[section:less_than_or_equal `operator<=`]
 
     bool operator<=(const id& y) const;