VDSF
Menu
You are here: Home

API functions for vdsf FIFO queues.

Detailed Description

A reminder: FIFO, First In First Out.

Data items are placed at the end of the queue and retrieved from the beginning of the queue.


Functions

VDSF_EXPORT int vdsQueueClose (VDS_HANDLE objectHandle)
 Close a FIFO queue.
VDSF_EXPORT int vdsQueueGetFirst (VDS_HANDLE objectHandle, void *buffer, size_t bufferLength, size_t *returnedLength)
 Iterate through the queue - no data items are removed from the queue by this function.
VDSF_EXPORT int vdsQueueGetNext (VDS_HANDLE objectHandle, void *buffer, size_t bufferLength, size_t *returnedLength)
 Iterate through the queue - no data items are removed from the queue by this function.
VDSF_EXPORT int vdsQueueOpen (VDS_HANDLE sessionHandle, const char *queueName, size_t nameLengthInBytes, VDS_HANDLE *objectHandle)
 Open an existing FIFO queue (see vdsCreateObject to create a new queue).
VDSF_EXPORT int vdsQueuePop (VDS_HANDLE objectHandle, void *buffer, size_t bufferLength, size_t *returnedLength)
 Remove the first item from the beginning of a FIFO queue and return it to the caller.
VDSF_EXPORT int vdsQueuePush (VDS_HANDLE objectHandle, const void *pItem, size_t length)
 Insert a data element at the end of the FIFO queue.
VDSF_EXPORT int vdsQueueStatus (VDS_HANDLE objectHandle, vdsObjStatus *pStatus)
 Return the status of the queue.

Function Documentation

VDSF_EXPORT int vdsQueueClose ( VDS_HANDLE  objectHandle  ) 

Close a FIFO queue.

This function terminates the current access to the queue in shared memory (the queue itself is untouched).

Warning:
Closing an object does not automatically commit or rollback data items that were inserted or removed. You still must use either vdsCommit or vdsRollback to end the current unit of work.
Parameters:
[in] objectHandle The handle to the queue (see vdsQueueOpen).
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsQueueGetFirst ( VDS_HANDLE  objectHandle,
void *  buffer,
size_t  bufferLength,
size_t *  returnedLength 
)

Iterate through the queue - no data items are removed from the queue by this function.

Data items which were added by another session and are not yet committed will not be seen by the iterator. Likewise, destroyed data items (even if not yet committed) are invisible.

Parameters:
[in] objectHandle The handle to the queue (see vdsQueueOpen).
[out] buffer The buffer provided by the user to hold the content of the first element. Memory allocation for this buffer is the responsability of the caller.
[in] bufferLength The length of buffer (in bytes).
[out] returnedLength The actual number of bytes in the data item.
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsQueueGetNext ( VDS_HANDLE  objectHandle,
void *  buffer,
size_t  bufferLength,
size_t *  returnedLength 
)

Iterate through the queue - no data items are removed from the queue by this function.

Data items which were added by another session and are not yet committed will not be seen by the iterator. Likewise, destroyed data items (even if not yet committed) are invisible.

Evidently, you must call vdsQueueGetFirst to initialize the iterator. Not so evident - calling vdsQueuePop will reset the iteration to the last element (they use the same internal storage). If this cause a problem, please let us know.

Parameters:
[in] objectHandle The handle to the queue (see vdsQueueOpen).
[out] buffer The buffer provided by the user to hold the content of the next element. Memory allocation for this buffer is the responsability of the caller.
[in] bufferLength The length of buffer (in bytes).
[out] returnedLength The actual number of bytes in the data item.
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsQueueOpen ( VDS_HANDLE  sessionHandle,
const char *  queueName,
size_t  nameLengthInBytes,
VDS_HANDLE *  objectHandle 
)

Open an existing FIFO queue (see vdsCreateObject to create a new queue).

Parameters:
[in] sessionHandle The handle to the current session.
[in] queueName The fully qualified name of the queue.
[in] nameLengthInBytes The length of queueName (in bytes) not counting the null terminator (null-terminators are not used by the vdsf engine).
[out] objectHandle The handle to the queue, allowing us access to the queue in shared memory. On error, this handle will be set to zero (NULL) unless the objectHandle pointer itself is NULL.
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsQueuePop ( VDS_HANDLE  objectHandle,
void *  buffer,
size_t  bufferLength,
size_t *  returnedLength 
)

Remove the first item from the beginning of a FIFO queue and return it to the caller.

Data items which were added by another session and are not yet committed will not be seen by this function. Likewise, destroyed data items (even if not yet committed) are invisible.

The removals only become permanent after a call to vdsCommit.

Parameters:
[in] objectHandle The handle to the queue (see vdsQueueOpen).
[out] buffer The buffer provided by the user to hold the content of the data item. Memory allocation for this buffer is the responsability of the caller.
[in] bufferLength The length of buffer (in bytes).
[out] returnedLength The actual number of bytes in the data item.
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsQueuePush ( VDS_HANDLE  objectHandle,
const void *  pItem,
size_t  length 
)

Insert a data element at the end of the FIFO queue.

The additions only become permanent after a call to vdsCommit.

Parameters:
[in] objectHandle The handle to the queue (see vdsQueueOpen).
[in] pItem The data item to be inserted.
[in] length The length of pItem (in bytes).
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsQueueStatus ( VDS_HANDLE  objectHandle,
vdsObjStatus *  pStatus 
)

Return the status of the queue.

Parameters:
[in] objectHandle The handle to the queue (see vdsQueueOpen).
[out] pStatus A pointer to the status structure.
Returns:
0 on success or a vdsErrors on error.

Last updated on April 07, 2008.