CmtGetTSQReadPtr
int CmtGetTSQReadPtr (CmtTSQHandle queueHandle, void *readPointer, int *numberOfAvailableItems);
Purpose
Gets a read pointer to a thread safe queue's internal buffer.
The pointer points to the first available item in the thread safe queue. You can use this pointer to read data directly from the thread safe queue's internal buffer. Only one thread can get the read pointer at a single time. When you finish reading from the thread safe queue, you must call CmtReleaseTSQReadPtr to release the pointer.
You can read only as many items as are located contiguously in the queue. The number of contiguous items is returned in the number_ofAvailableItems parameter. Depending on the state of the queue, this might not be equal to the total number of items in the queue. For example, if there are newer items at the beginning of the queue and older items at the end of the queue, you can read only the older items. To read the rest of the items in this case, you must call CmtReleaseTSQReadPtr to free your pointer to the end of the queue and then call this function again to get a pointer to the items at the front of the queue.
NI recommends that you use the read and write pointers only when you use the queue in the following manner:
- The total size of the queue is a multiple of the amount of data that you read from the queue in a single operation.
- The amount of data that you read in a single operation is a multiple of the amount of data that you write in a single operation.
Keep in mind that if you do not use the queue in this manner, you might need to get the read or write pointer twice in order to read or write all of the data you want to read or write.
For example, you can use the read pointer when you read 10 items at a time from, and write 5 or 10 items at a time to, a queue that can hold 20 items. You should not use the read pointer to read 10 items at a time from a queue that can hold 21 items. Instead, use CmtReadTSQData to read from the queue in this scenario.
Parameters
| Input | ||
| Name | Type | Description |
| queueHandle | CmtTSQHandle | The handle you obtained from CmtNewTSQ to identify the thread safe queue. |
| Output | ||
| Name | Type | Description |
| readPointer | void * | Returns a pointer to a thread safe queue's internal buffer. You must use this pointer only for reading from the queue. Pass the address of a pointer to the type of data stored in the queue. |
| numberOfAvailableItems | int | Returns the number of contiguous items in the queue. This parameter tells you how many items you can read from the queue with the read pointer that you obtain from this function. |
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 CmtGetTSQReadPtr function:
- utility\threading\ThreadSafeQueue\DirectPtrAccess\DirectPtrAccess.cws
Open example - utility\threading\ThreadSafeQueue\Overflow\Overflow.cws
Open example