TutThreadCreate

Name

TutThreadCreate — create a thread

Synopsis

T_THREAD TutThreadCreate(thread_func, thread_arg, ...) 
T_THREAD_FUNC thread_func; 
T_PTR thread_arg; 

Arguments

thread_func — function to call from the new thread

thread_arg — argument to pass to thread_func

additional arguments — NULL-terminated list of key-value argument pairs

Return Values

Thread handle if successful, T_INVALID_THREAD otherwise.

Diagnostics

If TutThreadCreate fails, it returns T_INVALID_THREAD and sets the global SmartSockets error number to one of:

Description

TutThreadCreate is used to create a new operating system thread executing thread_func with the supplied argument. When thread_func returns, or explicitly calls TutThreadExit, the operating system thread exits and the function’s return value, or the argument passed to TutThreadExit, is available to another thread with TutThreadWait.

The additional arguments accepted by this function allow key-value pairs to be defined that modify the platform-specific thread creation arguments passed to the operating system. At present, there are no such key-value pairs defined. Callers should simply pass NULL to indicate no additional arguments.

Caution

Threads created by TutThreadCreate or TutThreadCreateVa should always be exited with a call to TutThreadExit (or by returning from thread_func, which implicitly calls TutThreadExit for the thread).

Before you use any thread function, you must call TipcInitThreads to initialize SmartSockets thread synchronization.

The T_ENTRY declaration specifier is required in the definition of all thread functions as well as their prototypes.

See Also

TutThreadCreateVa, TutThreadEqual, TutThreadExit, TutThreadSelf, TutThreadWait; see the TIBCO SmartSockets Application Programming Interface reference for detailed information on TipcInitThreads

Examples

This example creates three threads, each executing a function that prints a simple message identifying the thread and then exits. It then waits until all three threads have finished.

T_PTR T_ENTRY my_thread_func(T_PTR arg) 
{ 
  TutOut("This output comes from thread %d\n", *((T_INT4 *)arg); 
  return NULL; 
} 
 
int main() 
{ 
  T_THREAD threads[3]; 
  T_INT4 args[3]; 
  T_INT4 i; 
 
  if (!TipcInitThreads()) 
    exit (T_EXIT_FAILURE); 
 
  for (i = 0; i < 3; i++) { 
    args[i] = i + 1; 
    threads[i] = TutThreadCreate(my_thread_func, &args[i], NULL); 
    if (TutThreadEqual(T_INVALID_THREAD, threads[i])) { 
      /* error */ 
    } 
  } 
  for (i = 0; i < 3; i++) { 
    T_PTR result; 
 
    if (!TutThreadWait(threads[i], &result)) { 
      /* error */ 
    } 
  } 
  return T_EXIT_SUCCESS; 
}