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

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

4. Public Constructors and Destructors

4.1. Zero-Argument Constructor

ExternalFifoQueue()

Initialize each member variable with its default value.

Example:

ExternalFifoQueue<U32> queue;

4.2. Constructor Providing Typed Backing Storage

ExternalFifoQueue(T* items, FwSizeType capacity)

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

1. Call setStorage(items, capacity).

2. Initialize the other member variables with their default values.

Example:

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

4.3. Constructor Providing Untyped Backing Storage

ExternalFifoQueue(ByteArray data, FwSizeType capacity)

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

1. Call setStorage(data, capacity).

2. Initialize the other member variables with their default values.

Example:

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

ExternalFifoQueue(const ExternalFifoQueue<T>& queue)

Set *this = queue.

Example:

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

~ExternalFifoQueue() override

Defined as = default.

5. Public Member Functions

5.1. operator=

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

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

2. Return *this.

Example:

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

void clear() override

1. Call m_enqueueIndex.setValue(0).

2. Call m_dequeueIndex.setValue(0).

3. Set m_size = 0.

Example:

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)

void setStorage(T* items, FwSizeType capacity)

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

1. Call m_items.setStorage(items, capacity).

2. If capacity > 0

   1. Call this->m_enqueueIndex.setModulus(capacity).

   2. Call this->m_dequeueIndex.setModulus(capacity).

3. Call this->clear().

Example:

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

5.4. setStorage (Untyped Data)

void setStorage(ByteArray data, FwSizeType capacity)

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

1. Call m_items.setStorage(data, capacity).

2. If capacity > 0

   1. Call this->m_enqueueIndex.setModulus(capacity).

   2. Call this->m_dequeueIndex.setModulus(capacity).

3. Call this->clear().

Example:

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

Success enqueue(const T& e) override

1. Set status = Success::FAILURE.

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

3. Return status.

Example:

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

const T& at(FwSizeType index) const override

1. Assert index < m_size.

2. Set ci = m_dequeueIndex.

3. Set i = ci.increment(index).

4. Return m_items[i].

Example:

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

Success dequeue(T& e) override

1. Set status = Success::FAILURE.

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

3. Return status.

Example:

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

FwSizeType getSize() const override

Return m_size.

Example:

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

FwSizeType getCapacity() const override

Return m_items.getSize().

Example:

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

6. Public Static Functions

6.1. getByteArrayAlignment

static constexpr U8 getByteArrayAlignment()

Return ExternalArray<T>::getByteArrayAlignment().

6.2. getByteArraySize

static constexpr FwSizeType getByteArraySize(FwSizeType capacity)

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