iceoryx_hoofs 2.0.3
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
iox::concurrent::ResizeableLockFreeQueue< ElementType, MaxCapacity > Class Template Reference

implements a lock free queue (i.e. container with FIFO order) of elements of type T with a maximum capacity MaxCapacity. The capacity can be defined to be anything between 0 and MaxCapacity at construction time or later at runtime using setCapacity. This is even possible while concurrent push and pop operations are executed, i.e. the queue does not have to be empty. Only one thread will succeed setting its desired capacity if there are more threads trying to change the capacity at the same time (it is unpredictable which thread). More...

#include <iceoryx_hoofs/concurrent/resizeable_lockfree_queue.hpp>

Inheritance diagram for iox::concurrent::ResizeableLockFreeQueue< ElementType, MaxCapacity >:
Inheritance graph
[legend]
Collaboration diagram for iox::concurrent::ResizeableLockFreeQueue< ElementType, MaxCapacity >:
Collaboration graph
[legend]

Public Types

using element_t = ElementType
 

Public Member Functions

 ResizeableLockFreeQueue (const ResizeableLockFreeQueue &)=delete
 
 ResizeableLockFreeQueue (ResizeableLockFreeQueue &&)=delete
 
ResizeableLockFreeQueueoperator= (const ResizeableLockFreeQueue &)=delete
 
ResizeableLockFreeQueueoperator= (ResizeableLockFreeQueue &&)=delete
 
 ResizeableLockFreeQueue (const uint64_t initialCapacity) noexcept
 
uint64_t capacity () const noexcept
 returns the current capacity of the queue More...
 
iox::cxx::optional< ElementType > push (const ElementType &value) noexcept
 inserts value in FIFO order, always succeeds by removing the oldest value when the queue is detected to be full (overflow) More...
 
iox::cxx::optional< ElementType > push (ElementType &&value) noexcept
 inserts value in FIFO order, always succeeds by removing the oldest value when the queue is detected to be full (overflow) More...
 
template<typename Function , typename = typename std::enable_if<cxx::is_invocable<Function, ElementType>::value>::type>
bool setCapacity (const uint64_t newCapacity, Function &&removeHandler) noexcept
 Set the capacity to some value. More...
 
bool setCapacity (const uint64_t newCapacity) noexcept
 Set the capacity to a new capacity between 0 and MaxCapacity, if the capacity is reduced it may be necessary to remove the least recent elements which are then discarded. More...
 

Static Public Member Functions

static constexpr uint64_t maxCapacity () noexcept
 returns the maximum capacity of the queue More...
 

Static Public Attributes

static constexpr uint64_t MAX_CAPACITY = MaxCapacity
 

Additional Inherited Members

- Protected Types inherited from iox::concurrent::LockFreeQueue< ElementType, MaxCapacity >
using Queue = IndexQueue< Capacity >
 
using BufferIndex = typename Queue::value_t
 
using element_t = ElementType
 
- Protected Member Functions inherited from iox::concurrent::LockFreeQueue< ElementType, MaxCapacity >
void writeBufferAt (const BufferIndex &, T &&) noexcept
 
iox::cxx::optional< ElementType > pushImpl (T &&value) noexcept
 
cxx::optional< ElementType > readBufferAt (const BufferIndex &) noexcept
 
 LockFreeQueue () noexcept
 creates and initalizes an empty LockFreeQueue
 
 LockFreeQueue (const LockFreeQueue &)=delete
 
 LockFreeQueue (LockFreeQueue &&)=delete
 
LockFreeQueueoperator= (const LockFreeQueue &)=delete
 
LockFreeQueueoperator= (LockFreeQueue &&)=delete
 
constexpr uint64_t capacity () const noexcept
 returns the capacity of the queue More...
 
bool tryPush (ElementType &&value) noexcept
 tries to insert value in FIFO order, moves the value internally More...
 
bool tryPush (const ElementType &value) noexcept
 tries to insert value in FIFO order, copies the value internally More...
 
iox::cxx::optional< ElementType > push (const ElementType &value) noexcept
 inserts value in FIFO order, always succeeds by removing the oldest value when the queue is detected to be full (overflow) More...
 
iox::cxx::optional< ElementType > push (ElementType &&value) noexcept
 inserts value in FIFO order, always succeeds by removing the oldest value when the queue is detected to be full (overflow) More...
 
iox::cxx::optional< ElementType > pop () noexcept
 tries to remove value in FIFO order More...
 
bool empty () const noexcept
 check whether the queue is empty More...
 
uint64_t size () const noexcept
 get the number of stored elements in the queue More...
 
- Protected Attributes inherited from iox::concurrent::LockFreeQueue< ElementType, MaxCapacity >
Queue m_freeIndices
 
Queue m_usedIndices
 
Buffer< ElementType, Capacity, BufferIndex > m_buffer
 
std::atomic< uint64_t > m_size
 

Detailed Description

template<typename ElementType, uint64_t MaxCapacity>
class iox::concurrent::ResizeableLockFreeQueue< ElementType, MaxCapacity >

implements a lock free queue (i.e. container with FIFO order) of elements of type T with a maximum capacity MaxCapacity. The capacity can be defined to be anything between 0 and MaxCapacity at construction time or later at runtime using setCapacity. This is even possible while concurrent push and pop operations are executed, i.e. the queue does not have to be empty. Only one thread will succeed setting its desired capacity if there are more threads trying to change the capacity at the same time (it is unpredictable which thread).

Member Function Documentation

◆ capacity()

template<typename ElementType , uint64_t MaxCapacity>
uint64_t iox::concurrent::ResizeableLockFreeQueue< ElementType, MaxCapacity >::capacity ( ) const
noexcept

returns the current capacity of the queue

Returns
the current capacity
Note
threadsafe, lockfree

◆ maxCapacity()

template<typename ElementType , uint64_t MaxCapacity>
static constexpr uint64_t iox::concurrent::ResizeableLockFreeQueue< ElementType, MaxCapacity >::maxCapacity ( )
staticconstexprnoexcept

returns the maximum capacity of the queue

Returns
the maximum capacity

◆ push() [1/2]

template<typename ElementType , uint64_t MaxCapacity>
iox::cxx::optional< ElementType > iox::concurrent::ResizeableLockFreeQueue< ElementType, MaxCapacity >::push ( const ElementType &  value)
noexcept

inserts value in FIFO order, always succeeds by removing the oldest value when the queue is detected to be full (overflow)

Parameters
[in]valueto be inserted is copied into the queue
Returns
removed value if an overflow occured, empty optional otherwise
Note
threadsafe, lockfree

◆ push() [2/2]

template<typename ElementType , uint64_t MaxCapacity>
iox::cxx::optional< ElementType > iox::concurrent::ResizeableLockFreeQueue< ElementType, MaxCapacity >::push ( ElementType &&  value)
noexcept

inserts value in FIFO order, always succeeds by removing the oldest value when the queue is detected to be full (overflow)

Parameters
[in]valueto be inserted is moved into the queue if possible
Returns
removed value if an overflow occured, empty optional otherwise
Note
threadsafe, lockfree

◆ setCapacity() [1/2]

template<typename ElementType , uint64_t MaxCapacity>
bool iox::concurrent::ResizeableLockFreeQueue< ElementType, MaxCapacity >::setCapacity ( const uint64_t  newCapacity)
noexcept

Set the capacity to a new capacity between 0 and MaxCapacity, if the capacity is reduced it may be necessary to remove the least recent elements which are then discarded.

Parameters
[in]newCapacitynew capacity to be set, if it is larger than MaxCapacity the call fails
Returns
true setting if the new capacity was successful, false otherwise (newCapacity > MaxCapacity)
Note
threadsafe, lockfree but multiple concurrent calls may have no effect

◆ setCapacity() [2/2]

template<typename ElementType , uint64_t MaxCapacity>
template<typename Function , typename = typename std::enable_if<cxx::is_invocable<Function, ElementType>::value>::type>
bool iox::concurrent::ResizeableLockFreeQueue< ElementType, MaxCapacity >::setCapacity ( const uint64_t  newCapacity,
Function &&  removeHandler 
)
noexcept

Set the capacity to some value.

Note
setCapacity is lockfree, but if an application crashes during setCapacity it currently may prevent other applications from setting the capacity (they will not block though). This is not a problem if for example there is only one application calling setCapacity or setCapacity is only called from vital applications (which if they crash will lead to system shutdown) and there is only one (non-vital, i.e. allowed to crash) application reading the data via pop. The reader application may also call setCapacity, since if it crashes there is no one reading the data and the capacity can be considered meaningless.
Parameters
[in]newCapacitycapacity to be set
[in]removeHandleris a function taking an element which specifies what to do with removed elements should the need for removal arise.
Returns
true if the capacity was successfully set, false otherwise

The documentation for this class was generated from the following file: