]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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/posix_time_types_wrk.hpp> | |
36 | #include <boost/interprocess/detail/simple_swap.hpp> | |
37 | ||
38 | //!\file | |
39 | //!Describes the scoped_lock class. | |
40 | ||
41 | namespace boost { | |
42 | namespace interprocess { | |
43 | ||
44 | ||
45 | //!scoped_lock is meant to carry out the tasks for locking, unlocking, try-locking | |
46 | //!and timed-locking (recursive or not) for the Mutex. The Mutex need not supply all | |
47 | //!of this functionality. If the client of scoped_lock<Mutex> does not use | |
48 | //!functionality which the Mutex does not supply, no harm is done. Mutex ownership | |
49 | //!transfer is supported through the syntax of move semantics. Ownership transfer | |
50 | //!is allowed both by construction and assignment. The scoped_lock does not support | |
51 | //!copy semantics. A compile time error results if copy construction or copy | |
52 | //!assignment is attempted. Mutex ownership can also be moved from an | |
53 | //!upgradable_lock and sharable_lock via constructor. In this role, scoped_lock | |
54 | //!shares the same functionality as a write_lock. | |
55 | template <class Mutex> | |
56 | class scoped_lock | |
57 | { | |
58 | #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED) | |
59 | private: | |
60 | typedef scoped_lock<Mutex> this_type; | |
61 | BOOST_MOVABLE_BUT_NOT_COPYABLE(scoped_lock) | |
62 | typedef bool this_type::*unspecified_bool_type; | |
63 | #endif //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED | |
64 | public: | |
65 | ||
66 | typedef Mutex mutex_type; | |
67 | ||
68 | //!Effects: Default constructs a scoped_lock. | |
69 | //!Postconditions: owns() == false and mutex() == 0. | |
70 | scoped_lock() | |
71 | : mp_mutex(0), m_locked(false) | |
72 | {} | |
73 | ||
74 | //!Effects: m.lock(). | |
75 | //!Postconditions: owns() == true and mutex() == &m. | |
76 | //!Notes: The constructor will take ownership of the mutex. If another thread | |
77 | //! already owns the mutex, this thread will block until the mutex is released. | |
78 | //! Whether or not this constructor handles recursive locking depends upon the mutex. | |
79 | explicit scoped_lock(mutex_type& m) | |
80 | : mp_mutex(&m), m_locked(false) | |
81 | { mp_mutex->lock(); m_locked = true; } | |
82 | ||
83 | //!Postconditions: owns() == false, and mutex() == &m. | |
84 | //!Notes: The constructor will not take ownership of the mutex. There is no effect | |
85 | //! required on the referenced mutex. | |
86 | scoped_lock(mutex_type& m, defer_lock_type) | |
87 | : mp_mutex(&m), m_locked(false) | |
88 | {} | |
89 | ||
90 | //!Postconditions: owns() == true, and mutex() == &m. | |
91 | //!Notes: The constructor will suppose that the mutex is already locked. There | |
92 | //! is no effect required on the referenced mutex. | |
93 | scoped_lock(mutex_type& m, accept_ownership_type) | |
94 | : mp_mutex(&m), m_locked(true) | |
95 | {} | |
96 | ||
97 | //!Effects: m.try_lock(). | |
98 | //!Postconditions: mutex() == &m. owns() == the return value of the | |
99 | //! m.try_lock() executed within the constructor. | |
100 | //!Notes: The constructor will take ownership of the mutex if it can do | |
101 | //! so without waiting. Whether or not this constructor handles recursive | |
102 | //! locking depends upon the mutex. If the mutex_type does not support try_lock, | |
103 | //! this constructor will fail at compile time if instantiated, but otherwise | |
104 | //! have no effect. | |
105 | scoped_lock(mutex_type& m, try_to_lock_type) | |
106 | : mp_mutex(&m), m_locked(mp_mutex->try_lock()) | |
107 | {} | |
108 | ||
109 | //!Effects: m.timed_lock(abs_time). | |
110 | //!Postconditions: mutex() == &m. owns() == the return value of the | |
111 | //! m.timed_lock(abs_time) executed within the constructor. | |
112 | //!Notes: The constructor will take ownership of the mutex if it can do | |
113 | //! it until abs_time is reached. Whether or not this constructor | |
114 | //! handles recursive locking depends upon the mutex. If the mutex_type | |
115 | //! does not support try_lock, this constructor will fail at compile | |
116 | //! time if instantiated, but otherwise have no effect. | |
117 | scoped_lock(mutex_type& m, const boost::posix_time::ptime& 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) | |
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> | |
206 | scoped_lock(BOOST_RV_REF(upgradable_lock<T>) upgr, boost::posix_time::ptime &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 | try{ if(m_locked && mp_mutex) mp_mutex->unlock(); } | |
257 | catch(...){} | |
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 | bool timed_lock(const boost::posix_time::ptime& abs_time) | |
311 | { | |
312 | if(!mp_mutex || m_locked) | |
313 | throw lock_exception(); | |
314 | m_locked = mp_mutex->timed_lock(abs_time); | |
315 | return m_locked; | |
316 | } | |
317 | ||
318 | //!Effects: If mutex() == 0 or if not locked, throws a lock_exception() | |
319 | //! exception. Calls unlock() on the referenced mutex. | |
320 | //!Postconditions: owns() == false. | |
321 | //!Notes: The scoped_lock changes from a state of owning the mutex, to not | |
322 | //! owning the mutex.*/ | |
323 | void unlock() | |
324 | { | |
325 | if(!mp_mutex || !m_locked) | |
326 | throw lock_exception(); | |
327 | mp_mutex->unlock(); | |
328 | m_locked = false; | |
329 | } | |
330 | ||
331 | //!Effects: Returns true if this scoped_lock has acquired | |
332 | //!the referenced mutex. | |
333 | bool owns() const | |
334 | { return m_locked && mp_mutex; } | |
335 | ||
336 | //!Conversion to bool. | |
337 | //!Returns owns(). | |
338 | operator unspecified_bool_type() const | |
339 | { return m_locked? &this_type::m_locked : 0; } | |
340 | ||
341 | //!Effects: Returns a pointer to the referenced mutex, or 0 if | |
342 | //!there is no mutex to reference. | |
343 | mutex_type* mutex() const | |
344 | { return mp_mutex; } | |
345 | ||
346 | //!Effects: Returns a pointer to the referenced mutex, or 0 if there is no | |
347 | //! mutex to reference. | |
348 | //!Postconditions: mutex() == 0 and owns() == false. | |
349 | mutex_type* release() | |
350 | { | |
351 | mutex_type *mut = mp_mutex; | |
352 | mp_mutex = 0; | |
353 | m_locked = false; | |
354 | return mut; | |
355 | } | |
356 | ||
357 | //!Effects: Swaps state with moved lock. | |
358 | //!Throws: Nothing. | |
359 | void swap( scoped_lock<mutex_type> &other) | |
360 | { | |
361 | (simple_swap)(mp_mutex, other.mp_mutex); | |
362 | (simple_swap)(m_locked, other.m_locked); | |
363 | } | |
364 | ||
365 | #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED) | |
366 | private: | |
367 | mutex_type *mp_mutex; | |
368 | bool m_locked; | |
369 | #endif //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED | |
370 | }; | |
371 | ||
372 | } // namespace interprocess | |
373 | } // namespace boost | |
374 | ||
375 | #include <boost/interprocess/detail/config_end.hpp> | |
376 | ||
377 | #endif // BOOST_INTERPROCESS_SCOPED_LOCK_HPP |