CmtInstallThreadPoolCallback
int CmtInstallThreadPoolCallback (CmtThreadPoolHandle poolHandle, int event, CmtThreadPoolCallbackPtr callbackFunction, void *callbackData, CmtThreadPoolCallbackID *callbackID);
Purpose
Specifies callbacks for thread pool events.
You can install only one callback per thread pool event. You can install a single callback for multiple events. A thread pool generates an event each time the thread pool creates or destroys a thread. You can use these callbacks to perform initialization and cleanup for each thread that the pool creates. For example, you can call CA_InitActiveXThreadStyleForCurrentThreadCA_InitActiveXThreadStyleForCurrentThread in these callbacks to initialize the ActiveX threading style for thread pool threads.
The thread pool threads are destroyed only when the thread pool is discarded using CmtDiscardThreadPool. You cannot specify callbacks for the default thread pool. You are not required to uninstall thread pool callbacks before discarding the pool.
The thread pool calls the callback in the thread pool thread that generated the event.
Parameters
Input | ||
Name | Type | Description |
poolHandle | CmtThreadPoolHandle | The handle you obtained from CmtNewThreadPool to identify the thread pool. Do not pass DEFAULT_THREAD_POOL_HANDLE to this function. |
event | 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_BEGIN—This event is generated each time the thread pool creates a new thread. EVENT_TP_THREAD_END—This event is generated each time the thread pool destroys a thread. The thread pool destroys threads only when it is being discarded. 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 thread begin and the thread end events, pass (EVENT_TP_THREAD_BEGIN | EVENT_TP_THREAD_END). |
callbackFunction | CmtThreadPoolCallbackPtr | The function that the thread pool calls when the specified event occurs. The function you pass in this parameter must have the following prototype: void CVICALLBACK Callback (CmtThreadPoolHandle poolHandle, unsigned int event, int value, void *callbackData); Upon entry to the callback, the poolHandle parameter contains the handle to the thread pool that is generating the event. The event parameter specifies the event that occurred. The value parameter contains the thread ID of the thread being created or destroyed. The callbackData parameter contains the value you passed in the callbackData parameter of this function. |
callbackData | void * | A value that you want the thread pool to pass to your callback 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. |
Output | ||
Name | Type | Description |
callbackID | CmtThreadPoolCallbackID | Returns an ID that uniquely identifies the callback. You can use this ID to uninstall the callback. You are not required to uninstall the callback before discarding the pool. Pass NULL if you do not want the callbackID. |
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