Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

ACE_Condition Class Template Reference

ACE_Condition variable wrapper, which allows threads to block until shared data changes state. More...

#include <Synch_T.h>

Inheritance diagram for ACE_Condition:

Inheritance graph
[legend]
Collaboration diagram for ACE_Condition:

Collaboration graph
[legend]
List of all members.

Public Methods

 ACE_Condition (MUTEX &m, int type=USYNC_THREAD, const ACE_TCHAR *name=0, void *arg=0)
 Initialize the condition variable. More...

 ~ACE_Condition (void)
 Implicitly destroy the condition variable. More...

int wait (const ACE_Time_Value *abstime)
int wait (void)
 Block on condition. More...

int wait (MUTEX &mutex, const ACE_Time_Value *abstime=0)
int signal (void)
 Signal one waiting thread. More...

int broadcast (void)
 Signal *all* waiting threads. More...

int remove (void)
 Explicitly destroy the condition variable. More...

MUTEX & mutex (void)
 Returns a reference to the underlying mutex_;. More...

void dump (void) const
 Dump the state of an object. More...


Protected Attributes

ACE_cond_t cond_
 Condition variable. More...

MUTEX & mutex_
 Reference to mutex lock. More...


Private Methods

void operator= (const ACE_Condition< MUTEX > &)
 ACE_Condition (const ACE_Condition< MUTEX > &)

Detailed Description

template<class MUTEX>
class ACE_Condition< MUTEX >

ACE_Condition variable wrapper, which allows threads to block until shared data changes state.

A condition variable enables threads to atomically block and test the condition under the protection of a mutual exclu- sion lock (mutex) until the condition is satisfied. That is, the mutex must have been held by the thread before calling wait or signal on the condition. If the condition is false, a thread blocks on a condition variable and atomically releases the mutex that is waiting for the condition to change. If another thread changes the condition, it may wake up waiting threads by signaling the associated condition variable. The waiting threads, upon awakening, reacquire the mutex and re-evaluate the condition. Note, you can only parameterize <ACE_Condition> with ACE_Thread_Mutex, ACE_Recursive_Thread_Mutex, or ACE_Null_Mutex.

Definition at line 680 of file Synch_T.h.

Constructor & Destructor Documentation

template<class MUTEX>
ACE_Condition< MUTEX >::ACE_Condition (  MUTEX &    m,
int    type = USYNC_THREAD,
const ACE_TCHAR *    name = 0,
void *    arg = 0
) 
 

Initialize the condition variable.

Definition at line 104 of file Synch_T.cpp.

References ACE_DEFAULT_FILE_PERMS, ACE_ERROR, ACE_LIB_TEXT, ACE_TCHAR, ACE_OS::close, ACE_OS::cond_init, ACE_OS::ftruncate, LM_ERROR, MAP_FAILED, MAP_SHARED, ACE_OS::mmap, PROT_RDWR, ACE_OS::shm_open, and ACE_OS_String::strdup. 

00108   :
00109 #if defined (CHORUS)
00110     process_cond_(0),
00111     condname_ (0),
00112 #endif /* CHORUS */
00113     mutex_ (m)
00114 {
00115 
00116 #if defined(CHORUS)
00117   if (type == USYNC_PROCESS)
00118     {
00119       // Let's see if the shared memory entity already exists.
00120       ACE_HANDLE fd = ACE_OS::shm_open (name,
00121                                         O_RDWR | O_CREAT | O_EXCL,
00122                                         ACE_DEFAULT_FILE_PERMS);
00123       if (fd == ACE_INVALID_HANDLE)
00124         {
00125           if (errno == EEXIST)
00126             fd = ACE_OS::shm_open (name,
00127                                    O_RDWR | O_CREAT,
00128                                    ACE_DEFAULT_FILE_PERMS);
00129           else
00130             return;
00131         }
00132       else
00133         {
00134           // We own this shared memory object!  Let's set its size.
00135           if (ACE_OS::ftruncate (fd,
00136                                  sizeof (ACE_mutex_t)) == -1)
00137             {
00138               ACE_OS::close (fd);
00139               return;
00140             }
00141           this->condname_ = ACE_OS::strdup (name);
00142           if (this->condname_ == 0)
00143             {
00144               ACE_OS::close (fd);
00145               return;
00146             }
00147         }
00148 
00149       this->process_cond_ =
00150         (ACE_cond_t *) ACE_OS::mmap (0,
00151                                      sizeof (ACE_cond_t),
00152                                      PROT_RDWR,
00153                                      MAP_SHARED,
00154                                      fd,
00155                                      0);
00156       ACE_OS::close (fd);
00157       if (this->process_cond_ == MAP_FAILED)
00158         return;
00159 
00160       if (this->condname_
00161           && ACE_OS::cond_init (this->process_cond_,
00162                                 type,
00163                                 name,
00164                                 arg) != 0)
00165         return;
00166     }
00167    // It is ok to fall through into the <cond_init> below if the
00168    // USYNC_PROCESS flag is not enabled.
00169 #endif /* CHORUS */
00170 
00171   // ACE_TRACE ("ACE_Condition<MUTEX>::ACE_Condition");
00172 
00173   if (ACE_OS::cond_init (&this->cond_,
00174                          (short) type,
00175                          name,
00176                          arg) != 0)
00177     ACE_ERROR ((LM_ERROR,
00178                 ACE_LIB_TEXT ("%p\n"),
00179                 ACE_LIB_TEXT ("ACE_Condition::ACE_Condition")));
00180 }

template<class MUTEX>
ACE_Condition< MUTEX >::~ACE_Condition (  void    ) 
 

Implicitly destroy the condition variable.

Definition at line 183 of file Synch_T.cpp.

References ACE_ERROR, ACE_LIB_TEXT, LM_ERROR, and remove. 

00184 {
00185   // ACE_TRACE ("ACE_Condition<MUTEX>::~ACE_Condition");
00186 
00187   if (this->remove () == -1)
00188     ACE_ERROR ((LM_ERROR,
00189                 ACE_LIB_TEXT ("%p\n"),
00190                 ACE_LIB_TEXT ("ACE_Condition::~ACE_Condition")));
00191 }

template<class MUTEX>
ACE_Condition< MUTEX >::ACE_Condition (  const ACE_Condition< MUTEX > &    )  [private]
 

Member Function Documentation

template<class MUTEX>
ACE_INLINE int ACE_Condition< MUTEX >::broadcast (  void    ) 
 

Signal *all* waiting threads.

Definition at line 408 of file Synch_T.i.

References ACE_OS::cond_broadcast. 

00409 {
00410 // ACE_TRACE ("ACE_Condition<MUTEX>::broadcast");
00411 #if defined (CHORUS)
00412   if (this->process_cond_ != 0)
00413     return ACE_OS::cond_broadcast (this->process_cond_);
00414 #endif /* CHORUS */
00415   return ACE_OS::cond_broadcast (&this->cond_);
00416 }

template<class MUTEX>
void ACE_Condition< MUTEX >::dump (  void    )  const
 

Dump the state of an object.

Reimplemented in ACE_Thread_Condition.

Definition at line 73 of file Synch_T.cpp.

References ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, ACE_LIB_TEXT, and LM_DEBUG.

Referenced by ACE_Thread_Condition::dump. 

00074 {
00075 // ACE_TRACE ("ACE_Condition<MUTEX>::dump");
00076 
00077   ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this));
00078 #if defined (CHORUS)
00079   ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("condname_ = %s\n"), this->condname_));
00080   ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("process_cond_ = %x\n"), this->process_cond_));
00081 #endif /* CHORUS */
00082   ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("\n")));
00083   ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP));
00084 }

template<class MUTEX>
ACE_INLINE MUTEX & ACE_Condition< MUTEX >::mutex (  void    ) 
 

Returns a reference to the underlying mutex_;.

Definition at line 390 of file Synch_T.i.

References mutex_.

Referenced by wait. 

00391 {
00392   // ACE_TRACE ("ACE_Condition<MUTEX>::mutex");
00393   return this->mutex_;
00394 }

template<class MUTEX>
void ACE_Condition< MUTEX >::operator= (  const ACE_Condition< MUTEX > &    )  [private]
 

template<class MUTEX>
ACE_INLINE int ACE_Condition< MUTEX >::remove (  void    ) 
 

Explicitly destroy the condition variable.

Definition at line 339 of file Synch_T.i.

References ACE_TCHAR, ACE_OS::cond_broadcast, ACE_OS::cond_destroy, EBUSY, ACE_OS_Memory::free, ACE_OS::munmap, ACE_OS::shm_unlink, and ACE_OS::thr_yield.

Referenced by ~ACE_Condition, and ACE_Condition< ACE_Recursive_Thread_Mutex >::~ACE_Condition. 

00340 {
00341   // ACE_TRACE ("ACE_Condition<MUTEX>::remove");
00342 
00343   // cond_destroy() is called in a loop if the condition variable is
00344   // BUSY.  This avoids a condition where a condition is signaled and
00345   // because of some timing problem, the thread that is to be signaled
00346   // has called the cond_wait routine after the signal call.  Since
00347   // the condition signal is not queued in any way, deadlock occurs.
00348 
00349   int result = 0;
00350 
00351 #if defined (CHORUS)
00352   // Are we the owner?
00353   if (this->process_cond_ && this->condname_)
00354     {
00355       // Only destroy the condition if we're the ones who initialized
00356       // it.
00357       while ((result = ACE_OS::cond_destroy (this->process_cond_)) == -1
00358              && errno == EBUSY)
00359         {
00360           ACE_OS::cond_broadcast (this->process_cond_);
00361           ACE_OS::thr_yield ();
00362         }
00363       ACE_OS::munmap (this->process_cond_,
00364                       sizeof (ACE_cond_t));
00365       ACE_OS::shm_unlink (this->condname_);
00366       ACE_OS::free (ACE_static_cast (void *,
00367                                      ACE_const_cast (ACE_TCHAR *,
00368                                                      this->condname_)));
00369     }
00370   else if (this->process_cond_)
00371     {
00372       ACE_OS::munmap (this->process_cond_,
00373                       sizeof (ACE_cond_t));
00374       result = 0;
00375     }
00376   else
00377 #endif /* CHORUS */
00378 
00379     while ((result = ACE_OS::cond_destroy (&this->cond_)) == -1
00380            && errno == EBUSY)
00381       {
00382         ACE_OS::cond_broadcast (&this->cond_);
00383         ACE_OS::thr_yield ();
00384       }
00385 
00386   return result;
00387 }

template<class MUTEX>
ACE_INLINE int ACE_Condition< MUTEX >::signal (  void    ) 
 

Signal one waiting thread.

Definition at line 397 of file Synch_T.i.

References ACE_OS::cond_signal. 

00398 {
00399 // ACE_TRACE ("ACE_Condition<MUTEX>::signal");
00400 #if defined (CHORUS)
00401   if (this->process_cond_ != 0)
00402     return ACE_OS::cond_signal (this->process_cond_);
00403 #endif /* CHORUS */
00404   return ACE_OS::cond_signal (&this->cond_);
00405 }

template<class MUTEX>
int ACE_Condition< MUTEX >::wait (  MUTEX &    mutex,
const ACE_Time_Value *    abstime = 0
) 
 

Block on condition or until absolute time-of-day has passed. If abstime == 0 use "blocking" wait() semantics on the <mutex> passed as a parameter (this is useful if you need to store the <Condition> in shared memory). Else, if <abstime> != 0 and the call times out before the condition is signaled <wait> returns -1 and sets errno to ETIME.

Definition at line 207 of file Synch_T.cpp.

References ACE_OS::cond_timedwait, mutex, mutex_, and wait. 

00209 {
00210 // ACE_TRACE ("ACE_Condition<MUTEX>::wait");
00211   if (abstime == 0)
00212     return this->wait ();
00213   else
00214     {
00215 #if defined (CHORUS)
00216       if (this->process_cond_ != 0)
00217         return ACE_OS::cond_timedwait (this->process_cond_,
00218                                       &mutex_.lock_,
00219                                       (ACE_Time_Value *) abstime);
00220 #endif /* CHORUS */
00221       return ACE_OS::cond_timedwait (&this->cond_,
00222                                      &mutex.lock_,
00223                                      (ACE_Time_Value *) abstime);
00224     }
00225 }

template<class MUTEX>
int ACE_Condition< MUTEX >::wait (  void    ) 
 

Block on condition.

Definition at line 194 of file Synch_T.cpp.

References ACE_OS::cond_wait.

Referenced by wait, and ACE_Condition< ACE_Recursive_Thread_Mutex >::wait. 

00195 {
00196   // ACE_TRACE ("ACE_Condition<MUTEX>::wait");
00197 #if defined (CHORUS)
00198   if (this->process_cond_ != 0)
00199     return ACE_OS::cond_wait (this->process_cond_,
00200                               &this->mutex_.lock_);
00201 #endif /* CHORUS */
00202   return ACE_OS::cond_wait (&this->cond_,
00203                             &this->mutex_.lock_);
00204 }

template<class MUTEX>
int ACE_Condition< MUTEX >::wait (  const ACE_Time_Value *    abstime ) 
 

Block on condition, or until absolute time-of-day has passed. If abstime == 0 use "blocking" <wait> semantics. Else, if <abstime> != 0 and the call times out before the condition is signaled <wait> returns -1 and sets errno to ETIME.

Definition at line 232 of file Synch_T.cpp.

References wait. 

00233 {
00234 // ACE_TRACE ("ACE_Condition<MUTEX>::wait");
00235   return this->wait (this->mutex_, abstime);
00236 }

Member Data Documentation

template<class MUTEX>
ACE_cond_t ACE_Condition::cond_ [protected]
 

Condition variable.

Definition at line 746 of file Synch_T.h.

template<class MUTEX>
MUTEX& ACE_Condition::mutex_ [protected]
 

Reference to mutex lock.

Definition at line 749 of file Synch_T.h.

Referenced by ACE_Condition< ACE_Recursive_Thread_Mutex >::dump, mutex, ACE_Condition< ACE_Recursive_Thread_Mutex >::mutex, and wait.

The documentation for this class was generated from the following files:
Generated on Mon Jun 16 12:46:39 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002