adt gqueue: Generic simple queue.

Data Structures
struct	gqueue_node
struct	gqueue
Defines
#define	GQUEUE_DECL(PREFIX, TYPE)
#define	GQUEUE_PUSH_DEFN(PREFIX, TYPE, COPY)
#define	GQUEUE_TOP_DEFN(PREFIX, TYPE)
#define	GQUEUE_POP_DEFN(PREFIX, FREE)
#define	GQUEUE_DEFN(PREFIX, TYPE, COPY, FREE)
Functions
int	gqueue_push (struct gqueue *d, unsigned datasize, const void *data, adt_copy_fn *fn)
void *	gqueue_top (const struct gqueue *q)
void	gqueue_pop (struct gqueue *q, adt_free_fn *fn)

---

Detailed Description

A generic queue is a first-in-first-out structure defined here based on three primary operations: push, top, and pop. Pushing an element onto a queue adds it to the tail of the list. The top operation fetches the least recently pushed element still on the queue, and popping removes it.

---

Define Documentation

#define GQUEUE_DECL	(	PREFIX,
		TYPE		)

Value:

extern int PREFIX##_push(struct gqueue* q, TYPE const* data); \
extern TYPE* PREFIX##_top(struct gqueue* q); \
extern void PREFIX##_pop(struct gqueue* q);

Declare specialized gqueue functions.

Examples:

adt/gqueue_test.c.

#define GQUEUE_DEFN	(	PREFIX,
		TYPE,
		COPY,
		FREE		)

Value:

GQUEUE_PUSH_DEFN(PREFIX,TYPE,COPY) \
GQUEUE_TOP_DEFN(PREFIX,TYPE) \
GQUEUE_POP_DEFN(PREFIX,FREE)

Define all the specialized gqueue functions. If COPY is NULL, a simple memcpy is used instead. If FREE is NULL, no attempt is made to free the data.

Examples:

adt/gqueue_test.c.

#define GQUEUE_POP_DEFN	(	PREFIX,
		FREE		)

Value:

void PREFIX##_pop(struct gqueue* q) { \
  gqueue_pop(q, (adt_free_fn*)(FREE)); \
}

Define a specialized gqueue pop function.

#define GQUEUE_PUSH_DEFN	(	PREFIX,
		TYPE,
		COPY		)

Value:

int PREFIX##_push(struct gqueue* q, TYPE const* data) { \
  return gqueue_push(q, sizeof *data, data, (adt_copy_fn*)COPY); \
}

Define a specialized gqueue push function.

#define GQUEUE_TOP_DEFN	(	PREFIX,
		TYPE		)

Value:

TYPE* PREFIX##_top(struct gqueue* q) { \
  return (q->head == 0) ? 0 : (TYPE*)q->head->data; \
}

Define a specialized gqueue top function.

---

Function Documentation

void gqueue_pop	(	struct gqueue *	q,
		adt_free_fn *	fn
	)

Remove the first (least recently pushed) element from the queue. If the free function fn is NULL no data freeing is done. Note that this does not return a pointer to the popped item, as once the item has been popped it is also freed.

int gqueue_push	(	struct gqueue *	q,
		unsigned	datasize,
		const void *	data,
		adt_copy_fn *	fn
	)

Add a new element onto the queue. If the copy function fn is NULL memcpy is used in its place.

void* gqueue_top

(

const struct gqueue *

q

)

Return the address of first (least recently pushed) element in the queue.

---