ringqOpen basic EMF

Synopsis

Create a new ring queue for dynamic strings

Prototype

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

Parameters

rq Pointer to a ringq_t struct that receives the new ring queue
increment The amount to increase the size of the ringq should it need to grow
maxsize The upper limit beyond which the queue must not grow

Description

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

WARNING:  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.

Eg. 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 fillers responsibility to ensure
the ringq is never filled such that servp == endp.

It is the fillers 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



See Also

ringqPutBlk, ringqPutStr, ringqPutc