adt gqueue: Generic simple queue.

## Data Structures

struct | gqueue_node
struct | gqueue

## Macros

#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.

## Macro Definition Documentation

## GQUEUE_DECL

#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);
gqueue
Definition: gqueue.h:29

Declare specialized `gqueue` functions.

Examples:
  adt/gqueue_test.c.

## GQUEUE_DEFN

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

Value:
GQUEUE_PUSH_DEFN(PREFIX,TYPE,COPY) \
GQUEUE_TOP_DEFN(PREFIX,TYPE) \
GQUEUE_POP_DEFN(PREFIX,FREE)
GQUEUE_PUSH_DEFN
#define GQUEUE_PUSH_DEFN(PREFIX, TYPE, COPY)
Definition: gqueue.h:51

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.

## GQUEUE_POP_DEFN

#define GQUEUE_POP_DEFN | ( |  | PREFIX,
|  |  | FREE
| ) |  |

Value:
void PREFIX##_pop(struct gqueue* q) { \
gqueue_pop(q, (adt_free_fn*)(FREE)); \
}
adt_free_fn
void adt_free_fn(void *)
Definition: adt_common.h:12
gqueue
Definition: gqueue.h:29

Define a specialized `gqueue` pop function.

## GQUEUE_PUSH_DEFN

#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); \
}
gqueue_push
int gqueue_push(struct gqueue *d, unsigned datasize, const void *data, adt_copy_fn *fn)
Definition: gqueue_push.c:8
gqueue
Definition: gqueue.h:29
adt_copy_fn
int adt_copy_fn(void *, const void *)
Definition: adt_common.h:16

Define a specialized `gqueue` push function.

## GQUEUE_TOP_DEFN

#define GQUEUE_TOP_DEFN | ( |  | PREFIX,
|  |  | TYPE
| ) |  |

Value:
TYPE* PREFIX##_top(struct gqueue* q) { \
return (q->head == 0) ? 0 : (TYPE*)q->head->data; \
}
gqueue_node::data
char data[0]
Definition: gqueue.h:25
gqueue
Definition: gqueue.h:29
gqueue::head
struct gqueue_node * head
Definition: gqueue.h:32

Define a specialized `gqueue` top function.

## Function Documentation

## gqueue_pop()

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.

References gqueue::count, gqueue_node::data, gqueue::head, gqueue_node::next, and gqueue::tail.

## gqueue_push()

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.

References gqueue::count, gqueue_node::data, gqueue::head, gqueue_node::next, and gqueue::tail.

## gqueue_top()

void* gqueue_top | ( | const struct gqueue * | q | ) |

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

References gqueue_node::data, and gqueue::head.