ceph/src/boost/libs/interprocess/include/boost/interprocess/sync/shm/named_upgradable_mutex.hpp

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