Mutex Class

Topics:

Overview
Enumerations
Mutex Functions
Error Handling

The mutual exclusion class provides simple lock primitives that can be used to control access to a shared resource. A mutex is used to cause other threads to wait while the thread holding the mutex executes code in a critical section.

Enumerations

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

enum gxMutexError { // Mutex error codes
  gxMUTEX_NO_ERROR = 0, // No errors reported
  gxMUTEX_INVALID_CODE, // Invalid error code

  gxMUTEX_ATTR_DESTROY_ERROR, // Error destroying attribute
  gxMUTEX_ATTR_INIT_ERROR,    // Error initializing the attribute
  gxMUTEX_DESTROY_ERROR,      // Error destroying mutex
  gxMUTEX_INIT_ERROR,         // Error initializing the mutex
  gxMUTEX_LOCK_ERROR,         // Error locking the mutex
  gxMUTEX_SET_SHARE_ERROR,    // Error setting shared attribute
  gxMUTEX_TRY_LOCK_ERROR,     // Error trying to lock the mutex
  gxMUTEX_UNLOCK_ERROR        // Error unlocking the mutex
};

Mutex Functions

gxMutex::GetMutex
gxMutex::GetMutexError
gxMutex::GetMutexProcessType
gxMutex::IsLocked
gxMutex::MutexDestroy
gxMutex::MutexExceptionMessage
gxMutex::MutexInit
gxMutex::MutexLock
gxMutex::MutexTryLock
gxMutex::MutexUnlock
gxMutex::NumLocks

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

gxMutexError gxMutex::GetMutexError() - Returns the last reported mutex error. The return value will match one of the integer constants defined in gxMutexError enumeration.

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

int gxMutex::IsLocked() - Returns true if the mutex is locked.

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

const char * gxMutex::MutexExceptionMessage() - Returns a null terminated string that can be used to log or print a mutex exception.

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

int gxMutex::MutexLock() - Lock the mutex. If the mutex is already locked, the calling thread blocks until the mutex becomes available. Returns a non-zero value if the mutex cannot be locked or if any errors occur.

int gxMutex::MutexTryLock() - Test the mutex state before locking it. Returns a non-zero if any errors occur.

int gxMutex::MutexUnlock() - Unlock the mutex. Returns a non-zero value if the mutex cannot be unlocked or if any errors occur.

int gxMutex::NumLocks() - Returns the total number of locks.

Error Handling

The application is responsible for monitoring and handling any mutex errors that occur following a mutex operation. An error condition is reported to the application by any mutex 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.

Mutex errors are recorded by the gxMutex_t helper functions and stored in the gxMutex_t::mutex_error variable. The mutex error variable is accessible to the application though the gxMutex::GetMutexError function. A mutex error is a numeric value corresponding to one of the integer constants defined in the gxMutexError enumeration. The gxMutex::MutexExceptionMessage function can be used to log or print a mutex exception.

End Of Document