Topics |
|
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.
The following enumeration is used define integer constants used with the vbMutex class:
enum vbMutexError { // Mutex error codes vbMUTEX_NO_ERROR = 0, // No errors reported vbMUTEX_INVALID_CODE, // Invalid error code vbMUTEX_ATTR_DESTROY_ERROR, // Error destroying attribute vbMUTEX_ATTR_INIT_ERROR, // Error initializing the attribute vbMUTEX_DESTROY_ERROR, // Error destroying mutex vbMUTEX_INIT_ERROR, // Error initializing the mutex vbMUTEX_LOCK_ERROR, // Error locking the mutex vbMUTEX_SET_SHARE_ERROR, // Error setting shared attribute vbMUTEX_TRY_LOCK_ERROR, // Error trying to lock the mutex vbMUTEX_UNLOCK_ERROR // Error unlocking the mutex };
vbMutex::GetMutex
vbMutex::GetMutexError
vbMutex::GetMutexProcessType
vbMutex::IsLocked
vbMutex::MutexDestroy
vbMutex::MutexExceptionMessage
vbMutex::MutexInit
vbMutex::MutexLock
vbMutex::MutexTryLock
vbMutex::MutexUnlock
vbMutex::NumLocks
vbMutex_t * vbMutex::GetMutex()
- Returns a pointer to the vbMutex_t data structure, which contains platform specific variables. NOTE: This function is provided for debugging and testing purposes only. The vbMutex_t data structure and the helper functions that operate on vbMutex_t types should not be used directly.vbMutexError vbMutex::GetMutexError()
- Returns the last reported mutex error. The return value will match one of the integer constants defined in vbMutexError enumeration.vbProcessType vbMutex::GetMutexProcessType()
- Returns the process type for this mutex. The return value will match one of the integer constants defined in vbProcessType enumeration.int vbMutex::IsLocked()
- Returns true if the mutex is locked.int vbMutex::MutexDestroy()
- Function used by the vbMutex 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 * vbMutex::MutexExceptionMessage()
- Returns a null terminated string that can be used to log or print a mutex exception.int vbMutex::MutexInit(vbProcessType type = vbPROCESS_PRIVATE)
- Function used by the vbMutex 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 vbPROCESS_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 vbMutex::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 vbMutex::MutexTryLock()
- Test the mutex state before locking it. Returns a non-zero if any errors occur.int vbMutex::MutexUnlock()
- Unlock the mutex. Returns a non-zero value if the mutex cannot be unlocked or if any errors occur.int vbMutex::NumLocks()
- Returns the total number of locks.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 vbMutex_t helper functions and stored in the vbMutex_t::mutex_error variable. The mutex error variable is accessible to the application though the vbMutex::GetMutexError function. A mutex error is a numeric value corresponding to one of the integer constants defined in the vbMutexError enumeration. The vbMutex::MutexExceptionMessage function can be used to log or print a mutex exception.