cnet's support functions

NAME

Queueing support functions.

SYNOPSIS

#include <cnet.h>
#include <cnetsupport.h>

typedef void *  QUEUE;
extern  QUEUE   queue_new(void);
extern  void    queue_free(QUEUE q);
extern  void    queue_add(QUEUE q, void *item, size_t len);
extern  void    *queue_remove(QUEUE q, size_t *len);
extern  void    *queue_peek(QUEUE q, size_t *len);
extern  int     queue_nitems(QUEUE q);

DESCRIPTION

It is a very common requirement of network protocols to manage items, such as packets, in a first-in-first-out manner. This set of functions supports the maintenance of queues of arbitrary data. A cnet node may have an unlimited number of such queues.

A new queue is firstly allocated by calling queue_new, and should eventually be deallocated with a call to queue_free. The opaque value returned by queue_new should be passed to all other functions, to identify which queue is being used.

Items, of any type, may be added to a queue with queue_add. The functions do not know what they are queueing, and so you must also provide the length, in bytes, of each added item. A copy is made of all items added to a queue. The number of items in a queue may be determined at any time by calling queue_nitems.

Removing the oldest (head) item from a queue returns a pointer to the previously allocated copy, which you should use and, eventually, free. Peeking at the head of a queue does not remove the item.

EXAMPLE

A typical use of these functions is:

QUEUE     myq;
MYTYPE    mydata, *myptr;
size_t    len;

myq     = queue_new();
queue_add(myq, &mydata, sizeof(mydata));
.....
queue_add(myq, &mydata, sizeof(mydata));
.....
if(queue_nitems(myq) > 0) {
    myptr   = queue_remove(myq, &len);
    .....
    free(myptr);
}
.....
queue_free(myq);