Consumer Class Reference

HiCR: HiCR::channel::variableSize::SPSC::Consumer Class Reference
HiCR
Public Member Functions | Static Public Member Functions | List of all members
HiCR::channel::variableSize::SPSC::Consumer Class Referencefinal

#include <consumer.hpp>

Inheritance diagram for HiCR::channel::variableSize::SPSC::Consumer:
HiCR::channel::variableSize::Base HiCR::channel::Base

Public Member Functions

 Consumer (CommunicationManager &coordinationCommunicationManager, CommunicationManager &payloadCommunicationManager, std::shared_ptr< GlobalMemorySlot > payloadBuffer, std::shared_ptr< GlobalMemorySlot > tokenBuffer, const std::shared_ptr< LocalMemorySlot > &internalCoordinationBufferForCounts, const std::shared_ptr< LocalMemorySlot > &internalCoordinationBufferForPayloads, const std::shared_ptr< GlobalMemorySlot > &producerCoordinationBufferForCounts, std::shared_ptr< GlobalMemorySlot > producerCoordinationBufferForPayloads, const size_t payloadCapacity, const size_t capacity)
 
__INLINE__ size_t basePeek (const size_t pos=0)
 
__INLINE__ std::array< size_t, 2 > peek (const size_t pos=0)
 
size_t getOldPayloadBytes (size_t n)
 
__INLINE__ void pop (const size_t n=1)
 
__INLINE__ void updateDepth ()
 
size_t getCoordinationDepth ()
 
size_t getPayloadDepth ()
 
bool isEmpty ()
 
bool isFull (size_t requiredBufferSize)
 
std::shared_ptr< GlobalMemorySlot > getPayloadBufferMemorySlot () const
 
- Public Member Functions inherited from HiCR::channel::Base
__INLINE__ size_t getTokenSize () const noexcept
 
__INLINE__ size_t getDepth () const noexcept
 
__INLINE__ bool isFull () const noexcept
 
__INLINE__ bool isEmpty () const noexcept
 
__INLINE__ auto getCircularBuffer () const noexcept
 

Static Public Member Functions

static __INLINE__ size_t getPayloadBufferSize (const size_t payloadSize) noexcept
 
- Static Public Member Functions inherited from HiCR::channel::Base
static __INLINE__ size_t getCoordinationBufferSize () noexcept
 
static __INLINE__ void initializeCoordinationBuffer (const std::shared_ptr< LocalMemorySlot > &coordinationBuffer)
 
static __INLINE__ size_t getTokenBufferSize (const size_t tokenSize, const size_t capacity) noexcept
 

Additional Inherited Members

- Protected Member Functions inherited from HiCR::channel::variableSize::Base
 Base (CommunicationManager &coordinationCommunicationManager, CommunicationManager &payloadCommunicationManager, const std::shared_ptr< LocalMemorySlot > &coordinationBufferForCounts, const std::shared_ptr< LocalMemorySlot > &coordinationBufferForPayloads, const size_t capacity, const size_t payloadCapacity)
 
__INLINE__ auto getCircularBufferForCounts () const
 
__INLINE__ auto getCircularBufferForPayloads () const
 
__INLINE__ auto getCoordinationBufferForCounts () const
 
__INLINE__ auto getCoordinationBufferForPayloads () const
 
- Protected Member Functions inherited from HiCR::channel::Base
 Base (CommunicationManager &coordinationCommunicationManager, CommunicationManager &payloadCommunicationManager, const std::shared_ptr< LocalMemorySlot > &coordinationBuffer, const size_t tokenSize, const size_t capacity)
 
__INLINE__ CommunicationManager * getPayloadCommunicationManager () const
 
__INLINE__ CommunicationManager * getCoordinationCommunicationManager () const
 
__INLINE__ auto getCoordinationBuffer () const
 

Detailed Description

Class definition for a HiCR Consumer Channel

It exposes the functionality to be expected for a variable-size consumer channel

Constructor & Destructor Documentation

◆ Consumer()

HiCR::channel::variableSize::SPSC::Consumer::Consumer ( CommunicationManager &  coordinationCommunicationManager,
CommunicationManager &  payloadCommunicationManager,
std::shared_ptr< GlobalMemorySlot >  payloadBuffer,
std::shared_ptr< GlobalMemorySlot >  tokenBuffer,
const std::shared_ptr< LocalMemorySlot > &  internalCoordinationBufferForCounts,
const std::shared_ptr< LocalMemorySlot > &  internalCoordinationBufferForPayloads,
const std::shared_ptr< GlobalMemorySlot > &  producerCoordinationBufferForCounts,
std::shared_ptr< GlobalMemorySlot >  producerCoordinationBufferForPayloads,
const size_t  payloadCapacity,
const size_t  capacity 
)
inline

The constructor of the variable-sized consumer channel class.

It requires the user to provide the allocated memory slots for the exchange (data) and coordination buffers.

Parameters
[in]coordinationCommunicationManagerThe backend's memory manager to facilitate communication between the producer and consumer coordination buffers
[in]payloadCommunicationManagerThe backend's memory manager to facilitate communication between the producer and consumer payload buffers
[in]payloadBufferThe memory slot pertaining to the payload buffer. The producer will push messages into this buffer, while there is enough space. This buffer should be large enough to hold twice the capacity specified by payloadCapacity argument. Half of the buffer is used as excess buffer to avoid internal fragmentation of messages
[in]tokenBufferThe memory slot pertaining to the token buffer. This buffer is only used to exchange internal metadata about the sizes of the individual messages being sent.
[in]internalCoordinationBufferForCountsThis is a small buffer to hold the internal (local) state of the channel's circular buffer message counts
[in]internalCoordinationBufferForPayloadsThis is a small buffer to hold the internal (local) state of the channel's circular buffer payload sizes (in bytes)
[in]producerCoordinationBufferForCountsA global reference to the producer channel's internal coordination buffer for message counts, used for remote updates on pop()
[in]producerCoordinationBufferForPayloadsA global reference to the producer channel's internal coordination buffer for payload sizes (in bytes), used for remote updates on pop()
[in]payloadCapacityThe capacity (in bytes) of the buffer for variable-sized messages.
[in]capacityThe maximum number of tokens that will be held by this channel
Note
: The token size in var-size channels is used only internally, and is passed as having a type size_t (with size sizeof(size_t))

Member Function Documentation

◆ basePeek()

__INLINE__ size_t HiCR::channel::variableSize::SPSC::Consumer::basePeek ( const size_t  pos = 0)
inline

Returns a pointer to the current token, which holds the payload size metadata here.

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

Parameters
[in]posThe token position required. pos = 0 indicates earliest token that is currently present in the buffer. pos = getDepth()-1 indicates the latest token to have arrived.
Returns
A value representing the relative position within the token buffer where the required element can be found.

This is a getter function that should complete in $ \Theta(1) $ time. This function has no side-effects.

An exception will occur if you do attempt to peek and no

Note
While this function does not modify the state of the channel, the contents of the token may be modified by the caller.

◆ getCoordinationDepth()

size_t HiCR::channel::variableSize::SPSC::Consumer::getCoordinationDepth ( )
inline

Get depth of variable-size consumer. Since we have 2 buffers - one for counts, and one for payloads, we need to be careful. Because the current implementation first receives the payload (phase 1) before receiving the message counts (phase 2), returning this depth should guarantee we already have received the payloads

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

Returns
The number of elements in variable-size consumer channel
Note
This is not a thread-safe call
Even though there might be space for additional tokens in the coordination buffer, it is not guaranteed that the push() will succeed due to insufficient space in the payload buffer

◆ getOldPayloadBytes()

size_t HiCR::channel::variableSize::SPSC::Consumer::getOldPayloadBytes ( size_t  n)
inline

This function inspects the oldest
variable-sized elements in the token buffer to find how many bytes they occupy in the payload buffer

Parameters
[in]nelement count to inspect, starting from oldest, in the token buffer
Returns
total byte size that the oldest
elements take in payload buffer

◆ getPayloadBufferMemorySlot()

std::shared_ptr< GlobalMemorySlot > HiCR::channel::variableSize::SPSC::Consumer::getPayloadBufferMemorySlot ( ) const
inline

Retrieves the pointer to the channel's payload buffer

Returns
The pointer to the payload buffer

◆ getPayloadBufferSize()

static __INLINE__ size_t HiCR::channel::variableSize::SPSC::Consumer::getPayloadBufferSize ( const size_t  payloadSize)
inlinestaticnoexcept

This function can be used to check the size of the payload buffer that needs to be provided in the creation of the channel. The returned size might differ based on the specific channle implementation

Parameters
[in]payloadSizethe desired payload buffer size
Returns
Size (bytes) of the payload buffer

◆ getPayloadDepth()

size_t HiCR::channel::variableSize::SPSC::Consumer::getPayloadDepth ( )
inline

Returns the current depth of the channel holding the payloads

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

Returns
The number of total bytes in the payloads channel
Note
This is not a thread-safe call
Even though there might be space for additional tokens in the payload buffer, it is not guaranteed that the push() will succeed due to insufficient space in the coordination buffer

◆ isEmpty()

bool HiCR::channel::variableSize::SPSC::Consumer::isEmpty ( )
inline

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

It does not affects the internal state of the channel

Returns
true, if both message count and payload buffers are empty
false, if one of the buffers is not empty

◆ isFull()

bool HiCR::channel::variableSize::SPSC::Consumer::isFull ( size_t  requiredBufferSize)
inline

This funciton can be used to quickly check whether the channel is becoming full when trying to push an element of a given size. First thing, we are checking if we can still push tokens (i.e., if the coordination buffer has space). Second thing, we are checking the payload buffer. If the current depth of the payload and the requiredBufferSize to push exceed the channel capacity, the channel is considered full.

Parameters
[in]requiredBufferSizesize of the token to push into the channel
Returns
true if there is enough space to push the token, false otherwise

◆ peek()

__INLINE__ std::array< size_t, 2 > HiCR::channel::variableSize::SPSC::Consumer::peek ( const size_t  pos = 0)
inline

This function gets the (starting position, size) pair for a given element in the consumer channel

Parameters
[in]posThe payload position required. pos = 0 indicates earliest payload that is currently present in the buffer. pos = getDepth()-1 indicates the latest payload to have arrived.
Returns
A 2-element array:
  • the first value is the starting position in bytes of element pos in the payload buffer (in relation to starting address of payload buffer)
  • the second value is the size in bytes of element pos in the payload buffer.

◆ pop()

__INLINE__ void HiCR::channel::variableSize::SPSC::Consumer::pop ( const size_t  n = 1)
inline

Removes the last
variable-sized elements from the payload buffer, and the associated metadata in the token buffer. This is a one-sided blocking call that need not be made collectively.

Parameters
[in]nHow many variable-sized elements to pop. Optional; default is one.

In case there are less than n elements in the channel, no elements will be popped.

◆ updateDepth()

__INLINE__ void HiCR::channel::variableSize::SPSC::Consumer::updateDepth ( )
inline

In this implementation of SPSC, updateDepth for the consumer is a NOP. Any push by the producer leads the producer to update the consumer head index in a one-sided manner. The consumer does not need to update the depth for this case.

The documentation for this class was generated from the following file:
  • /home/runner/work/HiCR/HiCR/include/hicr/frontends/channel/variableSize/spsc/consumer.hpp
Generated by doxygen 1.9.8