Semaphore Class

Topics:

Overview
Enumerations
Functions
Error Handling

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.

Enumerations

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

enum gxSemaphoreError { // Semaphore error codes
  gxSEMAPHORE_NO_ERROR = 0,   // No errors reported
  gxSEMAPHORE_INVALID_CODE,   // Invalid error code
  gxSEMAPHORE_DESTROY_ERROR,  // Error destroying semaphore
  gxSEMAPHORE_INIT_ERROR,     // Error initializing the semaphore
  gxSEMAPHORE_INTERNAL_ERROR, // Internal mutex error
  gxSEMAPHORE_POST_ERROR,     // Error posting
  gxSEMAPHORE_WAIT_ERROR      // Error waiting
};

Functions

gxSemaphore::GetSemaphore
gxSemaphore::GetSemaphoreError
gxSemaphore::GetSemaphoreProcessType
gxSemaphore::SemaphoreDecrement
gxSemaphore::SemaphoreDestroy
gxSemaphore::SemaphoreExceptionMessage
gxSemaphore::SemaphoreIncrement
gxSemaphore::SemaphoreInit
gxSemaphore::SemaphorePost
gxSemaphore::SemaphoreValue
gxSemaphore::SemaphoreWait

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

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

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

int gxSemaphore::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 gxSemaphore::SemaphoreDestroy() - Function used by the gxSemaphore 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 * gxSemaphore::SemaphoreExceptionMessage() - Returns a null terminated string that can be used to log or print a semaphore exception.

int gxSemaphore::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 gxSemaphore::SemaphoreInit(gxProcessType type = gxPROCESS_PRIVATE) - Function used by the gxSemaphore 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 gxPROCESS_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 gxSemaphore::SemaphorePost() - Increments the semaphore and signals any threads that are blocked. Returns a non-zero value if any errors occur.

int gxSemaphore::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 gxSemaphore objects to an int type.

int gxSemaphore::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.

Error Handling

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 gxSemaphore _t helper functions and stored in the gxSemaphore_t::semaphore_error variable. The semaphore error variable is accessible to the application though the gxSemaphore::GetSemaphoreError function. A semaphore error is a numeric value corresponding to one of the integer constants defined in the gxSemaphoreError enumeration. The gxSemaphore::SemaphoreExceptionMessage function can be used to log or print a semaphore exception.

End Of Document