DynBuffer.h

Classes

DynBuffer -- Store data in dynamically allocated buffers (full description)

class DynBuffer

Interface

Public Members
DynBuffer (uInt nrOfBytes=4096)
~DynBuffer ()
void allocstart ()
uInt alloc (uInt nrOfValues, uInt valueSize, Char*& ptr)
void remove (uInt nrOfBuffer=1)
void nextstart ()
Bool next (uInt& usedLength, Char*& ptr)
Private Members
uInt newbuf (uInt nrOfValues, uInt valueSize)

Description

Review Status

Reviewed By:
Friso Olnon
Date Reviewed:
1995/03/16
Programs:
Tests:

Synopsis

DynBuffer allows one to store data in dynamically allocated buffers. When a buffer is full, an additional buffer can be allocated and "linked" to the existing one; so, the data may not be stored contiguously You can loop through all the linked buffers and get their individual addresses and sizes, so that you can access the data.

Example

Example (without exception handling): 
    uInt nrOfValues, nrNeeded, nrAvailable;// nr of data values
    float* pData = floatarr;               // ptr to data to be handled
    Char* pBuffer;                         // ptr to buffer
    
    DynBuffer buffer;                      // create buffer
    buffer.allocstart();                   // prepare for storing
    nrNeeded = nrOfValues;                 // nr of values to store
    // copy data into dynamic buffer
    while (nrNeeded > 0) {
        nrAvailable = buffer.alloc (nrNeeded, sizeof(float), pBuffer);
                                           // get buffer space:
                                           // room for nrAvailable values
        memcpy (pBuffer, pData, nrAvailable*sizeof(float));
                                           // copy that many data values
        nrNeeded -= nrAvailable;           // how much more needed?
        pData += nrAvailable;              // pointer to as yet unstored data
    }
    // Maybe store more values
        .
        .
    // Retrieve all the data values from the buffers and write them
    buffer.nextstart();                    // goto buffer start
    while (buffer.next (nrAvailable, pBuffer)) {
                                           // get next buffer
        write (fd, nrAvailable, pBuffer);  // write data from that buffer
    }

Motivation

This class is developed as an intermediate buffer for class AipsIO, but it may serve other purposes as well.

Member Description

DynBuffer (uInt nrOfBytes=4096)

Allocate a first buffer of the specified number of bytes (default 4096). When the allocation fails, an exception is thrown.

Thrown Exceptions

~DynBuffer ()

Remove the whole buffer, i.e. the first buffer and all the buffers appended to it.

void allocstart ()

Prepare for storing data (re-initialize the buffer)

uInt alloc (uInt nrOfValues, uInt valueSize, Char*& ptr)

Allocate buffer space for nrOfValues values of size valueSize bytes, and return the pointer ptr to the buffer and the number of values that fit in the buffer.

When not all values fit in the current buffer, new buffer space is added (probably non-contiguous). If that allocation fails an exception is thrown.

Thrown Exceptions

void remove (uInt nrOfBuffer=1)

Remove buffer nrOfBuffer and the buffers appended to it, and re-initialize the current buffer. By default we keep the first buffer (i.e. the one numbered 0).

The idea is that you may want to free intermediate storage space taken up by data that you no longer need, and that the first buffer is often big enough to hold further data. So, you only remove the first buffer in special cases.

void nextstart ()

Prepare for data retrieval (set up for looping through the buffers).

Bool next (uInt& usedLength, Char*& ptr)

Get the pointer to the next buffer and its used length in bytes. The function returns a False value if there are no more buffers.

uInt newbuf (uInt nrOfValues, uInt valueSize)

Get the next buffer for storing nrOfValues values of size valueSize bytes, and return the number of values that can be stored in the free space of that buffer (maybe less than nrOfValues).

The new current buffer can be the present one (if it has free space), the next buffer already allocated (if there is one), or a newly allocated and linked-in buffer. If, in the last case, the allocation fails an exception is thrown.

Thrown Exceptions