dep/ACE_wrappers/ace/Condition_T.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Condition_T.h
   6  *
   7  *  $Id: Condition_T.h 81462 2008-04-28 11:39:40Z johnnyw $
   8  *
   9  *   Moved from Synch.h.
  10  *
  11  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
  12  */
  13 //==========================================================================
  14
  15 #ifndef ACE_CONDITION_T_H
  16 #define ACE_CONDITION_T_H
  17
  18 #include /**/ "ace/pre.h"
  19
  20 #include "ace/OS_NS_Thread.h"
  21 #include "ace/Lock.h"
  22
  23 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  24 # pragma once
  25 #endif /* ACE_LACKS_PRAGMA_ONCE */
  26
  27 #if defined (ACE_HAS_THREADS) /* ACE platform supports some form of threading. */
  28
  29 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  30
  31 class ACE_Time_Value;
  32
  33 /**
  34  * @class ACE_Condition
  35  *
  36  * @brief ACE_Condition variable wrapper, which allows threads to block
  37  * until shared data changes state.
  38  *
  39  * A condition variable enables threads to atomically block and
  40  * test the condition under the protection of a mutual exclu-
  41  * sion lock (mutex) until the condition is satisfied.  That is,
  42  * the mutex must have been held by the thread before calling
  43  * wait or signal on the condition.  If the condition is false,
  44  * a thread blocks on a condition variable and atomically
  45  * releases the mutex that is waiting for the condition to
  46  * change.  If another thread changes the condition, it may wake
  47  * up waiting threads by signaling the associated condition
  48  * variable.  The waiting threads, upon awakening, reacquire the
  49  * mutex and re-evaluate the condition.
  50  * Note, you can only parameterize <ACE_Condition> with
  51  * @a ACE_Thread_Mutex, @a ACE_Recursive_Thread_Mutex, or @a ACE_Null_Mutex.
  52  */
  53 template <class MUTEX>
  54 class ACE_Condition
  55 {
  56 public:
  57   // = Initialiation and termination methods.
  58   /// Initialize the condition variable.
  59   ACE_Condition (MUTEX &m, int type = USYNC_THREAD,
  60                  const ACE_TCHAR *name = 0, void *arg = 0);
  61
  62   /// Implicitly destroy the condition variable.
  63   ~ACE_Condition (void);
  64
  65   // = Lock accessors.
  66   /**
  67    * Block on condition, or until absolute time-of-day has passed.  If
  68    * @a abstime == 0 use "blocking" <wait> semantics.  Else, if @a abstime
  69    * != 0 and the call times out before the condition is signaled
  70    * <wait> returns -1 and sets errno to ETIME.
  71    */
  72   int wait (const ACE_Time_Value *abstime);
  73
  74   /// Block on condition.
  75   int wait (void);
  76
  77   /**
  78    * Block on condition or until absolute time-of-day has passed.  If
  79    * abstime == 0 use "blocking" wait() semantics on the <mutex>
  80    * passed as a parameter (this is useful if you need to store the
  81    * <Condition> in shared memory).  Else, if <abstime> != 0 and the
  82    * call times out before the condition is signaled <wait> returns -1
  83    * and sets errno to ETIME.
  84    */
  85   int wait (MUTEX &mutex, const ACE_Time_Value *abstime = 0);
  86
  87   /// Signal one waiting thread.
  88   int signal (void);
  89
  90   /// Signal *all* waiting threads.
  91   int broadcast (void);
  92
  93   // = Utility methods.
  94   /// Explicitly destroy the condition variable.
  95   int remove (void);
  96
  97   /// Returns a reference to the underlying mutex_;
  98   MUTEX &mutex (void);
  99
 100   /// Dump the state of an object.
 101   void dump (void) const;
 102
 103   // ACE_ALLOC_HOOK_DECLARE;
 104   // Declare the dynamic allocation hooks.
 105
 106 protected:
 107   /// Condition variable.
 108   ACE_cond_t cond_;
 109
 110   /// Reference to mutex lock.
 111   MUTEX &mutex_;
 112
 113 private:
 114   // = Prevent assignment and initialization.
 115   ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Condition<MUTEX> &))
 116   ACE_UNIMPLEMENTED_FUNC (ACE_Condition (const ACE_Condition<MUTEX> &))
 117 };
 118
 119 /**
 120  * @class ACE_Thread_Condition
 121  *
 122  * @brief ACE_Condition variable wrapper that works within processes.
 123  *
 124  * A condition variable enables threads to atomically block and
 125  * test the condition under the protection of a mutual exclu-
 126  * sion lock (mutex) until the condition is satisfied.  That is,
 127  * the mutex must have been held by the thread before calling
 128  * wait or signal on the condition.  If the condition is false,
 129  * a thread blocks on a condition variable and atomically
 130  * releases the mutex that is waiting for the condition to
 131  * change.  If another thread changes the condition, it may wake
 132  * up waiting threads by signaling the associated condition
 133  * variable.  The waiting threads, upon awakening, reacquire the
 134  * mutex and re-evaluate the condition.
 135  */
 136 template <class MUTEX>
 137 class ACE_Thread_Condition : public ACE_Condition<MUTEX>
 138 {
 139 public:
 140   // = Initialization method.
 141   ACE_Thread_Condition (MUTEX &m, const ACE_TCHAR *name = 0, void *arg = 0);
 142
 143   /// Dump the state of an object.
 144   void dump (void) const;
 145
 146   // ACE_ALLOC_HOOK_DECLARE;
 147   // Declare the dynamic allocation hooks.
 148 };
 149
 150 ACE_END_VERSIONED_NAMESPACE_DECL
 151
 152 #if defined (__ACE_INLINE__)
 153 #include "ace/Condition_T.inl"
 154 #endif /* __ACE_INLINE__ */
 155
 156 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
 157 #include "ace/Condition_T.cpp"
 158 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
 159
 160 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
 161 #pragma implementation ("Condition_T.cpp")
 162 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
 163
 164 #endif /* ACE_HAS_THREADS */
 165
 166 #include /**/ "ace/post.h"
 167 #endif /* ACE_CONDITION_T_H */