1[/ 2 / Copyright (c) 2013 Vicente J. Botet Escriba 3 / 4 / Distributed under the Boost Software License, Version 1.0. (See accompanying 5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 /] 7 8 9[section:ext_locked_streams Externally Locked Streams - EXPERIMENTAL] 10 11[warning These features are experimental and subject to change in future versions. There are not too much tests yet, so it is possible that you can find out some trivial bugs :(] 12 13[note These features are based on the [@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2013/n3535.html [*N3535 - C++ Streams Mutex]] C++1y proposal, even if the library proposes al alternative interface.] 14 15[section:tutorial Tutorial] 16 17[endsect] [/tutorial] 18 19[/////////////////////] 20[section:ref Reference] 21 22 #include <boost/thread/externally_locked_stream.hpp> 23 namespace boost 24 { 25 template <typename Stream, typename RecursiveMutex=recursive_mutex> 26 class externally_locked_stream; 27 template <class Stream, typename RecursiveMutex=recursive_mutex> 28 class stream_guard; 29 template <typename Stream, typename RecursiveMutex> 30 struct is_strict_lock_sur_parole<stream_guard<Stream, RecursiveMutex> > : true_type {}; 31 32 // Stream-like operators 33 template <typename Stream, typename RecursiveMutex, typename T> 34 const stream_guard<Stream, RecursiveMutex>& operator<<(const stream_guard<Stream, RecursiveMutex>& lck, T arg); 35 template <typename Stream, typename RecursiveMutex> 36 const stream_guard<Stream, RecursiveMutex>& 37 operator<<(const stream_guard<Stream, RecursiveMutex>& lck, Stream& (*arg)(Stream&)); 38 template <typename Stream, typename RecursiveMutex, typename T> 39 const stream_guard<Stream, RecursiveMutex>& 40 operator>>(const stream_guard<Stream, RecursiveMutex>& lck, T& arg); 41 template <typename Stream, typename RecursiveMutex, typename T> 42 stream_guard<Stream, RecursiveMutex> 43 operator<<(externally_locked_stream<Stream, RecursiveMutex>& mtx, T arg); 44 template <typename Stream, typename RecursiveMutex> 45 stream_guard<Stream, RecursiveMutex> 46 operator<<(externally_locked_stream<Stream, RecursiveMutex>& mtx, Stream& (*arg)(Stream&)); 47 template <typename Stream, typename RecursiveMutex, typename T> 48 stream_guard<Stream, RecursiveMutex> 49 operator>>(externally_locked_stream<Stream, RecursiveMutex>& mtx, T& arg); 50 } 51 52[/////////////////////////////////////////] 53[section:stream_guard Class `stream_guard`] 54 55 #include <boost/thread/externally_locked_stream.hpp> 56 namespace boost 57 { 58 template <class Stream, typename RecursiveMutex=recursive_mutex> 59 class stream_guard 60 { 61 public: 62 typedef typename externally_locked_stream<Stream, RecursiveMutex>::mutex_type mutex_type; 63 64 // Constructors, Assignment and Destructors 65 stream_guard(stream_guard const&) = delete; 66 stream_guard& operator=(stream_guard const&) = delete; 67 stream_guard(externally_locked_stream<Stream, RecursiveMutex>& mtx); 68 stream_guard(externally_locked_stream<Stream, RecursiveMutex>& mtx, adopt_lock_t); 69 stream_guard(stream_guard&& rhs); 70 ~stream_guard(); 71 72 // Observers 73 bool owns_lock(mutex_type const* l) const BOOST_NOEXCEPT; 74 Stream& get() const; 75 Stream& bypass() const; 76 77 }; 78 } 79 80`stream_guard` is a model of __StrictLock. 81 82[//////////////////////////////////////////////////] 83[section:constructor `stream_guard(mutex_type & m)`] 84 85[variablelist 86 87[[Effects:] [Stores a reference to `m`. Invokes [lock_ref_link `m.lock()`].]] 88 89[[Throws:] [Any exception thrown by the call to [lock_ref_link `m.lock()`].]] 90 91] 92 93[endsect] 94[////////////////////////////////////////////////////////////////////////////] 95[section:constructor_adopt `stream_guard(mutex_type & m,boost::adopt_lock_t)`] 96 97[variablelist 98 99[[Precondition:] [The current thread owns a lock on `m` equivalent to one 100obtained by a call to [lock_ref_link `m.lock()`].]] 101 102[[Effects:] [Stores a reference to `m`. Takes ownership of the lock state of 103`m`.]] 104 105[[Throws:] [Nothing.]] 106 107] 108 109[endsect] 110[//////////////////////////////////////////////////////////] 111[section:move_constructor `stream_guard(stream_guard && m)`] 112 113 114[variablelist 115 116[[Effects:] [Stores a reference to `m`. Invokes [lock_ref_link `m.lock()`].]] 117 118[[Throws:] [Any exception thrown by the call to [lock_ref_link `m.lock()`].]] 119 120] 121 122[endsect] 123[////////////////////////////////////] 124[section:destructor `~stream_guard()`] 125 126[variablelist 127 128[[Effects:] [Invokes [unlock_ref_link `m.unlock()`] on the __lockable_concept_type__ 129object passed to the constructor.]] 130 131[[Throws:] [Nothing.]] 132 133] 134 135[endsect] 136 137[endsect] 138[//////////////////////////////////////////////////////////////////] 139[section:externally_locked_stream Class `externally_locked_stream `] 140 141 #include <boost/thread/externally_locked_stream.hpp> 142 namespace boost 143 { 144 template <typename Stream, typename RecursiveMutex> 145 class externally_locked_stream: public externally_locked<Stream&, RecursiveMutex> 146 { 147 public: 148 // Constructors, Assignment and Destructors 149 externally_locked_stream(externally_locked_stream const&) = delete; 150 externally_locked_stream& operator=(externally_locked_stream const&) = delete; 151 externally_locked_stream(Stream& stream, RecursiveMutex& mtx); 152 153 // Modifiers 154 stream_guard<Stream, RecursiveMutex> hold(); 155 156 }; 157 } 158 159`externally_locked_stream` cloaks a reference to a stream of type `Stream`, and actually 160provides full access to that object through the `get` member functions, provided you 161pass a reference to a strict lock object. 162 163 164[////////////////////////////////////////////////////////////////////////] 165[section:constructor `externally_locked_stream(Stream&, RecursiveMutex&)`] 166 167[variablelist 168 169[[Effects:] [Constructs an externally locked object storing the cloaked reference object and its locking mutex.]] 170 171] 172 173[endsect] 174 175[/////////////////////] 176[section:hold `hold()`] 177 178[variablelist 179 180[[Returns:] [A stream_guard which will hold the mutex during it lifetime .]] 181 182] 183 184[endsect] 185 186 187 188[endsect] 189 190 191[endsect] [/ref] 192 193[endsect] [/Externally Locked Streams] 194