A circular buffer to store pointers. More...

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

Include dependency graph for epicsRingPointer.h:

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

Macros
#define	epicsRingPointerSize epicsRingPointerGetSize

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

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

A circular buffer to store pointers.

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.

Macro Definition Documentation

#define epicsRingPointerSize epicsRingPointerGetSize

Definition at line 207 of file epicsRingPointer.h.

Typedef Documentation

typedef void* epicsRingPointerId

An identifier for the C API to a ring buffer storing pointers.

Definition at line 118 of file epicsRingPointer.h.

typedef void const* epicsRingPointerIdConst

Definition at line 119 of file epicsRingPointer.h.

Function Documentation

LIBCOM_API epicsRingPointerId epicsStdCall epicsRingPointerCreate ( int size )

Create a new ring buffer.

Parameters

size	Size of ring buffer to create

Returns: Ring buffer identifier or NULL on failure

Definition at line 27 of file epicsRingPointer.cpp.

 {
     voidPointer *pvoidPointer = new voidPointer(size, false);
     return(reinterpret_cast<void *>(pvoidPointer));
 }

LIBCOM_API void epicsStdCall epicsRingPointerDelete ( epicsRingPointerId id )

Delete the ring buffer and free any associated memory.

Parameters

id	Ring buffer identifier

Definition at line 39 of file epicsRingPointer.cpp.

 {
     voidPointer *pvoidPointer = reinterpret_cast<voidPointer*>(id);
     delete pvoidPointer;
 }

LIBCOM_API void epicsStdCall epicsRingPointerFlush ( epicsRingPointerId id )

Remove all elements from the ring.

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.

Definition at line 57 of file epicsRingPointer.cpp.

 {
     voidPointer *pvoidPointer = reinterpret_cast<voidPointer*>(id);
     pvoidPointer->flush();
 }

LIBCOM_API int epicsStdCall epicsRingPointerGetFree ( epicsRingPointerId id )

Return the amount of empty space in the ring buffer.

Parameters

id	Ring buffer identifier

Returns: The number of additional elements it could hold.

Definition at line 63 of file epicsRingPointer.cpp.

 {
     voidPointer *pvoidPointer = reinterpret_cast<voidPointer*>(id);
     return(pvoidPointer->getFree());
 }

LIBCOM_API int epicsStdCall epicsRingPointerGetHighWaterMark ( epicsRingPointerIdConst id )

Get the Highwater mark of the ring buffer.

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

Definition at line 93 of file epicsRingPointer.cpp.

 {
     voidPointer const *pvoidPointer = reinterpret_cast<voidPointer const*>(id);
     return(pvoidPointer->getHighWaterMark());
 }

LIBCOM_API int epicsStdCall epicsRingPointerGetSize ( epicsRingPointerId id )

Return the size of the ring.

Parameters

id	Ring buffer identifier

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

Definition at line 75 of file epicsRingPointer.cpp.

 {
     voidPointer *pvoidPointer = reinterpret_cast<voidPointer*>(id);
     return(pvoidPointer->getSize());
 }

LIBCOM_API int epicsStdCall epicsRingPointerGetUsed ( epicsRingPointerId id )

Return the number of elements stored in the ring buffer.

Parameters

id	Ring buffer identifier

Returns: The number of elements stored in the ring buffer

Definition at line 69 of file epicsRingPointer.cpp.

 {
     voidPointer *pvoidPointer = reinterpret_cast<voidPointer*>(id);
     return(pvoidPointer->getUsed());
 }

LIBCOM_API int epicsStdCall epicsRingPointerIsEmpty ( epicsRingPointerId id )

Check if the ring buffer is currently empty.

Parameters

id	Ring buffer identifier

Returns: 1 if the ring is empty, otherwise 0

Definition at line 81 of file epicsRingPointer.cpp.

 {
     voidPointer *pvoidPointer = reinterpret_cast<voidPointer*>(id);
     return((pvoidPointer->isEmpty()) ? 1 : 0);
 }

LIBCOM_API int epicsStdCall epicsRingPointerIsFull ( epicsRingPointerId id )

Check if the ring buffer is currently full.

Parameters

id	Ring buffer identifier

Returns: 1 if the ring buffer is full, otherwise 0

Definition at line 87 of file epicsRingPointer.cpp.

 {
     voidPointer *pvoidPointer = reinterpret_cast<voidPointer*>(id);
     return((pvoidPointer->isFull()) ? 1 : 0);
 }

LIBCOM_API epicsRingPointerId epicsStdCall epicsRingPointerLockedCreate ( int size )

Create a new ring buffer, secured by a spinlock.

Parameters

size	Size of ring buffer to create

Returns: Ring buffer identifier or NULL on failure

Definition at line 33 of file epicsRingPointer.cpp.

 {
     voidPointer *pvoidPointer = new voidPointer(size, true);
     return(reinterpret_cast<void *>(pvoidPointer));
 }

LIBCOM_API void* epicsStdCall epicsRingPointerPop ( epicsRingPointerId id )

Take an element off the ring.

Parameters

id	Ring buffer identifier

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

Definition at line 45 of file epicsRingPointer.cpp.

 {
     voidPointer *pvoidPointer = reinterpret_cast<voidPointer*>(id);
     return pvoidPointer->pop();
 }

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

Push pointer into the ring buffer.

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

Definition at line 51 of file epicsRingPointer.cpp.

 {
     voidPointer *pvoidPointer = reinterpret_cast<voidPointer*>(id);
     return((pvoidPointer->push(p) ? 1 : 0));
 }

LIBCOM_API void epicsStdCall epicsRingPointerResetHighWaterMark ( epicsRingPointerId id )

Reset the Highwater mark of the ring buffer.

The Highwater mark will be set to the current usage

Parameters

id	Ring buffer identifier

Definition at line 99 of file epicsRingPointer.cpp.

 {
     voidPointer *pvoidPointer = reinterpret_cast<voidPointer*>(id);
     pvoidPointer->resetHighWaterMark();
 }

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation