queue.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/chrono>
#include <idfxx/error>
#include <idfxx/memory>
 
#include <chrono>
#include <cstddef>
#include <esp_attr.h>
#include <freertos/FreeRTOS.h>
#include <freertos/idf_additions.h>
#include <freertos/queue.h>
#include <optional>
#include <type_traits>
#include <utility>
 
namespace idfxx {
 
template<typename T>
    requires std::is_trivially_copyable_v<T>
class queue {
public:
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit queue(size_t length, flags<memory_caps> mem_caps = memory_caps::dram)
        : _handle(nullptr) {
        if (length == 0) {
            throw std::system_error(errc::invalid_arg);
        }
        _handle = xQueueCreateWithCaps(length, sizeof(T), to_underlying(mem_caps));
        if (_handle == nullptr) {
            raise_no_mem();
        }
    }
#endif
 
    [[nodiscard]] static result<queue> make(size_t length, flags<memory_caps> mem_caps = memory_caps::dram) {
        if (length == 0) {
            return error(errc::invalid_arg);
        }
        queue q;
        q._handle = xQueueCreateWithCaps(length, sizeof(T), to_underlying(mem_caps));
        if (q._handle == nullptr) {
            raise_no_mem();
        }
        return q;
    }
 
    ~queue() {
        if (_handle != nullptr) {
            vQueueDeleteWithCaps(_handle);
        }
    }
 
    queue(const queue&) = delete;
    queue& operator=(const queue&) = delete;
 
    queue(queue&& other) noexcept
        : _handle(std::exchange(other._handle, nullptr)) {}
 
    queue& operator=(queue&& other) noexcept {
        if (this != &other) {
            if (_handle != nullptr) {
                vQueueDeleteWithCaps(_handle);
            }
            _handle = std::exchange(other._handle, nullptr);
        }
        return *this;
    }
 
    // =========================================================================
    // Send operations
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void send(const T& item) { unwrap(try_send(item)); }
 
    template<typename Rep, typename Period>
    void send(const T& item, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_send(item, timeout));
    }
 
    template<typename Clock, typename Duration>
    void send_until(const T& item, const std::chrono::time_point<Clock, Duration>& deadline) {
        unwrap(try_send_until(item, deadline));
    }
 
    void send_to_front(const T& item) { unwrap(try_send_to_front(item)); }
 
    template<typename Rep, typename Period>
    void send_to_front(const T& item, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_send_to_front(item, timeout));
    }
 
    template<typename Clock, typename Duration>
    void send_to_front_until(const T& item, const std::chrono::time_point<Clock, Duration>& deadline) {
        unwrap(try_send_to_front_until(item, deadline));
    }
#endif
 
    [[nodiscard]] result<void> try_send(const T& item) { return _try_send(item, portMAX_DELAY); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_send(const T& item, const std::chrono::duration<Rep, Period>& timeout) {
        return _try_send(item, chrono::ticks(timeout));
    }
 
    template<typename Clock, typename Duration>
    [[nodiscard]] result<void> try_send_until(const T& item, const std::chrono::time_point<Clock, Duration>& deadline) {
        auto remaining = deadline - Clock::now();
        if (remaining <= decltype(remaining)::zero()) {
            return _try_send(item, 0);
        }
        return _try_send(item, chrono::ticks(remaining));
    }
 
    [[nodiscard]] result<void> try_send_to_front(const T& item) { return _try_send_to_front(item, portMAX_DELAY); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_send_to_front(const T& item, const std::chrono::duration<Rep, Period>& timeout) {
        return _try_send_to_front(item, chrono::ticks(timeout));
    }
 
    template<typename Clock, typename Duration>
    [[nodiscard]] result<void>
    try_send_to_front_until(const T& item, const std::chrono::time_point<Clock, Duration>& deadline) {
        auto remaining = deadline - Clock::now();
        if (remaining <= decltype(remaining)::zero()) {
            return _try_send_to_front(item, 0);
        }
        return _try_send_to_front(item, chrono::ticks(remaining));
    }
 
    // =========================================================================
    // Overwrite operations
    // =========================================================================
 
    void overwrite(const T& item) noexcept {
        if (_handle == nullptr) {
            return;
        }
        xQueueOverwrite(_handle, &item);
    }
 
    // =========================================================================
    // Receive operations
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] T receive() { return unwrap(try_receive()); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] T receive(const std::chrono::duration<Rep, Period>& timeout) {
        return unwrap(try_receive(timeout));
    }
 
    template<typename Clock, typename Duration>
    [[nodiscard]] T receive_until(const std::chrono::time_point<Clock, Duration>& deadline) {
        return unwrap(try_receive_until(deadline));
    }
#endif
 
    [[nodiscard]] result<T> try_receive() { return _try_receive(portMAX_DELAY); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<T> try_receive(const std::chrono::duration<Rep, Period>& timeout) {
        return _try_receive(chrono::ticks(timeout));
    }
 
    template<typename Clock, typename Duration>
    [[nodiscard]] result<T> try_receive_until(const std::chrono::time_point<Clock, Duration>& deadline) {
        auto remaining = deadline - Clock::now();
        if (remaining <= decltype(remaining)::zero()) {
            return _try_receive(0);
        }
        return _try_receive(chrono::ticks(remaining));
    }
 
    // =========================================================================
    // Peek operations
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] T peek() { return unwrap(try_peek()); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] T peek(const std::chrono::duration<Rep, Period>& timeout) {
        return unwrap(try_peek(timeout));
    }
 
    template<typename Clock, typename Duration>
    [[nodiscard]] T peek_until(const std::chrono::time_point<Clock, Duration>& deadline) {
        return unwrap(try_peek_until(deadline));
    }
#endif
 
    [[nodiscard]] result<T> try_peek() { return _try_peek(portMAX_DELAY); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<T> try_peek(const std::chrono::duration<Rep, Period>& timeout) {
        return _try_peek(chrono::ticks(timeout));
    }
 
    template<typename Clock, typename Duration>
    [[nodiscard]] result<T> try_peek_until(const std::chrono::time_point<Clock, Duration>& deadline) {
        auto remaining = deadline - Clock::now();
        if (remaining <= decltype(remaining)::zero()) {
            return _try_peek(0);
        }
        return _try_peek(chrono::ticks(remaining));
    }
 
    // =========================================================================
    // ISR operations
    // =========================================================================
 
    struct isr_send_result {
        bool success; 
        bool yield;   
    };
 
    struct isr_receive_result {
        std::optional<T> item; 
        bool yield;            
    };
 
    [[nodiscard]] isr_send_result IRAM_ATTR send_from_isr(const T& item) noexcept {
        if (_handle == nullptr) {
            return {false, false};
        }
        BaseType_t woken = pdFALSE;
        BaseType_t ret = xQueueSendFromISR(_handle, &item, &woken);
        return {ret == pdTRUE, woken == pdTRUE};
    }
 
    [[nodiscard]] isr_send_result IRAM_ATTR send_to_front_from_isr(const T& item) noexcept {
        if (_handle == nullptr) {
            return {false, false};
        }
        BaseType_t woken = pdFALSE;
        BaseType_t ret = xQueueSendToFrontFromISR(_handle, &item, &woken);
        return {ret == pdTRUE, woken == pdTRUE};
    }
 
    [[nodiscard]] bool IRAM_ATTR overwrite_from_isr(const T& item) noexcept {
        if (_handle == nullptr) {
            return false;
        }
        BaseType_t woken = pdFALSE;
        xQueueOverwriteFromISR(_handle, &item, &woken);
        return woken == pdTRUE;
    }
 
    [[nodiscard]] isr_receive_result IRAM_ATTR receive_from_isr() noexcept {
        if (_handle == nullptr) {
            return {std::nullopt, false};
        }
        T item;
        BaseType_t woken = pdFALSE;
        if (xQueueReceiveFromISR(_handle, &item, &woken) == pdTRUE) {
            return {item, woken == pdTRUE};
        }
        return {std::nullopt, woken == pdTRUE};
    }
 
    [[nodiscard]] std::optional<T> IRAM_ATTR peek_from_isr() const noexcept {
        if (_handle == nullptr) {
            return std::nullopt;
        }
        T item;
        if (xQueuePeekFromISR(_handle, &item) == pdTRUE) {
            return item;
        }
        return std::nullopt;
    }
 
    // =========================================================================
    // Query and reset
    // =========================================================================
 
    [[nodiscard]] size_t size() const noexcept {
        if (_handle == nullptr) {
            return 0;
        }
        return uxQueueMessagesWaiting(_handle);
    }
 
    [[nodiscard]] size_t available() const noexcept {
        if (_handle == nullptr) {
            return 0;
        }
        return uxQueueSpacesAvailable(_handle);
    }
 
    [[nodiscard]] bool empty() const noexcept {
        if (_handle == nullptr) {
            return true;
        }
        return uxQueueMessagesWaiting(_handle) == 0;
    }
 
    [[nodiscard]] bool full() const noexcept {
        if (_handle == nullptr) {
            return false;
        }
        return uxQueueSpacesAvailable(_handle) == 0;
    }
 
    [[nodiscard]] QueueHandle_t idf_handle() const noexcept { return _handle; }
 
    void reset() noexcept {
        if (_handle == nullptr) {
            return;
        }
        xQueueReset(_handle);
    }
 
private:
    queue() noexcept
        : _handle(nullptr) {}
 
    [[nodiscard]] result<void> _try_send(const T& item, TickType_t ticks) {
        if (_handle == nullptr) {
            return error(errc::invalid_state);
        }
        if (xQueueSend(_handle, &item, ticks) != pdTRUE) {
            return error(errc::timeout);
        }
        return {};
    }
 
    [[nodiscard]] result<void> _try_send_to_front(const T& item, TickType_t ticks) {
        if (_handle == nullptr) {
            return error(errc::invalid_state);
        }
        if (xQueueSendToFront(_handle, &item, ticks) != pdTRUE) {
            return error(errc::timeout);
        }
        return {};
    }
 
    [[nodiscard]] result<T> _try_receive(TickType_t ticks) {
        if (_handle == nullptr) {
            return error(errc::invalid_state);
        }
        T item;
        if (xQueueReceive(_handle, &item, ticks) != pdTRUE) {
            return error(errc::timeout);
        }
        return item;
    }
 
    [[nodiscard]] result<T> _try_peek(TickType_t ticks) {
        if (_handle == nullptr) {
            return error(errc::invalid_state);
        }
        T item;
        if (xQueuePeek(_handle, &item, ticks) != pdTRUE) {
            return error(errc::timeout);
        }
        return item;
    }
 
    QueueHandle_t _handle = nullptr;
};
 
 
} // namespace idfxx