ACE/ace/Process_Mutex.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Process_Mutex.h
   6  *
   7  *   A wrapper for mutexes that can be used across processes on the
   8  *   same host machine, as well as within a process, of course.
   9  *
  10  * @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
  11  */
  12 //=============================================================================
  13
  14 #ifndef ACE_PROCESS_MUTEX_H
  15 #define ACE_PROCESS_MUTEX_H
  16
  17 #include /**/ "ace/pre.h"
  18
  19 #include /**/ "ace/config-all.h"
  20
  21 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  22 # pragma once
  23 #endif /* ACE_LACKS_PRAGMA_ONCE */
  24
  25 // To make it easier to carry the setting though this file as well as
  26 // Process_Mutex.{cpp inl}, set a private macro here.
  27 #ifdef _ACE_USE_SV_SEM
  28 #  undef _ACE_USE_SV_SEM
  29 #endif /* _ACE_USE_SV_SEM */
  30
  31 #if defined (ACE_HAS_SYSV_IPC) && !defined (ACE_USES_MUTEX_FOR_PROCESS_MUTEX)
  32 #  include "ace/SV_Semaphore_Complex.h"
  33 #  define _ACE_USE_SV_SEM
  34 #else
  35 #  include "ace/Mutex.h"
  36 #endif /* ACE_HAS_SYSV_IPC && !ACE_USES_MUTEX_FOR_PROCESS_MUTEX */
  37
  38 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  39
  40 // Forward declarations
  41 class ACE_Time_Value;
  42
  43 /**
  44  * @class ACE_Process_Mutex
  45  *
  46  * @brief A wrapper for mutexes that can be used across processes on
  47  * the same host machine, as well as within a process, of course.
  48  *
  49  * @attention The mechanism upon which @c ACE_Process_Mutex is based
  50  * can be configured at build time to be either @c ACE_SV_Semaphore_Complex
  51  * (on platforms that support it) or @c ACE_Mutex. On platforms that offer
  52  * System V IPC (the @c ACE_HAS_SYSV_IPC config macro is defined)
  53  * @c ACE_SV_Semaphore_Complex is the default because it is more convenient
  54  * and easy to use. @c ACE_Mutex is the default on all other platforms.
  55  * On platforms where ACE_SV_Semaphore_Complex is used by default, the
  56  * mechanism can be changed to ACE_Mutex when ACE is built by adding
  57  * @code
  58  *   #define ACE_USES_MUTEX_FOR_PROCESS_MUTEX
  59  * @endcode
  60  * to your @c config.h file.
  61  * @par
  62  * Consider these tradeoffs when evaluating whether or not to change
  63  * the default:
  64  *   - Some platforms (e.g., Pthreads and UI Threads) require interprocess
  65  *     mutexes to be allocated from shared memory. On these platforms, using
  66  *     ACE_Mutex as the underlying mechanism requires that ACE_Process_Mutex
  67  *     objects be allocated in shared memory. Using ACE_SV_Semaphore_Complex
  68  *     avoids this restriction.
  69  *   - System V IPC kernel parameters have a low default limit on some
  70  *     platforms. This would restrict the number of ACE_Process_Mutex objects
  71  *     that can be in use simultaneously when using ACE_SV_Semaphore_Complex.
  72  *   - If you require the ability to do a timed @c acquire(), you must
  73  *     use ACE_Mutex as the underlying mechanism because timed acquire does not
  74  *     work with System V semaphores.
  75  *   - When using ACE_Mutex on a Pthreads-based platform, an ACE_Process_Mutex
  76  *     object is deleted when the process which created the object destroys
  77  *     it, regardless of whether or not there are other processes still
  78  *     accessing the ACE_Process_Mutex. Using ACE_SV_Semaphore_Complex avoids
  79  *     this problem; the semaphore is destroyed when the last use of the
  80  *     object ends. For portable applications it is better to always ensure
  81  *     that the owner of the mutex destroys it after all other processes have
  82  *     stopped using it.
  83  */
  84 class ACE_Export ACE_Process_Mutex
  85 {
  86 public:
  87   /**
  88    * Create an ACE_Process_Mutex.
  89    *
  90    * @param name optional, null-terminated string containing the name of
  91    * the object. Multiple users of the same @c ACE_Process_Mutex must use
  92    * the same name to access the same object.  If not specified, a name
  93    * is generated.
  94    * @param arg optional, attributes to be used to initialize the mutex.
  95    * If using @c ACE_SV_Semaphore_Complex as the underlying mechanism,
  96    * this argument is ignored.
  97    * @param mode optional, the protection mode for either the backing store
  98    * file (for ACE_Mutex use) or the ACE_SV_Semaphore_Complex that's created.
  99    */
 100   ACE_Process_Mutex (const char *name = 0,
 101                      void *arg = 0,
 102                      mode_t mode = ACE_DEFAULT_FILE_PERMS);
 103
 104 #if defined (ACE_HAS_WCHAR)
 105   /**
 106    * Create an ACE_Process_Mutex (@c wchar_t version)
 107    *
 108    * @param name optional, null-terminated string containing the name of
 109    * the object. Multiple users of the same @c ACE_Process_Mutex must use
 110    * the same name to access the same object. If not specified, a name
 111    * is generated.
 112    * @param arg optional, attributes to be used to initialize the mutex.
 113    * If using @c ACE_SV_Semaphore_Complex as the underlying mechanism,
 114    * this argument is ignored.
 115    * @param mode optional, the protection mode for either the backing store
 116    * file (for ACE_Mutex use) or the ACE_SV_Semaphore_Complex that's created.
 117    */
 118   ACE_Process_Mutex (const wchar_t *name,
 119                      void *arg = 0,
 120                      mode_t mode = ACE_DEFAULT_FILE_PERMS);
 121 #endif /* ACE_HAS_WCHAR */
 122
 123   /**
 124    * Destructor.
 125    *
 126    * @note The destructor will not release an acquired mutex except
 127    * on Windows.
 128    */
 129   ~ACE_Process_Mutex ();
 130
 131   /**
 132    * Explicitly destroy the mutex.  Note that only one thread should
 133    * call this method since it doesn't protect against race
 134    * conditions.
 135    *
 136    * @return 0 on success; -1 on failure.
 137    */
 138   int remove ();
 139
 140   /**
 141    * Acquire lock ownership (wait on queue if necessary).
 142    *
 143    * @return 0 on success; -1 on failure.
 144    */
 145   int acquire ();
 146
 147   /**
 148    * Acquire lock ownership, but timeout if lock if hasn't been
 149    * acquired by given time.
 150    *
 151    * @param tv the absolute time until which the caller is willing to
 152    * wait to acquire the lock.
 153    *
 154    * @return 0 on success; -1 on failure.
 155    */
 156   int acquire (ACE_Time_Value &tv);
 157
 158   /**
 159    * Conditionally acquire lock (i.e., don't wait on queue).
 160    *
 161    * @return 0 on success; -1 on failure.  If the lock could not be acquired
 162    * because someone else already had the lock, @c errno is set to @c EBUSY.
 163    */
 164   int tryacquire ();
 165
 166   /// Release lock and unblock a thread at head of queue.
 167   int release ();
 168
 169   /// Acquire lock ownership (wait on queue if necessary).
 170   int acquire_read ();
 171
 172   /// Acquire lock ownership (wait on queue if necessary).
 173   int acquire_write ();
 174
 175   /**
 176    * Conditionally acquire a lock (i.e., won't block).  Returns -1 on
 177    * failure.  If we "failed" because someone else already had the
 178    * lock, @c errno is set to @c EBUSY.
 179    */
 180   int tryacquire_read ();
 181
 182   /**
 183    * Conditionally acquire a lock (i.e., won't block).  Returns -1 on
 184    * failure.  If we "failed" because someone else already had the
 185    * lock, @c errno is set to @c EBUSY.
 186    */
 187   int tryacquire_write ();
 188
 189   /**
 190    * This is only here for consistency with the other synchronization
 191    * APIs and usability with Lock adapters. Assumes the caller already has
 192    * acquired the mutex and returns 0 in all cases.
 193    */
 194   int tryacquire_write_upgrade ();
 195
 196 #if !defined (_ACE_USE_SV_SEM)
 197   /// Return the underlying mutex.
 198   const ACE_mutex_t &lock () const;
 199 #endif /* !_ACE_USE_SV_SEM */
 200
 201   /// Get the name used for the lock, or null if no name is used.
 202   const ACE_TCHAR *name () const;
 203
 204   /// If a file was created as the underlying storage for the mutex,
 205   /// remove it from the filesystem.
 206   static int unlink (const ACE_TCHAR *name);
 207
 208   /// Dump the state of an object.
 209   void dump () const;
 210
 211   /// Declare the dynamic allocation hooks.
 212   ACE_ALLOC_HOOK_DECLARE;
 213
 214 private:
 215   /// If the user does not provide a name we generate a unique name in
 216   /// this buffer.
 217   ACE_TCHAR name_[ACE_UNIQUE_NAME_LEN];
 218
 219   /// Create and return the unique name.
 220   const ACE_TCHAR *unique_name ();
 221
 222 #if defined (_ACE_USE_SV_SEM)
 223   /// We need this to get the right semantics...
 224   ACE_SV_Semaphore_Complex lock_;
 225 #else
 226   ACE_Mutex lock_;
 227 #endif /* _ACE_USE_SV_SEM */
 228 };
 229
 230 ACE_END_VERSIONED_NAMESPACE_DECL
 231
 232 #if defined (__ACE_INLINE__)
 233 #include "ace/Process_Mutex.inl"
 234 #endif /* __ACE_INLINE__ */
 235
 236 #include /**/ "ace/post.h"
 237
 238 #endif /* ACE_PROCESS_MUTEX_H */