Consumer Class Reference

HiCR: HiCR::channel::variableSize::SPSC::Consumer Class Reference
HiCR
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 &communicationManager, 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)
 
size_t getNewPayloadBytes (size_t n)
 
__INLINE__ void pop (const size_t n=1)
 
__INLINE__ void updateDepth ()
 
size_t getDepth ()
 
size_t getPayloadDepth ()
 
bool isEmpty ()
 
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
 

Additional Inherited Members

- 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
 
- Protected Member Functions inherited from HiCR::channel::variableSize::Base
 Base (CommunicationManager &communicationManager, 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 &communicationManager, const std::shared_ptr< LocalMemorySlot > &coordinationBuffer, const size_t tokenSize, const size_t capacity)
 
__INLINE__ CommunicationManager * getCommunicationManager () 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 &  communicationManager,
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]communicationManagerThe backend to facilitate communication between the producer and consumer sides
[in]payloadBufferThe memory slot pertaining to the payload buffer. The producer will push new tokens into this buffer, while there is enough space (in bytes). This buffer should be big enough to hold at least the largest message of the variable-sized messages to be pushed.
[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.

◆ getDepth()

size_t HiCR::channel::variableSize::SPSC::Consumer::getDepth ( )
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

Note
This is not a thread-safe call

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

Returns
The number of elements in variable-size consumer channel

◆ getNewPayloadBytes()

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

This function inspects the newest
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 newest, in the token buffer
Returns
total byte size that the newest
elements take in 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

◆ getPayloadDepth()

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

Returns the current depth of the channel holding the payloads

Note
This is not a thread-safe call

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

Returns
The number of total bytes in the payloads channel

◆ 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

◆ 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