dep/ACE_wrappers/ace/Thread_Mutex.h

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