ACE/ace/Recursive_Thread_Mutex.h

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