]>
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_UPGRADABLE_LOCK_HPP | |
17 | #define BOOST_INTERPROCESS_UPGRADABLE_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/detail/mpl.hpp> | |
32 | #include <boost/interprocess/detail/type_traits.hpp> | |
33 | ||
34 | #include <boost/interprocess/exceptions.hpp> | |
35 | #include <boost/move/utility_core.hpp> | |
36 | #include <boost/interprocess/detail/posix_time_types_wrk.hpp> | |
37 | ||
38 | //!\file | |
39 | //!Describes the upgradable_lock class that serves to acquire the upgradable | |
40 | //!lock of a mutex. | |
41 | ||
42 | namespace boost { | |
43 | namespace interprocess { | |
44 | ||
45 | //!upgradable_lock is meant to carry out the tasks for read-locking, unlocking, | |
46 | //!try-read-locking and timed-read-locking (recursive or not) for the Mutex. | |
47 | //!Additionally the upgradable_lock can transfer ownership to a scoped_lock | |
48 | //!using transfer_lock syntax. The Mutex need not supply all of the functionality. | |
49 | //!If the client of upgradable_lock<Mutex> does not use functionality which the | |
50 | //!Mutex does not supply, no harm is done. Mutex ownership can be shared among | |
51 | //!read_locks, and a single upgradable_lock. upgradable_lock does not support | |
52 | //!copy semantics. However upgradable_lock supports ownership transfer from | |
53 | //!a upgradable_locks or scoped_locks via transfer_lock syntax. | |
54 | template <class UpgradableMutex> | |
55 | class upgradable_lock | |
56 | { | |
57 | public: | |
58 | typedef UpgradableMutex mutex_type; | |
59 | #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED) | |
60 | private: | |
61 | typedef upgradable_lock<UpgradableMutex> this_type; | |
62 | explicit upgradable_lock(scoped_lock<mutex_type>&); | |
63 | typedef bool this_type::*unspecified_bool_type; | |
64 | BOOST_MOVABLE_BUT_NOT_COPYABLE(upgradable_lock) | |
65 | #endif //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED | |
66 | public: | |
67 | ||
68 | //!Effects: Default constructs a upgradable_lock. | |
69 | //!Postconditions: owns() == false and mutex() == 0. | |
70 | upgradable_lock() | |
71 | : mp_mutex(0), m_locked(false) | |
72 | {} | |
73 | ||
74 | explicit upgradable_lock(mutex_type& m) | |
75 | : mp_mutex(&m), m_locked(false) | |
76 | { mp_mutex->lock_upgradable(); m_locked = true; } | |
77 | ||
78 | //!Postconditions: owns() == false, and mutex() == &m. | |
79 | //!Notes: The constructor will not take ownership of the mutex. There is no effect | |
80 | //! required on the referenced mutex. | |
81 | upgradable_lock(mutex_type& m, defer_lock_type) | |
82 | : mp_mutex(&m), m_locked(false) | |
83 | {} | |
84 | ||
85 | //!Postconditions: owns() == true, and mutex() == &m. | |
86 | //!Notes: The constructor will suppose that the mutex is already upgradable | |
87 | //! locked. There is no effect required on the referenced mutex. | |
88 | upgradable_lock(mutex_type& m, accept_ownership_type) | |
89 | : mp_mutex(&m), m_locked(true) | |
90 | {} | |
91 | ||
92 | //!Effects: m.try_lock_upgradable(). | |
93 | //!Postconditions: mutex() == &m. owns() == the return value of the | |
94 | //! m.try_lock_upgradable() executed within the constructor. | |
95 | //!Notes: The constructor will take upgradable-ownership of the mutex | |
96 | //! if it can do so without waiting. Whether or not this constructor | |
97 | //! handles recursive locking depends upon the mutex. If the mutex_type | |
98 | //! does not support try_lock_upgradable, this constructor will fail at | |
99 | //! compile time if instantiated, but otherwise have no effect. | |
100 | upgradable_lock(mutex_type& m, try_to_lock_type) | |
101 | : mp_mutex(&m), m_locked(false) | |
102 | { m_locked = mp_mutex->try_lock_upgradable(); } | |
103 | ||
104 | //!Effects: m.timed_lock_upgradable(abs_time) | |
105 | //!Postconditions: mutex() == &m. owns() == the return value of the | |
106 | //! m.timed_lock_upgradable() executed within the constructor. | |
107 | //!Notes: The constructor will take upgradable-ownership of the mutex if it | |
108 | //! can do so within the time specified. Whether or not this constructor | |
109 | //! handles recursive locking depends upon the mutex. If the mutex_type | |
110 | //! does not support timed_lock_upgradable, this constructor will fail | |
111 | //! at compile time if instantiated, but otherwise have no effect. | |
112 | upgradable_lock(mutex_type& m, const boost::posix_time::ptime& abs_time) | |
113 | : mp_mutex(&m), m_locked(false) | |
114 | { m_locked = mp_mutex->timed_lock_upgradable(abs_time); } | |
115 | ||
116 | //!Effects: No effects on the underlying mutex. | |
117 | //!Postconditions: mutex() == the value upgr.mutex() had before the | |
118 | //! construction. upgr.mutex() == 0. owns() == upgr.owns() before the | |
119 | //! construction. upgr.owns() == false. | |
120 | //!Notes: If upgr is locked, this constructor will lock this upgradable_lock | |
121 | //! while unlocking upgr. If upgr is unlocked, then this upgradable_lock will | |
122 | //! be unlocked as well. Only a moved upgradable_lock's will match this | |
123 | //! signature. An non-moved upgradable_lock can be moved with the | |
124 | //! expression: "boost::move(lock);". This constructor does not alter the | |
125 | //! state of the mutex, only potentially who owns it. | |
126 | upgradable_lock(BOOST_RV_REF(upgradable_lock<mutex_type>) upgr) | |
127 | : mp_mutex(0), m_locked(upgr.owns()) | |
128 | { mp_mutex = upgr.release(); } | |
129 | ||
130 | //!Effects: If scop.owns(), m_.unlock_and_lock_upgradable(). | |
131 | //!Postconditions: mutex() == the value scop.mutex() had before the construction. | |
132 | //! scop.mutex() == 0. owns() == scop.owns() before the constructor. After the | |
133 | //! construction, scop.owns() == false. | |
134 | //!Notes: If scop is locked, this constructor will transfer the exclusive-ownership | |
135 | //! to an upgradable-ownership of this upgradable_lock. | |
136 | //! Only a moved sharable_lock's will match this | |
137 | //! signature. An non-moved sharable_lock can be moved with the | |
138 | //! expression: "boost::move(lock);". | |
139 | template<class T> | |
140 | upgradable_lock(BOOST_RV_REF(scoped_lock<T>) scop | |
141 | , typename ipcdetail::enable_if< ipcdetail::is_same<T, UpgradableMutex> >::type * = 0) | |
142 | : mp_mutex(0), m_locked(false) | |
143 | { | |
144 | scoped_lock<mutex_type> &u_lock = scop; | |
145 | if(u_lock.owns()){ | |
146 | u_lock.mutex()->unlock_and_lock_upgradable(); | |
147 | m_locked = true; | |
148 | } | |
149 | mp_mutex = u_lock.release(); | |
150 | } | |
151 | ||
152 | //!Effects: If shar.owns() then calls try_unlock_sharable_and_lock_upgradable() | |
153 | //! on the referenced mutex. | |
154 | //! a)if try_unlock_sharable_and_lock_upgradable() returns true then mutex() | |
155 | //! obtains the value from shar.release() and owns() is set to true. | |
156 | //! b)if try_unlock_sharable_and_lock_upgradable() returns false then shar is | |
157 | //! unaffected and this upgradable_lock construction has the same | |
158 | //! effects as a default construction. | |
159 | //! c)Else shar.owns() is false. mutex() obtains the value from shar.release() | |
160 | //! and owns() is set to false. | |
161 | //!Notes: This construction will not block. It will try to obtain mutex | |
162 | //! ownership from shar immediately, while changing the lock type from a | |
163 | //! "read lock" to an "upgradable lock". If the "read lock" isn't held | |
164 | //! in the first place, the mutex merely changes type to an unlocked | |
165 | //! "upgradable lock". If the "read lock" is held, then mutex transfer | |
166 | //! occurs only if it can do so in a non-blocking manner. | |
167 | template<class T> | |
168 | upgradable_lock( BOOST_RV_REF(sharable_lock<T>) shar, try_to_lock_type | |
169 | , typename ipcdetail::enable_if< ipcdetail::is_same<T, UpgradableMutex> >::type * = 0) | |
170 | : mp_mutex(0), m_locked(false) | |
171 | { | |
172 | sharable_lock<mutex_type> &s_lock = shar; | |
173 | if(s_lock.owns()){ | |
174 | if((m_locked = s_lock.mutex()->try_unlock_sharable_and_lock_upgradable()) == true){ | |
175 | mp_mutex = s_lock.release(); | |
176 | } | |
177 | } | |
178 | else{ | |
179 | s_lock.release(); | |
180 | } | |
181 | } | |
182 | ||
183 | //!Effects: if (owns()) m_->unlock_upgradable(). | |
184 | //!Notes: The destructor behavior ensures that the mutex lock is not leaked. | |
185 | ~upgradable_lock() | |
186 | { | |
187 | try{ | |
188 | if(m_locked && mp_mutex) mp_mutex->unlock_upgradable(); | |
189 | } | |
190 | catch(...){} | |
191 | } | |
192 | ||
193 | //!Effects: If owns(), then unlock_upgradable() is called on mutex(). | |
194 | //! *this gets the state of upgr and upgr gets set to a default constructed state. | |
195 | //!Notes: With a recursive mutex it is possible that both this and upgr own the | |
196 | //! mutex before the assignment. In this case, this will own the mutex | |
197 | //! after the assignment (and upgr will not), but the mutex's upgradable lock | |
198 | //! count will be decremented by one. | |
199 | upgradable_lock &operator=(BOOST_RV_REF(upgradable_lock) upgr) | |
200 | { | |
201 | if(this->owns()) | |
202 | this->unlock(); | |
203 | m_locked = upgr.owns(); | |
204 | mp_mutex = upgr.release(); | |
205 | return *this; | |
206 | } | |
207 | ||
208 | //!Effects: If mutex() == 0 or if already locked, throws a lock_exception() | |
209 | //! exception. Calls lock_upgradable() on the referenced mutex. | |
210 | //!Postconditions: owns() == true. | |
211 | //!Notes: The sharable_lock changes from a state of not owning the mutex, | |
212 | //! to owning the mutex, blocking if necessary. | |
213 | void lock() | |
214 | { | |
215 | if(!mp_mutex || m_locked) | |
216 | throw lock_exception(); | |
217 | mp_mutex->lock_upgradable(); | |
218 | m_locked = true; | |
219 | } | |
220 | ||
221 | //!Effects: If mutex() == 0 or if already locked, throws a lock_exception() | |
222 | //! exception. Calls try_lock_upgradable() on the referenced mutex. | |
223 | //!Postconditions: owns() == the value returned from | |
224 | //! mutex()->try_lock_upgradable(). | |
225 | //!Notes: The upgradable_lock changes from a state of not owning the mutex, | |
226 | //! to owning the mutex, but only if blocking was not required. If the | |
227 | //! mutex_type does not support try_lock_upgradable(), this function will | |
228 | //! fail at compile time if instantiated, but otherwise have no effect. | |
229 | bool try_lock() | |
230 | { | |
231 | if(!mp_mutex || m_locked) | |
232 | throw lock_exception(); | |
233 | m_locked = mp_mutex->try_lock_upgradable(); | |
234 | return m_locked; | |
235 | } | |
236 | ||
237 | //!Effects: If mutex() == 0 or if already locked, throws a lock_exception() | |
238 | //! exception. Calls timed_lock_upgradable(abs_time) on the referenced mutex. | |
239 | //!Postconditions: owns() == the value returned from | |
240 | //! mutex()->timed_lock_upgradable(abs_time). | |
241 | //!Notes: The upgradable_lock changes from a state of not owning the mutex, | |
242 | //! to owning the mutex, but only if it can obtain ownership within the | |
243 | //! specified time. If the mutex_type does not support | |
244 | //! timed_lock_upgradable(abs_time), this function will fail at compile | |
245 | //! time if instantiated, but otherwise have no effect. | |
246 | bool timed_lock(const boost::posix_time::ptime& abs_time) | |
247 | { | |
248 | if(!mp_mutex || m_locked) | |
249 | throw lock_exception(); | |
250 | m_locked = mp_mutex->timed_lock_upgradable(abs_time); | |
251 | return m_locked; | |
252 | } | |
253 | ||
254 | //!Effects: If mutex() == 0 or if not locked, throws a lock_exception() | |
255 | //! exception. Calls unlock_upgradable() on the referenced mutex. | |
256 | //!Postconditions: owns() == false. | |
257 | //!Notes: The upgradable_lock changes from a state of owning the mutex, | |
258 | //! to not owning the mutex. | |
259 | void unlock() | |
260 | { | |
261 | if(!mp_mutex || !m_locked) | |
262 | throw lock_exception(); | |
263 | mp_mutex->unlock_upgradable(); | |
264 | m_locked = false; | |
265 | } | |
266 | ||
267 | //!Effects: Returns true if this scoped_lock has acquired the | |
268 | //!referenced mutex. | |
269 | bool owns() const | |
270 | { return m_locked && mp_mutex; } | |
271 | ||
272 | //!Conversion to bool. | |
273 | //!Returns owns(). | |
274 | operator unspecified_bool_type() const | |
275 | { return m_locked? &this_type::m_locked : 0; } | |
276 | ||
277 | //!Effects: Returns a pointer to the referenced mutex, or 0 if | |
278 | //!there is no mutex to reference. | |
279 | mutex_type* mutex() const | |
280 | { return mp_mutex; } | |
281 | ||
282 | //!Effects: Returns a pointer to the referenced mutex, or 0 if there is no | |
283 | //! mutex to reference. | |
284 | //!Postconditions: mutex() == 0 and owns() == false. | |
285 | mutex_type* release() | |
286 | { | |
287 | mutex_type *mut = mp_mutex; | |
288 | mp_mutex = 0; | |
289 | m_locked = false; | |
290 | return mut; | |
291 | } | |
292 | ||
293 | //!Effects: Swaps state with moved lock. | |
294 | //!Throws: Nothing. | |
295 | void swap(upgradable_lock<mutex_type> &other) | |
296 | { | |
297 | (simple_swap)(mp_mutex, other.mp_mutex); | |
298 | (simple_swap)(m_locked, other.m_locked); | |
299 | } | |
300 | ||
301 | #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED) | |
302 | private: | |
303 | mutex_type *mp_mutex; | |
304 | bool m_locked; | |
305 | #endif //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED | |
306 | }; | |
307 | ||
308 | } // namespace interprocess | |
309 | } // namespace boost | |
310 | ||
311 | #include <boost/interprocess/detail/config_end.hpp> | |
312 | ||
313 | #endif // BOOST_INTERPROCESS_UPGRADABLE_LOCK_HPP |