xhh1314 / CircularBuffer

circular buffer, circular queue, cyclic buffer, ring buffer

CircularBuffer

Difinition

The difinition of circular buffer from Wikipedia:

A circular buffer, circular queue, cyclic buffer or ring buffer is a data structure that uses a single, fixed-size buffer as if it were connected end-to-end. This structure lends itself easily to buffering data streams.

A circular buffer first starts empty and of some predefined length. For example, this is a 7-element buffer:

Assume that a 1 is written into the middle of the buffer (exact starting location does not matter in a circular buffer):

Then assume that two more elements are added — 2 & 3 — which get appended after the 1:

If two elements are then removed from the buffer, the oldest values inside the buffer are removed. The two elements removed, in this case, are 1 & 2, leaving the buffer with just a 3:

If the buffer has 7 elements then it is completely full:

A consequence of the circular buffer is that when it is full and a subsequent write is performed, then it starts overwriting the oldest data. In this case, two more elements — A & B — are added and they overwrite the 3 & 4:

Alternatively, the routines that manage the buffer could prevent overwriting the data and return an error or raise an exception. Whether or not data is overwritten is up to the semantics of the buffer routines or the application using the circular buffer.

Finally, if two elements are now removed then what would be returned is not 3 & 4 but 5 & 6 because A & B overwrote the 3 & the 4 yielding the buffer with:

Code

// CircularBuffer create
extern CircularBuffer CircularBufferCreate(size_t size);

// CircularBuffer free
extern void CircularBufferFree(CircularBuffer *cBuf);

// CircularBuffer reset
extern void CircularBufferReset(CircularBuffer *cBuf);

// CircularBuffer push
extern void CircularBufferPush(CircularBuffer *cBuf,void *src, size_t length);

// CircularBuffer pop
extern size_t CircularBufferPop(CircularBuffer *cBuf, size_t length, void *dataOut);

// CircularBuffer read
extern size_t CircularBufferRead(CircularBuffer *cBuf, size_t length, void *dataOut);

// Print CircularBuffer data in console for debug purpose 
extern void logCircularBuffer(CircularBuffer cBuf);

Author

Roen, [e-mail]

Licenses

All source code is licensed under the MIT License