Main Page | Modules | Namespace List | Class Hierarchy | Class List | File List | Class Members | File Members

Thread library


Detailed Description

C function library for basic mutex, thread, and timer functionality to ensure portability across a wide variety of operating systems and integration models (multi-threaded, multi-process, etc.

).


Defines

#define VXITRD_DEFINE_THREAD_FUNC(funcName, userData)   VXItrdThreadArg funcName(VXItrdThreadArg userData)

Typedefs

typedef VXItrdThreadArg(* VXItrdThreadStartFunc )(VXItrdThreadArg userData)
typedef enum VXItrdResult VXItrdResult
 Result codes for functions.

Enumerations

enum  VXItrdResult {
  VXItrd_RESULT_FATAL_ERROR = -100, VXItrd_RESULT_IO_ERROR = -8, VXItrd_RESULT_OUT_OF_MEMORY = -7, VXItrd_RESULT_SYSTEM_ERROR = -6,
  VXItrd_RESULT_PLATFORM_ERROR = -5, VXItrd_RESULT_BUFFER_TOO_SMALL = -4, VXItrd_RESULT_INVALID_PROP_NAME = -3, VXItrd_RESULT_INVALID_PROP_VALUE = -2,
  VXItrd_RESULT_INVALID_ARGUMENT = -1, VXItrd_RESULT_SUCCESS = 0, VXItrd_RESULT_FAILURE = 1, VXItrd_RESULT_NON_FATAL_ERROR = 2,
  VXItrd_RESULT_UNSUPPORTED = 100
}
 Result codes for functions. More...

Functions

VXITRD_API VXItrdResult VXItrdMutexCreate (VXItrdMutex **mutex)
 Create a mutex.
VXITRD_API VXItrdResult VXItrdMutexDestroy (VXItrdMutex **mutex)
 Destroy a mutex.
VXITRD_API VXItrdResult VXItrdMutexLock (VXItrdMutex *mutex)
 Lock a mutex.
VXITRD_API VXItrdResult VXItrdMutexUnlock (VXItrdMutex *mutex)
 Unlock a Mutex.
VXITRD_API VXItrdResult VXItrdThreadCreate (VXItrdThread **thread, VXItrdThreadStartFunc startFunc, VXItrdThreadArg arg)
 Create a thread.
VXITRD_API VXItrdResult VXItrdThreadDestroyHandle (VXItrdThread **thread)
 Destroy a thread handle.
VXITRD_API void VXItrdThreadExit (VXItrdThreadArg status)
 Terminate a thread (called by the thread to exit).
VXITRD_API VXItrdResult VXItrdThreadJoin (VXItrdThread *thread, VXItrdThreadArg *status, long timeout)
 Wait for the termination of a specified thread.
VXITRD_API VXIthreadID VXItrdThreadGetIDFromHandle (VXItrdThread *thread)
 Get the thread ID for the specified thread.
VXITRD_API VXIthreadID VXItrdThreadGetID (void)
 Get the thread ID for the current thread.
VXITRD_API void VXItrdThreadYield (void)
 Yield execution of the current thread to other threads/processes.
VXITRD_API VXItrdResult VXItrdTimerCreate (VXItrdTimer **timer)
 Create a timer.
VXITRD_API VXItrdResult VXItrdTimerDestroy (VXItrdTimer **timer)
 Destroy a timer.
VXITRD_API VXItrdResult VXItrdTimerSleep (VXItrdTimer *timer, VXIint sleepMs, VXIbool *interrupted)
 Suspend the current thread for a time period using a timer.
VXITRD_API VXItrdResult VXItrdTimerWake (VXItrdTimer *timer)
 Wakes a thread that is sleeping on a timer.
VXITRD_API VXItrdResult VXItrdInit (VXIint32 threadStackSize)
 Initialize the TRD utilities library.
VXITRD_API VXItrdResult VXItrdShutDown (void)
 Shutdown the TRD utilities library.

Variables

*typedef void * VXItrdThreadArg
 Function signature invoked on the new thread by VXItrdThreadCreate( ), and the argument to that function.


Define Documentation

#define VXITRD_DEFINE_THREAD_FUNC funcName,
userData   )     VXItrdThreadArg funcName(VXItrdThreadArg userData)
 


Typedef Documentation

typedef enum VXItrdResult VXItrdResult
 

Result codes for functions.

Result codes less then zero are severe errors (likely to be platform faults), those greater then zero are warnings (likely to be application issues)

typedef VXItrdThreadArg(* VXItrdThreadStartFunc)(VXItrdThreadArg userData)
 


Enumeration Type Documentation

enum VXItrdResult
 

Result codes for functions.

Result codes less then zero are severe errors (likely to be platform faults), those greater then zero are warnings (likely to be application issues)

Enumeration values:
VXItrd_RESULT_FATAL_ERROR 
VXItrd_RESULT_IO_ERROR 
VXItrd_RESULT_OUT_OF_MEMORY 
VXItrd_RESULT_SYSTEM_ERROR 
VXItrd_RESULT_PLATFORM_ERROR 
VXItrd_RESULT_BUFFER_TOO_SMALL 
VXItrd_RESULT_INVALID_PROP_NAME 
VXItrd_RESULT_INVALID_PROP_VALUE 
VXItrd_RESULT_INVALID_ARGUMENT 
VXItrd_RESULT_SUCCESS 
VXItrd_RESULT_FAILURE 
VXItrd_RESULT_NON_FATAL_ERROR 
VXItrd_RESULT_UNSUPPORTED 


Function Documentation

VXITRD_API VXItrdResult VXItrdInit VXIint32  threadStackSize  ) 
 

Initialize the TRD utilities library.

Parameters:
threadStackSize Stack size to use when creating new threads. Pass 0 to use the default (OS-specific) size, usually this means new threads will use the same stack size as the main (parent) process.
Returns:
VXItrd_RESULT_SUCCESS if sucess, different value on failure

VXITRD_API VXItrdResult VXItrdMutexCreate VXItrdMutex **  mutex  ) 
 

Create a mutex.

Parameters:
mutex Handle to the created mutex
Returns:
VXItrdResult 0 on success

VXITRD_API VXItrdResult VXItrdMutexDestroy VXItrdMutex **  mutex  ) 
 

Destroy a mutex.

Parameters:
mutex Handle to the mutex to destroy
Returns:
VXItrdResult 0 on success

VXITRD_API VXItrdResult VXItrdMutexLock VXItrdMutex *  mutex  ) 
 

Lock a mutex.

Parameters:
mutex Handle to the mutex to lock
Returns:
VXItrdResult 0 on success

VXITRD_API VXItrdResult VXItrdMutexUnlock VXItrdMutex *  mutex  ) 
 

Unlock a Mutex.

Parameters:
mutex Handle to the mutex to unlock
Returns:
VXItrdResult 0 on success

VXITRD_API VXItrdResult VXItrdShutDown void   ) 
 

Shutdown the TRD utilities library.

Returns:
VXItrd_RESULT_SUCCESS if sucess, different value on failure

VXITRD_API VXItrdResult VXItrdThreadCreate VXItrdThread **  thread,
VXItrdThreadStartFunc  startFunc,
VXItrdThreadArg  arg
 

Create a thread.

Note thread values are not supported on some older operating systems (such as IBM OS/2). Execution starts on the thread immediately. To pause execution use a mutex between the thread and the thread creator.

Parameters:
thread Handle to the thread that is created
startFunc Function for the thread to start execution on
arg Argument to the thread function
Returns:
VXItrdResult 0 on success

VXITRD_API VXItrdResult VXItrdThreadDestroyHandle VXItrdThread **  thread  ) 
 

Destroy a thread handle.

Note: this does NOT stop or destroy the thread, it just releases the handle for accessing it. If this is not done, a memory leak occurs, so if the creator of the thread never needs to communicate with the thread again it should call this immediately after the create if the create was successful.

Parameters:
thread Handle to the thread to destroy
Returns:
VXItrdResult 0 on success

VXITRD_API void VXItrdThreadExit VXItrdThreadArg  status  ) 
 

Terminate a thread (called by the thread to exit).

Parameters:
status Exit value of the thread
Returns:
N/A, never returns

VXITRD_API VXIthreadID VXItrdThreadGetID void   ) 
 

Get the thread ID for the current thread.

Returns:
Thread ID number

VXITRD_API VXIthreadID VXItrdThreadGetIDFromHandle VXItrdThread *  thread  ) 
 

Get the thread ID for the specified thread.

Parameters:
thread Handle to the thread to get the ID for
Returns:
Thread ID number

VXITRD_API VXItrdResult VXItrdThreadJoin VXItrdThread *  thread,
VXItrdThreadArg status,
long  timeout
 

Wait for the termination of a specified thread.

Parameters:
thread Handle to the thread to wait for
status Set to the exit value of the thread's start routine
timeout Timeout, in milliseconds, for waiting for the thread to exit, pass -1 to wait forever
Returns:
VXItrdResult 0 on success, VXItrd_RESULT_FAILURE on timeout

VXITRD_API void VXItrdThreadYield void   ) 
 

Yield execution of the current thread to other threads/processes.

Returns:
N/A, no return value, always succeeds

VXITRD_API VXItrdResult VXItrdTimerCreate VXItrdTimer **  timer  ) 
 

Create a timer.

Parameters:
timer Handle to the created timere
Returns:
VXItrdResult 0 on success

VXITRD_API VXItrdResult VXItrdTimerDestroy VXItrdTimer **  timer  ) 
 

Destroy a timer.

Parameters:
timer Handle to the timer to destroy
Returns:
VXItrdResult 0 on success

VXITRD_API VXItrdResult VXItrdTimerSleep VXItrdTimer *  timer,
VXIint  sleepMs,
VXIbool interrupted
 

Suspend the current thread for a time period using a timer.

Note: due to other activities of the machine, the delay may be greater then the configured duration.

Parameters:
timer Handle to the timer to use to execute the suspend
sleepMs Duration to sleep, in milliseconds
interrupted Pointer indicating whether or not the sleep was interrupted by VXItrdTimerWake, TRUE if interrupted, FALSE if not. Pass NULL if this information is not desired.
Returns:
VXItrdResult 0 on success

VXITRD_API VXItrdResult VXItrdTimerWake VXItrdTimer *  timer  ) 
 

Wakes a thread that is sleeping on a timer.

Note: if no thread is currently waiting on the specified timer, the next VXItrdTimerSleep( ) call on that timer will immediately wake up.

Parameters:
timer Handle to the timer to wake up
Returns:
VXItrdResult 0 on success


Variable Documentation

* typedef void* VXItrdThreadArg
 

Function signature invoked on the new thread by VXItrdThreadCreate( ), and the argument to that function.


Generated on Wed Jun 1 12:50:19 2005 for OpenVXI by  doxygen 1.4.2