Skip to content

iox::concurrent::ResizeableLockFreeQueue🔗

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 <resizeable_lockfree_queue.hpp>

Inherits from iox::concurrent::LockFreeQueue< ElementType, MaxCapacity >

Public Types🔗

Name
using ElementType element_t

Public Functions🔗

Name
ResizeableLockFreeQueue() =default
~ResizeableLockFreeQueue() =default
ResizeableLockFreeQueue(const ResizeableLockFreeQueue & )
ResizeableLockFreeQueue(ResizeableLockFreeQueue && )
ResizeableLockFreeQueue & operator=(const ResizeableLockFreeQueue & )
ResizeableLockFreeQueue & operator=(ResizeableLockFreeQueue && )
ResizeableLockFreeQueue(const uint64_t initialCapacity)
uint64_t capacity() const
returns the current capacity of the queue
iox::cxx::optional< ElementType > push(const ElementType & value)
inserts value in FIFO order, always succeeds by removing the oldest value when the queue is detected to be full (overflow)
iox::cxx::optional< ElementType > push(ElementType && value)
inserts value in FIFO order, always succeeds by removing the oldest value when the queue is detected to be full (overflow)
template \<typename Function ,typename =typename std::enable_if::value>::type>
bool
setCapacity(const uint64_t newCapacity, Function && removeHandler)
Set the capacity to some value.
bool setCapacity(const uint64_t newCapacity)
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.
constexpr uint64_t maxCapacity()
returns the maximum capacity of the queue

Public Attributes🔗

Name
constexpr uint64_t MAX_CAPACITY

Additional inherited members🔗

Protected Types inherited from iox::concurrent::LockFreeQueue< ElementType, MaxCapacity >

Name
using IndexQueue< Capacity > Queue

Public Functions inherited from iox::concurrent::LockFreeQueue< ElementType, MaxCapacity >

Name
LockFreeQueue()
creates and initalizes an empty LockFreeQueue
~LockFreeQueue() =default
LockFreeQueue(const LockFreeQueue & )
LockFreeQueue(LockFreeQueue && )
bool tryPush(ElementType && value)
tries to insert value in FIFO order, moves the value internally
bool tryPush(const ElementType & value)
tries to insert value in FIFO order, copies the value internally
iox::cxx::optional< ElementType > pop()
tries to remove value in FIFO order
bool empty() const
check whether the queue is empty
uint64_t size() const
get the number of stored elements in the queue

Protected Functions inherited from iox::concurrent::LockFreeQueue< ElementType, MaxCapacity >

Name
template \<typename T >
void
writeBufferAt(const BufferIndex & index, T && value)
cxx::optional< ElementType > readBufferAt(const BufferIndex & index)

Protected Attributes inherited from iox::concurrent::LockFreeQueue< ElementType, MaxCapacity >

Name
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;

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).

Public Types Documentation🔗

using element_t🔗

using iox::concurrent::ResizeableLockFreeQueue< ElementType, MaxCapacity >::element_t =  ElementType;

Public Functions Documentation🔗

function ResizeableLockFreeQueue🔗

ResizeableLockFreeQueue() =default

function ~ResizeableLockFreeQueue🔗

~ResizeableLockFreeQueue() =default

function ResizeableLockFreeQueue🔗

ResizeableLockFreeQueue(
    const ResizeableLockFreeQueue & 
)

function ResizeableLockFreeQueue🔗

ResizeableLockFreeQueue(
    ResizeableLockFreeQueue && 
)

function operator=🔗

ResizeableLockFreeQueue & operator=(
    const ResizeableLockFreeQueue & 
)

function operator=🔗

ResizeableLockFreeQueue & operator=(
    ResizeableLockFreeQueue && 
)

function ResizeableLockFreeQueue🔗

ResizeableLockFreeQueue(
    const uint64_t initialCapacity
)

function capacity🔗

uint64_t capacity() const

returns the current capacity of the queue

Return: the current capacity

Note: threadsafe, lockfree

function push🔗

iox::cxx::optional< ElementType > push(
    const ElementType & value
)

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

Parameters:

  • value to be inserted is copied into the queue

Return: removed value if an overflow occured, empty optional otherwise

Note: threadsafe, lockfree

function push🔗

iox::cxx::optional< ElementType > push(
    ElementType && value
)

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

Parameters:

  • value to be inserted is moved into the queue if possible

Return: removed value if an overflow occured, empty optional otherwise

Note: threadsafe, lockfree

function setCapacity🔗

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

Set the capacity to some value.

Parameters:

  • newCapacity capacity to be set
  • removeHandler is a function taking an element which specifies what to do with removed elements should the need for removal arise.

Return: true if the capacity was successfully set, false otherwise

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.

The vector m_unusedIndices is protected by the atomic flag, but this also means dying during a resize will prevent further resizes. This is not a problem for the use case were only the dying receiver itself requests the resize. I.e. resize is lockfree, but it assumes that a concurrent resize will always eventually complete (which is true when the application does not die and the relevant thread is scheduled eventually. The latter is the case for any OS and mandatory for a Realtime OS.

function setCapacity🔗

bool setCapacity(
    const uint64_t newCapacity
)

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:

  • newCapacity new capacity to be set, if it is larger than MaxCapacity the call fails

Return: true setting if the new capacity was successful, false otherwise (newCapacity > MaxCapacity)

Note: threadsafe, lockfree but multiple concurrent calls may have no effect

function maxCapacity🔗

static constexpr uint64_t maxCapacity()

returns the maximum capacity of the queue

Return: the maximum capacity

Public Attributes Documentation🔗

variable MAX_CAPACITY🔗

static constexpr uint64_t MAX_CAPACITY = MaxCapacity;

Updated on 26 April 2021 at 15:31:01 CEST