CmtScheduleThreadPoolFunctionAdv
int CmtScheduleThreadPoolFunctionAdv (CmtThreadPoolHandle poolHandle, CmtThreadFunctionPtr threadFunction, void *threadFunctionData, int threadFunctionPriority, CmtThreadFunctionCallbackPtr callbackFunction, unsigned int callbackEventMask, void *callbackData, unsigned int callbackThreadID, CmtThreadFunctionID *threadFunctionID);
Purpose
Notifies a thread pool that you want to execute a function in a thread from the pool.
If an idle thread exists in the thread pool, it is used to execute the function. If no idle threads exist, and the maximum number of threads for the thread pool has not been reached, the pool creates a new thread and executes the function in it. If the maximum number of threads has been reached and no idle threads exist, the pool executes the function when a thread becomes available. Functions waiting to execute in this manner are assigned threads in the order in which they were scheduled.
You also can use this function to set the thread priority for the call and to specify a callback that the thread pool calls when Thread Function execution events occur.
Use the callbackEventMask parameter to specify the events that the thread pool sends to the callback.
Use the callbackThreadID parameter to specify the thread in which the thread pool calls the callback. If you specify RUN_IN_SCHEDULED_THREAD, the thread pool calls the callback in the thread that executes the Thread Function. If you specify another thread, the thread pool calls the callback when the specified thread processes events using RunUserInterface, GetUserEvent, or ProcessSystemEvents.
If you get threadFunctionID from this function, you must free it by calling CmtReleaseThreadPoolFunctionID.
 |
Note If you want to perform some operation in a timer callback that executes in its own thread, you can use the cvi/toolslib/toolbox/asynctmr.fp instrument driver. This timer uses its own thread to execute the timer callback and does not require you to create a thread or explicitly schedule a function in another thread. |
Parameters
| Input | ||||||||||||||||||
| Name | Type | Description | ||||||||||||||||
| poolHandle | CmtThreadPoolHandle | The handle you obtained from CmtNewThreadPool to identify the thread pool. Pass DEFAULT_THREAD_POOL_HANDLE to specify the default thread pool. (RT) Do not use the default thread pool in RT applications. Default thread pool threads continue running after RTMain exits. This behavior can cause the real-time target to become unstable. Instead, create a new thread pool and discard the thread pool before you exit RTMain. |
||||||||||||||||
| threadFunction | CmtThreadFunctionPtr | The function to schedule for execution. The function must have the
following prototype: int CVICALLBACK ThreadFunction (void *functionData); Upon entry to the Thread Function, the functionData parameter contains the value you passed in the Thread Function Data parameter of this function. You can call, from any thread, CmtGetThreadPoolFunctionAttribute with the ATTR_TP_FUNCTION_RETURN_VALUE attribute to obtain the return value from the Thread Function. |
||||||||||||||||
| threadFunctionData | void * | The value that you want the thread pool to pass to the Thread Function
as the function data parameter. Do not pass the address of a local variable or any other variable that might not be valid when the function is executed. |
||||||||||||||||
| threadFunctionPriority | int | The priority for the thread that executes the scheduled function. You can specify one of the following values:
The thread runs at this priority only while executing the Thread Function. Pass DEFAULT_THREAD_PRIORITY if you want the thread to run under the default priority for the thread pool. Call CmtGetThreadPoolAttribute with the ATTR_TP_THREAD_PRIORITY attribute to obtain the default priority for the pool. (RT) On real-time systems the thread priority can be any value from -15 to 15. The default priority of a thread in the system is 0. The operating system scheduler runs at priority level 9. Any threads running at a priority level equal to or higher than 9 are not subject to timeslicing by the scheduler and will run until they yield the CPU or are preempted by a higher priority thread. (Linux) Thread priority is not supported. The only valid value for this parameter is THREAD_PRIORITY_NORMAL. |
||||||||||||||||
| callbackFunction | CmtThreadFunctionCallbackPtr | The function that you want the thread pool to call before and/or after
the Thread Function executes. This mechanism can be used to notify another thread that the function has started or finished executing. Pass NULL if you do not want the thread pool to call a callback when the thread pool begins or ends execution. The function you pass in this parameter must have the following prototype: void CVICALLBACK Callback (CmtThreadPoolHandle poolHandle, CmtThreadFunctionID functionID, unsigned int event, int value, void *callbackData); Upon entry to the callback, the poolHandle parameter contains the handle to the thread pool that executed the Thread Function. The functionID parameter contains the Thread Function's threadFunctionID. The callbackData parameter contains the value you passed in the callbackData parameter of this function. The event parameter indicates which event triggered the callback. The value parameter contains different information for each type of event. The following table shows the possible event constants and the meaning of their corresponding value parameters:
|
||||||||||||||||
| callbackEventMask | unsigned int | The constants corresponding to the events that you want to receive
in the callback. You can specify the following event constants: EVENT_TP_THREAD_FUNCTION_BEGIN—Pass this constant if you want the thread pool to call your callback after a thread pool thread has been assigned to execute the Thread Function, but before the Thread Function is executed. EVENT_TP_THREAD_FUNCTION_END—Pass this constant if you want the thread pool to call your callback after the Thread Function is executed. If you specify multiple events, the callback is called when each event occurs. In the function panel, press <Ctrl-T> to change the ring control to an input box. Use the bit-wise OR operator (|) to specify the events that you want to receive in this callback. For example, to register the callback for both the function begin and the function end events, pass (EVENT_TP_THREAD_FUNCTION_BEGIN | EVENT_TP_THREAD_FUNCTION_END). |
||||||||||||||||
| callbackData | void * | A value that you want the thread pool to pass to your Callback Function as the callbackData parameter. Do not pass the address of a local variable or any other variable that might not be valid when the function is executed. | ||||||||||||||||
| callbackThreadID | unsigned int | The ID of the thread that you want the thread pool to use to execute the
Callback Function. Pass RUN_IN_SCHEDULED_THREAD if you want the callback called in the same thread that executes the Thread Function. Pass the return value of CmtGetCurrentThreadID if you want the callback called in the thread that is calling CmtScheduleThreadPoolFunctionAdv. If you do not pass RUN_IN_SCHEDULED_THREAD, the thread you specify in this parameter must process events using RunUserInterface, GetUserEvent, or ProcessSystemEvents. If you pass RUN_IN_SCHEDULED_THREAD, the thread pool calls the callback directly. You do not have to configure the scheduled thread to process events in order to receive the callback. |
||||||||||||||||
| Output | ||||||||||||||||||
| Name | Type | Description | ||||||||||||||||
| threadFunctionID | CmtThreadFunctionID | Returns a unique ID that you can use to identify the Thread Function. You can
use this ID to get various attributes of the Thread Function, including the
return value of the Thread Function. You can also pass the ID to the CmtWaitForThreadPoolFunctionCompletion or CmtWaitForThreadPoolFunctionCompletionEx functions if you want to wait for the Thread Function to finish executing.
If you do not pass NULL for this parameter, you must call CmtReleaseThreadPoolFunctionID to free the threadFunctionID. |
||||||||||||||||
Return Value
| Name | Type | Description |
| cmtStatus | int | The CmtStatus code that the function call returns. This function returns 0 to indicate success and negative values to indicate failure. Pass the CmtStatus code to CmtGetErrorMessage to get a description of the error code. |
Additional Information
Library: Utility Library
Include file: utility.h
LabWindows/CVI compatibility: LabWindows/CVI 5.5 and later
Examples
Refer to the following examples that use the CmtScheduleThreadPoolFunctionAdv function:
- apps\daqmthread\daqMT.cws
Open example - utility\threading\ThreadPool\MultiPanel\MultiPanel.cws
Open example - utility\threading\ThreadSafeQueue\BuffNoDataLoss\BuffNoDataLoss.cws
Open example - utility\threading\ThreadSafeQueue\Overflow\Overflow.cws
Open example