CmtGetTSQWritePtr
int CmtGetTSQWritePtr (CmtTSQHandle queueHandle, void *writePointer, int *numberOfEmptyItems);
Purpose
Gets a write pointer to a thread safe queue's internal buffer.
The pointer points to the first empty space in the thread safe queue. You can use this pointer to write data directly into the thread safe queue's internal buffer. Only one thread can get the write pointer at a single time. When you finish writing to the thread safe queue, you must call CmtReleaseTSQWritePtr to release the pointer.
You can write only as many items as will fit in the contiguous free space in the thread safe queue. The amount of contiguous free space is returned in the number_ofEmptyItems parameter. Depending on the state of the queue, this number might not be equal to the total amount of free space in the queue. For example, if there is empty space at the beginning of the queue and at the end of the queue, you can write only as many items to the queue as there are empty spaces at the end of the queue. To write to the rest of the queue in this case, you must call CmtReleaseTSQWritePtr to free your pointer to the end of the queue and then call this function again to get a pointer to the free space 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 have 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 write pointer when you write 10 items at a time to, and read 10 or 20 items at a time from, a queue that can hold 20 items. Do not use the write pointer to write 10 items at a time to a queue that can hold 21 items. Instead, use CmtWriteTSQData to write to 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 |
| writePointer | void * | Returns a pointer to a thread safe queue's internal buffer. You must use this pointer only for writing into the queue. Pass the address of a pointer to the type of data stored in the queue. |
| numberOfEmptyItems | int | Returns the amount of contiguous free space, in number of items, in the queue. This parameter tells you how many items you can add to the queue with the write pointer 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 CmtGetTSQWritePtr function:
- utility\threading\ThreadSafeQueue\DirectPtrAccess\DirectPtrAccess.cws
Open example - utility\threading\ThreadSafeQueue\Overflow\Overflow.cws
Open example