TutCondCreate

Name

TutCondCreate — create a condition variable

Synopsis

T_COND TutCondCreate() 

Arguments

None

Return Values

Condition variable if successful, T_INVALID_COND otherwise.

Diagnostics

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

Description

TutCondCreate creates a condition variable. Condition variables provide the mechanism by which one thread can wait for another thread to complete an activity. Mutexes alone cannot do this; they can only ensure serialization of an activity. Condition variables are used in conjunction with mutexes, allowing a thread to wait until an arbitrary condition has occurred.

There are two basic operations on a condition variable: waiting for the condition and waking all waiting threads when the condition occurs. First, one or more threads wait on the condition variable. When the threads are later awakened, all waiting threads are allowed to proceed. A wake operation on a condition variable that does not have any waiting threads is not remembered. The next thread that waits on the condition variable blocks until the condition variable is again awakened.

The condition variable should be destroyed when it is no longer needed by calling TutCondDestroy.

Caution

None

See Also

TutCondDestroy, TutCondWait, 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 */ 
}