epicsRingPointer.h File Reference

A circular buffer to store pointers. More...

#include "epicsSpin.h"
#include "libComAPI.h"

Include dependency graph for epicsRingPointer.h:

Go to the source code of this file.

Classes
class	epicsRingPointer< T >
	A C++ template class providing methods for creating and using a ring buffer (a first in, first out circular buffer) that stores pointers to objects of the template type. More...

Macros
#define	epicsRingPointerSize   epicsRingPointerGetSize

Typedefs
typedef void *	epicsRingPointerId
	An identifier for the C API to a ring buffer storing pointers.
typedef void const *	epicsRingPointerIdConst

Functions
LIBCOM_API epicsRingPointerId epicsStdCall	epicsRingPointerCreate (int size)
	Create a new ring buffer. More...
LIBCOM_API epicsRingPointerId epicsStdCall	epicsRingPointerLockedCreate (int size)
	Create a new ring buffer, secured by a spinlock. More...
LIBCOM_API void epicsStdCall	epicsRingPointerDelete (epicsRingPointerId id)
	Delete the ring buffer and free any associated memory. More...
LIBCOM_API int epicsStdCall	epicsRingPointerPush (epicsRingPointerId id, void *p)
	Push pointer into the ring buffer. More...
LIBCOM_API void *epicsStdCall	epicsRingPointerPop (epicsRingPointerId id)
	Take an element off the ring. More...
LIBCOM_API void epicsStdCall	epicsRingPointerFlush (epicsRingPointerId id)
	Remove all elements from the ring. More...
LIBCOM_API int epicsStdCall	epicsRingPointerGetFree (epicsRingPointerId id)
	Return the amount of empty space in the ring buffer. More...
LIBCOM_API int epicsStdCall	epicsRingPointerGetUsed (epicsRingPointerId id)
	Return the number of elements stored in the ring buffer. More...
LIBCOM_API int epicsStdCall	epicsRingPointerGetSize (epicsRingPointerId id)
	Return the size of the ring. More...
LIBCOM_API int epicsStdCall	epicsRingPointerIsEmpty (epicsRingPointerId id)
	Check if the ring buffer is currently empty. More...
LIBCOM_API int epicsStdCall	epicsRingPointerIsFull (epicsRingPointerId id)
	Check if the ring buffer is currently full. More...
LIBCOM_API int epicsStdCall	epicsRingPointerGetHighWaterMark (epicsRingPointerIdConst id)
	Get the Highwater mark of the ring buffer. More...
LIBCOM_API void epicsStdCall	epicsRingPointerResetHighWaterMark (epicsRingPointerId id)
	Reset the Highwater mark of the ring buffer. More...

Detailed Description

Author

Marty Kraimer, Ralph Lange

epicsRingPointer.h provides both C and C++ APIs for creating and using ring buffers (first in first out circular buffers) that store pointers. The unlocked kind 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 pushes. If there is a single reader it is not necessary to lock pops. epicsRingPointerLocked uses a spinlock.

Definition in file epicsRingPointer.h.

Function Documentation

LIBCOM_API epicsRingPointerId epicsStdCall epicsRingPointerCreate

(

int

size

)

Parameters

size	Size of ring buffer to create

Returns

Ring buffer identifier or NULL on failure

LIBCOM_API epicsRingPointerId epicsStdCall epicsRingPointerLockedCreate

(

int

size

)

Parameters

size	Size of ring buffer to create

Returns

Ring buffer identifier or NULL on failure

LIBCOM_API void epicsStdCall epicsRingPointerDelete

(

epicsRingPointerId

id

)

Parameters

id	Ring buffer identifier

LIBCOM_API int epicsStdCall epicsRingPointerPush	(	epicsRingPointerId	id,
		void *	p
	)

Parameters

id	Ring buffer identifier
p	Pointer to be pushed to the ring

Returns

1 if the pointer was successfully pushed, 0 if the buffer was full

LIBCOM_API void* epicsStdCall epicsRingPointerPop

(

epicsRingPointerId

id

)

Parameters

id	Ring buffer identifier

Returns

The pointer from the buffer, or NULL if the ring was empty

LIBCOM_API void epicsStdCall epicsRingPointerFlush

(

epicsRingPointerId

id

)

Parameters

id	Ring buffer identifier

Note

If this operation is performed on a ring buffer of the unsecured kind, all access to the ring should be locked.

LIBCOM_API int epicsStdCall epicsRingPointerGetFree

(

epicsRingPointerId

id

)

Parameters

id	Ring buffer identifier

Returns

The number of additional elements it could hold.

LIBCOM_API int epicsStdCall epicsRingPointerGetUsed

(

epicsRingPointerId

id

)

Parameters

id	Ring buffer identifier

Returns

The number of elements stored in the ring buffer

LIBCOM_API int epicsStdCall epicsRingPointerGetSize

(

epicsRingPointerId

id

)

Parameters

id	Ring buffer identifier

Returns

The size of the ring buffer, i.e. the value of size given when the ring was created.

LIBCOM_API int epicsStdCall epicsRingPointerIsEmpty

(

epicsRingPointerId

id

)

Parameters

id	Ring buffer identifier

Returns

1 if the ring is empty, otherwise 0

LIBCOM_API int epicsStdCall epicsRingPointerIsFull

(

epicsRingPointerId

id

)

Parameters

id	Ring buffer identifier

Returns

1 if the ring buffer is full, otherwise 0

LIBCOM_API int epicsStdCall epicsRingPointerGetHighWaterMark

(

epicsRingPointerIdConst

id

)

Returns the largest number of elements the ring buffer has held since the water mark was last reset. A new ring buffer starts with a water mark of 0.

Parameters

id	Ring buffer identifier

Returns

Actual Highwater mark

LIBCOM_API void epicsStdCall epicsRingPointerResetHighWaterMark

(

epicsRingPointerId

id

)

The Highwater mark will be set to the current usage

Parameters

id	Ring buffer identifier