CmtWriteTSQData
- Updated2023-02-21
- 4 minute(s) read
CmtWriteTSQData
int CmtWriteTSQData (CmtTSQHandle queueHandle, const void *buffer, size_t numberOfItems, int timeout_ms, int *numberOfItemsFlushed);
Purpose
Writes a specified number of items into a thread safe queue.
If enough empty space exists in the thread safe queue to hold all the items, this function copies the items into the queue and returns.
If there is not enough space in the thread safe queue and the thread safe queue is not configured to grow or automatically flush when full, this function waits until the specified amount of space is available or a timeout occurs. If a timeout occurs, this function copies as many items as it can fit into the thread safe queue.
CmtWriteTSQData returns the number of items that it copied into the thread safe queue. Note that when this function returns due to a timeout, the number of items it wrote to the queue might be less than the number you indicated in the number_ofItems parameter to this function.
Refer to CmtNewTSQ for more information about configuring a thread safe queue to grow or automatically flush when full.
Parameters
| Input | ||
| Name | Type | Description |
| queueHandle | CmtTSQHandle | The handle you obtained from CmtNewTSQ to identify the thread safe queue. |
| buffer | const void * | A pointer to an array of items to write into the thread safe queue. |
| numberOfItems | size_t | The number of items to copy into the thread safe queue. The pointer you pass in the buffer parameter must point to at least as many items as you specify in this parameter. 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 writing data to the thread safe queue. Pass 0 if you want this function to write as much as it can write immediately and return without waiting for free space in the queue. Pass TSQ_INFINITE_TIMEOUT if you want this function to return only when all of the data has been written into the queue. The function returns without writing the requested number of items into the queue if another thread calls the CmtSetTSQAttribute with the ATTR_TSQ_ACCESS_DENY attribute set to VAL_TSQ_ACCESS_DENY_WRITE before the CmtWriteTSQData function has written all of its data to the queue. This timeout applies only to the amount of time the function spends waiting for another thread to free space in the queue by reading items from the queue. The timeout does not apply to time spent waiting for another thread to finish writing. The timeout also does not apply to time spent waiting for another thread to finish reading when the thread safe queue is full and you have configured the queue to automatically flush. Refer to CmtNewTSQ for more information about configuring thread safe queues to automatically flush when full. |
| Output | ||
| Name | Type | Description |
| numberOfItemsFlushed | int | Returns the number of items that the thread safe queue removed from the
beginning of the queue to make room for the new data. number_ofItemsFlushed applies only to thread safe queues that you configured with the OPT_TSQ_AUTO_FLUSH_ALL or OPT_TSQ_AUTO_FLUSH_EXACT options. Pass NULL if you do not want this value. |
Return Value
| Name | Type | Description |
| cmtStatusOrItemsWritten | int | The number of items written into 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 written to the queue. Note that this number might be less than the number of items you specified 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 CmtWriteTSQData function:
- apps\daqmthread\daqMT.cws
Open example - toolbox\asyncdem.cws
Open example - utility\threading\ThreadSafeQueue\BuffNoDataLoss\BuffNoDataLoss.cws
Open example