Topics |
|
The semaphore synchronization class is implemented using condition variables and a mutually exclusive integer variable. Typically, an application uses a semaphore to limit the number of threads using a resource by causing a thread to stop and wait until another thread signals that it has arrived at a certain place in the entry function.
The following enumeration is used define integer constants used with the vbSemaphore class:
enum vbSemaphoreError { // Semaphore error codes vbSEMAPHORE_NO_ERROR = 0, // No errors reported vbSEMAPHORE_INVALID_CODE, // Invalid error code vbSEMAPHORE_DESTROY_ERROR, // Error destroying semaphore vbSEMAPHORE_INIT_ERROR, // Error initializing the semaphore vbSEMAPHORE_INTERNAL_ERROR, // Internal mutex error vbSEMAPHORE_POST_ERROR, // Error posting vbSEMAPHORE_WAIT_ERROR // Error waiting };
vbSemaphore::GetSemaphore
vbSemaphore::GetSemaphoreError
vbSemaphore::GetSemaphoreProcessType
vbSemaphore::SemaphoreDecrement
vbSemaphore::SemaphoreDestroy
vbSemaphore::SemaphoreExceptionMessage
vbSemaphore::SemaphoreIncrement
vbSemaphore::SemaphoreInit
vbSemaphore::SemaphorePost
vbSemaphore::SemaphoreValue
vbSemaphore::SemaphoreWait
vbSemaphore_t * vbSemaphore::GetSemaphore()
- Returns a pointer to the vbSemaphore_t data structure, which contains platform specific variables. NOTE: This function is provided for debugging and testing purposes only. The vbSemaphore_t data structure and the helper functions that operate on vbSemaphore_t types should not be used directly.vbSemaphoreError vbSemaphore::GetSemaphoreError()
- Returns the last reported condition variable error. The return value will match one of the integer constants defined in vbSemaphoreError enumeration.vbProcessType vbSemaphore::GetSemaphoreProcessType()
- Returns the process type for this semaphore. The return value will match one of the integer constants defined in vbProcessType enumeration.int vbSemaphore::SemaphoreDecrement()
- This is a non-blocking function that decrements the value of the semaphore. It allows threads to decrement the semaphore to some negative value as part of an initialization process. Decrements allow multiple threads to move up on a semaphore before another thread can go down. Returns a non-zero value if any errors occur. NOTE: An overloaded postfix -- operator is also provided that can be used in place of this function.int vbSemaphore::SemaphoreDestroy()
- Function used by the vbSemaphore 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 * vbSemaphore::SemaphoreExceptionMessage()
- Returns a null terminated string that can be used to log or print a semaphore exception.int vbSemaphore::SemaphoreIncrement()
- This is a non-blocking function that increments the value of the semaphore. Returns a non-zero value if any errors occur. NOTE: An overloaded postfix ++ operator is also provided that can be used in place of this function.int vbSemaphore::SemaphoreInit(vbProcessType type = vbPROCESS_PRIVATE)
- Function used by the vbSemaphore constructor to initialize the semaphore. By default the process type is set to private meaning that this semaphore can only be shared by threads of the same process. If a vbPROCESS_SHARED process type is specified the semaphore can be shared across multiple processes. Returns a non-zero value if the semaphore cannot be initialized or if any errors occur.int vbSemaphore::SemaphorePost()
- Increments the semaphore and signals any threads that are blocked. Returns a non-zero value if any errors occur.int vbSemaphore::SemaphoreValue()
- Returns the integer value of the semaphore at the time the critical section is accessed. NOTE: The value may change after the function unlocks the critical section. An int conversion function is also provided that will automatically convert vbSemaphore objects to an int type.int vbSemaphore::SemaphoreWait()
- Decrement the semaphore and block if the semaphore value is zero until another thread signals a change. Returns a non-zero value if any errors occur.The application is responsible for monitoring and handling any semaphore errors that occur following a semaphore operation. An error condition is reported to the application by any semaphore 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.
Semaphore errors are recorded by the vbSemaphore _t helper functions and stored in the vbSemaphore _t::semaphore _error variable. The semaphore error variable is accessible to the application though the vbSemaphore::GetSemaphoreError function. A semaphore error is a numeric value corresponding to one of the integer constants defined in the vbSemaphoreError enumeration. The vbSemaphore::SemaphoreExceptionMessage function can be used to log or print a semaphore exception.