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 <memory>
#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, memory_type mem_type = memory_type::internal)
        : _handle(nullptr) {
        if (length == 0) {
            throw std::system_error(errc::invalid_arg);
        }
        _handle = xQueueCreateWithCaps(length, sizeof(T), std::to_underlying(mem_type));
        if (_handle == nullptr) {
            throw std::system_error(errc::no_mem);
        }
    }
#endif
 
    [[nodiscard]] static result<std::unique_ptr<queue>>
    make(size_t length, memory_type mem_type = memory_type::internal) {
        if (length == 0) {
            return error(errc::invalid_arg);
        }
        auto q = std::unique_ptr<queue>(new queue());
        q->_handle = xQueueCreateWithCaps(length, sizeof(T), std::to_underlying(mem_type));
        if (q->_handle == nullptr) {
            return error(errc::no_mem);
        }
        return q;
    }
 
    ~queue() {
        if (_handle != nullptr) {
            vQueueDeleteWithCaps(_handle);
        }
    }
 
    // Non-copyable and non-movable
    queue(const queue&) = delete;
    queue& operator=(const queue&) = delete;
    queue(queue&&) = delete;
    queue& operator=(queue&&) = delete;
 
    // =========================================================================
    // 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
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void overwrite(const T& item) noexcept { try_overwrite(item); }
#endif
 
    void try_overwrite(const T& item) noexcept { 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 {
        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 {
        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 {
        BaseType_t woken = pdFALSE;
        xQueueOverwriteFromISR(_handle, &item, &woken);
        return woken == pdTRUE;
    }
 
    [[nodiscard]] isr_receive_result IRAM_ATTR receive_from_isr() noexcept {
        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 {
        T item;
        if (xQueuePeekFromISR(_handle, &item) == pdTRUE) {
            return item;
        }
        return std::nullopt;
    }
 
    // =========================================================================
    // Query and reset
    // =========================================================================
 
    [[nodiscard]] size_t size() const noexcept { return uxQueueMessagesWaiting(_handle); }
 
    [[nodiscard]] size_t available() const noexcept { return uxQueueSpacesAvailable(_handle); }
 
    [[nodiscard]] bool empty() const noexcept { return uxQueueMessagesWaiting(_handle) == 0; }
 
    [[nodiscard]] bool full() const noexcept { return uxQueueSpacesAvailable(_handle) == 0; }
 
    [[nodiscard]] QueueHandle_t idf_handle() const noexcept { return _handle; }
 
    void reset() noexcept { xQueueReset(_handle); }
 
private:
    queue() noexcept
        : _handle(nullptr) {}
 
    [[nodiscard]] result<void> _try_send(const T& item, TickType_t ticks) {
        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 (xQueueSendToFront(_handle, &item, ticks) != pdTRUE) {
            return error(errc::timeout);
        }
        return {};
    }
 
    [[nodiscard]] result<T> _try_receive(TickType_t ticks) {
        T item;
        if (xQueueReceive(_handle, &item, ticks) != pdTRUE) {
            return error(errc::timeout);
        }
        return item;
    }
 
    [[nodiscard]] result<T> _try_peek(TickType_t ticks) {
        T item;
        if (xQueuePeek(_handle, &item, ticks) != pdTRUE) {
            return error(errc::timeout);
        }
        return item;
    }
 
    QueueHandle_t _handle;
};
 
 
} // namespace idfxx