Threading


Functions

Boolean_t TecUtilThreadCreateDetached (ThreadFunction_pf ThreadFunction, ArbParam_t ThreadData)
  Create a new thread.
Mutex_pa TecUtilThreadMutexAlloc (void)
  Allocates and initializes a new thread mutex for use with the mutex locking and unlocking functions.
Mutex_pa TecUtilThreadRecursiveMutexAlloc (void)
  Allocates and initializes a new thread mutex for use with the mutex locking and unlocking functions.
void TecUtilThreadMutexDealloc (Mutex_pa *Mutex)
  Deallocates thread mutex previously allocated with TecUtilThreadMutexAlloc().
void TecUtilThreadMutexLock (Mutex_pa Mutex)
  Lock on a thread mutex previously allocated with TecUtilThreadMutexAlloc().
void TecUtilThreadMutexUnlock (Mutex_pa Mutex)
  Unlock on a thread mutex previously locked with TecUtilThreadMutexLock().
Condition_pa TecUtilThreadConditionAlloc (void)
  Allocates a condition variable.
void TecUtilThreadConditionDealloc (Condition_pa *Condition)
  Deallocates a previously allocated condition variable.
void TecUtilThreadSignalCondition (Condition_pa Condition)
  Signals at least one thread, if any, waiting on the condition variable.
void TecUtilThreadBroadcastCondition (Condition_pa Condition)
  Signals all threads, if any, waiting on the condition variable.
void TecUtilThreadWaitForCondition (Condition_pa Condition, Mutex_pa Mutex)
  Wait on the specified condition variable until signaled.
ConditionAwakeReason_e TecUtilThreadTimedWaitForCondition (Condition_pa Condition, Mutex_pa Mutex, Int32_t WaitPeriodInMS)
  Wait on the specified condition variable until signaled or until timed out.
JobControl_pa TecUtilThreadPoolJobControlAlloc (void)
  Allocates a job control variable for associating jobs submitted to Tecplot's standard thread pool with one another other.
void TecUtilThreadPoolJobControlDealloc (JobControl_pa *JobControl)
  Deallocates a previously allocated job control variable that is no longer needed.
void TecUtilThreadPoolAddJob (ThreadPoolJob_pf Job, ArbParam_t JobData, JobControl_pa JobControl)
  Submits a job to the thread pool using the specified job control.
void TecUtilThreadPoolWait (JobControl_pa JobControl)
  Blocks the calling thread until all jobs associated with the job control are finished.

Function Documentation

void TecUtilThreadBroadcastCondition ( Condition_pa  Condition  ) 

Signals all threads, if any, waiting on the condition variable.

The signaling thread does not have to hold the mutex associated with the conditional variable to broadcast the signal, however if predictable scheduling is required, it is recommended that the mutex be acquired first. This function is Thread Safe.

Since:
11.2-1-015
Parameters:
Condition Condition variable potentially being waited upon by other threads.
Add a message to the message queue and signal all waiting waiting consumer threads. 
   MyMessage SomeMessage;
   ... prepare message
   // add the message to the queue and signal all waiting consumer threads
   TecUtilThreadMutexLock(MyMutex);
   QueueAddMessage(MyMessageQueue,SomeMessage);
   TecUtilThreadBroadcastCondition(MyCondition);
   TecUtilThreadMutexUnlock(MyMutex);
   ...

Precondition:
Condition Pointer must be a valid address and non-NULL.
Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

    This function is not supported in Python.

Condition_pa TecUtilThreadConditionAlloc ( void   ) 

Allocates a condition variable.

This function is Thread Safe.

Since:
11.2-1-015
Returns:
Allocated condition variable or NULL if insufficient resources.
Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

  Results = TecUtil.ThreadConditionAlloc()

  Output:
    Results[0]    ReturnVal

void TecUtilThreadConditionDealloc ( Condition_pa *  Condition  ) 

Deallocates a previously allocated condition variable.

This function is Thread Safe.

Since:
11.2-1-015
Parameters:
Condition Address of a previously allocated condition variable or address to a NULL pointer.
Precondition:
Condition Pointer must be a valid address and non-NULL.

Condition Pointer must be a valid address or NULL.

Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

    This function is not supported in Python.

Boolean_t TecUtilThreadCreateDetached ( ThreadFunction_pf  ThreadFunction,
ArbParam_t  ThreadData 
)

Create a new thread.

The thread will execute the specified function with the specified client data. This function is Thread Safe.

Since:
11.2-0-374
Parameters:
ThreadFunction Function called with the new thread.
ThreadData Client data for the newly created thread.
Returns:
Returns TRUE if the thread was successfully created otherwise FALSE.
Precondition:
ThreadFunction Pointer must be a valid address and non-NULL.
Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

    This function is not supported in Python.

Create a new thread that executes a function called SpawnedFunction.

   if (!TecUtilThreadCreateDetached(SpawnedFunction,(ArbParam_t)0))
     {
        //
        // Do something to handle thread failure.  System likely is
        // in serious trouble.
        //
     }

Mutex_pa TecUtilThreadMutexAlloc ( void   ) 

Allocates and initializes a new thread mutex for use with the mutex locking and unlocking functions.

This function is Thread Safe.

Since:
11.0-0-089
Returns:
Returns the newly allocated Mutex.
See also:
TecUtilThreadRecursiveMutexAlloc(), TecUtilThreadMutexDealloc(), TecUtilThreadMutexLock(), TecUtilThreadMutexUnlock().
Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

  Results = TecUtil.ThreadMutexAlloc()

  Output:
    Results[0]    ReturnVal

Allocate and use a mutex to make a section of code thread-safe. In reality, the mutex should be allocated in a thread-safe portion of the code, such as the add-on's InitTecAddOn routine, and freed only when there is no chance it will be locked again:

   extern Mutex_pa Mutex;

   if (!Mutex)
       Mutex = TecUtilThreadMutexAlloc();

   TecUtilThreadMutexLock(Mutex);

   // do some operation involving global data
             .
             .
             .
   TecUtilThreadMutexUnlock(Mutex);

   // get rid of the mutex
   TecUtilThreadMutexDealloc(&Mutex);

void TecUtilThreadMutexDealloc ( Mutex_pa *  Mutex  ) 

Deallocates thread mutex previously allocated with TecUtilThreadMutexAlloc().

The mutex must not be locked when this routine is called. This function is Thread Safe.

Since:
11.0-0-089
Parameters:
Mutex Pointer to the mutex to be deallocated.
See also:
TecUtilThreadMutexAlloc(), TecUtilThreadRecursiveMutexAlloc(), TecUtilThreadMutexLock(), TecUtilThreadMutexUnlock()
Precondition:
Mutex Pointer must be a valid address and non-NULL.

Mutex Pointer must be a valid address or NULL.

Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

    This function is not supported in Python.

void TecUtilThreadMutexLock ( Mutex_pa  Mutex  ) 

Lock on a thread mutex previously allocated with TecUtilThreadMutexAlloc().

Returns only when the lock is available. This function is Thread Safe.

Since:
11.0-0-089
Parameters:
Mutex The mutex to be locked.
See also:
TecUtilThreadMutexAlloc(), TecUtilThreadRecursiveMutexAlloc(), TecUtilThreadMutexDealloc(), TecUtilThreadMutexUnlock()
Precondition:
Mutex Pointer must be a valid address and non-NULL.
Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

    This function is not supported in Python.

void TecUtilThreadMutexUnlock ( Mutex_pa  Mutex  ) 

Unlock on a thread mutex previously locked with TecUtilThreadMutexLock().

This function is Thread Safe.

Since:
11.0-0-089
Parameters:
Mutex The mutex to be unlocked.
See also:
TecUtilThreadMutexAlloc(), TecUtilThreadRecursiveMutexAlloc(), TecUtilThreadMutexDealloc(), TecUtilThreadMutexLock()
Precondition:
Mutex Pointer must be a valid address and non-NULL.
Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

    This function is not supported in Python.

void TecUtilThreadPoolAddJob ( ThreadPoolJob_pf  Job,
ArbParam_t  JobData,
JobControl_pa  JobControl 
)

Submits a job to the thread pool using the specified job control.

The job may execute immediately or sometime in the future. This function is Thread Safe.

Since:
11.2-1-015
Note:
All jobs submitted to the thread pool must be finished before Tecplot exits. To ensure that submitted jobs have finished use TecUtilThreadPoolWait() in conjunction with the associated JobControl to block the current thread until all jobs have finished. The last possible time to complete unfinished jobs is when you receive a StateChange_QuitTecplot in your registered state change callback.
Parameters:
Job Callback function executed by a thread in the pool.
JobData Job specific client data needed by the callback. It is passed to the callback when executed by the thread.
JobControl Used to track jobs submitted to the thread pool. Most add-ons will submit all jobs to the pool using the same job control. Add-ons utilize this value by issuing calls to TecUtilThreadPoolWait() with the job control.
   typedef struct
   {
     int  Count;
     int* SomeData;
     ...perhaps some other data for the concurrent task
   } MyJobInfo_s;

   ...
   static void MyConcurrentJob(ArbParam_t JobData)
   {
     MyJobInfo_s* MyJobInfo = (MyJobInfo_s*)JobData;
     ...do concurrent task
   }

  ...
  MyJobInfo_s* MyJobInfoList; // ...allocated and initialized elsewhere
  JobControl_pa MyJobControl = TecUtilThreadPoolJobControlAlloc();
  ...
  // submit jobs and wait until all threads complete
  for (int J = 0; J < NumJobs; J++)
    TecUtilThreadPoolAddJob(MyConcurrentJob,
                            &MyJobInfoList[J],
                            MyJobControl);
  TecUtilThreadPoolWait(MyJobControl);

  // all jobs have finished, summarize results
  MyResults_s Results = SummarizeMyResults(MyJobInfoList);

See also:
TecUtilThreadPoolWait(), TecUtilThreadPoolJobControlAlloc()
Precondition:
JobControl Pointer must be a valid address and non-NULL.
Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

    This function is not supported in Python.

JobControl_pa TecUtilThreadPoolJobControlAlloc ( void   ) 

Allocates a job control variable for associating jobs submitted to Tecplot's standard thread pool with one another other.

Primarily this value is used to perform a join via a call to TecUtilThreadPoolWait(). This function is Thread Safe.

Since:
11.2-1-015
Returns:
Allocated job control variable or NULL if insufficient resources.
See also:
TecUtilThreadPoolAddJob(), TecUtilThreadPoolJobControlDealloc(), TecUtilThreadPoolPoolSize(), TecUtilThreadPoolJobThreadOffset()
Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

  Results = TecUtil.ThreadPoolJobControlAlloc()

  Output:
    Results[0]    ReturnVal

void TecUtilThreadPoolJobControlDealloc ( JobControl_pa *  JobControl  ) 

Deallocates a previously allocated job control variable that is no longer needed.

A job control variable is no longer needed when there are no more jobs associated with it executing or waiting to be executed in the thread pool. This function is Thread Safe.

Since:
11.2-1-015
Parameters:
JobControl Address of a previously allocated job control variable or address to a NULL pointer.
See also:
TecUtilThreadPoolAddJob(), TecUtilThreadPoolJobControlAlloc(), TecUtilThreadPoolPoolSize(), TecUtilThreadPoolJobThreadOffset()
Precondition:
JobControl Pointer must be a valid address and non-NULL.

JobControl Pointer must be a valid address or NULL.

Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

    This function is not supported in Python.

void TecUtilThreadPoolWait ( JobControl_pa  JobControl  ) 

Blocks the calling thread until all jobs associated with the job control are finished.

If all jobs associated with the job control are finished this function returns immediately. This function is Thread Safe.

Since:
11.2-1-015
Note:
All jobs submitted to the thread pool must be finish before Tecplot exists. The last possible time to complete unfinished jobs is when you receive a StateChange_QuitTecplot in your registered state change callback.
Parameters:
JobControl Identifies which jobs to wait on for completion.
See also:
TecUtilThreadPoolAddJob(), TecUtilThreadPoolJobControlAlloc(), TecUtilThreadPoolPoolSize(), TecUtilThreadPoolJobThreadOffset()
Precondition:
JobControl Pointer must be a valid address and non-NULL.
Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

    This function is not supported in Python.

Mutex_pa TecUtilThreadRecursiveMutexAlloc ( void   ) 

Allocates and initializes a new thread mutex for use with the mutex locking and unlocking functions.

Unlike the non-recursive mutex, the same thread may attempt to re-lock the mutex without causing a deadlock. This function is Thread Safe.

Since:
13.4.0.23334
Returns:
Returns the newly allocated Mutex.
See also:
TecUtilThreadMutexAlloc(), TecUtilThreadMutexDealloc(), TecUtilThreadMutexLock(), TecUtilThreadMutexUnlock()
Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

  Results = TecUtil.ThreadRecursiveMutexAlloc()

  Output:
    Results[0]    ReturnVal

Allocate and use a mutex to make a section of code thread-safe. In reality, the mutex should be allocated in a thread-safe portion of the code, such as the add-on's InitTecAddOn routine, and freed only when there is no chance it will be locked again:

   extern Mutex_pa Mutex;

   if (!Mutex)
       Mutex = TecUtilThreadRecursiveMutexAlloc();

   TecUtilThreadMutexLock(Mutex);

   // do some operation involving global data
             .
             .
             .
   TecUtilThreadMutexUnlock(Mutex);

   // get rid of the mutex
   TecUtilThreadMutexDealloc(&Mutex);

void TecUtilThreadSignalCondition ( Condition_pa  Condition  ) 

Signals at least one thread, if any, waiting on the condition variable.

The signaling thread does not have to hold the mutex associated with the conditional variable to send the signal however if predictable scheduling is required it is recommended that the mutex be acquired first. This function is Thread Safe.

Since:
11.2-1-015
Parameters:
Condition Condition variable potentially being waited upon by other threads.
Add a message to the message queue and signal a single waiting consumer thread. 
   MyMessage SomeMessage;
   ... prepare message
   // add the message to the queue and signal a single waiting consumer thread
   TecUtilThreadMutexLock(MyMutex);
   QueueAddMessage(MyMessageQueue,SomeMessage);
   TecUtilThreadSignalCondition(MyCondition);
   TecUtilThreadMutexUnlock(MyMutex);
   ...

Precondition:
Condition Pointer must be a valid address and non-NULL.
Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

    This function is not supported in Python.

ConditionAwakeReason_e TecUtilThreadTimedWaitForCondition ( Condition_pa  Condition,
Mutex_pa  Mutex,
Int32_t  WaitPeriodInMS 
)

Wait on the specified condition variable until signaled or until timed out.

The associated mutex must be locked before issuing this call. After entering a wait state the thread unlocks the mutex and waits for a signal or the time to expire. Upon successful return the mutex is locked and owned by the calling thread. This function is Thread Safe.

Since:
11.2-1-015
Parameters:
Condition Condition variable used to wait upon.
Mutex A locked mutex associated with the condition variable.
WaitPeriodInMS Maximum time to wait before returning if not first signaled.
Returns:
ConditionAwakeReason_Signaled is returned if the condition variable was signaled by another thread prior to the time expiring or ConditionAwakeReason_TimedOut is returned if the time expired prior prior to being signaled by another thread.
Wait for message queue to be given a message and consume it. 
   TecUtilThreadMutexLock(MyMutex);

   Boolean_t TimedOut = FALSE;
   const Int32_t OneMinute = 60*1000L;

   // loop to make sure another thread didn't sneak in and take the message
   while (QueueIsEmpty(MyMessageQueue) && !TimedOut)
     {
       ConditionAwakeReason_e AwakeReason =
         TecUtilThreadTimedWaitForCondition(MyCondition,MyMutex,OneMinute);
       TimedOut = (AwakeReason == ConditionAwakeReason_TimedOut);
     }

   MyMessage SomeMessage;
   if (!TimedOut)
     SomeMessage = QueuePopMessage(MyMessageQueue);

   TecUtilThreadMutexUnlock(MyMutex);
   ...do something with retrieved message if the wait didn't time out

Precondition:
Condition Pointer must be a valid address and non-NULL.

Mutex Pointer must be a valid address and non-NULL.

Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

    This function is not supported in Python.

void TecUtilThreadWaitForCondition ( Condition_pa  Condition,
Mutex_pa  Mutex 
)

Wait on the specified condition variable until signaled.

The associated mutex must be locked before issuing this call. After entering a wait state the thread unlocks the mutex and waits for a signal. Upon successful return the mutex is locked and owned by the calling thread. This function is Thread Safe.

Since:
11.2-1-015
Parameters:
Condition Condition variable used to wait upon.
Mutex A locked mutex associated with the condition variable.
Wait for message queue to be given a message and consume it. 
   TecUtilThreadMutexLock(MyMutex);

   // loop to make sure another thread didn't sneak in and take the message
   while (QueueIsEmpty(MyMessageQueue))
     TecUtilThreadWaitForCondition(MyCondition,MyMutex);

   MyMessage SomeMessage = QueuePopMessage(MyMessageQueue);

   TecUtilThreadMutexUnlock(MyMutex);
   ...do something with retrieved message

Precondition:
Condition Pointer must be a valid address and non-NULL.

Mutex Pointer must be a valid address and non-NULL.

Fortran Syntax:
   This function is not available for FORTRAN.

Python Syntax:

    This function is not supported in Python.

Generated on Tue Mar 12 02:24:44 2013 for Tecplot by  doxygen 1.5.5