/Src/Dependencies/Boost/boost/interprocess/sync/named_upgradable_mutex.hpp

  1//////////////////////////////////////////////////////////////////////////////
  2//
  3// (C) Copyright Ion Gaztanaga 2005-2009. 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#ifndef BOOST_INTERPROCESS_named_upgradable_mutex_HPP
 12#define BOOST_INTERPROCESS_named_upgradable_mutex_HPP
 13
 14#if (defined _MSC_VER) && (_MSC_VER >= 1200)
 15#  pragma once
 16#endif
 17
 18#include <boost/interprocess/detail/config_begin.hpp>
 19#include <boost/interprocess/detail/workaround.hpp>
 20#include <boost/interprocess/creation_tags.hpp>
 21#include <boost/interprocess/exceptions.hpp>
 22#include <boost/interprocess/shared_memory_object.hpp>
 23#include <boost/interprocess/detail/managed_open_or_create_impl.hpp>
 24#include <boost/interprocess/sync/interprocess_upgradable_mutex.hpp>
 25#include <boost/interprocess/detail/posix_time_types_wrk.hpp>
 26#include <boost/interprocess/sync/emulation/named_creation_functor.hpp>
 27#include <boost/interprocess/permissions.hpp>
 28
 29//!\file
 30//!Describes a named upgradable mutex class for inter-process synchronization
 31
 32namespace boost {
 33namespace interprocess {
 34
 35/// @cond
 36namespace detail{ class interprocess_tester; }
 37/// @endcond
 38
 39class named_condition;
 40
 41//!A upgradable mutex with a global name, so it can be found from different 
 42//!processes. This mutex can't be placed in shared memory, and
 43//!each process should have it's own named upgradable mutex.
 44class named_upgradable_mutex
 45{
 46   /// @cond
 47   //Non-copyable
 48   named_upgradable_mutex();
 49   named_upgradable_mutex(const named_upgradable_mutex &);
 50   named_upgradable_mutex &operator=(const named_upgradable_mutex &);
 51   friend class named_condition;
 52   /// @endcond
 53   public:
 54
 55   //!Creates a global upgradable mutex with a name. 
 56   //!If the upgradable mutex can't be created throws interprocess_exception
 57   named_upgradable_mutex(create_only_t create_only, const char *name, const permissions &perm = permissions());
 58
 59   //!Opens or creates a global upgradable mutex with a name, and an initial count. 
 60   //!If the upgradable mutex is created, this call is equivalent to
 61   //!named_upgradable_mutex(create_only_t, ...)
 62   //!If the upgradable mutex is already created, this call is equivalent to
 63   //!named_upgradable_mutex(open_only_t, ... ).
 64   named_upgradable_mutex(open_or_create_t open_or_create, const char *name, const permissions &perm = permissions());
 65
 66   //!Opens a global upgradable mutex with a name if that upgradable mutex
 67   //!is previously.
 68   //!created. If it is not previously created this function throws
 69   //!interprocess_exception.
 70   named_upgradable_mutex(open_only_t open_only, const char *name);
 71
 72   //!Destroys *this and indicates that the calling process is finished using
 73   //!the resource. The destructor function will deallocate
 74   //!any system resources allocated by the system for use by this process for
 75   //!this resource. The resource can still be opened again calling
 76   //!the open constructor overload. To erase the resource from the system
 77   //!use remove().
 78   ~named_upgradable_mutex();
 79
 80   //Exclusive locking
 81
 82   //!Effects: The calling thread tries to obtain exclusive ownership of the mutex,
 83   //!   and if another thread has exclusive, sharable or upgradable ownership of
 84   //!   the mutex, it waits until it can obtain the ownership.
 85   //!Throws: interprocess_exception on error.
 86   void lock();
 87
 88   //!Effects: The calling thread tries to acquire exclusive ownership of the mutex
 89   //!   without waiting. If no other thread has exclusive, sharable or upgradable
 90   //!   ownership of the mutex this succeeds.
 91   //!Returns: If it can acquire exclusive ownership immediately returns true.
 92   //!   If it has to wait, returns false.
 93   //!Throws: interprocess_exception on error.
 94   bool try_lock();
 95
 96   //!Effects: The calling thread tries to acquire exclusive ownership of the mutex
 97   //!   waiting if necessary until no other thread has has exclusive, sharable or
 98   //!   upgradable ownership of the mutex or abs_time is reached. 
 99   //!Returns: If acquires exclusive ownership, returns true. Otherwise returns false. 
100   //!Throws: interprocess_exception on error.
101   bool timed_lock(const boost::posix_time::ptime &abs_time);
102
103   //!Precondition: The thread must have exclusive ownership of the mutex. 
104   //!Effects: The calling thread releases the exclusive ownership of the mutex. 
105   //!Throws: An exception derived from interprocess_exception on error.
106   void unlock();
107
108   //Sharable locking
109
110   //!Effects: The calling thread tries to obtain sharable ownership of the mutex,
111   //!   and if another thread has exclusive or upgradable ownership of the mutex,
112   //!   waits until it can obtain the ownership.
113   //!Throws: interprocess_exception on error.
114   void lock_sharable();
115
116   //!Effects: The calling thread tries to acquire sharable ownership of the mutex
117   //!   without waiting. If no other thread has has exclusive or upgradable ownership
118   //!   of the mutex this succeeds. 
119   //!Returns: If it can acquire sharable ownership immediately returns true. If it
120   //!   has to wait, returns false. 
121   //!Throws: interprocess_exception on error.
122   bool try_lock_sharable();
123
124   //!Effects: The calling thread tries to acquire sharable ownership of the mutex
125   //!   waiting if necessary until no other thread has has exclusive or upgradable
126   //!   ownership of the mutex or abs_time is reached. 
127   //!Returns: If acquires sharable ownership, returns true. Otherwise returns false. 
128   //!Throws: interprocess_exception on error.
129   bool timed_lock_sharable(const boost::posix_time::ptime &abs_time);
130
131   //!Precondition: The thread must have sharable ownership of the mutex. 
132   //!Effects: The calling thread releases the sharable ownership of the mutex. 
133   //!Throws: An exception derived from interprocess_exception on error.
134   void unlock_sharable();
135
136   //Upgradable locking
137
138   //!Effects: The calling thread tries to obtain upgradable ownership of the mutex,
139   //!   and if another thread has exclusive or upgradable ownership of the mutex,
140   //!   waits until it can obtain the ownership.
141   //!Throws: interprocess_exception on error.
142   void lock_upgradable();
143
144   //!Effects: The calling thread tries to acquire upgradable ownership of the mutex
145   //!   without waiting. If no other thread has has exclusive or upgradable ownership
146   //!   of the mutex this succeeds. 
147   //!Returns: If it can acquire upgradable ownership immediately returns true.
148   //!   If it has to wait, returns false.
149   //!Throws: interprocess_exception on error.
150   bool try_lock_upgradable();
151
152   //!Effects: The calling thread tries to acquire upgradable ownership of the mutex
153   //!   waiting if necessary until no other thread has has exclusive or upgradable
154   //!   ownership of the mutex or abs_time is reached.
155   //!Returns: If acquires upgradable ownership, returns true. Otherwise returns false. 
156   //!Throws: interprocess_exception on error.
157   bool timed_lock_upgradable(const boost::posix_time::ptime &abs_time);
158
159   //!Precondition: The thread must have upgradable ownership of the mutex. 
160   //!Effects: The calling thread releases the upgradable ownership of the mutex. 
161   //!Throws: An exception derived from interprocess_exception on error.
162   void unlock_upgradable();
163
164   //Demotions
165
166   //!Precondition: The thread must have exclusive ownership of the mutex. 
167   //!Effects: The thread atomically releases exclusive ownership and acquires
168   //!   upgradable ownership. This operation is non-blocking. 
169   //!Throws: An exception derived from interprocess_exception on error.
170   void unlock_and_lock_upgradable();
171
172   //!Precondition: The thread must have exclusive ownership of the mutex. 
173   //!Effects: The thread atomically releases exclusive ownership and acquires
174   //!   sharable ownership. This operation is non-blocking. 
175   //!Throws: An exception derived from interprocess_exception on error.
176   void unlock_and_lock_sharable();
177
178   //!Precondition: The thread must have upgradable ownership of the mutex. 
179   //!Effects: The thread atomically releases upgradable ownership and acquires
180   //!   sharable ownership. This operation is non-blocking. 
181   //!Throws: An exception derived from interprocess_exception on error.
182   void unlock_upgradable_and_lock_sharable();
183
184   //Promotions
185
186   //!Precondition: The thread must have upgradable ownership of the mutex. 
187   //!Effects: The thread atomically releases upgradable ownership and acquires
188   //!   exclusive ownership. This operation will block until all threads with
189   //!   sharable ownership release it. 
190   //!Throws: An exception derived from interprocess_exception on error.
191   void unlock_upgradable_and_lock();
192
193   //!Precondition: The thread must have upgradable ownership of the mutex. 
194   //!Effects: The thread atomically releases upgradable ownership and tries to
195   //!   acquire exclusive ownership. This operation will fail if there are threads
196   //!   with sharable ownership, but it will maintain upgradable ownership. 
197   //!Returns: If acquires exclusive ownership, returns true. Otherwise returns false.
198   //!Throws: An exception derived from interprocess_exception on error.
199   bool try_unlock_upgradable_and_lock();
200
201   //!Precondition: The thread must have upgradable ownership of the mutex. 
202   //!Effects: The thread atomically releases upgradable ownership and tries to acquire
203   //!   exclusive ownership, waiting if necessary until abs_time. This operation will
204   //!   fail if there are threads with sharable ownership or timeout reaches, but it
205   //!   will maintain upgradable ownership. 
206   //!Returns: If acquires exclusive ownership, returns true. Otherwise returns false. 
207   //!Throws: An exception derived from interprocess_exception on error.
208   bool timed_unlock_upgradable_and_lock(const boost::posix_time::ptime &abs_time);
209
210   //!Precondition: The thread must have sharable ownership of the mutex. 
211   //!Effects: The thread atomically releases sharable ownership and tries to acquire
212   //!   exclusive ownership. This operation will fail if there are threads with sharable
213   //!   or upgradable ownership, but it will maintain sharable ownership.
214   //!Returns: If acquires exclusive ownership, returns true. Otherwise returns false. 
215   //!Throws: An exception derived from interprocess_exception on error.
216   bool try_unlock_sharable_and_lock();
217
218   bool try_unlock_sharable_and_lock_upgradable();
219
220   //!Erases a named upgradable mutex from the system.
221   //!Returns false on error. Never throws.
222   static bool remove(const char *name);
223
224   /// @cond
225   private:
226   friend class detail::interprocess_tester;
227   void dont_close_on_destruction();
228
229   interprocess_upgradable_mutex *mutex() const
230   {  return static_cast<interprocess_upgradable_mutex*>(m_shmem.get_user_address()); }
231
232   detail::managed_open_or_create_impl<shared_memory_object> m_shmem;
233   typedef detail::named_creation_functor<interprocess_upgradable_mutex> construct_func_t;
234   /// @endcond
235};
236
237/// @cond
238
239inline named_upgradable_mutex::~named_upgradable_mutex()
240{}
241
242inline named_upgradable_mutex::named_upgradable_mutex
243   (create_only_t, const char *name, const permissions &perm)
244   :  m_shmem  (create_only
245               ,name
246               ,sizeof(interprocess_upgradable_mutex) +
247                  detail::managed_open_or_create_impl<shared_memory_object>::
248                     ManagedOpenOrCreateUserOffset
249               ,read_write
250               ,0
251               ,construct_func_t(detail::DoCreate)
252               ,perm)
253{}
254
255inline named_upgradable_mutex::named_upgradable_mutex
256   (open_or_create_t, const char *name, const permissions &perm)
257   :  m_shmem  (open_or_create
258               ,name
259               ,sizeof(interprocess_upgradable_mutex) +
260                  detail::managed_open_or_create_impl<shared_memory_object>::
261                     ManagedOpenOrCreateUserOffset
262               ,read_write
263               ,0
264               ,construct_func_t(detail::DoOpenOrCreate)
265               ,perm)
266{}
267
268inline named_upgradable_mutex::named_upgradable_mutex
269   (open_only_t, const char *name)
270   :  m_shmem  (open_only
271               ,name
272               ,read_write
273               ,0
274               ,construct_func_t(detail::DoOpen))
275{}
276
277inline void named_upgradable_mutex::dont_close_on_destruction()
278{  detail::interprocess_tester::dont_close_on_destruction(m_shmem);  }
279
280inline void named_upgradable_mutex::lock()
281{  this->mutex()->lock();  }
282
283inline void named_upgradable_mutex::unlock()
284{  this->mutex()->unlock();  }
285
286inline bool named_upgradable_mutex::try_lock()
287{  return this->mutex()->try_lock();  }
288
289inline bool named_upgradable_mutex::timed_lock
290   (const boost::posix_time::ptime &abs_time)
291{
292   if(abs_time == boost::posix_time::pos_infin){
293      this->lock();
294      return true;
295   }
296   return this->mutex()->timed_lock(abs_time);
297}
298
299inline void named_upgradable_mutex::lock_upgradable()
300{  this->mutex()->lock_upgradable();  }
301
302inline void named_upgradable_mutex::unlock_upgradable()
303{  this->mutex()->unlock_upgradable();  }
304
305inline bool named_upgradable_mutex::try_lock_upgradable()
306{  return this->mutex()->try_lock_upgradable();  }
307
308inline bool named_upgradable_mutex::timed_lock_upgradable
309   (const boost::posix_time::ptime &abs_time)
310{
311   if(abs_time == boost::posix_time::pos_infin){
312      this->lock_upgradable();
313      return true;
314   }
315   return this->mutex()->timed_lock_upgradable(abs_time);
316}
317
318inline void named_upgradable_mutex::lock_sharable()
319{  this->mutex()->lock_sharable();  }
320
321inline void named_upgradable_mutex::unlock_sharable()
322{  this->mutex()->unlock_sharable();  }
323
324inline bool named_upgradable_mutex::try_lock_sharable()
325{  return this->mutex()->try_lock_sharable();  }
326
327inline bool named_upgradable_mutex::timed_lock_sharable
328   (const boost::posix_time::ptime &abs_time)
329{
330   if(abs_time == boost::posix_time::pos_infin){
331      this->lock_sharable();
332      return true;
333   }
334   return this->mutex()->timed_lock_sharable(abs_time);
335}
336
337inline void named_upgradable_mutex::unlock_and_lock_upgradable()
338{  this->mutex()->unlock_and_lock_upgradable();  }
339
340inline void named_upgradable_mutex::unlock_and_lock_sharable()
341{  this->mutex()->unlock_and_lock_sharable();  }
342
343inline void named_upgradable_mutex::unlock_upgradable_and_lock_sharable()
344{  this->mutex()->unlock_upgradable_and_lock_sharable();  }
345
346inline void named_upgradable_mutex::unlock_upgradable_and_lock()
347{  this->mutex()->unlock_upgradable_and_lock();  }
348
349inline bool named_upgradable_mutex::try_unlock_upgradable_and_lock()
350{  return this->mutex()->try_unlock_upgradable_and_lock();  }
351
352inline bool named_upgradable_mutex::timed_unlock_upgradable_and_lock
353   (const boost::posix_time::ptime &abs_time)
354{  return this->mutex()->timed_unlock_upgradable_and_lock(abs_time);  }
355
356inline bool named_upgradable_mutex::try_unlock_sharable_and_lock()
357{  return this->mutex()->try_unlock_sharable_and_lock();  }
358
359inline bool named_upgradable_mutex::try_unlock_sharable_and_lock_upgradable()
360{  return this->mutex()->try_unlock_sharable_and_lock_upgradable();  }
361
362inline bool named_upgradable_mutex::remove(const char *name)
363{  return shared_memory_object::remove(name); }
364
365/// @endcond
366
367}  //namespace interprocess {
368}  //namespace boost {
369
370#include <boost/interprocess/detail/config_end.hpp>
371
372#endif   //BOOST_INTERPROCESS_named_upgradable_mutex_HPP