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);


 cnet v3.3.4, written by Chris.McDonald@uwa.edu.au
 Last modified: Tue Mar 1 7:43AM 2016