epicsRingBytes.h File Reference

A circular buffer to store bytes. More...

#include "libComAPI.h"

Include dependency graph for epicsRingBytes.h:

Go to the source code of this file.

Typedefs
typedef void *	epicsRingBytesId
	An identifier for a ring buffer.
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

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.

Function Documentation

LIBCOM_API epicsRingBytesId epicsStdCall epicsRingBytesCreate

(

int

nbytes

)

Parameters

nbytes

Size of ring buffer to create

Returns

Ring buffer Id or NULL on failure

LIBCOM_API epicsRingBytesId epicsStdCall epicsRingBytesLockedCreate

(

int

nbytes

)

Parameters

nbytes

Size of ring buffer to create

Returns

Ring buffer Id or NULL on failure

LIBCOM_API void epicsStdCall epicsRingBytesDelete

(

epicsRingBytesId

id

)

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

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

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

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

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

LIBCOM_API void epicsStdCall epicsRingBytesFlush

(

epicsRingBytesId

id

)

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Note

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

LIBCOM_API int epicsStdCall epicsRingBytesFreeBytes

(

epicsRingBytesId

id

)

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Returns

The number of free bytes in the ring buffer

LIBCOM_API int epicsStdCall epicsRingBytesUsedBytes

(

epicsRingBytesId

id

)

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Returns

The number of bytes currently stored in the ring buffer

LIBCOM_API int epicsStdCall epicsRingBytesSize

(

epicsRingBytesId

id

)

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Returns

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

LIBCOM_API int epicsStdCall epicsRingBytesIsEmpty

(

epicsRingBytesId

id

)

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Returns

1 if the buffer is empty, otherwise 0

LIBCOM_API int epicsStdCall epicsRingBytesIsFull

(

epicsRingBytesId

id

)

Parameters

id	RingbufferID returned by epicsRingBytesCreate()

Returns

1 if the buffer is full, otherwise 0

LIBCOM_API int epicsStdCall epicsRingBytesHighWaterMark

(

epicsRingBytesIdConst

id

)

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

LIBCOM_API void epicsStdCall epicsRingBytesResetHighWaterMark

(

epicsRingBytesId

id

)

The Highwater mark will be set to the current usage

Parameters

id	RingbufferID returned by epicsRingBytesCreate()