# CmtScheduleThreadPoolFunctionAdv

int CmtScheduleThreadPoolFunctionAdv (int poolHandle, ThreadFunctionPtr threadFunction, void *threadFunctionData, int threadFunctionPriority, ThreadFunctionCallbackPtr callbackFunction, unsigned int callbackEventMask, void *callbackData, unsigned int callbackThreadID, 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.

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 | 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.
threadFunctionPriority | integer | The priority for the thread that executes the scheduled function. Linux Thread priority is not supported. The only valid value for this parameter is THREAD_PRIORITY_NORMAL. 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.
callbackFunction | ThreadFunctionCallbackPtr | 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 (int poolHandle, int 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:
Event | Value
EVENT_TP_THREAD_FUNCTION_BEGIN | Reserved.
EVENT_TP_THREAD_FUNCTION_END | The return value from the Thread Function.
callbackEventMask | unsigned integer | 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 integer | 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 | 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.