epicsRingBytes.h File Reference

A circular buffer to store bytes. More...

#include "libComAPI.h"

Include dependency graph for epicsRingBytes.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef void *	epicsRingBytesId
	An identifier for a ring buffer. More...
typedef void const *	epicsRingBytesIdConst

Functions
LIBCOM_API epicsRingBytesId epicsStdCall	epicsRingBytesCreate (int nbytes)
	Create a new ring buffer. More...
LIBCOM_API epicsRingBytesId epicsStdCall	epicsRingBytesLockedCreate (int nbytes)
	Create a new ring buffer, secured by a spinlock. More...
LIBCOM_API void epicsStdCall	epicsRingBytesDelete (epicsRingBytesId id)
	Delete the ring buffer and free any associated memory. More...
LIBCOM_API int epicsStdCall	epicsRingBytesGet (epicsRingBytesId id, char *value, int nbytes)
	Read data out of the ring buffer. More...
LIBCOM_API int epicsStdCall	epicsRingBytesPut (epicsRingBytesId id, char *value, int nbytes)
	Write data into the ring buffer. More...
LIBCOM_API void epicsStdCall	epicsRingBytesFlush (epicsRingBytesId id)
	Make the ring buffer empty. More...
LIBCOM_API int epicsStdCall	epicsRingBytesFreeBytes (epicsRingBytesId id)
	Return the number of free bytes in the ring buffer. More...
LIBCOM_API int epicsStdCall	epicsRingBytesUsedBytes (epicsRingBytesId id)
	Return the number of bytes currently stored in the ring buffer. More...
LIBCOM_API int epicsStdCall	epicsRingBytesSize (epicsRingBytesId id)
	Return the size of the ring buffer. More...
LIBCOM_API int epicsStdCall	epicsRingBytesIsEmpty (epicsRingBytesId id)
	Test if the ring buffer is currently empty. More...
LIBCOM_API int epicsStdCall	epicsRingBytesIsFull (epicsRingBytesId id)
	Test if the ring buffer is currently full. More...
LIBCOM_API int epicsStdCall	epicsRingBytesHighWaterMark (epicsRingBytesIdConst id)
	See how full a ring buffer has been since it was last checked. More...
LIBCOM_API void epicsStdCall	epicsRingBytesResetHighWaterMark (epicsRingBytesId id)
	Reset the Highwater mark of the ring buffer. More...

Detailed Description

A circular buffer to store bytes.

Author

Marty Kraimer, Eric Norum, Ralph Lange

EpicsRingBytes provides a C API for creating and using ring buffers (first in first out circular buffers) that store bytes. The unlocked variant is designed so that one writer thread and one reader thread can access the ring simultaneously without requiring mutual exclusion. The locked variant uses an epicsSpinLock, and works with any numbers of writer and reader threads.

Note

If there is only one writer it is not necessary to lock for puts. If there is a single reader it is not necessary to lock for gets. epicsRingBytesLocked uses a spinlock.

Definition in file epicsRingBytes.h.

Typedef Documentation

typedef void* epicsRingBytesId

An identifier for a ring buffer.

Definition at line 37 of file epicsRingBytes.h.

typedef void const* epicsRingBytesIdConst

Definition at line 38 of file epicsRingBytes.h.

Function Documentation

LIBCOM_API epicsRingBytesId epicsStdCall epicsRingBytesCreate

(

int

nbytes

)

Create a new ring buffer.

Parameters

nbytes

Size of ring buffer to create

Returns

Ring buffer Id or NULL on failure

Definition at line 44 of file epicsRingBytes.c.

{
    ringPvt *pring = malloc(sizeof(ringPvt) + size + SLOP);
    if(!pring)
        return NULL;
    pring->size = size + SLOP;
    pring->highWaterMark = 0;
    pring->nextGet = 0;
    pring->nextPut = 0;
    pring->lock    = 0;
    return((void *)pring);
}

LIBCOM_API void epicsStdCall epicsRingBytesDelete

(

epicsRingBytesId

id

)

Delete the ring buffer and free any associated memory.

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Definition at line 66 of file epicsRingBytes.c.

{
    ringPvt *pring = (ringPvt *)id;
    if (pring->lock) epicsSpinDestroy(pring->lock);
    free((void *)pring);
}

LIBCOM_API void epicsStdCall epicsRingBytesFlush

(

epicsRingBytesId

id

)

Make the ring buffer empty.

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Note

Should only be used when both gets and puts are locked out.

Definition at line 169 of file epicsRingBytes.c.

{
    ringPvt *pring = (ringPvt *)id;

    if (pring->lock) epicsSpinLock(pring->lock);
    pring->nextGet = pring->nextPut;
    if (pring->lock) epicsSpinUnlock(pring->lock);
}

LIBCOM_API int epicsStdCall epicsRingBytesFreeBytes

(

epicsRingBytesId

id

)

Return the number of free bytes in the ring buffer.

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Returns

The number of free bytes in the ring buffer

Definition at line 178 of file epicsRingBytes.c.

{
    ringPvt *pring = (ringPvt *)id;
    int nextGet, nextPut;

    if (pring->lock) epicsSpinLock(pring->lock);
    nextGet = pring->nextGet;
    nextPut = pring->nextPut;
    if (pring->lock) epicsSpinUnlock(pring->lock);

    if (nextPut < nextGet)
        return nextGet - nextPut - SLOP;
    else
        return pring->size - nextPut + nextGet - SLOP;
}

LIBCOM_API int epicsStdCall epicsRingBytesGet	(	epicsRingBytesId	id,
		char *	value,
		int	nbytes
	)

Read data out of the ring buffer.

Parameters

id	RingbufferID returned by epicsRingBytesCreate()
value	Where to put the data fetched from the buffer
nbytes	Maximum number of bytes to get

Returns

The number of bytes actually fetched

Definition at line 73 of file epicsRingBytes.c.

{
    ringPvt *pring = (ringPvt *)id;
    int nextGet, nextPut, size;
    int count;

    if (pring->lock) epicsSpinLock(pring->lock);
    nextGet = pring->nextGet;
    nextPut = pring->nextPut;
    size = pring->size;

    if (nextGet <= nextPut) {
        count = nextPut - nextGet;
        if (count < nbytes)
            nbytes = count;
        if (nbytes)
            memcpy (value, (void *)&pring->buffer[nextGet], nbytes);
        nextGet += nbytes;
    }
    else {
        count = size - nextGet;
        if (count > nbytes)
            count = nbytes;
        memcpy (value, (void *)&pring->buffer[nextGet], count);
        nextGet += count;
        if (nextGet == size) {
            int nLeft = nbytes - count;
            if (nLeft > nextPut)
                nLeft = nextPut;
            memcpy (value+count, (void *)&pring->buffer[0], nLeft);
            nextGet = nLeft;
            nbytes = count + nLeft;
        }
        else {
            nbytes = count;
        }
    }
    pring->nextGet = nextGet;

    if (pring->lock) epicsSpinUnlock(pring->lock);
    return nbytes;
}

LIBCOM_API int epicsStdCall epicsRingBytesHighWaterMark

(

epicsRingBytesIdConst

id

)

See how full a ring buffer has been since it was last checked.

Returns the maximum amount of data the ring buffer has held in bytes since the water mark was last reset. A new ring buffer starts with a water mark of 0.

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Returns

Actual Highwater mark

Definition at line 235 of file epicsRingBytes.c.

{
    ringPvt *pring = (ringPvt *)id;
    return pring->highWaterMark;
}

LIBCOM_API int epicsStdCall epicsRingBytesIsEmpty

(

epicsRingBytesId

id

)

Test if the ring buffer is currently empty.

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Returns

1 if the buffer is empty, otherwise 0

Definition at line 218 of file epicsRingBytes.c.

{
    ringPvt *pring = (ringPvt *)id;
    int isEmpty;

    if (pring->lock) epicsSpinLock(pring->lock);
    isEmpty = (pring->nextPut == pring->nextGet);
    if (pring->lock) epicsSpinUnlock(pring->lock);

    return isEmpty;
}

LIBCOM_API int epicsStdCall epicsRingBytesIsFull

(

epicsRingBytesId

id

)

Test if the ring buffer is currently full.

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Returns

1 if the buffer is full, otherwise 0

Definition at line 230 of file epicsRingBytes.c.

{
    return (epicsRingBytesFreeBytes(id) <= 0);
}

LIBCOM_API epicsRingBytesId epicsStdCall epicsRingBytesLockedCreate

(

int

nbytes

)

Create a new ring buffer, secured by a spinlock.

Parameters

nbytes

Size of ring buffer to create

Returns

Ring buffer Id or NULL on failure

Definition at line 57 of file epicsRingBytes.c.

{
    ringPvt *pring = (ringPvt *)epicsRingBytesCreate(size);
    if(!pring)
        return NULL;
    pring->lock = epicsSpinCreate();
    return((void *)pring);
}

LIBCOM_API int epicsStdCall epicsRingBytesPut	(	epicsRingBytesId	id,
		char *	value,
		int	nbytes
	)

Write data into the ring buffer.

Parameters

id	RingbufferID returned by epicsRingBytesCreate()
value	Source of the data to be put into the buffer
nbytes	How many bytes to put

Returns

The number of bytes actually stored, zero if not enough space

Definition at line 117 of file epicsRingBytes.c.

{
    ringPvt *pring = (ringPvt *)id;
    int nextGet, nextPut, size;
    int freeCount, copyCount, topCount, used;

    if (pring->lock) epicsSpinLock(pring->lock);
    nextGet = pring->nextGet;
    nextPut = pring->nextPut;
    size = pring->size;

    if (nextPut < nextGet) {
        freeCount = nextGet - nextPut - SLOP;
        if (nbytes > freeCount) {
            if (pring->lock) epicsSpinUnlock(pring->lock);
            return 0;
        }
        if (nbytes) {
            memcpy ((void *)&pring->buffer[nextPut], value, nbytes);
        }
        nextPut += nbytes;
    }
    else {
        freeCount = size - nextPut + nextGet - SLOP;
        if (nbytes > freeCount) {
            if (pring->lock) epicsSpinUnlock(pring->lock);
            return 0;
        }
        topCount = size - nextPut;
        copyCount = (nbytes > topCount) ?  topCount : nbytes;
        if (copyCount) {
            memcpy ((void *)&pring->buffer[nextPut], value, copyCount);
        }
        nextPut += copyCount;
        if (nextPut == size) {
            int nLeft = nbytes - copyCount;
            if (nLeft)
                memcpy ((void *)&pring->buffer[0], value+copyCount, nLeft);
            nextPut = nLeft;
        }
    }
    pring->nextPut = nextPut;

    used = nextPut - nextGet;
    if (used < 0) used += pring->size;
    if (used > pring->highWaterMark) pring->highWaterMark = used;

    if (pring->lock) epicsSpinUnlock(pring->lock);
    return nbytes;
}

LIBCOM_API void epicsStdCall epicsRingBytesResetHighWaterMark

(

epicsRingBytesId

id

)

Reset the Highwater mark of the ring buffer.

The Highwater mark will be set to the current usage

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Definition at line 241 of file epicsRingBytes.c.

{
    ringPvt *pring = (ringPvt *)id;
    int used;
    if (pring->lock) epicsSpinLock(pring->lock);
    used = pring->nextGet - pring->nextPut;
    if (used < 0) used += pring->size;
    pring->highWaterMark = used;
    if (pring->lock) epicsSpinUnlock(pring->lock);
}

LIBCOM_API int epicsStdCall epicsRingBytesSize

(

epicsRingBytesId

id

)

Return the size of the ring buffer.

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Returns

Return the size of the ring buffer, i.e., nbytes specified in the call to epicsRingBytesCreate().

Definition at line 211 of file epicsRingBytes.c.

{
    ringPvt *pring = (ringPvt *)id;

    return pring->size - SLOP;
}

LIBCOM_API int epicsStdCall epicsRingBytesUsedBytes

(

epicsRingBytesId

id

)

Return the number of bytes currently stored in the ring buffer.

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Returns

The number of bytes currently stored in the ring buffer

Definition at line 194 of file epicsRingBytes.c.

{
    ringPvt *pring = (ringPvt *)id;
    int nextGet, nextPut;
    int used;

    if (pring->lock) epicsSpinLock(pring->lock);
    nextGet = pring->nextGet;
    nextPut = pring->nextPut;
    if (pring->lock) epicsSpinUnlock(pring->lock);

    used = nextPut - nextGet;
    if (used < 0) used += pring->size;

    return used;
}