VDSF
Menu
You are here: Home

vdsQueue Class Reference

List of all members.

Public Member Functions

 vdsQueue (vdsSession &session)
virtual ~vdsQueue ()
void Close ()
 Close a FIFO queue.
int GetFirst (void *buffer, size_t bufferLength, size_t *returnedLength)
 Iterate through the queue - no data items are removed from the queue by this function.
int GetNext (void *buffer, size_t bufferLength, size_t *returnedLength)
 Iterate through the queue - no data items are removed from the queue by this function.
void Open (const std::string &queueName)
 Open an existing FIFO queue (see Session::CreateObject to create a new queue).
void Open (const char *queueName, size_t nameLengthInBytes)
 Open an existing FIFO queue (see Session::CreateObject to create a new queue).
int Pop (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.
void Push (const void *pItem, size_t length)
 Insert a data element at the end of the FIFO queue.
void Status (vdsObjStatus *pStatus)
 Return the status of the queue.

Private Attributes

VDS_HANDLE m_objectHandle
 Pointer to the vdsaQueue struct.
VDS_HANDLE & m_sessionHandle
 Reference to the vdsaSession struct (we belong to).

Constructor & Destructor Documentation

vdsQueue::vdsQueue ( vdsSession &  session  ) 

virtual vdsQueue::~vdsQueue (  )  [virtual]

Member Function Documentation

void vdsQueue::Close (  ) 

Close a FIFO queue.

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

Warning:
Closing an object does not automatically commit or rollback data items that were inserted or removed. You still must use either vdsSession::Commit or vdsSession::Rollback to end the current unit of work.
Exceptions:
vdsException An abnormal error occured.

int vdsQueue::GetFirst ( 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:
[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 VDS_IS_EMPTY if the queue is empty.
Exceptions:
vdsException An abnormal error occured.

int vdsQueue::GetNext ( 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 GetFirst to initialize the iterator. Not so evident - calling Pop will reset the iteration to the last element (they use the same internal storage). If this cause a problem, please let us know.

Parameters:
[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 VDS_REACHED_THE_END when the iteration reaches the end of the queue.
Exceptions:
vdsException An abnormal error occured.

void vdsQueue::Open ( const char *  queueName,
size_t  nameLengthInBytes 
)

Open an existing FIFO queue (see Session::CreateObject to create a new queue).

Parameters:
[in] queueName The fully qualified name of the queue.
[in] nameLengthInBytes The length of queueName (in bytes) not counting the null terminator.
Exceptions:
vdsException An abnormal error occured.

void vdsQueue::Open ( const std::string &  queueName  ) 

Open an existing FIFO queue (see Session::CreateObject to create a new queue).

Parameters:
[in] queueName The fully qualified name of the queue.
Exceptions:
vdsException An abnormal error occured.

int vdsQueue::Pop ( 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 vdsSession::Commit.

Parameters:
[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 VDS_IS_EMPTY if the queue is empty or VDS_ITEM_IS_IN_USE if all existing items are "invisible".
Exceptions:
vdsException An abnormal error occured.

void vdsQueue::Push ( 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 vdsSession::Commit.

Parameters:
[in] pItem The data item to be inserted.
[in] length The length of pItem (in bytes).
Exceptions:
vdsException An abnormal error occured.

void vdsQueue::Status ( vdsObjStatus *  pStatus  ) 

Return the status of the queue.

Parameters:
[out] pStatus A pointer to the status structure.
Exceptions:
vdsException An abnormal error occured.

Member Data Documentation

VDS_HANDLE vdsQueue::m_objectHandle [private]

Pointer to the vdsaQueue struct.

VDS_HANDLE& vdsQueue::m_sessionHandle [private]

Reference to the vdsaSession struct (we belong to).

The documentation for this class was generated from the following file:

Last updated on March 23, 2008.