Template Class ResizeableLockFreeQueue

Inheritance Relationships

Base Type

Class Documentation

template<typename ElementType, uint64_t MaxCapacity>
class ResizeableLockFreeQueue : protected iox::concurrent::LockFreeQueue<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).

Public Types

using element_t = ElementType

Public Functions

ResizeableLockFreeQueue() noexcept = default
~ResizeableLockFreeQueue() noexcept = default
ResizeableLockFreeQueue(const ResizeableLockFreeQueue&) = delete
ResizeableLockFreeQueue(ResizeableLockFreeQueue&&) = delete
ResizeableLockFreeQueue &operator=(const ResizeableLockFreeQueue&) = delete
ResizeableLockFreeQueue &operator=(ResizeableLockFreeQueue&&) = delete
ResizeableLockFreeQueue(const uint64_t initialCapacity) noexcept
uint64_t capacity() const noexcept

returns the current capacity of the queue

Note

threadsafe, lockfree

Returns:

the current capacity

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)

Note

threadsafe, lockfree

Parameters:

value – [in] to be inserted is copied into the queue

Returns:

removed value if an overflow occured, empty optional otherwise

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)

Note

threadsafe, lockfree

Parameters:

value – [in] to be inserted is moved into the queue if possible

Returns:

removed value if an overflow occured, empty optional otherwise

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.

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:

  • newCapacity – [in] capacity to be set

  • removeHandler – [in] is 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

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.

Note

threadsafe, lockfree but multiple concurrent calls may have no effect

Parameters:

newCapacity – [in] new 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)

Public Static Functions

static constexpr uint64_t maxCapacity() noexcept

returns the maximum capacity of the queue

Returns:

the maximum capacity

Public Static Attributes

static constexpr uint64_t MAX_CAPACITY = MaxCapacity