Synopsis

Create a new ring queue for dynamic strings.

Prototype

 #include "uemf.h"

 int ringqOpen(ringq_t *rq, int increment, int maxsize); 

Parameters

Description

A ring queue allows maximum utilization of memory for data storage and is ideal for input/output buffering. This module provides a highly efficient implementation and a vehicle for dynamic strings.

Caution: This is a public implementation and callers have full access to the queue structure and pointers. Change this module very carefully.

This module follows the open/close model.

Operation of a ringq where rq is a pointer to a ringq:

rq->buflen contains the size of the buffer.
rq->buf will point to the start of the buffer.
rq->servp will point to the first (un-consumed) data byte.
rq->endp will point to the next free location to which new data is added.
rq->endbuf will point to one past the end of the buffer.

E.g.: If the ringq contains the data "abcdef", it might look like:

+-------------------------------------------------------------------+
 |   |   |   |   |   |   |   | a | b | c | d | e | f |   |   |   |   |
+-------------------------------------------------------------------+
   ^                           ^                       ^               ^
   |                           |                       |               |
 rq->buf                    rq->servp               rq->endp      rq->enduf

The queue is empty when servp == endp. This means that the queue will hold at most rq->buflen -1 bytes. It is the filler's responsibility to ensure that the ringq is never filled such that servp == endp.

It is the filler's responsibility to "wrap" the endp back to point to rq->buf when the pointer steps past the end. Correspondingly, it is the consumers responsibility to "wrap" the servp when it steps to rq->endbuf. The ringqPutc and ringqGetc routines will do this automatically.

Return Value

0 on success, -1 on error.

Example

if (ringqOpen(&p.tagbuf, XML_INC, XML_MAX) < 0) {
    return -1;
}

Stability Classification

Evolving.

See Also

ringqPutBlk, ringqPutStr