ACE/ace/Condition_Thread_Mutex.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Condition_Thread_Mutex.h
   6  *
   7  *   Moved from Synch.h.
   8  *
   9  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
  10  */
  11 //==========================================================================
  12
  13 #ifndef ACE_CONDITION_THREAD_MUTEX_H
  14 #define ACE_CONDITION_THREAD_MUTEX_H
  15 #include /**/ "ace/pre.h"
  16
  17 #include /**/ "ace/ACE_export.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 #if !defined (ACE_HAS_THREADS)
  24 #  include "ace/Null_Condition.h"
  25 #else /* ACE_HAS_THREADS */
  26 // ACE platform supports some form of threading.
  27
  28 #include "ace/Thread_Mutex.h"
  29 #include "ace/Condition_Attributes.h"
  30 #include "ace/Condition_T.h"
  31
  32 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  33
  34 class ACE_Time_Value;
  35
  36 /**
  37  * @brief ACE_Condition template specialization written using
  38  * ACE_Mutexes. This allows threads to block until shared data
  39  * changes state.
  40  * A condition variable enables threads to atomically block and
  41  * test the condition under the protection of a mutual exclu-
  42  * sion lock (mutex) until the condition is satisfied.  That is,
  43  * the mutex must have been held by the thread before calling
  44  * wait or signal on the condition.  If the condition is false,
  45  * a thread blocks on a condition variable and atomically
  46  * releases the mutex that is waiting for the condition to
  47  * change.  If another thread changes the condition, it may wake
  48  * up waiting threads by signaling the associated condition
  49  * variable.  The waiting threads, upon awakening, reacquire the
  50  * mutex and re-evaluate the condition.
  51  */
  52 template <>
  53 class ACE_Export ACE_Condition<ACE_Thread_Mutex>
  54 {
  55 public:
  56   /// Initialize the condition variable.
  57   ACE_Condition (ACE_Thread_Mutex &m,
  58                  const ACE_TCHAR *name = 0,
  59                  void *arg = 0);
  60
  61   /// Initialize the condition variable.
  62   ACE_Condition (ACE_Thread_Mutex &m,
  63                  const ACE_Condition_Attributes &attributes,
  64                  const ACE_TCHAR *name = 0,
  65                  void *arg = 0);
  66
  67   /// Implicitly destroy the condition variable.
  68   ~ACE_Condition (void);
  69
  70   /**
  71    * Explicitly destroy the condition variable.  Note that only one
  72    * thread should call this method since it doesn't protect against
  73    * race conditions.
  74    */
  75   int remove (void);
  76
  77   /**
  78    * Block on condition, or until absolute time-of-day has passed.  If
  79    * abstime == 0 use "blocking" wait semantics.  Else, if @a abstime
  80    * != 0 and the call times out before the condition is signaled
  81    * wait() returns -1 and sets errno to ETIME.
  82    */
  83   int wait (const ACE_Time_Value *abstime);
  84
  85   /// Block on condition.
  86   int wait (void);
  87
  88   /**
  89    * Block on condition or until absolute time-of-day has passed.  If
  90    * abstime == 0 use "blocking" wait() semantics on the @a mutex
  91    * passed as a parameter (this is useful if you need to store the
  92    * <Condition> in shared memory).  Else, if @a abstime != 0 and the
  93    * call times out before the condition is signaled <wait> returns -1
  94    * and sets errno to ETIME.
  95    */
  96   int wait (ACE_Thread_Mutex &mutex, const ACE_Time_Value *abstime = 0);
  97
  98   /// Signal one waiting thread.
  99   int signal (void);
 100
 101   /// Signal *all* waiting threads.
 102   int broadcast (void);
 103
 104   /// Returns a reference to the underlying mutex;
 105   ACE_Thread_Mutex &mutex (void);
 106
 107   /// Dump the state of an object.
 108   void dump (void) const;
 109
 110   /// Declare the dynamic allocation hooks.
 111   ACE_ALLOC_HOOK_DECLARE;
 112
 113 protected:
 114   /// Condition variable.
 115   ACE_cond_t cond_;
 116
 117   /// Reference to mutex lock.
 118   ACE_Thread_Mutex &mutex_;
 119
 120   /// Keeps track of whether remove() has been called yet to avoid
 121   /// multiple remove() calls, e.g., explicitly and implicitly in the
 122   /// destructor.  This flag isn't protected by a lock, so make sure
 123   /// that you don't have multiple threads simultaneously calling
 124   /// remove() on the same object, which is a bad idea anyway...
 125   bool removed_;
 126
 127 private:
 128   // = Prevent assignment and initialization.
 129   void operator= (const ACE_Condition<ACE_Thread_Mutex> &);
 130   ACE_Condition (const ACE_Condition<ACE_Thread_Mutex> &);
 131 };
 132
 133 typedef ACE_Condition<ACE_Thread_Mutex> ACE_Condition_Thread_Mutex;
 134
 135 ACE_END_VERSIONED_NAMESPACE_DECL
 136
 137 #if defined (__ACE_INLINE__)
 138 #include "ace/Condition_Thread_Mutex.inl"
 139 #endif /* __ACE_INLINE__ */
 140
 141 #endif /* !ACE_HAS_THREADS */
 142
 143 #include /**/ "ace/post.h"
 144 #endif /* ACE_CONDITION_THREAD_MUTEX_H */