Thread Variable Class

Topics:

Overview
Thread Variables
Member Functions
Error Handling

The gxThread_t class is a data structure used to initialize and store thread variables prior to and after thread creation. Thread variables are set by the gxThread base class and handled in a consistent manner across multiple platforms. A complete set of thread variables will be made available to classes derived from the gxThread base class and to the application though the use of gxThread_t pointers.

Thread Variables

Thread variables are used to store various thread information that can be used by the application to perform an operation based on the particular value. The variables are accessed directly by the gxThread class and the low-level thread API wrapper class. An application can access these variables through the gxThread_t member functions.

gxThread *entry - Pointer to this thread's entry function. The gxThread base class sets this value when a new thread is constructed or created. The thread API wrapper class uses this variable to access the thread's entry function.

gxStackSizeType stack_size - Variable used to set the thread's stack size if the default stack size is not sufficient to execute the thread's entry function. A value of zero will set the stack size to the default value of the native thread API.

gxThreadPriority thread_priority - Variable used to set the thread's priority. The thread priority value must match one of the enumerated integer constants defined in the gxThreadPriority enumeration.

gxThreadPriorityClass thread_priority_class - Variable used to set the thread's scheduling policy. The thread priority class value must match one of the enumerated integer constants defined in the gxThreadPriorityClass enumeration.

gxThreadState thread_state - Variable used by the gxThread base class to set the thread's current state. This value will match one of the integer constants defined in the gxThreadState enumeration.

gxThreadID thread_id - Variable used to store the platform specific thread ID after the thread has been created.

gxThreadAttribute thread_attribute - Platform specific thread attribute used to initialize a thread during creation.

gxThreadType thread_type - Variable used to set the thread's state. By default all threads are created as joinable threads. This value will match one of the integer constants defined in the gxThreadType enumeration.

gxThreadError thread_error - Variable used to hold the last error reported following a thread operation. This value will match one of the integer constants defined in the gxThreadError enumeration.

gxThreadExitCode thread_exit_code - Variable used to store the exit code returned by the thread's entry function or the value set following a gxThread::ExitThread() call.

void *thread_parm - Optional thread parameter pointer used to pass a parameter to thread when a new thread is constructed or created.

gxThreadObjectID thread_oid - Variable used to store the optional object ID of a thread. The OID variable can be used by an application in place of the platform-specific thread ID to identify threads in a consistent manner regardless of the platform used.

gxThreadClassID thread_cid - Variable used to store the optional class ID of a thread. The CID and OID variables can be used by an application in place of the platform-specific thread ID to identify threads in a consistent manner regardless of the platform used.

Member Functions

Thread Status Functions
Thread Status/Debug Message Functions
Thread Initialization Functions
Thread Priority Functions
Thread Error Functions
Thread Parameter Functions
Thread Class ID/Object ID Functions
Overloaded Operators

Thread Status Functions:

gxThreadState gxThread_t::GetThreadState() - Returns current state of the thread. This value will match one of the integer constants defined in the gxThreadState enumeration.

gxThreadID gxThread_t::GetThreadID() - Returns the platform specific thread ID.

gxThreadType gxThread_t::GetThreadType() - Returns the thread type. This value will match one of the integer constants defined in the gxThreadType enumeration.

gxStackSizeType gxThread_t::GetStackSize() - Returns the thread's stack size or zero if the default stack size was used.

gxThreadAttribute * gxThread_t::GetThreadAttribute() - Returns a pointer to the platform specific thread attribute used to initialize a thread during creation.

Thread Status/Debug Message Functions:

const char * gxThread_t::ThreadExceptionMessage() - Returns a null terminated string that can be used to log or print a thread exception.

const char * gxThread_t::ThreadPriorityMessage() - Returns a null terminated string that can be used to log or print the thread's priority.

const char * gxThread_t::ThreadPriorityClassMessage() - Returns a null terminated string that can be used to log or print the thread's priority class.

const char * gxThread_t::ThreadStateMessage() - Returns a null terminated string that can be used to log or print the thread's state.

const char * gxThread_t::ThreadTypeMessage() - Returns a null terminated string that can be used to log or print the thread type.

Thread Initialization Functions:

void gxThread_t::SetThreadStackSize(unsigned ssize) - Function used to set the thread's stack size if the default stack size is not sufficient to execute the thread's entry function. NOTE: This value must be set before the thread is created.

void gxThread_t::SetThreadType(gxThreadType t) - Function used to set the thread type prior to thread creation. This value must correspond to one of the integer constants defined in the gxThreadType enumeration. NOTE: This value must be set before the thread is created.

Thread Priority Functions:

void gxThread_t::SetThreadPriority(gxThreadPriority p) - Function use to set a thread priority value. This value must correspond to one of the integer constants defined in the gxThreadPriority enumeration.

gxThreadPriority gxThread_t::GetThreadPriority() - Returns the current thread priority. The return value will match one of the integer constants defined in the gxThreadPriority enumeration.

void gxThread_t::SetThreadPriorityClass(gxThreadPriorityClass prio_class) - Function use to set the thread's priority class. This value must correspond to one of the integer constants defined in the gxThreadPriorityClass enumeration.

gxThreadPriorityClass gxThread_t::GetThreadPriorityClass() - Returns the current thread priority class. The return value will match one of the integer constants defined in gxThreadPriorityClass gxthread.htm - gxThreadPriority enumeration.

Thread Error Functions:

gxThreadError gxThread_t::GetThreadError() - Returns the last reported thread error. The return value will match one of the integer constants defined in gxThreadError enumeration.

gxThreadExitCode gxThread_t::GetThreadExitCode() - Returns the value returned by the thread's entry function or the value set following a gxThread::ExitThread() call.

void gxThread_t::ResetThreadError() - Function used by the application to reset a thread error.

void gxThread_t::ResetThreadExitCode() - Function used by the application to reset the thread's exit code value to zero.

Thread Parameter Functions:

void * gxThread_t::GetThreadParm() - Returns a pointer to the optional thread parameter.

void gxThread_t::SetThreadParm(void *v) - Function used by the application to set the thread's parameter prior to thread creation.

Class ID/Object ID Functions:

gxThreadClassID gxThread_t::GetClassID() - Returns the class ID of the thread.

gxThreadObjectID gxThread_t::GetObjectID() - Returns the object ID of the thread.

void gxThread_t::SetClassID(gxThreadClassID cid) - Function used by the application to set the thread's class ID.

void gxThread_t::SetObjectID(gxThreadObjectID oid) - Function used by the application to set the thread's object ID.

Overloaded Operators:

int operator==(const gxThread_t &a, const gxThread_t &b) - Friend function used to compare the thread IDs of gxThread_t "a" and gxThread_t "b". Returns true if the IDs are equal. NOTE: This function was added specifically for UNIX variants that do not use an integer type for thread IDs.

int operator!=(const gxThread_t &a, const gxThread_t &b) - Friend function used to compare the thread IDs of gxThread_t "a" and gxThread_t "b". Returns true if the IDs are not equal. NOTE: This function was added specifically for UNIX variants that do not use an integer type for thread IDs.

Error Handling

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

Thread errors are recorded by the thread API wrapper class and stored in the gxThread_t::thread_error variable. The thread error variable is accessible to the application though the appropriate gxThread_t Error Function. A thread error is a numeric value corresponding to one of the integer constants defined in the gxThreadError enumeration. The appropriate gxThread_t Message Function can be used to log or print a thread exception.

End Of Document