CircularBuffer Class Reference

HiCR: HiCR::channel::CircularBuffer Class Reference
HiCR
Public Member Functions | Static Protected Member Functions | List of all members
HiCR::channel::CircularBuffer Class Reference

Generic class type for circular buffer. More...

#include <circularBuffer.hpp>

Public Member Functions

 CircularBuffer (size_t capacity, __volatile__ size_t *headAdvanceCounter, __volatile__ size_t *tailAdvanceCounter)
 
__INLINE__ size_t getHeadPosition () const noexcept
 
__INLINE__ size_t getTailPosition () const noexcept
 
__INLINE__ void advanceHead (const size_t n=1, bool useCachedDepth=false)
 
__INLINE__ void advanceTail (const size_t n=1)
 
__INLINE__ size_t getCapacity () const noexcept
 
__INLINE__ size_t getDepth () const noexcept
 
void setCachedDepth (size_t depth)
 
__INLINE__ size_t getCachedDepth () const noexcept
 
__INLINE__ bool isFull () const noexcept
 
__INLINE__ bool isEmpty () const noexcept
 
__INLINE__ void setHead (const size_t headAdvanceCounter)
 
__INLINE__ void setTail (const size_t tailAdvanceCounter)
 
__INLINE__ size_t getHeadAdvanceCounter () const noexcept
 
__INLINE__ size_t getTailAdvanceCounter () const noexcept
 

Static Protected Member Functions

static __INLINE__ size_t calculateDepth (const size_t headAdvanceCounter, const size_t tailAdvanceCounter)
 

Detailed Description

Generic class type for circular buffer.

Abstracts away the implementation of a circular buffer with two pointers

  • Head Advance Counter: How many positions has the head been advanced
  • Tail Advance Counter: How many positions has the tail been advanced Storage for these pointers shall be provided by the caller as pointers and will be considered volatile (this is useful for RDMA changes to the internal state of the circular buffer).

Constructor & Destructor Documentation

◆ CircularBuffer()

HiCR::channel::CircularBuffer::CircularBuffer ( size_t  capacity,
__volatile__ size_t *  headAdvanceCounter,
__volatile__ size_t *  tailAdvanceCounter 
)
inline

Constructor for the circular buffer class

Parameters
[in]capacityThe maximum capacity (elements) in the buffer
[in]headAdvanceCounterA pointer to storage for the head advance counter
[in]tailAdvanceCounterA pointer to storage fot the tail advance counter

Member Function Documentation

◆ advanceHead()

__INLINE__ void HiCR::channel::CircularBuffer::advanceHead ( const size_t  n = 1,
bool  useCachedDepth = false 
)
inline

This function increases the circular buffer depth (e.g., when an element is pushed) by advancing a virtual head. The head cannot advance in such a way that the depth exceeds capacity.

Parameters
[in]nThe number of positions to advance
[in]useCachedDepthA boolean signalling if we should read a cached, slightly outdated channel depth. This parameter can be used if in a combination of push from producer and pop from consumer the two might cross over and lead to a brief tail index > head index. This is normally illegal. In this scenario, getCached = true allows a crossover between push and pop to complete

◆ advanceTail()

__INLINE__ void HiCR::channel::CircularBuffer::advanceTail ( const size_t  n = 1)
inline

This function advances buffer tail (e.g., when an element is popped). It goes back around if the capacity is exceeded The tail cannot advanced more than the current depth (that would mean that more elements were consumed than pushed).

Parameters
[in]nThe number of positions to advance the head of the circular buffer

◆ calculateDepth()

static __INLINE__ size_t HiCR::channel::CircularBuffer::calculateDepth ( const size_t  headAdvanceCounter,
const size_t  tailAdvanceCounter 
)
inlinestaticprotected

Calculate depth of circular buffer

Parameters
[in]headAdvanceCounterhead index
[in]tailAdvanceCountertail index
Returns
depth of buffer (in elements)

◆ getCachedDepth()

__INLINE__ size_t HiCR::channel::CircularBuffer::getCachedDepth ( ) const
inlinenoexcept

A getter function for the attribute _cachedDepth

Returns
cached depth of channel

◆ getCapacity()

__INLINE__ size_t HiCR::channel::CircularBuffer::getCapacity ( ) const
inlinenoexcept
Returns
The capacity of the circular buffer.

This is a one-sided blocking call that need not be made collectively.

This function when called on a valid circular buffer instance will never fail.

◆ getDepth()

__INLINE__ size_t HiCR::channel::CircularBuffer::getDepth ( ) const
inlinenoexcept

Returns the current circular buffer depth.

Note
This is not a thread-safe call

This is a getter function that should complete in $ \Theta(1) $ time.

Returns
The number of tokens in this circular buffer.

This function when called on a valid circular buffer instance will never fail.

◆ getHeadAdvanceCounter()

__INLINE__ size_t HiCR::channel::CircularBuffer::getHeadAdvanceCounter ( ) const
inlinenoexcept
Returns
The absolute counter for the number of times the head was advanced

◆ getHeadPosition()

__INLINE__ size_t HiCR::channel::CircularBuffer::getHeadPosition ( ) const
inlinenoexcept
Returns
The current position of the buffer head

Returns the position of the buffer head to set as offset for sending/receiving operations.

This is a one-sided blocking call that need not be made collectively.

This is a getter function that should complete in $ \Theta(1) $ time.

This function when called on a valid circular buffer instance will never fail.

◆ getTailAdvanceCounter()

__INLINE__ size_t HiCR::channel::CircularBuffer::getTailAdvanceCounter ( ) const
inlinenoexcept
Returns
The absolute counter for the number of times the tail was advanced

◆ getTailPosition()

__INLINE__ size_t HiCR::channel::CircularBuffer::getTailPosition ( ) const
inlinenoexcept
Returns
The current position of the buffer head

Returns the position of the buffer head to set as offset for sending/receiving operations.

This is a one-sided blocking call that need not be made collectively.

This is a getter function that should complete in $ \Theta(1) $ time.

This function when called on a valid circular buffer instance will never fail.

◆ isEmpty()

__INLINE__ bool HiCR::channel::CircularBuffer::isEmpty ( ) const
inlinenoexcept

This function can be used to quickly check whether the circular buffer is empty.

It does not affects the internal state of the circular buffer

Returns
true, if the buffer is empty
false, if the buffer is not empty

◆ isFull()

__INLINE__ bool HiCR::channel::CircularBuffer::isFull ( ) const
inlinenoexcept

This function can be used to quickly check whether the circular buffer is full.

It affects the internal state of the circular buffer because it detects any updates in the internal state of the buffers

Returns
true, if the buffer is full
false, if the buffer is not full

◆ setCachedDepth()

void HiCR::channel::CircularBuffer::setCachedDepth ( size_t  depth)
inline

A setter function for the attribute cached depth of the channel

Parameters
[in]depthValue to set _cachedDepth to

◆ setHead()

__INLINE__ void HiCR::channel::CircularBuffer::setHead ( const size_t  headAdvanceCounter)
inline

Forces the head advance counter into a specific absolute value

Parameters
[in]headAdvanceCounterthe new value of the head advance counter. This value should never be smaller than the current tail advance counter, othewise this means the circular buffer has negative depth

◆ setTail()

__INLINE__ void HiCR::channel::CircularBuffer::setTail ( const size_t  tailAdvanceCounter)
inline

Forces the tail advance counter into a specific absolute value

Parameters
[in]tailAdvanceCounterthe new value of the head advance counter. This value should never be smaller than the current tail advance counter, othewise this means the circular buffer has negative depth
The documentation for this class was generated from the following file:
Generated by doxygen 1.9.8