Condition Variable Class

Topics:

Overview
Enumerations
Functions
Error Handling

The condition variable class is a synchronization mechanism used by a thread to block its own execution until an expression involving shared data reaches a particular state.

Enumerations

The following enumeration is used define integer constants used with the gxCondition class:

enum gxConditionError { // Condition variables error codes
  gxCONDITION_NO_ERROR = 0, // No errors reported
  gxCONDITION_INVALID_CODE, // Invalid error code
  
  gxCONDITION_ATTR_DESTROY_ERROR, // Error destroying attribute
  gxCONDITION_ATTR_INIT_ERROR,    // Error initializing the attribute
  gxCONDITION_BROADCAST_ERROR,    // Error broadcasting
  gxCONDITION_DESTROY_ERROR,      // Error destroying condition
  gxCONDITION_EXTERNAL_ERROR,     // External mutex error
  gxCONDITION_INIT_ERROR,         // Error initializing condition
  gxCONDITION_INTERNAL_ERROR,     // Internal condition error
  gxCONDITION_SET_SHARE_ERROR,    // Error setting shared attribute
  gxCONDITION_SIGNAL_ERROR,       // Error signaling
  gxCONDITION_TIMED_WAIT_ERROR,   // Error during a timed waiting
  gxCONDITION_WAIT_ERROR          // Error waiting
};

Functions

gxCondition::ConditionBroadcast
gxCondition::ConditionDestroy
gxCondition::ConditionExceptionMessage
gxCondition::ConditionInit
gxCondition::ConditionSignal
gxCondition::ConditionTimedWait
gxCondition::ConditionWait
gxCondition::GetCondition
gxCondition::GetConditionError
gxCondition::GetConditionProcessType
gxCondition::NumWaiting
gxCondition::ThreadsWaiting

int gxCondition::ConditionBroadcast() - Function used to wake up all threads waiting on this condition. Returns a non-zero value if any errors occur.

int gxCondition::ConditionDestroy() - Function used by the gxCondition destructor to destroy the condition variable and free its resources. Returns a non-zero value if the condition variable cannot be destroyed or if any errors occur.

const char * gxCondition::ConditionExceptionMessage() - Returns a null terminated string that can be used to log or print a condition exception.

int gxCondition::ConditionInit(gxProcessType type = gxPROCESS_PRIVATE) - Function used by the gxCondition constructor to initialize the condition variable. By default the process type is set to private meaning that this condition variable can only be shared by threads of the same process. If a gxPROCESS_SHARED process type is specified the condition variable can be shared across multiple processes. Returns a non-zero value if the condition variable cannot be initialized or if any errors occur.

int gxCondition::ConditionSignal() - Function used to wake up a thread waiting on the this condition. Returns a non-zero value if any errors occur.

int gxCondition::ConditionTimedWait(gxMutex *m, unsigned long sec, unsigned long nsec=0) - Function used to block a thread from its own execution until this condition is signaled or the timeout value elapses. Returns a non-zero value if any errors occur.

int gxCondition::ConditionWait(gxMutex *m) - Function used to block a thread from its own execution until this condition is signaled. Returns a non-zero value if any errors occur.

gxCondition_t * gxCondition::GetCondition() - Returns a pointer to the gxCondition_t data structure, which contains platform specific variables. NOTE: This function is provided for debugging and testing purposes only. The gxCondition_t data structure and the helper functions that operate on gxCondition_t types should not be used directly.

gxConditionError gxCondition::GetConditionError() - Returns the last reported condition variable error. The return value will match one of the integer constants defined in gxConditionError enumeration.

gxProcessType gxCondition::GetConditionProcessType() - Returns the process type for this condition. The return value will match one of the integer constants defined in gxProcessType enumeration.

int gxCondition::NumWaiting() - Returns the total number of threads waiting on this condition.

int gxCondition::ThreadsWaiting() - Returns true if any threads are waiting on this condition.

Error Handling

The application is responsible for monitoring and handling any condition variable errors that occur following a condition variable operation. An error condition is reported to the application by any condition variable function returning a non-zero value. If any value other then 0 is returned the application must generate the appropriate exception to handle the error condition.

Condition variable errors are recorded by the gxCondition_t helper functions and stored in the gxCondition_t::condition_error variable. The condition variable error variable is accessible to the application though the gxCondition::GetConditionError function. A condition variable error is a numeric value corresponding to one of the integer constants defined in the gxConditionError enumeration. The gxCondition::ConditionExceptionMessage function can be used to log or print a condition variable exception.

End Of Document