queue.hpp

Go to the documentation of this file.

/*
 * Copyright (C) 2026 Kamil Lulko <kamil.lulko@gmail.com>
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 * This file is part of oveRTOS.
 */
 
#pragma once
 
#include <ove/queue.h>
#include <ove/types.hpp>
#include <ove/error.hpp>
 
#include <type_traits>
 
#ifdef CONFIG_OVE_QUEUE
 
namespace ove
{
 
template <typename T, size_t MaxItems = 0> class Queue
{
    static_assert(std::is_trivially_copyable_v<T>,
              "ove::Queue<T, N> requires T to be trivially copyable. "
              "The substrate memcpy()s items of sizeof(T) bytes — non-trivial "
              "types (std::string, std::vector, std::unique_ptr, user types with "
              "explicit copy/move ctors or destructors that do bookkeeping) corrupt "
              "their internal state on memcpy.  Wrap them in a smart pointer or "
              "POD struct, or transfer ownership by pointer through the queue.");
 
      public:
    Queue()
        requires(MaxItems > 0)
    {
#ifdef CONFIG_OVE_ZERO_HEAP
        static_assert(MaxItems > 0, "MaxItems must be > 0 in zero-heap mode");
        int err = ove_queue_init(&handle_, &storage_, buffer_, sizeof(T), MaxItems);
#else
        int err = ove_queue_create(&handle_, sizeof(T), MaxItems);
#endif
        OVE_STATIC_INIT_ASSERT(err == OVE_OK);
    }
 
    ~Queue() noexcept
    {
        if (!handle_)
            return;
#ifdef CONFIG_OVE_ZERO_HEAP
        ove_queue_deinit(handle_);
#else
        ove_queue_destroy(handle_);
#endif
    }
 
    Queue(const Queue &) = delete;
    Queue &operator=(const Queue &) = delete;
 
#ifdef CONFIG_OVE_ZERO_HEAP
    Queue(Queue &&) = delete;
    Queue &operator=(Queue &&) = delete;
#else
    Queue(Queue &&other) noexcept : handle_(other.handle_)
    {
        other.handle_ = nullptr;
    }
 
    Queue &operator=(Queue &&other) noexcept
    {
        if (this != &other) {
            if (handle_)
                ove_queue_destroy(handle_);
            handle_ = other.handle_;
            other.handle_ = nullptr;
        }
        return *this;
    }
#endif
 
    void send(const T &item)
    {
        const int err = ove_queue_send(handle_, &item, OVE_WAIT_FOREVER);
        OVE_STATIC_INIT_ASSERT(err == OVE_OK);
    }
 
    [[nodiscard]] bool try_send(const T &item)
    {
        return ove_queue_send(handle_, &item, 0) == OVE_OK;
    }
 
    template <class Rep, class Period>
    [[nodiscard]] Result<void>
    try_send_for(const T &item, const std::chrono::duration<Rep, Period> &rel) noexcept
    {
        return from_rc(ove_queue_send(handle_, &item, to_timeout_ns(rel)));
    }
 
    template <class Clock, class Duration>
    [[nodiscard]] Result<void>
    try_send_until(const T &item,
               const std::chrono::time_point<Clock, Duration> &deadline) noexcept
    {
        const auto rel = deadline - Clock::now();
        return from_rc(ove_queue_send(handle_, &item, to_timeout_ns(rel)));
    }
 
    void receive(T &out)
    {
        const int err = ove_queue_receive(handle_, &out, OVE_WAIT_FOREVER);
        OVE_STATIC_INIT_ASSERT(err == OVE_OK);
    }
 
    [[nodiscard]] bool try_receive(T &out)
    {
        return ove_queue_receive(handle_, &out, 0) == OVE_OK;
    }
 
    template <class Rep, class Period>
    [[nodiscard]] Result<void>
    try_receive_for(T &out, const std::chrono::duration<Rep, Period> &rel) noexcept
    {
        return from_rc(ove_queue_receive(handle_, &out, to_timeout_ns(rel)));
    }
 
    template <class Clock, class Duration>
    [[nodiscard]] Result<void>
    try_receive_until(T &out, const std::chrono::time_point<Clock, Duration> &deadline) noexcept
    {
        const auto rel = deadline - Clock::now();
        return from_rc(ove_queue_receive(handle_, &out, to_timeout_ns(rel)));
    }
 
    [[nodiscard]] Result<void> send_from_isr(const T &item) noexcept
    {
        return from_rc(ove_queue_send_from_isr(handle_, &item));
    }
 
    [[nodiscard]] Result<void> receive_from_isr(T &out) noexcept
    {
        return from_rc(ove_queue_receive_from_isr(handle_, &out));
    }
 
    bool valid() const
    {
        return handle_ != nullptr;
    }
 
    ove_queue_t handle() const
    {
        return handle_;
    }
 
      private:
    ove_queue_t handle_ = nullptr;
#ifdef CONFIG_OVE_ZERO_HEAP
    /* `buffer_` precedes `storage_` so the latter (whose underlying C
     * struct ends in a flexible-array `inline_storage[]`) sits at the
     * end of the C++ class.  C99 allows FAMs anywhere in a struct, but
     * C++ rejects another member after one — see
     * backends/freertos/include/ove_storage_freertos.h FAM commentary. */
    T buffer_[MaxItems > 0 ? MaxItems : 1];
    ove_queue_storage_t storage_ = {};
#endif
};
 
} // namespace ove
 
#endif /* CONFIG_OVE_QUEUE */