dnxQueue.c File Reference

Implements thread-safe queues for DNX. More...

#include "dnxQueue.h"
#include "dnxError.h"
#include "dnxDebug.h"
#include "dnxLogging.h"
#include <stdlib.h>
#include <syslog.h>
#include <assert.h>
#include <pthread.h>

Go to the source code of this file.

Data Structures

struct iDnxQueueEntry_

Queue entry wrapper structure - wraps user payload. More...

struct iDnxQueue_

Queue implementation structure. More...

Typedefs

typedef struct iDnxQueueEntry_ iDnxQueueEntry

Queue entry wrapper structure - wraps user payload.

typedef struct iDnxQueue_ iDnxQueue

Queue implementation structure.

Functions

int dnxQueueGetWait (DnxQueue *queue, void **ppPayload)

Waits and returns the first pending item payload from a queue.

int dnxQueueNext (DnxQueue *queue, void **ppPayload)

Return the next item payload without removing it from the queue.

int dnxQueueSize (DnxQueue *queue)

Return the number of items in the queue.

int dnxQueuePut (DnxQueue *queue, void *pPayload)

Add an opaque payload to a queue.

int dnxQueueGet (DnxQueue *queue, void **ppPayload)

Returns the first entry from the queue.

DnxQueueResult dnxQueueRemove (DnxQueue *queue, void **ppPayload, DnxQueueResult(*Compare)(void *pLeft, void *pRight))

Remove a matching payload from a queue.

DnxQueueResult dnxQueueFind (DnxQueue *queue, void **ppPayload, DnxQueueResult(*Compare)(void *pLeft, void *pRight))

Find a node matching a specified payload in a queue.

int dnxQueueCreate (unsigned maxsz, void(*pldtor)(void *), DnxQueue **pqueue)

Create a new queue object.

void dnxQueueDestroy (DnxQueue *queue)

Delete a requests queue.

Detailed Description

Implements thread-safe queues for DNX.

Author:: Robert W. Ingraham (dnx-devel@lists.sourceforge.net)

Attention:: Please submit patches to http://dnx.sourceforge.net

Definition in file dnxQueue.c.

Typedef Documentation

typedef struct iDnxQueue_ iDnxQueue

Queue implementation structure.

typedef struct iDnxQueueEntry_ iDnxQueueEntry

Queue entry wrapper structure - wraps user payload.

Function Documentation

int dnxQueueCreate	(	unsigned	maxsz,
		void()(void )	pldtor,
		DnxQueue **	pqueue
	)

Create a new queue object.

Parameters:

`[in]`	maxsz	- the maximum size of the queue - zero means unlimited.
`[in]`	pldtor	- a function that is called when the queue needs to delete a queue item payload. Optional; may be passed as 0.
`[out]`	pqueue	- the address of storage in which to return the new queue object.

Returns:: Zero on success, or a non-zero error value.

Note:: Cancellation safe.

Definition at line 373 of file dnxQueue.c.

References iDnxQueue_::cv, DNX_ERR_MEMORY, DNX_OK, DNX_PT_MUTEX_INIT, iDnxQueue_::freepayload, iDnxQueue_::maxsz, iDnxQueue_::mutex, and xmalloc.

void dnxQueueDestroy ( DnxQueue * queue )

Delete a requests queue.

Delete a request queue structure, and free all memory it uses.

Parameters:

[in] queue - the requests queue to be deleted.

Definition at line 398 of file dnxQueue.c.

References iDnxQueue_::cv, DNX_PT_MUTEX_DESTROY, DNX_PT_MUTEX_LOCK, DNX_PT_MUTEX_UNLOCK, iDnxQueue_::freepayload, iDnxQueue_::head, iDnxQueue_::mutex, iDnxQueueEntry_::next, iDnxQueueEntry_::pPayload, and xfree.

DnxQueueResult dnxQueueFind	(	DnxQueue *	queue,
		void **	ppPayload,
		DnxQueueResult()(void pLeft, void *pRight)	Compare
	)

Find a node matching a specified payload in a queue.

Parameters:

`[in]`	queue	- the queue to be queried for a matching payload.
`[in,out]`	ppPayload	- on entry contains the payload to be matched; on exit, returns the located matching payload.
`[in]`	Compare	- a node comparison routine; accepts two void pointers to payload objects, and returns a DnxQueueResult code.

Returns:: A DnxQueueResult code; DNX_QRES_FOUND (1) if the requested item payload was found in the queue, or DNX_QRES_CONTINUE of not. This is essentially a boolean return value, as the value of DNX_QRES_CONTINUE is zero.

Note:: Cancellation safe.

Definition at line 345 of file dnxQueue.c.

References DNX_PT_MUTEX_LOCK, DNX_PT_MUTEX_UNLOCK, DNX_QRES_CONTINUE, DNX_QRES_FOUND, iDnxQueue_::head, iDnxQueue_::mutex, iDnxQueueEntry_::next, and iDnxQueueEntry_::pPayload.

int dnxQueueGet	(	DnxQueue *	queue,
		void **	ppPayload
	)

Returns the first entry from the queue.

The returned payload needs to be destroyed/freed by the caller.

Parameters:

`[in]`	queue	- the queue from which to get the next pending queue item.
`[out]`	ppPayload	- the address of storage in which to return the first pending queue item, if found.

Returns:: Zero if found, or DNX_ERR_NOTFOUND if not found.

Note:: Cancellation safe.

Definition at line 256 of file dnxQueue.c.

References iDnxQueue_::current, DNX_ERR_NOTFOUND, DNX_OK, DNX_PT_MUTEX_LOCK, DNX_PT_MUTEX_UNLOCK, iDnxQueue_::head, iDnxQueue_::mutex, iDnxQueueEntry_::next, iDnxQueueEntry_::pPayload, iDnxQueue_::size, iDnxQueue_::tail, and xfree.

int dnxQueueGetWait	(	DnxQueue *	queue,
		void **	ppPayload
	)

Waits and returns the first pending item payload from a queue.

Suspends the calling thread if the queue is empty. The returned payload and its resources becomes the property of the caller.

Parameters:

`[in]`	queue	- the queue to be waited on.
`[out]`	ppPayload	- the address of storage in which to return the payload of the first queue item.

Returns:: Zero on success, or DNX_ERR_NOTFOUND if not found.

Note:: Not currently used (or exported by the dnxQueue.h header file).
Cancellation safe.

Definition at line 78 of file dnxQueue.c.

References iDnxQueue_::current, iDnxQueue_::cv, DNX_ERR_NOTFOUND, DNX_OK, DNX_PT_MUTEX_LOCK, DNX_PT_MUTEX_UNLOCK, iDnxQueue_::head, iDnxQueue_::mutex, iDnxQueueEntry_::next, iDnxQueueEntry_::pPayload, iDnxQueue_::size, iDnxQueue_::tail, and xfree.

int dnxQueueNext	(	DnxQueue *	queue,
		void **	ppPayload
	)

Return the next item payload without removing it from the queue.

Ownership of the queue item payload does NOT transfer to the caller.

Parameters:

`[in]`	queue	- the queue from which the next item payload should be returned.
`[out]`	ppPayload	- the address of storage in which to return a reference to the next item payload.

Returns:: Zero on success, or DNX_ERR_NOTFOUND if there is no next node.

Note:: Not currently used (or exported by the dnxQueue.h header file).
Cancellation safe.

Definition at line 138 of file dnxQueue.c.

References iDnxQueue_::current, DNX_ERR_NOTFOUND, DNX_OK, DNX_PT_MUTEX_LOCK, DNX_PT_MUTEX_UNLOCK, iDnxQueue_::head, iDnxQueue_::mutex, iDnxQueueEntry_::next, and iDnxQueueEntry_::pPayload.

int dnxQueuePut	(	DnxQueue *	queue,
		void *	pPayload
	)

Add an opaque payload to a queue.

Parameters:

`[in]`	queue	- the queue to which `pPayload` should be added.
`[in]`	pPayload	- the data to be added to `queue`.

Returns:: Zero on success, or a non-zero error value.

Note:: Cancellation safe.

Definition at line 197 of file dnxQueue.c.

References iDnxQueue_::current, iDnxQueue_::cv, DNX_ERR_MEMORY, DNX_OK, DNX_PT_MUTEX_LOCK, DNX_PT_MUTEX_UNLOCK, iDnxQueue_::freepayload, iDnxQueue_::head, iDnxQueue_::maxsz, iDnxQueue_::mutex, iDnxQueueEntry_::next, iDnxQueueEntry_::pPayload, iDnxQueue_::size, iDnxQueue_::tail, xfree, and xmalloc.

DnxQueueResult dnxQueueRemove	(	DnxQueue *	queue,
		void **	ppPayload,
		DnxQueueResult()(void pLeft, void *pRight)	Compare
	)

Remove a matching payload from a queue.

Parameters:

`[in]`	queue	- the queue to be queried for a matching payload.
`[in,out]`	ppPayload	- on entry contains the payload to be located; on exit returns the located payload.
`[in]`	Compare	- a comparison function used to location an item whose payload matches `ppPayload`; accepts two void pointers to user payload objects, and returns a DnxQueueResult code.

Returns:: A DnxQueueResult code - DNX_QRES_FOUND (1) if found, or DNX_QRES_CONTINUE (0) if not found. This is essentially a boolean value as the value of DNX_QRES_CONTINUE is zero.

Note:: Cancellation safe.

Definition at line 295 of file dnxQueue.c.

References iDnxQueue_::current, DNX_PT_MUTEX_LOCK, DNX_PT_MUTEX_UNLOCK, DNX_QRES_CONTINUE, DNX_QRES_FOUND, iDnxQueue_::head, iDnxQueue_::mutex, iDnxQueueEntry_::next, iDnxQueueEntry_::pPayload, iDnxQueue_::size, iDnxQueue_::tail, and xfree.

int dnxQueueSize ( DnxQueue * queue )

Return the number of items in the queue.

Parameters:

[in] queue - the queue to be queried for item count.

Returns:: The count of items in the queue.

Note:: Not currently used (or exported by the dnxQueue.h header file).
Cancellation safe.

Definition at line 177 of file dnxQueue.c.

References DNX_PT_MUTEX_LOCK, DNX_PT_MUTEX_UNLOCK, iDnxQueue_::mutex, and iDnxQueue_::size.


Data Structures
struct	iDnxQueueEntry_
	Queue entry wrapper structure - wraps user payload. More...
struct	iDnxQueue_
	Queue implementation structure. More...
Typedefs
typedef struct iDnxQueueEntry_	iDnxQueueEntry
	Queue entry wrapper structure - wraps user payload.
typedef struct iDnxQueue_	iDnxQueue
	Queue implementation structure.
Functions
int	dnxQueueGetWait (DnxQueue queue, void *ppPayload)
	Waits and returns the first pending item payload from a queue.
int	dnxQueueNext (DnxQueue queue, void *ppPayload)
	Return the next item payload without removing it from the queue.
int	dnxQueueSize (DnxQueue *queue)
	Return the number of items in the queue.
int	dnxQueuePut (DnxQueue queue, void pPayload)
	Add an opaque payload to a queue.
int	dnxQueueGet (DnxQueue queue, void *ppPayload)
	Returns the first entry from the queue.
DnxQueueResult	dnxQueueRemove (DnxQueue queue, void ppPayload, DnxQueueResult(Compare)(void pLeft, void pRight))
	Remove a matching payload from a queue.
DnxQueueResult	dnxQueueFind (DnxQueue queue, void ppPayload, DnxQueueResult(Compare)(void pLeft, void pRight))
	Find a node matching a specified payload in a queue.
int	dnxQueueCreate (unsigned maxsz, void(pldtor)(void ), DnxQueue **pqueue)
	Create a new queue object.
void	dnxQueueDestroy (DnxQueue *queue)
	Delete a requests queue.