dep/ACE_wrappers/ace/Mutex.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Mutex.h
   6  *
   7  *  $Id: Mutex.h 80826 2008-03-04 14:51:23Z wotte $
   8  *
   9  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
  10  */
  11 //==========================================================================
  12
  13 #ifndef ACE_MUTEX_H
  14 #define ACE_MUTEX_H
  15
  16 #include /**/ "ace/pre.h"
  17
  18 #include /**/ "ace/ACE_export.h"
  19
  20 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  21 # pragma once
  22 #endif /* ACE_LACKS_PRAGMA_ONCE */
  23
  24 #include "ace/OS_NS_Thread.h"
  25 #include "ace/OS_NS_unistd.h"
  26 #include "ace/os_include/os_fcntl.h"
  27
  28 # if !defined (ACE_DEFAULT_MUTEX_A)
  29 #   define ACE_DEFAULT_MUTEX_A "ACE_MUTEX"
  30 # endif /* ACE_DEFAULT_MUTEX_A */
  31
  32 # if defined (ACE_HAS_WCHAR)
  33 #   define ACE_DEFAULT_MUTEX_W ACE_TEXT_WIDE(ACE_DEFAULT_MUTEX_A)
  34 # endif /* ACE_HAS_WCHAR */
  35
  36 # define ACE_DEFAULT_MUTEX ACE_TEXT (ACE_DEFAULT_MUTEX_A)
  37
  38 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  39
  40 class ACE_Time_Value;
  41
  42 /**
  43  * @class ACE_Mutex
  44  *
  45  * @brief @c ACE_Mutex wrapper (valid in same process or across
  46  *        processes (depending on @a TYPE flag)).  In general,
  47  *        however, we recommend using @a ACE_Process_Mutex or @a
  48  *        ACE_Thread_Mutex rather than @a ACE_Mutex.
  49  */
  50 class ACE_Export ACE_Mutex
  51 {
  52 public:
  53   /// Initialize the mutex.
  54   ACE_Mutex (int type = USYNC_THREAD,
  55              const ACE_TCHAR *name = 0,
  56              ACE_mutexattr_t *arg = 0,
  57              mode_t mode = ACE_DEFAULT_FILE_PERMS);
  58
  59   /// Implicitly destroy the mutex.
  60   ~ACE_Mutex (void);
  61
  62   /// Explicitly destroy the mutex.
  63   /**
  64    * @note Only one thread should call this method since it doesn't
  65    *        protect against race conditions.
  66    */
  67   int remove (void);
  68
  69   /// Acquire lock ownership (wait on queue if necessary).
  70   int acquire (void);
  71
  72   /// Block the thread until the mutex is acquired or @a tv times out,
  73   /// in which case -1 is returned and @c errno == @c ETIME.
  74   /**
  75    * @note @a tv is assumed  to be in "absolute" rather than
  76    * "     relative" time.  The value of @a tv is updated upon return
  77    *       to show the actual(absolute) acquisition time.
  78    */
  79   int acquire (ACE_Time_Value &tv);
  80
  81   /// Block the thread until the mutex is acquired or @a *tv times
  82   /// out, in which case -1 is returned and @c errno == @c ETIME.
  83   /**
  84    * If @a tv == 0 then call @c acquire() directly.  Otherwise, block
  85    * the thread until the mutex is acquired or @a tv times out, in
  86    * which case -1 is returned and @c errno == @c ETIME.
  87    *
  88    * @note @a *tv is assumed to be in "absolute" rather than
  89    *       "relative" time.  The value of @a *tv is updated upon
  90    *       return to show the actual (absolute) acquisition time.
  91    */
  92   int acquire (ACE_Time_Value *tv);
  93
  94   /// Conditionally acquire lock (i.e., don't wait on queue).
  95   /**
  96    * @return -1 on failure.  If we "failed" because someone
  97    *         else already had the lock, @c errno is set to @c EBUSY.
  98    */
  99   int tryacquire (void);
 100
 101   /// Release lock and unblock a thread at head of queue.
 102   int release (void);
 103
 104   /// Acquire mutex ownership.
 105   /**
 106    * This calls @c acquire and is only here to make the @c ACE_Mutex
 107    * interface consistent with the other synchronization APIs.
 108    */
 109   int acquire_read (void);
 110
 111   /// Acquire mutex ownership.
 112   /**
 113    * This calls @c acquire and is only here to make the @c ACE_Mutex
 114    * interface consistent with the other synchronization APIs.
 115    */
 116   int acquire_write (void);
 117
 118   /// Conditionally acquire mutex (i.e., won't block).
 119   /**
 120    * This calls @c tryacquire and is only here to make the @c ACE_Mutex
 121    * interface consistent with the other synchronization APIs.
 122    *
 123    * @return -1 on failure.  If we "failed" because someone else
 124    *         already had the lock, @c errno is set to @c EBUSY.
 125    */
 126   int tryacquire_read (void);
 127
 128   /// Conditionally acquire mutex (i.e., won't block).
 129   /**
 130    * This calls @c tryacquire and is only here to make the @c ACE_Mutex
 131    * interface consistent with the other synchronization APIs.
 132    *
 133    * @return -1 on failure.  If we "failed" because someone else
 134    *         already had the lock, @c errno is set to @c EBUSY.
 135    */
 136   int tryacquire_write (void);
 137
 138   /**
 139    * This is only here for consistency with the other synchronization
 140    * APIs and usability with Lock adapters. Assumes the caller already has
 141    * acquired the mutex and returns 0 in all cases.
 142    */
 143   int tryacquire_write_upgrade (void);
 144
 145   /// Return the underlying mutex.
 146   const ACE_mutex_t &lock (void) const;
 147
 148   /// Dump the state of an object.
 149   void dump (void) const;
 150
 151   /// Declare the dynamic allocation hooks.
 152   ACE_ALLOC_HOOK_DECLARE;
 153
 154   // = This should be protected but some C++ compilers complain...
 155 public:
 156 #if defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS)
 157   /// This lock resides in shared memory.
 158   ACE_mutex_t *process_lock_;
 159
 160   /**
 161    * Remember the name of the mutex if we created it so we can unlink
 162    * it when we go away (only the actor that initialized the memory
 163    * can destroy it).
 164    */
 165   const ACE_TCHAR *lockname_;
 166 #endif /* ACE_HAS_PTHREADS */
 167
 168   /// Mutex type supported by the OS.
 169   ACE_mutex_t lock_;
 170
 171   /// Keeps track of whether @c remove has been called yet to avoid
 172   /// multiple @c remove calls, e.g., explicitly and implicitly in the
 173   /// destructor.  This flag isn't protected by a lock, so make sure
 174   /// that you don't have multiple threads simultaneously calling
 175   /// @c remove on the same object, which is a bad idea anyway.
 176   bool removed_;
 177
 178 private:
 179   // Prevent assignment and initialization.
 180   void operator= (const ACE_Mutex &);
 181   ACE_Mutex (const ACE_Mutex &);
 182 };
 183
 184 ACE_END_VERSIONED_NAMESPACE_DECL
 185
 186 #if defined (__ACE_INLINE__)
 187 #include "ace/Mutex.inl"
 188 #endif /* __ACE_INLINE__ */
 189
 190 #include /**/ "ace/post.h"
 191
 192 #endif /* ACE_MUTEX_H */