PriorityMemQueue.hpp

Go to the documentation of this file.

// ======================================================================
// \title  Os/Generic/PriorityMemQueue.hpp
// \author B. Duckett
// \brief  hpp file for AtomicQueue-based priority queue implementation for Os::Queue
//
// \copyright
// Copyright 2026, by the California Institute of Technology.
// ALL RIGHTS RESERVED.  United States Government Sponsorship
// acknowledged.
// ======================================================================
#ifndef OS_GENERIC_PRIORITYMEMQUEUE_HPP
#define OS_GENERIC_PRIORITYMEMQUEUE_HPP

#include <atomic>
#include "Fw/Types/MemAllocator.hpp"
#include "Os/CountingSemaphore.hpp"
#include "Os/Generic/Types/AtomicQueue.hpp"
#include "Os/Queue.hpp"

namespace Os {
namespace Generic {

// Constants
namespace Queue {
// Maximum number of priority levels supported per queue (0-31).
// Limited to 32 to:
// - Fit priority bitmask in a 32-bit atomic for efficient lock-free operations
// - Meet typical F' component needs (most use 2-4 priorities)
// WARNING: Standard F' components may use priorities outside this range.
// Ensure FPP priority assignments are within [0, MAX_PRIORITIES-1].
constexpr static FwSizeType MAX_PRIORITIES = 32;
constexpr static FwSizeType DEFAULT_PRIORITY = 0;
}  // namespace Queue

// Forward declarations
class PriorityMemQueue;

struct PriorityMemQueueHandle : public QueueHandle {
    // Sparse priority support: map priority→index into m_atomicQueues
    // Reduces memory waste when using non-consecutive priorities (e.g., {0, 15, 31})
    I8 m_priorityMap[Queue::MAX_PRIORITIES];       // Priority→index mapping (-1 = unused)
    Types::AtomicQueue* m_atomicQueues = nullptr;  // Array sized to actual configured priorities

    // Rule of Five: prevent accidental copy/move of resource-owning handle
    PriorityMemQueueHandle(const PriorityMemQueueHandle&) = delete;
    PriorityMemQueueHandle& operator=(const PriorityMemQueueHandle&) = delete;
    PriorityMemQueueHandle(PriorityMemQueueHandle&&) = delete;
    PriorityMemQueueHandle& operator=(PriorityMemQueueHandle&&) = delete;
    FwQueuePriorityType m_maxPriority = 0;           // Highest priority value (for iteration)
    FwSizeType m_numActivePriorities = 0;            // Number of configured priorities
    Os::CountingSemaphore* m_notEmptySem = nullptr;  // Counting semaphore signaling messages available
    FwEnumStoreType m_id = 0;                        // Queue identifier
    FwEnumStoreType m_allocatorId = 0;               // Allocator ID for memory operations
    std::atomic<U32> m_priorityMask{0};              // Bit mask of enabled priorities
    std::atomic<U32>* m_highWaterMarks = nullptr;    // Array indexed by priority map

    PriorityMemQueueHandle() {
        // Initialize priority map to all -1 (unused)
        for (FwSizeType i = 0; i < Queue::MAX_PRIORITIES; ++i) {
            m_priorityMap[i] = -1;
        }
    }

    void init();

    bool allocateArrays(Fw::MemAllocator& allocator, FwEnumStoreType allocatorId);

    void deallocateArrays(Fw::MemAllocator& allocator, FwEnumStoreType allocatorId);

    void enablePriority(FwQueuePriorityType priority);

    void disablePriority(FwQueuePriorityType priority);

    I8 getPriorityIndex(FwQueuePriorityType priority) const {
        // Bounds check before array access (buffer overflow protection)
        FW_ASSERT(priority < Queue::MAX_PRIORITIES, priority);
        return this->m_priorityMap[priority];
    }
};

class PriorityMemQueue : public Os::QueueInterface {
  public:
    struct QueuePriorityConfig {
        FwQueuePriorityType priority;
        FwSizeType maxMsgSize;
        FwSizeType numMsgs;
    };

    struct QueueConfig {
        FwEnumStoreType instanceId;            // Per component creates pass in instance ID
        FwSizeType numPriorities;              // Number of priorities
        QueuePriorityConfig* priorityConfigs;  // Array of priority configurations
    };
    static void configure(QueueConfig* queueConfigs,
                          FwSizeType numQueueConfigs,
                          bool required,
                          FwEnumStoreType allocatorId);

    static void resetConfig();

  public:
    PriorityMemQueue();

    virtual ~PriorityMemQueue();

    explicit PriorityMemQueue(const QueueInterface& other) = delete;

    explicit PriorityMemQueue(const QueueInterface* other) = delete;

    PriorityMemQueue& operator=(const QueueInterface& other) override = delete;

    Status create(FwEnumStoreType id,
                  const Fw::ConstStringBase& name,
                  FwSizeType depth,
                  FwSizeType messageSize) override;

    void teardown() override;

    void teardownInternal();

    Status send(const U8* buffer, FwSizeType size, FwQueuePriorityType priority, BlockingType blockType) override;

    Status receive(U8* destination,
                   FwSizeType capacity,
                   BlockingType blockType,
                   FwSizeType& actualSize,
                   FwQueuePriorityType& priority) override;

    FwSizeType getMessagesAvailable() const override;

    FwSizeType getMessageHighWaterMark() const override;

    QueueHandle* getHandle() override;

    PriorityMemQueueHandle m_handle;

  private:
    static QueueConfig* s_configs;
    static FwSizeType s_numConfigs;
    static bool s_requirePrioritySizing;
    static std::atomic<bool>* s_configsUsed;
    static bool s_configured;
    static FwEnumStoreType s_allocatorId;

  private:
    FwQueuePriorityType findHighestPriority(U32 priorities = 0);

    bool isPriorityEnabled(FwQueuePriorityType priority);

    void setPriorityEnabled(FwQueuePriorityType priority, bool enabled);

    Fw::MemAllocator& getAllocator();

  private:
    QueueConfig* findMatchingConfig(FwEnumStoreType id);

    QueueInterface::Status createConfiguredQueues(QueueConfig* queueConfig,
                                                  Fw::MemAllocator& allocator,
                                                  FwEnumStoreType allocatorId);

    QueueInterface::Status createDefaultQueue(FwSizeType depth,
                                              FwSizeType messageSize,
                                              Fw::MemAllocator& allocator,
                                              FwEnumStoreType allocatorId);

    QueueInterface::Status createPriorityQueue(FwQueuePriorityType priority,
                                               FwSizeType maxMsgSize,
                                               FwSizeType numMsgs,
                                               Fw::MemAllocator& allocator,
                                               FwEnumStoreType allocatorId);
};
}  // namespace Generic
}  // namespace Os

#endif  // OS_GENERIC_PRIORITYMEMQUEUE_HPP