CmtReadTSQData
int CmtReadTSQData (CmtTSQHandle queueHandle, void *buffer, size_t numberOfItems, int timeout_ms, unsigned int options);
Purpose
Reads a specified number of items from a thread safe queue.
If the thread safe queue contains enough items, this function gets the items from the queue and returns.
If the thread safe queue does not contain enough items, this function waits until the specified number of items are available or a timeout occurs. If the timeout occurs, this function reads as many items as are available in the thread safe queue.
This function returns the number of items that it got from the queue. Notice that when this function returns due to a timeout, the number of items read from the queue might be less than the number requested in number_ofItems parameter to this function.
Parameters
| Input | ||
| Name | Type | Description |
| queueHandle | CmtTSQHandle | The handle you obtained from CmtNewTSQ to identify the thread safe queue. |
| numberOfItems | size_t | The number of items to copy into the buffer. The pointer passed in the buffer parameter must point to at least as many items as specified in this parameter. If the thread safe queue does not contain enough items, this function waits for another thread to write more items to the thread safe queue. The function returns an error if this value is greater than INT_MAX. |
| timeout_ms | int | The maximum amount of time, in milliseconds, that you want this function to spend reading data from the thread safe queue. Pass 0 to make this function read as much as it can read immediately and return without waiting for the specified number of items to be in the thread safe queue. Pass TSQ_INFINITE_TIMEOUT if you want this function to return only when the requested amount of data has been read from the queue. This function returns without reading the requested number of items from the queue if another thread calls the CmtSetTSQAttribute with the ATTR_TSQ_ACCESS_DENY attribute set to VAL_TSQ_ACCESS_DENY_READ before the CmtReadTSQData function has read the requested amount of data from the queue. |
| options | unsigned int | Pass OPT_TSQ_READ_PEEK to leave the data returned in the buffer parameter in the queue. This allows the same data to be read more than once. Pass 0 to remove the returned in the buffer parameter from the queue. |
| Output | ||
| Name | Type | Description |
| buffer | void * | A pointer to an array of items to receive the data from the thread safe queue. The array must contain at least as many items as you specify in the number_ofItems parameter. You cannot pass NULL in this parameter. |
Return Value
| Name | Type | Description |
| cmtStatusOrItemsRead | int | Contains the number of items read from the queue if the function call succeeded or a CmtStatus code if the function call failed. If the value is greater than or equal to 0, the function call succeeded and this value is the number of items read from the queue. This number might be less than the number of items you requested in the number_ofItems parameter to this function. If the value is less than zero, the function call failed and this value is a CmtStatus code. 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 CmtReadTSQData function:
- apps\daqmthread\daqMT.cws
Open example - toolbox\asyncdem.cws
Open example - utility\threading\ThreadSafeQueue\BuffNoDataLoss\BuffNoDataLoss.cws
Open example