CmtNewTSQ
- Updated2023-02-21
- 4 minute(s) read
int CmtNewTSQ (int numberOfItems, size_t itemSize, unsigned int options, CmtTSQHandle *queueHandle);
Purpose
Creates a thread safe queue.
You can use a thread safe queue to safely pass data between two threads. You can use one thread to write data into the queue and another thread to read data from the queue.
You can specify the size of the thread safe queue by passing the number of items you want to hold in the queue and the size of each item. When the thread safe queue is full, you cannot write more data until the data that is in the queue is read. Alternatively, you can use the OPT_TSQ_DYNAMIC_SIZE option to specify that the thread safe queue is dynamically sizeable. When a thread safe queue that is created with this option becomes full, it grows dynamically to accommodate new data. In this case, your system could run out of memory while attempting a write operation.
Call CmtDiscardTSQ to free the thread safe queue resources when you finish using it.
Parameters
| Input | ||
| Name | Type | Description |
| numberOfItems | int | The number of items you want the thread safe queue to hold. For both dynamically sized thread safe queues and non-dynamically sized thread safe queues, this is the initial number of items in the queue. |
| itemSize | size_t | The size, in bytes, of the items in the thread safe queue. The sizeof operator is useful for this. If you need to store items of varying size in the thread safe queue, you must either use more than one thread safe queue, store pointers in the queue, or set the size to 1 and treat the queue as a byte stream. |
| options | unsigned int | An option constant to configure the behavior of the thread safe queue when it is full and a write operation occurs. Pass 0 to configure the thread safe queue to do nothing when it is full and a write operation occurs. The following three options are mutually exclusive. These options affect only the queue when you use CmtWriteTSQData to write to a queue. These options are ignored when you use CmtGetTSQWritePtr and CmtReleaseTSQWritePtr to write data to the queue. OPT_TSQ_DYNAMIC_SIZE—Configures the thread safe queue to grow when a thread attempts to write to the queue when the queue is full. By default, the thread safe queue grows by 50% of the original number of items in the queue. Call CmtSetTSQAttribute with the ATTR_TSQ_GROWTH_INCREMENT attribute to change the growth policy for a thread safe queue. OPT_TSQ_AUTO_FLUSH_ALL—Configures the thread safe queue to throw out all old data when a thread attempts to write to the queue when the queue is full. The new data is written into the newly freed space in the queue. If another thread is reading from the queue when this occurs, the write function waits until the reader is done its operation. OPT_TSQ_AUTO_FLUSH_EXACT—Configures the thread safe queue to throw out exactly the amount of old data that it needs to in order to fit new data when a thread attempts to write to the queue when the queue is full. The new data is written into the newly freed space in the queue. If another thread is reading from the queue when this occurs, the write function waits until the reader is done its operation. |
| Output | ||
| Name | Type | Description |
| queueHandle | CmtTSQHandle | Returns a handle that you use to identify the thread safe queue in subsequent function calls. The handle is never 0. |
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 CmtNewTSQ function:
- apps\daqmthread\daqMT.cws
Open example - toolbox\asyncdem.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