ACE/ace/Condition_Thread_Mutex.h

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