[Boost-commit] svn:boost r84109 - in trunk: boost/thread libs/thread/doc libs/thread/example

Subject: [Boost-commit] svn:boost r84109 - in trunk: boost/thread libs/thread/doc libs/thread/example
From: vicente.botet_at_[hidden]
Date: 2013-05-02 11:32:30

Author: viboes
Date: 2013-05-02 11:32:29 EDT (Thu, 02 May 2013)
New Revision: 84109
URL: http://svn.boost.org/trac/boost/changeset/84109

Log:
Thread: update the externally_locked_stream interface.
Text files modified: 
   trunk/boost/thread/externally_locked_stream.hpp |    31 ++++---                                 
   trunk/boost/thread/strict_lock.hpp              |    23 ++++-                                   
   trunk/libs/thread/doc/compliance.qbk            |   159 ++++++++++++++++++++++++++++++++++++--- 
   trunk/libs/thread/doc/sync_queues_ref.qbk       |     4                                         
   trunk/libs/thread/doc/sync_streams.qbk          |    89 +++++++++++++++++++++-                  
   trunk/libs/thread/example/not_interleaved.cpp   |     4                                         
   6 files changed, 269 insertions(+), 41 deletions(-)

Modified: trunk/boost/thread/externally_locked_stream.hpp
==============================================================================
--- trunk/boost/thread/externally_locked_stream.hpp	(original)
+++ trunk/boost/thread/externally_locked_stream.hpp	2013-05-02 11:32:29 EDT (Thu, 02 May 2013)
@@ -21,12 +21,6 @@
 namespace boost
 {
 
-  //  inline static recursive_mutex& terminal_mutex()
-  //  {
-  //    static recursive_mutex mtx;
-  //    return mtx;
-  //  }
-
   template <typename Stream, typename RecursiveMutex=recursive_mutex>
   class externally_locked_stream;
 
@@ -51,7 +45,7 @@
     {
     }
 
-    stream_guard(BOOST_THREAD_RV_REF(stream_guard) rhs)
+    stream_guard(BOOST_THREAD_RV_REF(stream_guard) rhs) BOOST_NOEXCEPT
     : mtx_(rhs.mtx_)
     {
       rhs.mtx_= 0;
@@ -62,15 +56,24 @@
       if (mtx_ != 0) mtx_->unlock();
     }
 
-    bool owns_lock(mutex_type const* l) const BOOST_NOEXCEPT
+    bool owns_lock(const mutex_type * l) const BOOST_NOEXCEPT
     {
       return l == mtx_->mutex();
     }
 
+    /**
+     * @Requires mtx_
+     */
     Stream& get() const
     {
+      BOOST_THREAD_ASSERT_PRECONDITION(  mtx_, lock_error() );
       return mtx_->get(*this);
     }
+    Stream& bypass() const
+    {
+      return get();
+    }
+
 
   private:
     externally_locked_stream<Stream, RecursiveMutex>* mtx_;
@@ -98,22 +101,20 @@
     /**
      * Effects: Constructs an externally locked object storing the cloaked reference object.
      */
-    externally_locked_stream(Stream& stream, RecursiveMutex& mtx) :
+    externally_locked_stream(Stream& stream, RecursiveMutex& mtx) BOOST_NOEXCEPT :
       base_type(stream, mtx)
     {
     }
 
-    stream_guard<Stream, RecursiveMutex> hold()
+    stream_guard<Stream, RecursiveMutex> hold() BOOST_NOEXCEPT
     {
       return stream_guard<Stream, RecursiveMutex> (*this);
     }
-
-    Stream& hold(strict_lock<RecursiveMutex>& lk)
+    Stream& bypass() const
     {
-      return this->get(lk);
+      stream_guard<Stream, RecursiveMutex> lk(*this);
+      return get(lk);
     }
-
-
   };
   //]
 

Modified: trunk/boost/thread/strict_lock.hpp
==============================================================================
--- trunk/boost/thread/strict_lock.hpp	(original)
+++ trunk/boost/thread/strict_lock.hpp	2013-05-02 11:32:29 EDT (Thu, 02 May 2013)
@@ -73,7 +73,6 @@
 
 
     // observers
-  private:
 
     /**
      * @return the owned mutex.
@@ -82,12 +81,19 @@
     {
       return &mtx_;
     }
-  public:
+
+    /**
+     * @return whether this lock is locking a mutex.
+     */
+    bool owns_lock() const BOOST_NOEXCEPT
+    {
+      return true;
+    }
 
     /**
      * @return whether this lock is locking that mutex.
      */
-    bool owns_lock(mutex_type const* l) const BOOST_NOEXCEPT
+    bool owns_lock(const mutex_type* l) const BOOST_NOEXCEPT
     {
       return l == mutex();
     } /*< strict locks specific function >*/
@@ -173,7 +179,6 @@
     }
 
     // observers
-private:
     /**
      * return @c the owned mutex.
      */
@@ -181,7 +186,15 @@
     {
       return tmp_lk_.mutex();
     }
-public:
+
+    /**
+     * @return whether this lock is locking a mutex.
+     */
+    bool owns_lock() const BOOST_NOEXCEPT
+    {
+      return true;
+    }
+
     /**
      * @return whether if this lock is locking that mutex.
      */

Modified: trunk/libs/thread/doc/compliance.qbk
==============================================================================
--- trunk/libs/thread/doc/compliance.qbk	(original)
+++ trunk/libs/thread/doc/compliance.qbk	2013-05-02 11:32:29 EDT (Thu, 02 May 2013)
@@ -9,6 +9,8 @@
 
 [section:cpp11 C++11 standard Thread library]
 
+[note [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3376.html C++11 standard]]
+
 
 [table C++11 standard Conformance
     [[Section]        [Description]  [Status] [Comments] [Ticket]]
@@ -86,24 +88,155 @@
 [endsect]
 
 
-[section:shared Shared Locking extensions]
+[section:cxx14 C++14 standard Thread library - accepted changes]
+
+[note [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3485.html C++14 on-going standard]]
+
+
+[table [@http://isocpp.org/files/papers/N3659.html N3659 Shared locking in C++ revision 2] Conformance
+    [[Section]  [Description]  [Status] [Comments]]
+    [[30.4.1.4]      [Shared Lockables Types]  [Yes] [ - ]]
+    [[30.4.1.4.1]      [shared_mutex class]  [Yes] [ - ]]
+    [[30.4.2.3]      [Class template shared_lock]  [Yes] [-]]
+]
+
+[endsect]
+
+[section:cxx1y C++1y TS Concurrency - On going proposals]
+
+[section:latch C++ Latches and Barriers]
+
+[note [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3600.html N3659 C++ Latches and Barriers]]
+
+[table C++ Latches and Barriers Conformance
+    [[Section]  [Description]  [Status] [Comments]]
+    [[X.1]      [Class latch]  [Partial] [ A new class latch has been added. The interface is a super set of the one of the proposal, taking some of the functions of the class barrier.]]
+    [[X.2]      [Class barrier]  [No] [ Even if Boost.Thread has a class boost:barrier it doesn't provides the same kind of services. There is an experimental completion_latch that could be used instead. ]]
+]
+
+[endsect]
+[section:queue C++ Concurrent Queues]
+
+[note [@ http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3533.html N3533 C++ Concurrent Queues]]
+
+[table C++ Concurrent Queues Conformance
+    [[Section]  [Description]  [Status] [Comments]]
+    [[X.1]      [Conceptual interface]  [Partial] [ The interface provided has some differences respect to this proposal. All the functions having a queue_op_status are not provided. No lock-free concrete classes ]]
+    [[X.1.1]      [Basic Operations]  [Partial] [ - ]]
+    [[X.1.1.1]      [push]  [yes] [ - ]]
+    [[X.1.1.2]      [value_pop]  [no] [ renamed pull with two flavors + a ptr_pull that returns a sharted_ptr<>. ]]
+    [[X.1.2]      [Non-waiting operations]  [] [ - ]]
+    [[X.1.2.1]      [try_push]  [Partial] [ return bool instead ]]
+    [[X.1.2.2]      [try_pop]  [Partial] [ renamed try_pull, returns null ]]
+    [[X.1.3]      [Non-blocking operations]  [] [ - ]]
+    [[X.1.3.1]      [nonblocking_push]  [Partial] [ renamed try_push(no_block,  ]]
+    [[X.1.3.2]      [nonblocking_pop]  [Partial] [ renamed try_pop(no_block,  ]]
+    [[X.1.4]      [Push-front operations]  [No] [ - ]]
+    [[X.1.5]      [Closed queues]  [Partial] [ - ]]
+    [[X.1.5.1]      [close]  [Yes] [ - ]]
+    [[X.1.5.2]      [is_closed]  [Yes] [ - ]]
+    [[X.1.5.3]      [wait_push]  [Partial] [ - ]]
+    [[X.1.5.4]      [wait_pop]  [Partial] [ - ]]
+    [[X.1.5.5]      [wait_push_front]  [no] [ - ]]
+    [[X.1.5.6]      [wait_pop]  [Partial] [ - ]]
+    [[X.1.5.6]      [open]  [no] [ - ]]
+    [[X.1.6]      [Empty and Full Queues]  [Yes] [ - ]]
+    [[X.1.6.1]      [is_empty]  [Yes] [ - ]]
+    [[X.1.6.2]      [is_full]  [Yes] [ Added capacity ]]
+    [[X.1.7]      [Queue Names]  [No] [ Not considere a must for the time been. ]]
+    [[X.1.8]      [Element Type Requirements]  [Yes?] [ - ]]
+    [[X.1.9]      [Exception Handling]  [Yes?] [ - ]]
+    [[X.1.10]      [Queue Ordering]  [Yes?] [ - ]]
+    [[X.1.11]      [Lock-Free Implementations]  [No] [ waiting to stabilize the lock-based interface. Will use Boost.LockFree once it is Move aware. ]]
+    [[X.2]      [Concrete queues]  [Partial] [  ]]
+    [[X.2.1]      [Locking Buffer Queue]  [Partial] [ classes sync_queue and a sync_bounded_queue. ]]
+    [[X.2.1]      [Lock-Free Buffer Queue]  [No] [  ]]
+    [[X.3]      [Additional Conceptual Tools]  [No] [  ]]
+    [[X.3.1]      [Fronts and Backs]  [No] [  ]]
+    [[X.3.2]      [Streaming Iterators]  [No] [  ]]
+    [[X.3.3]      [Storage Iterators]  [No] [  ]]
+    [[X.3.4]      [Binary Interfaces]  [No] [  ]]
+    [[X.3.4]      [Managed Indirection]  [No] [  ]]
+]
+[endsect]
+
+
+[section:executors Asynchronous Executors]
+
+While Boost.Thread implementation of executors would not use dynamic polymorphism, it is worth comparing with the current trend on the standard.
+
+[note [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3378.pdf N3378 A preliminary proposal for work executors]]
+
+
+[table Asynchronous Executors
+    [[Section]  [Description]  [Status] [Comments]]
+    [[30.X.1]      [Class executor]  [No] [ - ]]
+    [[30.X.1.1]      [add]  [No] [ renamed with a function template submit   ]]
+    [[30.X.1.1]      [num_of_pendin_closures]  [??] [    ]]
+    [[30.X.2]      [Class sceduled_executor]  [No] [ - ]]
+    [[30.X.2.1]      [add_at]  [No] [ renamed with a function template submit_at   ]]
+    [[30.X.2.2]      [add_after]  [No] [ renamed with a function template submit_after   ]]
+    [[30.X.3]      [Executor utilities functions]  [No] [ - ]]
+    [[30.X.3.1]      [default_executor]  [No] [ - ]]
+    [[30.X.3.2]      [set_default_executor]  [No] [ - ]]
+    [[30.X.3.3]      [singleton_inline_executor]  [No] [ - ]]
+    [[30.X.4]      [Concrete executor classes]  [No] [ - ]]
+    [[30.X.4.1]      [loop_executor]  [No] [ - ]]
+    [[30.X.4.1]      [serial_executor]  [No] [ - ]]
+    [[30.X.4.1]      [thread_pool]  [No] [ #8513 ]]
+]
+
+[endsect]
+
+
+[section:async A Standardized Representation of Asynchronous Operations]
+
+[note [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3558.pdf N3558 A Standardized Representation of Asynchronous Operations]]
+
+[table A Standardized Representation of Asynchronous Operations Conformance
+    [[Section]  [Description]  [Status] [Comments]]
+    [[30.6.6]      [Class template future]  [Partial] [ - ]]
+    [[30.6.6.1]      [then]  [Partial] [ executor interface missing #8516  ]]
+    [[30.6.6.2]      [unwrap]  [No] [ #XXXX  ]]
+    [[30.6.6.3]      [ready]  [yes] [ is_ready  ]]
+    [[30.6.7]      [Class template shared_future]  [Partial] [ - ]]
+    [[30.6.7.1]      [then]  [No] [ #8515 ]]
+    [[30.6.7.2]      [unwrap]  [No] [ #XXXX ]]
+    [[30.6.7.3]      [ready]  [Yes] [ is_ready  ]]
+    [[30.6.X]      [Function template when_any]  [No] [ #7446  ]]
+    [[30.6.X]      [Function template when_all]  [No] [ #7447  ]]
+    [[30.6.X]      [Function template make_ready_future]  [Yes] [ - ]]
+    [[30.6.8]      [Function template async ]  [No] [ executor interface missing #7448    ]]
+]
+
+[endsect]
+
+[section:stream_mutex	C++ Stream Mutexes]
+
+While Boost.Thread implementation of stream mutexes differ in the approach, it is worth comparing with the current trend on the standard.
+
+[note [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3535.html N3535 - C++ Stream Mutexes]]
 
-[table Howard's Shared Locking Proposal Conformance
+[table C++ C++ Stream MutexesConformance
     [[Section]  [Description]  [Status] [Comments]]
-    [[X]        [Shared Locking]  [Yes] [Needs `BOOST_THREAD_PROVIDES_SHARED_MUTEX_UPWARDS_CONVERSION]]
-    [[X.1]      [Shared Lockables Concepts]  [Yes] [ - ]]
-    [[X.1.1]      [SharedLockable concept]  [Yes] [ - ]]
-    [[X.1.2]      [UpgradeLockable concept]  [Yes] [ - ]]
-    [[X.2]      [Shared Mutex Types]  [Yes] [ - ]]
-    [[X.2.1]      [shared_mutex class]  [Yes] [ - ]]
-    [[X.2.2]      [upgrade_mutex class]  [Yes] [ - ]]
-    [[X.3]      [Locks]  [Yes] [-]]
-    [[X.3.1]      [unique_lock class adaptations]  [Yes] [-]]
-    [[X.3.2]      [shared_lock class]  [Yes] [ - ]]
-    [[X.3.3]      [upgrade_lock class]  [Yes] [-]]
+    [[X.1]      [Class template stream_mutex]  [Partial] [ externally_locked_stream<> ]]
+    [[X.2.1]      [constructor]  [Partial] [ externally_locked_stream needs a mutex in addition as argumement. ]]
+    [[X.2.2]      [lock]  [yes] [ - ]]
+    [[X.2.3]      [unlock]  [yes] [ - ]]
+    [[X.2.4]      [try_lock]  [yes] [ - ]]
+    [[X.2.5]      [hold]  [Yes] [ - ]]
+    [[X.2.6]      [bypass]  [Yes] [ - ]]
+    [[X.2]      [Class template stream_guard]  [Yes] [ - ]]
+    [[X.2.1]      [stream_guard]  [Yes] [ - ]]
+    [[X.2.2]      [~stream_guard]  [Yes] [ - ]]
+    [[X.2.3]      [bypass]  [Yes] [ - ]]
+    [[X.3]      [Stream Operators]  [Yes] [.]]
+    [[X.4]      [Predefined Objects]  [No] [.]]
 ]
 
 [endsect]
 
 
 [endsect]
+
+[endsect]

Modified: trunk/libs/thread/doc/sync_queues_ref.qbk
==============================================================================
--- trunk/libs/thread/doc/sync_queues_ref.qbk	(original)
+++ trunk/libs/thread/doc/sync_queues_ref.qbk	2013-05-02 11:32:29 EDT (Thu, 02 May 2013)
@@ -381,7 +381,7 @@
 
 [endsect]
 
-[section:sync_bounded_queue Class `sync_bounded_queue<>`]
+[section:sync_bounded_queue Class template `sync_bounded_queue<>`]
 
   #include <boost/thread/sync_bounded_queue.hpp>
   namespace boost
@@ -470,7 +470,7 @@
     sync_queue<ValueType>& operator>>(sync_queue<ValueType>& sbq, ValueType &elem);
   }
 
-[section:sync_queue Class `sync_queue<>`]
+[section:sync_queue Class template `sync_queue<>`]
 
   #include <boost/thread/sync_queue.hpp>
 

Modified: trunk/libs/thread/doc/sync_streams.qbk
==============================================================================
--- trunk/libs/thread/doc/sync_streams.qbk	(original)
+++ trunk/libs/thread/doc/sync_streams.qbk	2013-05-02 11:32:29 EDT (Thu, 02 May 2013)
@@ -65,15 +65,76 @@
       stream_guard& operator=(stream_guard const&) = delete;
       stream_guard(externally_locked_stream<Stream, RecursiveMutex>& mtx);
       stream_guard(externally_locked_stream<Stream, RecursiveMutex>& mtx, adopt_lock_t);
-      stream_guard(BOOST_THREAD_RV_REF(stream_guard) rhs);
+      stream_guard(stream_guard&& rhs);
       ~stream_guard();
 
       // Observers  
       bool owns_lock(mutex_type const* l) const BOOST_NOEXCEPT;
       Stream& get() const;
+      Stream& bypass() const;
+
     };
   }
 
+`stream_guard` is a model of __StrictLock.
+
+[section:constructor `stream_guard(mutex_type & 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:constructor_adopt `stream_guard(mutex_type & m,boost::adopt_lock_t)`]
+
+[variablelist
+
+[[Precondition:] [The current thread owns a lock on `m` equivalent to one
+obtained by a call to [lock_ref_link `m.lock()`].]]
+
+[[Effects:] [Stores a reference to `m`. Takes ownership of the lock state of
+`m`.]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+
+
+[section:move_constructor `stream_guard(stream_guard && 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 `~stream_guard()`]
+
+[variablelist
+
+[[Effects:] [Invokes [unlock_ref_link `m.unlock()`] on the __lockable_concept_type__
+object passed to the constructor.]]
+
+[[Throws:] [Nothing.]]
+
+]
+
+[endsect]
+
+
 [endsect]
 [section:externally_locked_stream Class `externally_locked_stream `]
 
@@ -87,12 +148,12 @@
       // Constructors, Assignment and Destructors
       externally_locked_stream(externally_locked_stream const&) = delete;
       externally_locked_stream& operator=(externally_locked_stream const&) = delete;
-      // Effects: Constructs an externally locked object storing the cloaked reference object.
       externally_locked_stream(Stream& stream, RecursiveMutex& mtx);
   
-      // Observers  
+      // Modifiers  
       stream_guard<Stream, RecursiveMutex> hold();
-      Stream& hold(strict_lock<RecursiveMutex>& lk);
+      Stream& bypass() const;
+
     };
   }
 
@@ -101,6 +162,26 @@
 pass a reference to a strict lock object.
 
 
+[section:constructor `externally_locked_stream(Stream&, RecursiveMutex&)`]
+
+[variablelist
+
+[[Effects:] [Constructs an externally locked object storing the cloaked reference object and its locking mutex.]]
+
+]
+
+[endsect]
+
+[section:hold `hold()`]
+
+[variablelist
+
+[[Returns:] [A stream_guard which will hold the mutex during it lifetime .]]
+
+]
+
+[endsect]
+
 [endsect]
 
 

Modified: trunk/libs/thread/example/not_interleaved.cpp
==============================================================================
--- trunk/libs/thread/example/not_interleaved.cpp	(original)
+++ trunk/libs/thread/example/not_interleaved.cpp	2013-05-02 11:32:29 EDT (Thu, 02 May 2013)
@@ -50,8 +50,8 @@
   std::string nm;
   {
     strict_lock<recursive_mutex> lk(terminal_mutex);
-    std::ostream & gcout = mcout.hold(lk);
-    //std::istream & gcin = mcin.hold(lk);
+    std::ostream & gcout = mcout.get(lk);
+    //std::istream & gcin = mcin.get(lk);
     gcout << "Enter name: ";
     //gcin >> nm;
   }