epicsRingBytes.h

A circular buffer to store bytes.

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.

Author

Marty Kraimer, Eric Norum, Ralph Lange

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.

Typedefs

typedef void *epicsRingBytesId

An identifier for a ring buffer.

typedef void const *epicsRingBytesIdConst

Functions

epicsRingBytesId epicsRingBytesCreate(int nbytes)

Create a new ring buffer.

Parameters:

nbytes – Size of ring buffer to create

Returns:

Ring buffer Id or NULL on failure

epicsRingBytesId 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

void epicsRingBytesDelete(epicsRingBytesId id)

Delete the ring buffer and free any associated memory.

Parameters:

id – RingbufferID returned by epicsRingBytesCreate()

int 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

int 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

void epicsRingBytesFlush(epicsRingBytesId id)

Make the ring buffer empty.

Note

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

Parameters:

id – RingbufferID returned by epicsRingBytesCreate()

int 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

int 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

int 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().

int 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

int 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

int 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

void 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()