CmtScheduleThreadPoolFunction

int CmtScheduleThreadPoolFunction (int poolHandle, ThreadFunctionPtr threadFunction, void *threadFunctionData, int *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.

If you do not pass NULL for the threadFunctionID parameter, you must call CmtReleaseThreadPoolFunctionID to free the Thread Function ID.

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 integer The handle you obtained from CmtNewThreadPool to identify the thread pool.

Pass DEFAULT_THREAD_POOL_HANDLE to specify the default thread pool.
threadFunction ThreadFunctionPtr 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.
Output
Name Type Description
threadFunctionID integer (passed by reference) 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 function if you want to wait for the Thread Function to finish executing.

Pass NULL if you do not want the threadFunctionID.

If you do not pass NULL for this parameter, you must call CmtReleaseThreadPoolFunctionID to free the threadFunctionID.

Return Value

Name Type Description
CmtStatus integer 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.