ACE/ace/Recursive_Thread_Mutex.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Recursive_Thread_Mutex.h
   6  *
   7  *   Moved from Synch.h.
   8  *
   9  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu> and
  10  *          Abdullah Sowayan <abdullah.sowayan@lmco.com>
  11  */
  12 //==========================================================================
  13
  14 #ifndef ACE_RECURSIVE_THREAD_MUTEX_H
  15 #define ACE_RECURSIVE_THREAD_MUTEX_H
  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 #if !defined (ACE_HAS_THREADS)
  25 #  include "ace/Null_Mutex.h"
  26 #else /* ACE_HAS_THREADS */
  27 // ACE platform supports some form of threading.
  28
  29 #include "ace/OS_NS_Thread.h"
  30
  31 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  32
  33 /**
  34  * @class ACE_Recursive_Thread_Mutex
  35  *
  36  * @brief Implement a C++ wrapper that allows nested acquisition and
  37  * release of a mutex that occurs in the same thread.
  38  */
  39 class ACE_Export ACE_Recursive_Thread_Mutex
  40 {
  41 public:
  42   /// Initialize a recursive mutex.
  43   ACE_Recursive_Thread_Mutex (const ACE_TCHAR *name = 0,
  44                               ACE_mutexattr_t *arg = 0);
  45
  46   /// Implicitly release a recursive mutex.
  47   ~ACE_Recursive_Thread_Mutex ();
  48
  49   /**
  50    * Implicitly release a recursive mutex.  Note that only one thread
  51    * should call this method since it doesn't protect against race
  52    * conditions.
  53    */
  54   int remove ();
  55
  56   /**
  57    * Acquire a recursive mutex (will increment the nesting level and
  58    * not deadmutex if the owner of the mutex calls this method more
  59    * than once).
  60    */
  61   int acquire ();
  62
  63   /**
  64    * Block the thread until we acquire the mutex or until @a tv times
  65    * out, in which case -1 is returned with @c errno == @c ETIME.  Note
  66    * that @a tv is assumed to be in "absolute" rather than "relative"
  67    * time.  The value of @a tv is updated upon return to show the
  68    * actual (absolute) acquisition time.
  69    */
  70   int acquire (ACE_Time_Value &tv);
  71
  72   /**
  73    * If @a tv == 0 the call acquire() directly.  Otherwise, Block the
  74    * thread until we acquire the mutex or until @a tv times out, in
  75    * which case -1 is returned with @c errno == @c ETIME.  Note that
  76    * <*tv> is assumed to be in "absolute" rather than "relative" time.
  77    * The value of <*tv> is updated upon return to show the actual
  78    * (absolute) acquisition time.
  79    */
  80   int acquire (ACE_Time_Value *tv);
  81
  82   /**
  83    * Conditionally acquire a recursive mutex (i.e., won't block).
  84    * Returns -1 on failure.  If we "failed" because someone else
  85    * already had the lock, @c errno is set to @c EBUSY.
  86    */
  87   int tryacquire ();
  88
  89   /**
  90    * Acquire mutex ownership.  This calls acquire() and is only
  91    * here to make the ACE_Recusive_Thread_Mutex interface consistent
  92    * with the other synchronization APIs.
  93    */
  94   int acquire_read ();
  95
  96   /**
  97    * Acquire mutex ownership.  This calls acquire() and is only
  98    * here to make the ACE_Recusive_Thread_Mutex interface consistent
  99    * with the other synchronization APIs.
 100    */
 101   int acquire_write ();
 102
 103   /**
 104    * Conditionally acquire mutex (i.e., won't block).  This calls
 105    * tryacquire() and is only here to make the
 106    * ACE_Recusive_Thread_Mutex interface consistent with the other
 107    * synchronization APIs.  Returns -1 on failure.  If we "failed"
 108    * because someone else already had the lock, @c errno is set to
 109    * @c EBUSY.
 110    */
 111   int tryacquire_read ();
 112
 113   /**
 114    * Conditionally acquire mutex (i.e., won't block).  This calls
 115    * tryacquire() and is only here to make the
 116    * ACE_Recusive_Thread_Mutex interface consistent with the other
 117    * synchronization APIs.  Returns -1 on failure.  If we "failed"
 118    * because someone else already had the lock, @c errno is set to
 119    * @c EBUSY.
 120    */
 121   int tryacquire_write ();
 122
 123   /**
 124    * This is only here to make the ACE_Recursive_Thread_Mutex
 125    * interface consistent with the other synchronization APIs.
 126    * Assumes the caller has already acquired the mutex using one of
 127    * the above calls, and returns 0 (success) always.
 128    */
 129   int tryacquire_write_upgrade ();
 130
 131   /**
 132    * Releases a recursive mutex (will not release mutex until all the
 133    * nesting level drops to 0, which means the mutex is no longer
 134    * held).
 135    */
 136   int release ();
 137
 138   /// Return the id of the thread that currently owns the mutex.
 139   ACE_thread_t get_thread_id ();
 140
 141   /**
 142    * Return the nesting level of the recursion.  When a thread has
 143    * acquired the mutex for the first time, the nesting level == 1.
 144    * The nesting level is incremented every time the thread acquires
 145    * the mutex recursively.  Note that if the ACE_HAS_RECURSIVE_MUTEXES
 146    * macro is enabled then this method may return -1 on platforms that
 147    * do not expose the internal count.
 148    */
 149   int get_nesting_level ();
 150
 151   /// Returns a reference to the recursive mutex;
 152   ACE_recursive_thread_mutex_t &lock ();
 153
 154   /// Returns a reference to the recursive mutex's internal mutex;
 155   ACE_thread_mutex_t &get_nesting_mutex ();
 156
 157   /// Dump the state of an object.
 158   void dump () const;
 159
 160   /// Declare the dynamic allocation hooks.
 161   ACE_ALLOC_HOOK_DECLARE;
 162
 163 protected:
 164   // = This method should *not* be public (they hold no locks...)
 165   void set_thread_id (ACE_thread_t t);
 166
 167   /// Recursive mutex.
 168   ACE_recursive_thread_mutex_t lock_;
 169
 170   /// Keeps track of whether remove() has been called yet to avoid
 171   /// multiple remove() calls, e.g., explicitly and implicitly in the
 172   /// destructor.  This flag isn't protected by a lock, so make sure
 173   /// that you don't have multiple threads simultaneously calling
 174   /// remove() on the same object, which is a bad idea anyway...
 175   bool removed_;
 176
 177 private:
 178   // = Prevent assignment and initialization.
 179   void operator= (const ACE_Recursive_Thread_Mutex &);
 180   ACE_Recursive_Thread_Mutex (const ACE_Recursive_Thread_Mutex &);
 181 };
 182
 183 ACE_END_VERSIONED_NAMESPACE_DECL
 184
 185 #if defined (__ACE_INLINE__)
 186 #include "ace/Recursive_Thread_Mutex.inl"
 187 #endif /* __ACE_INLINE__ */
 188
 189 #endif /* !ACE_HAS_THREADS */
 190
 191 #include /**/ "ace/post.h"
 192 #endif /* ACE_RECURSIVE_THREAD_MUTEX_H */