1//////////////////////////////////////////////////////////////////////////////
2//
3// (C) Copyright Ion Gaztanaga 2005-2012. Distributed under the Boost
4// Software License, Version 1.0. (See accompanying file
5// LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6//
7// See http://www.boost.org/libs/interprocess for documentation.
8//
9//////////////////////////////////////////////////////////////////////////////
10//
11// This interface is inspired by Howard Hinnant's lock proposal.
12// http://home.twcny.rr.com/hinnant/cpp_extensions/threads_move.html
13//
14//////////////////////////////////////////////////////////////////////////////
15
16#ifndef BOOST_INTERPROCESS_SCOPED_LOCK_HPP
17#define BOOST_INTERPROCESS_SCOPED_LOCK_HPP
18
19#ifndef BOOST_CONFIG_HPP
20# include <boost/config.hpp>
21#endif
22#
23#if defined(BOOST_HAS_PRAGMA_ONCE)
24# pragma once
25#endif
26
27#include <boost/interprocess/detail/config_begin.hpp>
28#include <boost/interprocess/detail/workaround.hpp>
29#include <boost/interprocess/interprocess_fwd.hpp>
30#include <boost/interprocess/sync/lock_options.hpp>
31#include <boost/interprocess/exceptions.hpp>
32#include <boost/interprocess/detail/mpl.hpp>
33#include <boost/interprocess/detail/type_traits.hpp>
34#include <boost/move/utility_core.hpp>
35#include <boost/interprocess/detail/simple_swap.hpp>
36
37//!\file
38//!Describes the scoped_lock class.
39
40namespace boost {
41namespace interprocess {
42
43
44//!scoped_lock is meant to carry out the tasks for locking, unlocking, try-locking
45//!and timed-locking (recursive or not) for the Mutex. The Mutex need not supply all
46//!of this functionality. If the client of scoped_lock<Mutex> does not use
47//!functionality which the Mutex does not supply, no harm is done. Mutex ownership
48//!transfer is supported through the syntax of move semantics. Ownership transfer
49//!is allowed both by construction and assignment. The scoped_lock does not support
50//!copy semantics. A compile time error results if copy construction or copy
51//!assignment is attempted. Mutex ownership can also be moved from an
52//!upgradable_lock and sharable_lock via constructor. In this role, scoped_lock
53//!shares the same functionality as a write_lock.
54template <class Mutex>
55class scoped_lock
56{
57 #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
58 private:
59 typedef scoped_lock<Mutex> this_type;
60 BOOST_MOVABLE_BUT_NOT_COPYABLE(scoped_lock)
61 typedef bool this_type::*unspecified_bool_type;
62 #endif //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
63 public:
64
65 typedef Mutex mutex_type;
66
67 //!Effects: Default constructs a scoped_lock.
68 //!Postconditions: owns() == false and mutex() == 0.
69 scoped_lock() BOOST_NOEXCEPT
70 : mp_mutex(0), m_locked(false)
71 {}
72
73 //!Effects: m.lock().
74 //!Postconditions: owns() == true and mutex() == &m.
75 //!Notes: The constructor will take ownership of the mutex. If another thread
76 //! already owns the mutex, this thread will block until the mutex is released.
77 //! Whether or not this constructor handles recursive locking depends upon the mutex.
78 explicit scoped_lock(mutex_type& m)
79 : mp_mutex(&m), m_locked(false)
80 { mp_mutex->lock(); m_locked = true; }
81
82 //!Postconditions: owns() == false, and mutex() == &m.
83 //!Notes: The constructor will not take ownership of the mutex. There is no effect
84 //! required on the referenced mutex.
85 scoped_lock(mutex_type& m, defer_lock_type)
86 : mp_mutex(&m), m_locked(false)
87 {}
88
89 //!Postconditions: owns() == true, and mutex() == &m.
90 //!Notes: The constructor will suppose that the mutex is already locked. There
91 //! is no effect required on the referenced mutex.
92 scoped_lock(mutex_type& m, accept_ownership_type)
93 : mp_mutex(&m), m_locked(true)
94 {}
95
96 //!Effects: m.try_lock().
97 //!Postconditions: mutex() == &m. owns() == the return value of the
98 //! m.try_lock() executed within the constructor.
99 //!Notes: The constructor will take ownership of the mutex if it can do
100 //! so without waiting. Whether or not this constructor handles recursive
101 //! locking depends upon the mutex. If the mutex_type does not support try_lock,
102 //! this constructor will fail at compile time if instantiated, but otherwise
103 //! have no effect.
104 scoped_lock(mutex_type& m, try_to_lock_type)
105 : mp_mutex(&m), m_locked(mp_mutex->try_lock())
106 {}
107
108 //!Effects: m.timed_lock(abs_time).
109 //!Postconditions: mutex() == &m. owns() == the return value of the
110 //! m.timed_lock(abs_time) executed within the constructor.
111 //!Notes: The constructor will take ownership of the mutex if it can do
112 //! it until abs_time is reached. Whether or not this constructor
113 //! handles recursive locking depends upon the mutex. If the mutex_type
114 //! does not support try_lock, this constructor will fail at compile
115 //! time if instantiated, but otherwise have no effect.
116 template<class TimePoint>
117 scoped_lock(mutex_type& m, const TimePoint& abs_time)
118 : mp_mutex(&m), m_locked(mp_mutex->timed_lock(abs_time))
119 {}
120
121 //!Postconditions: mutex() == the value scop.mutex() had before the
122 //! constructor executes. s1.mutex() == 0. owns() == the value of
123 //! scop.owns() before the constructor executes. scop.owns().
124 //!Notes: If the scop scoped_lock owns the mutex, ownership is moved
125 //! to thisscoped_lock with no blocking. If the scop scoped_lock does not
126 //! own the mutex, then neither will this scoped_lock. Only a moved
127 //! scoped_lock's will match this signature. An non-moved scoped_lock
128 //! can be moved with the expression: "boost::move(lock);". This
129 //! constructor does not alter the state of the mutex, only potentially
130 //! who owns it.
131 scoped_lock(BOOST_RV_REF(scoped_lock) scop) BOOST_NOEXCEPT
132 : mp_mutex(0), m_locked(scop.owns())
133 { mp_mutex = scop.release(); }
134
135 //!Effects: If upgr.owns() then calls unlock_upgradable_and_lock() on the
136 //! referenced mutex. upgr.release() is called.
137 //!Postconditions: mutex() == the value upgr.mutex() had before the construction.
138 //! upgr.mutex() == 0. owns() == upgr.owns() before the construction.
139 //! upgr.owns() == false after the construction.
140 //!Notes: If upgr is locked, this constructor will lock this scoped_lock while
141 //! unlocking upgr. If upgr is unlocked, then this scoped_lock will be
142 //! unlocked as well. Only a moved upgradable_lock's will match this
143 //! signature. An non-moved upgradable_lock can be moved with
144 //! the expression: "boost::move(lock);" This constructor may block if
145 //! other threads hold a sharable_lock on this mutex (sharable_lock's can
146 //! share ownership with an upgradable_lock).
147 template<class T>
148 explicit scoped_lock(BOOST_RV_REF(upgradable_lock<T>) upgr
149 , typename ipcdetail::enable_if< ipcdetail::is_same<T, Mutex> >::type * = 0)
150 : mp_mutex(0), m_locked(false)
151 {
152 upgradable_lock<mutex_type> &u_lock = upgr;
153 if(u_lock.owns()){
154 u_lock.mutex()->unlock_upgradable_and_lock();
155 m_locked = true;
156 }
157 mp_mutex = u_lock.release();
158 }
159
160 //!Effects: If upgr.owns() then calls try_unlock_upgradable_and_lock() on the
161 //!referenced mutex:
162 //! a)if try_unlock_upgradable_and_lock() returns true then mutex() obtains
163 //! the value from upgr.release() and owns() is set to true.
164 //! b)if try_unlock_upgradable_and_lock() returns false then upgr is
165 //! unaffected and this scoped_lock construction as the same effects as
166 //! a default construction.
167 //! c)Else upgr.owns() is false. mutex() obtains the value from upgr.release()
168 //! and owns() is set to false
169 //!Notes: This construction will not block. It will try to obtain mutex
170 //! ownership from upgr immediately, while changing the lock type from a
171 //! "read lock" to a "write lock". If the "read lock" isn't held in the
172 //! first place, the mutex merely changes type to an unlocked "write lock".
173 //! If the "read lock" is held, then mutex transfer occurs only if it can
174 //! do so in a non-blocking manner.
175 template<class T>
176 scoped_lock(BOOST_RV_REF(upgradable_lock<T>) upgr, try_to_lock_type
177 , typename ipcdetail::enable_if< ipcdetail::is_same<T, Mutex> >::type * = 0)
178 : mp_mutex(0), m_locked(false)
179 {
180 upgradable_lock<mutex_type> &u_lock = upgr;
181 if(u_lock.owns()){
182 if((m_locked = u_lock.mutex()->try_unlock_upgradable_and_lock()) == true){
183 mp_mutex = u_lock.release();
184 }
185 }
186 else{
187 u_lock.release();
188 }
189 }
190
191 //!Effects: If upgr.owns() then calls timed_unlock_upgradable_and_lock(abs_time)
192 //! on the referenced mutex:
193 //! a)if timed_unlock_upgradable_and_lock(abs_time) returns true then mutex()
194 //! obtains the value from upgr.release() and owns() is set to true.
195 //! b)if timed_unlock_upgradable_and_lock(abs_time) returns false then upgr
196 //! is unaffected and this scoped_lock construction as the same effects
197 //! as a default construction.
198 //! c)Else upgr.owns() is false. mutex() obtains the value from upgr.release()
199 //! and owns() is set to false
200 //!Notes: This construction will not block. It will try to obtain mutex ownership
201 //! from upgr immediately, while changing the lock type from a "read lock" to a
202 //! "write lock". If the "read lock" isn't held in the first place, the mutex
203 //! merely changes type to an unlocked "write lock". If the "read lock" is held,
204 //! then mutex transfer occurs only if it can do so in a non-blocking manner.
205 template<class T, class TimePoint>
206 scoped_lock(BOOST_RV_REF(upgradable_lock<T>) upgr, const TimePoint &abs_time
207 , typename ipcdetail::enable_if< ipcdetail::is_same<T, Mutex> >::type * = 0)
208 : mp_mutex(0), m_locked(false)
209 {
210 upgradable_lock<mutex_type> &u_lock = upgr;
211 if(u_lock.owns()){
212 if((m_locked = u_lock.mutex()->timed_unlock_upgradable_and_lock(abs_time)) == true){
213 mp_mutex = u_lock.release();
214 }
215 }
216 else{
217 u_lock.release();
218 }
219 }
220
221 //!Effects: If shar.owns() then calls try_unlock_sharable_and_lock() on the
222 //!referenced mutex.
223 //! a)if try_unlock_sharable_and_lock() returns true then mutex() obtains
224 //! the value from shar.release() and owns() is set to true.
225 //! b)if try_unlock_sharable_and_lock() returns false then shar is
226 //! unaffected and this scoped_lock construction has the same
227 //! effects as a default construction.
228 //! c)Else shar.owns() is false. mutex() obtains the value from
229 //! shar.release() and owns() is set to false
230 //!Notes: This construction will not block. It will try to obtain mutex
231 //! ownership from shar immediately, while changing the lock type from a
232 //! "read lock" to a "write lock". If the "read lock" isn't held in the
233 //! first place, the mutex merely changes type to an unlocked "write lock".
234 //! If the "read lock" is held, then mutex transfer occurs only if it can
235 //! do so in a non-blocking manner.
236 template<class T>
237 scoped_lock(BOOST_RV_REF(sharable_lock<T>) shar, try_to_lock_type
238 , typename ipcdetail::enable_if< ipcdetail::is_same<T, Mutex> >::type * = 0)
239 : mp_mutex(0), m_locked(false)
240 {
241 sharable_lock<mutex_type> &s_lock = shar;
242 if(s_lock.owns()){
243 if((m_locked = s_lock.mutex()->try_unlock_sharable_and_lock()) == true){
244 mp_mutex = s_lock.release();
245 }
246 }
247 else{
248 s_lock.release();
249 }
250 }
251
252 //!Effects: if (owns()) mp_mutex->unlock().
253 //!Notes: The destructor behavior ensures that the mutex lock is not leaked.*/
254 ~scoped_lock()
255 {
256 BOOST_TRY{ if(m_locked && mp_mutex) mp_mutex->unlock(); }
257 BOOST_CATCH(...){} BOOST_CATCH_END
258 }
259
260 //!Effects: If owns() before the call, then unlock() is called on mutex().
261 //! *this gets the state of scop and scop gets set to a default constructed state.
262 //!Notes: With a recursive mutex it is possible that both this and scop own
263 //! the same mutex before the assignment. In this case, this will own the
264 //! mutex after the assignment (and scop will not), but the mutex's lock
265 //! count will be decremented by one.
266 scoped_lock &operator=(BOOST_RV_REF(scoped_lock) scop)
267 {
268 if(this->owns())
269 this->unlock();
270 m_locked = scop.owns();
271 mp_mutex = scop.release();
272 return *this;
273 }
274
275 //!Effects: If mutex() == 0 or if already locked, throws a lock_exception()
276 //! exception. Calls lock() on the referenced mutex.
277 //!Postconditions: owns() == true.
278 //!Notes: The scoped_lock changes from a state of not owning the mutex, to
279 //! owning the mutex, blocking if necessary.
280 void lock()
281 {
282 if(!mp_mutex || m_locked)
283 throw lock_exception();
284 mp_mutex->lock();
285 m_locked = true;
286 }
287
288 //!Effects: If mutex() == 0 or if already locked, throws a lock_exception()
289 //! exception. Calls try_lock() on the referenced mutex.
290 //!Postconditions: owns() == the value returned from mutex()->try_lock().
291 //!Notes: The scoped_lock changes from a state of not owning the mutex, to
292 //! owning the mutex, but only if blocking was not required. If the
293 //! mutex_type does not support try_lock(), this function will fail at
294 //! compile time if instantiated, but otherwise have no effect.*/
295 bool try_lock()
296 {
297 if(!mp_mutex || m_locked)
298 throw lock_exception();
299 m_locked = mp_mutex->try_lock();
300 return m_locked;
301 }
302
303 //!Effects: If mutex() == 0 or if already locked, throws a lock_exception()
304 //! exception. Calls timed_lock(abs_time) on the referenced mutex.
305 //!Postconditions: owns() == the value returned from mutex()-> timed_lock(abs_time).
306 //!Notes: The scoped_lock changes from a state of not owning the mutex, to
307 //! owning the mutex, but only if it can obtain ownership by the specified
308 //! time. If the mutex_type does not support timed_lock (), this function
309 //! will fail at compile time if instantiated, but otherwise have no effect.*/
310 template<class TimePoint>
311 bool timed_lock(const TimePoint& abs_time)
312 {
313 if(!mp_mutex || m_locked)
314 throw lock_exception();
315 m_locked = mp_mutex->timed_lock(abs_time);
316 return m_locked;
317 }
318
319 //!Effects: If mutex() == 0 or if already locked, throws a lock_exception()
320 //! exception. Calls try_lock_until(abs_time) on the referenced mutex.
321 //!Postconditions: owns() == the value returned from mutex()-> timed_lock(abs_time).
322 //!Notes: The scoped_lock changes from a state of not owning the mutex, to
323 //! owning the mutex, but only if it can obtain ownership by the specified
324 //! time. If the mutex_type does not support timed_lock (), this function
325 //! will fail at compile time if instantiated, but otherwise have no effect.*/
326 template<class TimePoint>
327 bool try_lock_until(const TimePoint& abs_time)
328 {
329 if(!mp_mutex || m_locked)
330 throw lock_exception();
331 m_locked = mp_mutex->try_lock_until(abs_time);
332 return m_locked;
333 }
334
335 //!Effects: If mutex() == 0 or if already locked, throws a lock_exception()
336 //! exception. Calls try_lock_until(abs_time) on the referenced mutex.
337 //!Postconditions: owns() == the value returned from mutex()-> timed_lock(abs_time).
338 //!Notes: The scoped_lock changes from a state of not owning the mutex, to
339 //! owning the mutex, but only if it can obtain ownership by the specified
340 //! time. If the mutex_type does not support timed_lock (), this function
341 //! will fail at compile time if instantiated, but otherwise have no effect.*/
342 template<class Duration>
343 bool try_lock_for(const Duration& dur)
344 {
345 if(!mp_mutex || m_locked)
346 throw lock_exception();
347 m_locked = mp_mutex->try_lock_for(dur);
348 return m_locked;
349 }
350
351 //!Effects: If mutex() == 0 or if not locked, throws a lock_exception()
352 //! exception. Calls unlock() on the referenced mutex.
353 //!Postconditions: owns() == false.
354 //!Notes: The scoped_lock changes from a state of owning the mutex, to not
355 //! owning the mutex.*/
356 void unlock()
357 {
358 if(!mp_mutex || !m_locked)
359 throw lock_exception();
360 mp_mutex->unlock();
361 m_locked = false;
362 }
363
364 //!Effects: Returns true if this scoped_lock has acquired
365 //!the referenced mutex.
366 bool owns() const BOOST_NOEXCEPT
367 { return m_locked && mp_mutex; }
368
369 //!Conversion to bool.
370 //!Returns owns().
371 operator unspecified_bool_type() const BOOST_NOEXCEPT
372 { return m_locked? &this_type::m_locked : 0; }
373
374 //!Effects: Returns a pointer to the referenced mutex, or 0 if
375 //!there is no mutex to reference.
376 mutex_type* mutex() const BOOST_NOEXCEPT
377 { return mp_mutex; }
378
379 //!Effects: Returns a pointer to the referenced mutex, or 0 if there is no
380 //! mutex to reference.
381 //!Postconditions: mutex() == 0 and owns() == false.
382 mutex_type* release() BOOST_NOEXCEPT
383 {
384 mutex_type *mut = mp_mutex;
385 mp_mutex = 0;
386 m_locked = false;
387 return mut;
388 }
389
390 //!Effects: Swaps state with moved lock.
391 //!Throws: Nothing.
392 void swap( scoped_lock<mutex_type> &other) BOOST_NOEXCEPT
393 {
394 (simple_swap)(mp_mutex, other.mp_mutex);
395 (simple_swap)(x&: m_locked, y&: other.m_locked);
396 }
397
398 #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
399 private:
400 mutex_type *mp_mutex;
401 bool m_locked;
402 #endif //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
403};
404
405} // namespace interprocess
406} // namespace boost
407
408#include <boost/interprocess/detail/config_end.hpp>
409
410#endif // BOOST_INTERPROCESS_SCOPED_LOCK_HPP
411

source code of boost/libs/interprocess/include/boost/interprocess/sync/scoped_lock.hpp