dep/ACE_wrappers/ace/Process_Mutex.h

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