ExternalFifoQueue

ExternalFifoQueue is a final class template defined in Fw/DataStructures. It represents a FIFO queue with external storage. Internally it maintains an ExternalArray for storing the items on the queue.

1. Template Parameters

ExternalFifoQueue has the following template parameters.

Kind	Name	Purpose
`typename`	`T`	The type of an item on the queue

2. Base Class

ExternalFifoQueue<T> is publicly derived from FifoQueueBase<T>.

3. Private Member Variables

ExternalFifoQueue has the following private member variables.

Name	Type	Purpose	Default Value
`m_items`	`ExternalArray<T>`	The array for storing the queue items	C++ default initialization
`m_enqueueIndex`	`CircularIndex`	The enqueue index	`CircularIndex(m_items.size(), 0)`
`m_dequeueIndex`	`CircularIndex`	The dequeue index	`CircularIndex(m_items.size(), 0)`
`m_size`	`FwSizeType`	The number of items on the queue	0

mermaid

classDiagram
    FifoQueue *-- ExternalArray
    FifoQueue *-- CircularIndex
    FifoQueue *-- CircularIndex

4. Public Constructors and Destructors

4.1. Zero-Argument Constructor

c++

ExternalFifoQueue()

Initialize each member variable with its default value.

Example:

c++

ExternalFifoQueue<U32> queue;

4.2. Constructor Providing Typed Backing Storage

c++

ExternalFifoQueue(T* items, FwSizeType capacity)

items must point to a primitive array of at least capacity items of type T.

Call setStorage(items, capacity).
Initialize the other member variables with their default values.

Example:

c++

constexpr FwSizeType capacity = 10;
U32 items[capacity];
ExternalFifoQueue<U32> queue(items, capacity);

4.3. Constructor Providing Untyped Backing Storage

c++

ExternalFifoQueue(ByteArray data, FwSizeType capacity)

data must be aligned according to getByteArrayAlignment() and must contain at least getByteArraySize(capacity) bytes.

Call setStorage(data, capacity).
Initialize the other member variables with their default values.

Example:

c++

constexpr FwSizeType capacity = 10;
constexpr U8 alignment = ExternalFifoQueue<U32>::getByteArrayAlignment();
constexpr FwSizeType byteArraySize = ExternalFifoQueue<U32>::getByteArraySize(capacity);
alignas(alignment) U8 bytes[byteArraySize];
ExternalFifoQueue<U32> queue(ByteArray(&bytes[0], sizeof bytes), capacity);

4.4. Copy Constructor

c++

ExternalFifoQueue(const ExternalFifoQueue<T>& queue)

Set *this = queue.

Example:

c++

constexpr FwSizeType capacity = 3;
U32 items[capacity];
// Call the constructor providing backing storage
ExternalFifoQueue<U32> q1(items, capacity);
// Enqueue an item
U32 value = 42;
(void) q1.enqueue(value);
// Call the copy constructor
ExternalFifoQueue<U32> q2(q1);
ASSERT_EQ(q2.getSize(), 1);

4.5. Destructor

c++

~ExternalFifoQueue() override

Defined as = default.

5. Public Member Functions

5.1. operator=

c++

ExternalFifoQueue<T>& operator=(const ExternalFifoQueue<T>& queue)

If &queue != this
1. Set m_items = queue.m_items.
2. Set m_enqueueIndex = queue.m_enqueueIndex.
3. Set m_dequeueIndex = queue.m_dequeueIndex.
4. Set m_size = queue.m_size.
Return *this.

Example:

c++

constexpr FwSizeType capacity = 3;
U32 items[capacity];
// Call the constructor providing backing storage
ExternalFifoQueue<U32> q1(items, capacity);
// Enqueue an item
U32 value = 42;
(void) q1.enqueue(value);
// Call the default constructor
ExternalFifoQueue q2;
ASSERT_EQ(q2.getSize(), 0);
// Call the copy assignment operator
q2 = q1;
ASSERT_EQ(q2.getSize(), 1);

5.2. clear

c++

void clear() override

Call m_enqueueIndex.setValue(0).
Call m_dequeueIndex.setValue(0).
Set m_size = 0.

Example:

c++

constexpr FwSizeType capacity = 10;
U32 items[capacity];
ExternalFifoQueue<U32> queue(items, capacity);
const auto status = queue.enqueue(3);
ASSERT_EQ(queue.getSize(), 1);
queue.clear();
ASSERT_EQ(queue.getSize(), 0);

5.3. setStorage (Typed Data)

c++

void setStorage(T* items, FwSizeType capacity)

items must point to a primitive array of at least capacity items of type T.

Call m_items.setStorage(items, capacity).
If capacity > 0
1. Call this->m_enqueueIndex.setModulus(capacity).
2. Call this->m_dequeueIndex.setModulus(capacity).
Call this->clear().

Example:

c++

constexpr FwSizeType capacity = 10;
ExternalFifoQueue<U32> queue;
U32 items[capacity];
queue.setStorage(items, capacity);

5.4. setStorage (Untyped Data)

c++

void setStorage(ByteArray data, FwSizeType capacity)

data must be aligned according to getByteArrayAlignment() and must contain at least getByteArraySize(capacity) bytes.

Call m_items.setStorage(data, capacity).
If capacity > 0
1. Call this->m_enqueueIndex.setModulus(capacity).
2. Call this->m_dequeueIndex.setModulus(capacity).
Call this->clear().

Example:

c++

constexpr FwSizeType capacity = 10;
constexpr U8 alignment = ExternalFifoQueue<U32>::getByteArrayAlignment();
constexpr FwSizeType byteArraySize = ExternalFifoQueue<U32>::getByteArraySize(capacity);
alignas(alignment) U8 bytes[byteArraySize];
ExternalFifoQueue<U32> queue;
queue.setStorage(ByteArray(&bytes[0], sizeof bytes), capacity);

5.5. enqueue

c++

Success enqueue(const T& e) override

Set status = Success::FAILURE.
If m_size < getCapacity() then
1. Set i = m_enqueueIndex.getValue().
2. Set m_items[i] = e.
3. Call m_enqueueIndex.increment().
4. Increment m_size.
Return status.

Example:

c++

constexpr FwSizeType capacity = 3;
U32 items[capacity];
ExternalFifoQueue<U32> queue(items, capacity);
ASSERT_EQ(queue.getSize(), 0);
auto status = queue.enqueue(42);
ASSERT_EQ(status, Success::SUCCESS);
ASSERT_EQ(queue.getSize(), 1);

5.6. at

c++

const T& at(FwSizeType index) const override

Assert index < m_size.
Set ci = m_dequeueIndex.
Set i = ci.increment(index).
Return m_items[i].

Example:

c++

constexpr FwSizeType capacity = 3;
U32 items[capacity];
ExternalFifoQueue<U32> queue(items, capacity);
const auto status = queue.enqueue(3);
ASSERT_EQ(status, Success::SUCCESS);
ASSERT_EQ(queue.at(0), 3);
ASSERT_DEATH(queue.at(1), "Assert");

5.7. dequeue

c++

Success dequeue(T& e) override

Set status = Success::FAILURE.
If m_size > 0 then
1. Set i = m_dequeueIndex.getValue().
2. Set e = m_items[i].
3. Call m_dequeueIndex.increment().
4. Decrement m_size.
Return status.

Example:

c++

constexpr FwSizeType capacity = 3;
U32 items[capacity];
ExternalFifoQueue<U32> queue(items, capacity);
U32 val;
auto status = queue.dequeue(val);
ASSERT_EQ(status, Success::FAILURE);
status = queue.enqueue(42);
ASSERT_EQ(status, Success::SUCCESS);
status = queue.dequeue(val);
ASSERT_EQ(status, Success::SUCCESS);
ASSERT_EQ(val, 42);

5.8. getSize

c++

FwSizeType getSize() const override

Return m_size.

Example:

c++

constexpr FwSizeType capacity = 10;
U32 items[capacity];
ExternalFifoQueue<U32> queue(items, capacity);
auto size = queue.getSize();
ASSERT_EQ(size, 0);
const auto status = queue.enqueue(3);
ASSERT_EQ(status, Success::SUCCESS);
size = queue.getSize();
ASSERT_EQ(size, 1);

5.9. getCapacity

c++

FwSizeType getCapacity() const override

Return m_items.getSize().

Example:

c++

constexpr FwSizeType capacity = 10;
U32 items[capacity];
ExternalFifoQueue<U32> queue(items, capacity);
ASSERT_EQ(queue.getCapacity(), capacity);

6. Public Static Functions

6.1. getByteArrayAlignment

c++

static constexpr U8 getByteArrayAlignment()

Return ExternalArray<T>::getByteArrayAlignment().

6.2. getByteArraySize

c++

static constexpr FwSizeType getByteArraySize(FwSizeType capacity)

Return ExternalArray<T>::getByteArraySize(capacity).