ACE/ace/Thread_Mutex.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Thread_Mutex.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_THREAD_MUTEX_H
  12 #define ACE_THREAD_MUTEX_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include /**/ "ace/config-all.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #if !defined (ACE_HAS_THREADS)
  22 #  include "ace/Null_Mutex.h"
  23 #else /* ACE_HAS_THREADS */
  24 // ACE platform supports some form of threading.
  25
  26 #include /**/ "ace/ACE_export.h"
  27 #include "ace/OS_NS_Thread.h"
  28
  29 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  30
  31 /**
  32  * @class ACE_Thread_Mutex
  33  *
  34  * @brief ACE_Thread_Mutex wrapper (only valid for threads in the same
  35  * process).
  36  *
  37  * This implementation is optimized for locking threads that are
  38  * in the same process.  It maps to <CRITICAL_SECTION>s on NT
  39  * and <ACE_mutex_t> with <type> set to <USYNC_THREAD> on UNIX.
  40  * ACE_Thread_Mutex is recursive on some platforms (like
  41  * Win32). However, on most platforms it is not
  42  * recursive.  To be totally safe and portable, developers
  43  * should use ACE_Recursive_Thread_Mutex when they need a
  44  * recursive mutex.
  45  */
  46 class ACE_Export ACE_Thread_Mutex
  47 {
  48 public:
  49   /// Constructor.
  50   ACE_Thread_Mutex (const ACE_TCHAR *name = 0,
  51                     ACE_mutexattr_t *attributes = 0);
  52
  53   /// Implicitly destroy the mutex.
  54   ~ACE_Thread_Mutex ();
  55
  56   /**
  57    * Explicitly destroy the mutex.  Note that only one thread should
  58    * call this method since it doesn't protect against race
  59    * conditions.
  60    */
  61   int remove ();
  62
  63   /// Acquire lock ownership (wait on queue if necessary).
  64   int acquire ();
  65
  66   /**
  67    * Block the thread until we acquire the mutex or until @a tv times
  68    * out, in which case -1 is returned with @c errno == @c ETIME.  Note
  69    * that @a tv is assumed to be in "absolute" rather than "relative"
  70    * time.  The value of @a tv is updated upon return to show the
  71    * actual (absolute) acquisition time.
  72    */
  73   int acquire (ACE_Time_Value &tv);
  74
  75   /**
  76    * If @a tv == 0 the call acquire() directly.  Otherwise, Block the
  77    * thread until we acquire the mutex or until @a tv times out, in
  78    * which case -1 is returned with @c errno == @c ETIME.  Note that
  79    * @a tv is assumed to be in "absolute" rather than "relative" time.
  80    * The value of @a tv is updated upon return to show the actual
  81    * (absolute) acquisition time.
  82    */
  83   int acquire (ACE_Time_Value *tv);
  84
  85   /**
  86    * Conditionally acquire lock (i.e., don't wait on queue).  Returns
  87    * -1 on failure.  If we "failed" because someone else already had
  88    * the lock, @c errno is set to @c EBUSY.
  89    */
  90   int tryacquire ();
  91
  92   /// Release lock and unblock a thread at head of queue.
  93   int release ();
  94
  95   /**
  96    * Acquire mutex ownership.  This calls acquire() and is only here
  97    * to make the ACE_Thread_Mutex interface consistent with the
  98    * other synchronization APIs.
  99    */
 100   int acquire_read ();
 101
 102   /**
 103    * Acquire mutex ownership.  This calls acquire() and is only here
 104    * to make the ACE_Thread_Mutex interface consistent with the
 105    * other synchronization APIs.
 106    */
 107   int acquire_write ();
 108
 109   /**
 110    * Conditionally acquire mutex (i.e., won't block).  This calls
 111    * tryacquire() and is only here to make the ACE_Thread_Mutex
 112    * interface consistent with the other synchronization APIs.
 113    * Returns -1 on failure.  If we "failed" because someone else
 114    * already had the lock, @c errno is set to @c EBUSY.
 115    */
 116   int tryacquire_read ();
 117
 118   /**
 119    * Conditionally acquire mutex (i.e., won't block).  This calls
 120    * tryacquire() and is only here to make the ACE_Thread_Mutex
 121    * interface consistent with the other synchronization APIs.
 122    * Returns -1 on failure.  If we "failed" because someone else
 123    * already had the lock, @c errno is set to @c EBUSY.
 124    */
 125   int tryacquire_write ();
 126
 127   /**
 128    * This is only here to make the ACE_Thread_Mutex interface
 129    * consistent with the other synchronization APIs.  Assumes the
 130    * caller has already acquired the mutex using one of the above
 131    * calls, and returns 0 (success) always.
 132    */
 133   int tryacquire_write_upgrade ();
 134
 135   /// Return the underlying mutex.
 136   const ACE_thread_mutex_t &lock () const;
 137   ACE_thread_mutex_t &lock ();
 138
 139   /// Dump the state of an object.
 140   void dump () const;
 141
 142   /// Declare the dynamic allocation hooks.
 143   ACE_ALLOC_HOOK_DECLARE;
 144
 145 protected:
 146   /// Mutex type that supports single-process locking efficiently.
 147   ACE_thread_mutex_t lock_;
 148
 149   /// Keeps track of whether remove() has been called yet to avoid
 150   /// multiple <remove> calls, e.g., explicitly and implicitly in the
 151   /// destructor.  This flag isn't protected by a lock, so make sure
 152   /// that you don't have multiple threads simultaneously calling
 153   /// <remove> on the same object, which is a bad idea anyway...
 154   bool removed_;
 155
 156 private:
 157   void operator= (const ACE_Thread_Mutex &) = delete;
 158   ACE_Thread_Mutex (const ACE_Thread_Mutex &) = delete;
 159 };
 160
 161 ACE_END_VERSIONED_NAMESPACE_DECL
 162
 163 #if defined (__ACE_INLINE__)
 164 #include "ace/Thread_Mutex.inl"
 165 #endif /* __ACE_INLINE__ */
 166
 167 #endif /* !ACE_HAS_THREADS */
 168
 169 #include /**/ "ace/post.h"
 170 #endif /* ACE_THREAD_MUTEX_H */