# CmtInstallTSQCallback

int CmtInstallTSQCallback (int queueHandle, unsigned int event, int eventThresholdValue, TSQCallbackPtr callbackFunction, void *callbackData, unsigned int callbackThreadID, int *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 | integer | The handle you obtained from CmtNewTSQ to identify the thread safe queue.
event | unsigned integer | 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: A thread writes items to the thread safe queue. The number of items in the queue after the new items are added is greater than or equal to the threshold value. EVENT_TSQ_QUEUE_SPACE_FREE—A thread safe queue generates this event when both of the following conditions are true: A thread reads items from the thread safe queue or the thread safe queue is flushed by a call to CmtFlushTSQ. The total amount, in number of items, of free space in the queue after the read or flush is greater than or equal to the threshold value. 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. You register a callback for EVENT_TSQ_ITEMS_IN_QUEUE and set the threshold to 50. The writer writes 50 items to the queue. A callback is scheduled but thread in which the callback needs to be called is busy (it is not processing events) and therefore the callback is not called yet. The writer writes another 20 items to the queue. The thread in which the callback needs to be called is no longer busy (it processes events). The callback is called and the queue contains 70 items. If at this point only 60 items are read, the callback will not be called again when the writer writes 30 items because the number of items in the queue (40) is below the threshold value.
eventThresholdValue | integer | 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:
Event | Value
EVENT_TSQ_QUEUE_SIZE | The total size, in number of items, of the thread safe queue.
EVENT_TSQ_ITEMS_IN_QUEUE | The total number of items in the thread safe queue.
EVENT_TSQ_QUEUE_SPACE_FREE | The total amount of free space, in number of items, in the thread safe queue.
callbackFunction | TSQCallbackPtr | 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 (int 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:
Event | Value
EVENT_TSQ_QUEUE_SIZE | The total size, in number of items, of the thread safe queue.
EVENT_TSQ_ITEMS_IN_QUEUE | The total number of items in the thread safe queue.
EVENT_TSQ_QUEUE_SPACE_FREE | The total amount of free space, in number of items, in the thread safe queue.
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 integer | 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 | integer (passed by reference) | 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 | 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.