1 //////////////////////////////////////////////////////////////////////////////
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)
7 // See http://www.boost.org/libs/interprocess for documentation.
9 //////////////////////////////////////////////////////////////////////////////
11 // This interface is inspired by Howard Hinnant's lock proposal.
12 // http://home.twcny.rr.com/hinnant/cpp_extensions/threads_move.html
14 //////////////////////////////////////////////////////////////////////////////
16 #ifndef BOOST_INTERPROCESS_SHARABLE_LOCK_HPP
17 #define BOOST_INTERPROCESS_SHARABLE_LOCK_HPP
19 #ifndef BOOST_CONFIG_HPP
20 # include <boost/config.hpp>
23 #if defined(BOOST_HAS_PRAGMA_ONCE)
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/interprocess/detail/simple_swap.hpp>
35 #include <boost/move/utility_core.hpp>
36 #include <boost/interprocess/detail/posix_time_types_wrk.hpp>
39 //!Describes the upgradable_lock class that serves to acquire the upgradable
43 namespace interprocess {
46 //!sharable_lock is meant to carry out the tasks for sharable-locking
47 //!(such as read-locking), unlocking, try-sharable-locking and timed-sharable-locking
48 //!(recursive or not) for the Mutex. The Mutex need not supply all of this
49 //!functionality. If the client of sharable_lock<Mutex> does not use functionality which
50 //!the Mutex does not supply, no harm is done. Mutex ownership can be shared among
51 //!sharable_locks, and a single upgradable_lock. sharable_lock does not support
52 //!copy semantics. But sharable_lock supports ownership transfer from an sharable_lock,
53 //!upgradable_lock and scoped_lock via transfer_lock syntax.*/
54 template <class SharableMutex>
58 typedef SharableMutex mutex_type;
59 #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
61 typedef sharable_lock<SharableMutex> this_type;
62 explicit sharable_lock(scoped_lock<mutex_type>&);
63 typedef bool this_type::*unspecified_bool_type;
64 BOOST_MOVABLE_BUT_NOT_COPYABLE(sharable_lock)
65 #endif //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
68 //!Effects: Default constructs a sharable_lock.
69 //!Postconditions: owns() == false and mutex() == 0.
71 : mp_mutex(0), m_locked(false)
74 //!Effects: m.lock_sharable().
75 //!Postconditions: owns() == true and mutex() == &m.
76 //!Notes: The constructor will take sharable-ownership of the mutex. If
77 //! another thread already owns the mutex with exclusive ownership
78 //! (scoped_lock), this thread will block until the mutex is released.
79 //! If another thread owns the mutex with sharable or upgradable ownership,
80 //! then no blocking will occur. Whether or not this constructor handles
81 //! recursive locking depends upon the mutex.
82 explicit sharable_lock(mutex_type& m)
83 : mp_mutex(&m), m_locked(false)
84 { mp_mutex->lock_sharable(); m_locked = true; }
86 //!Postconditions: owns() == false, and mutex() == &m.
87 //!Notes: The constructor will not take ownership of the mutex. There is no effect
88 //! required on the referenced mutex.
89 sharable_lock(mutex_type& m, defer_lock_type)
90 : mp_mutex(&m), m_locked(false)
93 //!Postconditions: owns() == true, and mutex() == &m.
94 //!Notes: The constructor will suppose that the mutex is already sharable
95 //! locked. There is no effect required on the referenced mutex.
96 sharable_lock(mutex_type& m, accept_ownership_type)
97 : mp_mutex(&m), m_locked(true)
100 //!Effects: m.try_lock_sharable()
101 //!Postconditions: mutex() == &m. owns() == the return value of the
102 //! m.try_lock_sharable() executed within the constructor.
103 //!Notes: The constructor will take sharable-ownership of the mutex if it
104 //! can do so without waiting. Whether or not this constructor handles
105 //! recursive locking depends upon the mutex. If the mutex_type does not
106 //! support try_lock_sharable, this constructor will fail at compile
107 //! time if instantiated, but otherwise have no effect.
108 sharable_lock(mutex_type& m, try_to_lock_type)
109 : mp_mutex(&m), m_locked(false)
110 { m_locked = mp_mutex->try_lock_sharable(); }
112 //!Effects: m.timed_lock_sharable(abs_time)
113 //!Postconditions: mutex() == &m. owns() == the return value of the
114 //! m.timed_lock_sharable() executed within the constructor.
115 //!Notes: The constructor will take sharable-ownership of the mutex if it
116 //! can do so within the time specified. Whether or not this constructor
117 //! handles recursive locking depends upon the mutex. If the mutex_type
118 //! does not support timed_lock_sharable, this constructor will fail at
119 //! compile time if instantiated, but otherwise have no effect.
120 sharable_lock(mutex_type& m, const boost::posix_time::ptime& abs_time)
121 : mp_mutex(&m), m_locked(false)
122 { m_locked = mp_mutex->timed_lock_sharable(abs_time); }
124 //!Postconditions: mutex() == upgr.mutex(). owns() == the value of upgr.owns()
125 //! before the construction. upgr.owns() == false after the construction.
126 //!Notes: If the upgr sharable_lock owns the mutex, ownership is moved to this
127 //! sharable_lock with no blocking. If the upgr sharable_lock does not own the mutex, then
128 //! neither will this sharable_lock. Only a moved sharable_lock's will match this
129 //! signature. An non-moved sharable_lock can be moved with the expression:
130 //! "boost::move(lock);". This constructor does not alter the state of the mutex,
131 //! only potentially who owns it.
132 sharable_lock(BOOST_RV_REF(sharable_lock<mutex_type>) upgr)
133 : mp_mutex(0), m_locked(upgr.owns())
134 { mp_mutex = upgr.release(); }
136 //!Effects: If upgr.owns() then calls unlock_upgradable_and_lock_sharable() on the
137 //! referenced mutex.
138 //!Postconditions: mutex() == the value upgr.mutex() had before the construction.
139 //! upgr.mutex() == 0 owns() == the value of upgr.owns() before construction.
140 //! upgr.owns() == false after the construction.
141 //!Notes: If upgr is locked, this constructor will lock this sharable_lock while
142 //! unlocking upgr. Only a moved sharable_lock's will match this
143 //! signature. An non-moved upgradable_lock can be moved with the expression:
144 //! "boost::move(lock);".*/
146 sharable_lock(BOOST_RV_REF(upgradable_lock<T>) upgr
147 , typename ipcdetail::enable_if< ipcdetail::is_same<T, SharableMutex> >::type * = 0)
148 : mp_mutex(0), m_locked(false)
150 upgradable_lock<mutex_type> &u_lock = upgr;
152 u_lock.mutex()->unlock_upgradable_and_lock_sharable();
155 mp_mutex = u_lock.release();
158 //!Effects: If scop.owns() then calls unlock_and_lock_sharable() on the
159 //! referenced mutex.
160 //!Postconditions: mutex() == the value scop.mutex() had before the construction.
161 //! scop.mutex() == 0 owns() == scop.owns() before the constructor. After the
162 //! construction, scop.owns() == false.
163 //!Notes: If scop is locked, this constructor will transfer the exclusive ownership
164 //! to a sharable-ownership of this sharable_lock.
165 //! Only a moved scoped_lock's will match this
166 //! signature. An non-moved scoped_lock can be moved with the expression:
167 //! "boost::move(lock);".
169 sharable_lock(BOOST_RV_REF(scoped_lock<T>) scop
170 , typename ipcdetail::enable_if< ipcdetail::is_same<T, SharableMutex> >::type * = 0)
171 : mp_mutex(0), m_locked(false)
173 scoped_lock<mutex_type> &e_lock = scop;
175 e_lock.mutex()->unlock_and_lock_sharable();
178 mp_mutex = e_lock.release();
181 //!Effects: if (owns()) mp_mutex->unlock_sharable().
182 //!Notes: The destructor behavior ensures that the mutex lock is not leaked.
186 if(m_locked && mp_mutex) mp_mutex->unlock_sharable();
191 //!Effects: If owns() before the call, then unlock_sharable() is called on mutex().
192 //! *this gets the state of upgr and upgr gets set to a default constructed state.
193 //!Notes: With a recursive mutex it is possible that both this and upgr own the mutex
194 //! before the assignment. In this case, this will own the mutex after the assignment
195 //! (and upgr will not), but the mutex's lock count will be decremented by one.
196 sharable_lock &operator=(BOOST_RV_REF(sharable_lock<mutex_type>) upgr)
200 m_locked = upgr.owns();
201 mp_mutex = upgr.release();
205 //!Effects: If mutex() == 0 or already locked, throws a lock_exception()
206 //! exception. Calls lock_sharable() on the referenced mutex.
207 //!Postconditions: owns() == true.
208 //!Notes: The sharable_lock changes from a state of not owning the
209 //! mutex, to owning the mutex, blocking if necessary.
212 if(!mp_mutex || m_locked)
213 throw lock_exception();
214 mp_mutex->lock_sharable();
218 //!Effects: If mutex() == 0 or already locked, throws a lock_exception()
219 //! exception. Calls try_lock_sharable() on the referenced mutex.
220 //!Postconditions: owns() == the value returned from
221 //! mutex()->try_lock_sharable().
222 //!Notes: The sharable_lock changes from a state of not owning the mutex,
223 //! to owning the mutex, but only if blocking was not required. If the
224 //! mutex_type does not support try_lock_sharable(), this function will
225 //! fail at compile time if instantiated, but otherwise have no effect.
228 if(!mp_mutex || m_locked)
229 throw lock_exception();
230 m_locked = mp_mutex->try_lock_sharable();
234 //!Effects: If mutex() == 0 or already locked, throws a lock_exception()
235 //! exception. Calls timed_lock_sharable(abs_time) on the referenced mutex.
236 //!Postconditions: owns() == the value returned from
237 //! mutex()->timed_lock_sharable(elps_time).
238 //!Notes: The sharable_lock changes from a state of not owning the mutex,
239 //! to owning the mutex, but only if it can obtain ownership within the
240 //! specified time interval. If the mutex_type does not support
241 //! timed_lock_sharable(), this function will fail at compile time if
242 //! instantiated, but otherwise have no effect.
243 bool timed_lock(const boost::posix_time::ptime& abs_time)
245 if(!mp_mutex || m_locked)
246 throw lock_exception();
247 m_locked = mp_mutex->timed_lock_sharable(abs_time);
251 //!Effects: If mutex() == 0 or not locked, throws a lock_exception() exception.
252 //! Calls unlock_sharable() on the referenced mutex.
253 //!Postconditions: owns() == false.
254 //!Notes: The sharable_lock changes from a state of owning the mutex, to
255 //! not owning the mutex.
258 if(!mp_mutex || !m_locked)
259 throw lock_exception();
260 mp_mutex->unlock_sharable();
264 //!Effects: Returns true if this scoped_lock has
265 //!acquired the referenced mutex.
267 { return m_locked && mp_mutex; }
269 //!Conversion to bool.
271 operator unspecified_bool_type() const
272 { return m_locked? &this_type::m_locked : 0; }
274 //!Effects: Returns a pointer to the referenced mutex, or 0 if
275 //!there is no mutex to reference.
276 mutex_type* mutex() const
279 //!Effects: Returns a pointer to the referenced mutex, or 0 if there is no
280 //! mutex to reference.
281 //!Postconditions: mutex() == 0 and owns() == false.
282 mutex_type* release()
284 mutex_type *mut = mp_mutex;
290 //!Effects: Swaps state with moved lock.
292 void swap(sharable_lock<mutex_type> &other)
294 (simple_swap)(mp_mutex, other.mp_mutex);
295 (simple_swap)(m_locked, other.m_locked);
298 #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
300 mutex_type *mp_mutex;
302 #endif //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
305 } // namespace interprocess
308 #include <boost/interprocess/detail/config_end.hpp>
310 #endif // BOOST_INTERPROCESS_SHARABLE_LOCK_HPP