TutCondWait

Name

TutCondWait — wait to be awakened by a condition variable

Synopsis

T_BOOL TutCondWait(cond, mutex, timeout) 
T_COND cond; 
T_MUTEX mutex; 
T_REAL8 timeout; 

Arguments

cond — condition variable to wait on

mutex — locked mutex to release and re-obtain

timeout — maximum number of seconds to wait for condition variable

Return Values

TRUE if thread was awakened by the condition variable, FALSE otherwise.

Diagnostics

If TutCondWait fails, it returns FALSE and sets the global SmartSockets error number to one of:

Description

TutCondWait causes the calling thread to be suspended until awakened by the condition variable or until the timeout period specified has expired. The reserved timeout value T_TIMEOUT_FOREVER may be used to specify an infinite wait. The mutex passed to this function must be locked at the time the function is called. The mutex is unlocked while the thread is suspended and locked again before the function returns.

Caution

Care must be taken to assure that the mutex passed to this function has not been recursively locked by the calling thread. TutCondWait unlocks the mutex passed to it so as to allow other threads access to the protected resources utilized by the condition variable’s predicate. If the calling thread holds recursive locks on the mutex, no other threads are able to obtain a lock on the mutex so as to change the state of the predicate.

The semantics of condition variables can also lead to threads being awakened at times they should not. TutCondWait must normally be called within a loop whose controlling expression is a test of the predicate that the condition variable is intended to reflect. See the example below.

See Also

TutCondCreate, TutCondWakeAll

Examples

This example creates a condition variable, waits to be awakened and then destroys the condition variable:

T_COND cond; 
T_MUTEX mutex; 
T_BOOL status; 
 
cond = TutCondCreate(); 
if (T_INVALID_COND == cond) { 
  /* error */ 
} 
 
/* create mutex with initial lock */ 
mutex = TutMutexCreate(TRUE); 
if (T_INVALID_MUTEX == mutex) { 
  /* error */ 
} 
 
/* wait for condition */ 
while (!predicate()) { 
  status = TutCondWait(cond, mutex, T_TIMEOUT_FOREVER); 
  if (FALSE == status) { 
    /* error */ 
  } 
} 
 
... 
 
if (!TutCondDestroy(cond)) { 
  /* error */ 
} 
 
if (!TutMutexDestroy(mutex)) { 
  /* error */ 
}