epicsRingPointer.h

Go to the documentation of this file.

/*************************************************************************\
* Copyright (c) 2002 The University of Chicago, as Operator of Argonne
*     National Laboratory.
* Copyright (c) 2002 The Regents of the University of California, as
*     Operator of Los Alamos National Laboratory.
* Copyright (c) 2012 ITER Organization.
* SPDX-License-Identifier: EPICS
* EPICS BASE is distributed subject to a Software License Agreement found
* in file LICENSE that is included with this distribution.
\*************************************************************************/
#ifndef INCepicsRingPointerh
#define INCepicsRingPointerh


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

#ifdef __cplusplus

template <class T>
class epicsRingPointer {
public: /* Functions */
    epicsRingPointer(int size, bool locked);
    ~epicsRingPointer();
    bool push(T *p);
    T* pop();
    void flush();
    int getFree() const;
    int getUsed() const;
    int getSize() const;
    bool isEmpty() const;
    bool isFull() const;
    int getHighWaterMark() const;
    void resetHighWaterMark();

private: /* Prevent compiler-generated member functions */
    /* default constructor, copy constructor, assignment operator */
    epicsRingPointer();
    epicsRingPointer(const epicsRingPointer &);
    epicsRingPointer& operator=(const epicsRingPointer &);
    int getUsedNoLock() const;

private: /* Data */
    epicsSpinId lock;
    volatile int nextPush;
    volatile int nextPop;
    int size;
    int highWaterMark;
    T  * volatile * buffer;
};

extern "C" {
#endif /*__cplusplus */

typedef void *epicsRingPointerId;
typedef void const *epicsRingPointerIdConst;
LIBCOM_API epicsRingPointerId  epicsStdCall epicsRingPointerCreate(int size);
LIBCOM_API epicsRingPointerId  epicsStdCall epicsRingPointerLockedCreate(int size);
LIBCOM_API void epicsStdCall epicsRingPointerDelete(epicsRingPointerId id);
LIBCOM_API int  epicsStdCall epicsRingPointerPush(epicsRingPointerId id,void *p);
LIBCOM_API void* epicsStdCall epicsRingPointerPop(epicsRingPointerId id) ;
LIBCOM_API void epicsStdCall epicsRingPointerFlush(epicsRingPointerId id);
LIBCOM_API int  epicsStdCall epicsRingPointerGetFree(epicsRingPointerId id);
LIBCOM_API int  epicsStdCall epicsRingPointerGetUsed(epicsRingPointerId id);
LIBCOM_API int  epicsStdCall epicsRingPointerGetSize(epicsRingPointerId id);
LIBCOM_API int  epicsStdCall epicsRingPointerIsEmpty(epicsRingPointerId id);
LIBCOM_API int  epicsStdCall epicsRingPointerIsFull(epicsRingPointerId id);
LIBCOM_API int  epicsStdCall epicsRingPointerGetHighWaterMark(epicsRingPointerIdConst id);
LIBCOM_API void epicsStdCall epicsRingPointerResetHighWaterMark(epicsRingPointerId id);

/* This routine was incorrectly named in previous releases */
#define epicsRingPointerSize epicsRingPointerGetSize

#ifdef __cplusplus
}
#endif
/* END OF DECLARATIONS */

/* INLINE FUNCTIONS */

#ifdef __cplusplus

template <class T>
inline epicsRingPointer<T>::epicsRingPointer(int sz, bool locked) :
    lock(0), nextPush(0), nextPop(0), size(sz+1), highWaterMark(0),
    buffer(new T* [sz+1])
{
    if (locked)
        lock = epicsSpinCreate();
}

template <class T>
inline epicsRingPointer<T>::~epicsRingPointer()
{
    if (lock) epicsSpinDestroy(lock);
    delete [] buffer;
}

template <class T>
inline bool epicsRingPointer<T>::push(T *p)
{
    if (lock) epicsSpinLock(lock);
    int next = nextPush;
    int newNext = next + 1;
    if(newNext>=size) newNext=0;
    if (newNext == nextPop) {
        if (lock) epicsSpinUnlock(lock);
        return(false);
    }
    buffer[next] = p;
    nextPush = newNext;
    int used = getUsedNoLock();
    if (used > highWaterMark) highWaterMark = used;
    if (lock) epicsSpinUnlock(lock);
    return(true);
}

template <class T>
inline T* epicsRingPointer<T>::pop()
{
    if (lock) epicsSpinLock(lock);
    int next = nextPop;
    if (next == nextPush) {
        if (lock) epicsSpinUnlock(lock);
        return(0);
    }
    T*p  = buffer[next];
    ++next;
    if(next >=size) next = 0;
    nextPop = next;
    if (lock) epicsSpinUnlock(lock);
    return(p);
}

template <class T>
inline void epicsRingPointer<T>::flush()
{
    if (lock) epicsSpinLock(lock);
    nextPop = 0;
    nextPush = 0;
    if (lock) epicsSpinUnlock(lock);
}

template <class T>
inline int epicsRingPointer<T>::getFree() const
{
    if (lock) epicsSpinLock(lock);
    int n = nextPop - nextPush - 1;
    if (n < 0) n += size;
    if (lock) epicsSpinUnlock(lock);
    return n;
}

template <class T>
inline int epicsRingPointer<T>::getUsedNoLock() const
{
    int n = nextPush - nextPop;
    if (n < 0) n += size;
    return n;
}

template <class T>
inline int epicsRingPointer<T>::getUsed() const
{
    if (lock) epicsSpinLock(lock);
    int n = getUsedNoLock();
    if (lock) epicsSpinUnlock(lock);
    return n;
}

template <class T>
inline int epicsRingPointer<T>::getSize() const
{
    return(size-1);
}

template <class T>
inline bool epicsRingPointer<T>::isEmpty() const
{
    bool isEmpty;
    if (lock) epicsSpinLock(lock);
    isEmpty = (nextPush == nextPop);
    if (lock) epicsSpinUnlock(lock);
    return isEmpty;
}

template <class T>
inline bool epicsRingPointer<T>::isFull() const
{
    if (lock) epicsSpinLock(lock);
    int count = nextPush - nextPop +1;
    if (lock) epicsSpinUnlock(lock);
    return((count == 0) || (count == size));
}

template <class T>
inline int epicsRingPointer<T>::getHighWaterMark() const
{
    return highWaterMark;
}

template <class T>
inline void epicsRingPointer<T>::resetHighWaterMark()
{
    if (lock) epicsSpinLock(lock);
    highWaterMark = getUsedNoLock();
    if (lock) epicsSpinUnlock(lock);
}

#endif /* __cplusplus */

#endif /* INCepicsRingPointerh */