dnxQueue.h File Reference

Definitions and prototypes for thread-safe DNX queues. More...

Go to the source code of this file.

Data Structures
struct	DnxQueue
	An abstract data type for DnxQueue. More...
Typedefs
typedef enum DnxQueueResult_	DnxQueueResult
Enumerations
enum	DnxQueueResult_ {   DNX_QRES_CONTINUE = 0, DNX_QRES_FOUND, DNX_QRES_EXIT, DNX_QRES_ERROR,   DNX_QRES_CONTINUE = 0, DNX_QRES_FOUND, DNX_QRES_EXIT, DNX_QRES_ERROR }
Functions
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.
int	dnxQueueGetWait (DnxQueue *queue, unsigned timeout, void **ppPayload)
	Waits and returns the first pending item payload from a 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

Definitions and prototypes for thread-safe DNX queues.

Author:

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

Attention:

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

Definition in file dnxQueue.h.

---

Typedef Documentation

typedef enum DnxQueueResult_ DnxQueueResult

---

Enumeration Type Documentation

enum DnxQueueResult_

Enumerator:

DNX_QRES_CONTINUE
DNX_QRES_FOUND
DNX_QRES_EXIT
DNX_QRES_ERROR
DNX_QRES_CONTINUE
DNX_QRES_FOUND
DNX_QRES_EXIT
DNX_QRES_ERROR

Definition at line 31 of file dnxQueue.h.

---

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 367 of file dnxQueue.c.

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 392 of file dnxQueue.c.

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 339 of file dnxQueue.c.

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 196 of file dnxQueue.c.

int dnxQueueGetWait	(	DnxQueue *	queue,
		unsigned	timeout,
		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.
[in]	timeout	- seconds to wait (0 means infinite).
[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:

Cancellation safe.

Definition at line 235 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 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 137 of file dnxQueue.c.

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 289 of file dnxQueue.c.