CmtInstallTSQCallback
int CmtInstallTSQCallback (CmtTSQHandle queueHandle, unsigned int event, int eventThresholdValue, CmtTSQCallbackPtr callbackFunction, void *callbackData, unsigned int callbackThreadID, CmtTSQCallbackID *callbackID);
Purpose
Specifies callbacks for thread safe queue events.
You can install only one callback per thread safe queue event. You can install a single callback that you want to call for more than one event.
Events are generated when items are added to the thread safe queue, when items are read from the thread safe queue, and when a dynamically sized thread safe queue grows. Your callback is called when the event occurs and the threshold value that you specified for the event has been exceeded. You are not required to uninstall thread safe queue callbacks.
Use callbacks to initiate reads and writes when a specified amount of data or space becomes available. Depending on the nature of your program, this can be a better model than continuously reading and writing data.
Parameters
| Input | ||||||||||
| Name | Type | Description | ||||||||
| queueHandle | CmtTSQHandle | The handle you obtained from CmtNewTSQ to identify the thread safe queue. | ||||||||
| event | unsigned int | The event that causes the thread safe queue to call your callback. Your callback is called when the event occurs and the threshold value you specify is exceeded. You can specify the following events: EVENT_TSQ_QUEUE_SIZE—A thread safe queue generates this event when its size meets or exceeds the threshold value. Only dynamically sizable queues can generate this event. Use this event if you want to know when the size of the queue meets or exceeds the size you specify in the threshold parameter. EVENT_TSQ_ITEMS_IN_QUEUE—A thread safe queue generates this event when both of the following conditions are true:
EVENT_TSQ_QUEUE_SPACE_FREE—A thread safe queue generates this event when both of the following conditions are true:
Remember that you must check to see how much data or free space is in the queue when you get the EVENT_TSQ_QUEUE_SPACE_FREE and EVENT_TSQ_ITEMS_IN_QUEUE events because the queue might contain more than the threshold number of items or free space. The following lists examples.
|
||||||||
| eventThresholdValue | int | The value that must be exceeded before the thread safe queue calls your callback function. This value contains different information for each event type. The following table shows the meaning of the value parameter for each event type:
|
||||||||
| callbackFunction | CmtTSQCallbackPtr | The function that the thread safe queue calls when the specified event occurs and the threshold value is exceeded. The function you pass in this parameter must have the following prototype: void CVICALLBACK Callback (CmtTSQHandle queueHandle, unsigned int event, int value, void *callbackData); Upon entry to the callback, the queueHandle parameter contains the handle of the thread safe queue that is generating the event. The callbackData parameter contains the value you passed to the callbackData parameter of this function. The event parameter indicates which event triggered the callback. The value parameter contains different information for each event type. The following table shows the possible event constants and the meaning of their corresponding value parameters:
|
||||||||
| callbackData | void * | A value that you want the thread safe queue 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. |
||||||||
| callbackThreadID | unsigned int | The ID of the thread that you want to use to execute the Callback Function. Call CmtGetCurrentThreadID to get the current thread's ID. The specified thread must process events using RunUserInterface, GetUserEvent, or ProcessSystemEvents. |
||||||||
| Output | ||||||||||
| Name | Type | Description | ||||||||
| callbackID | CmtTSQCallbackID | Returns an ID that uniquely identifies the callback. Use this ID to uninstall the callback. You are not required to uninstall the callback before discarding the thread safe queue. 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
Examples
Refer to the following examples that use the CmtInstallTSQCallback function:
- apps\daqmthread\daqMT.cws
Open example - utility\threading\ThreadSafeQueue\BuffNoDataLoss\BuffNoDataLoss.cws
Open example - utility\threading\ThreadSafeQueue\DirectPtrAccess\DirectPtrAccess.cws
Open example - utility\threading\ThreadSafeQueue\Overflow\Overflow.cws
Open example