event_group.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/flags>
 
#include <chrono>
#include <esp_attr.h>
#include <freertos/FreeRTOS.h>
#include <freertos/event_groups.h>
#include <memory>
#include <type_traits>
 
namespace idfxx {
 
enum class wait_mode {
    any, 
    all, 
};
 
template<flag_enum E>
    requires(sizeof(std::underlying_type_t<E>) <= sizeof(EventBits_t))
class event_group {
public:
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] event_group()
        : _handle(xEventGroupCreate()) {
        if (_handle == nullptr) {
            throw std::system_error(errc::no_mem);
        }
    }
#endif
 
    [[nodiscard]] static result<std::unique_ptr<event_group>> make() {
        auto eg = std::unique_ptr<event_group>(new event_group(private_tag{}));
        if (eg->_handle == nullptr) {
            return error(errc::no_mem);
        }
        return eg;
    }
 
    ~event_group() {
        if (_handle != nullptr) {
            vEventGroupDelete(_handle);
        }
    }
 
    // Non-copyable and non-movable
    event_group(const event_group&) = delete;
    event_group& operator=(const event_group&) = delete;
    event_group(event_group&&) = delete;
    event_group& operator=(event_group&&) = delete;
 
    // =========================================================================
    // Set operations
    // =========================================================================
 
    flags<E> set(flags<E> bits) noexcept {
        return flags<E>::from_raw(static_cast<std::underlying_type_t<E>>(xEventGroupSetBits(_handle, bits.value())));
    }
 
    // =========================================================================
    // Clear operations
    // =========================================================================
 
    flags<E> clear(flags<E> bits) noexcept {
        return flags<E>::from_raw(static_cast<std::underlying_type_t<E>>(xEventGroupClearBits(_handle, bits.value())));
    }
 
    // =========================================================================
    // Get operations
    // =========================================================================
 
    [[nodiscard]] flags<E> get() const noexcept {
        return flags<E>::from_raw(static_cast<std::underlying_type_t<E>>(xEventGroupGetBits(_handle)));
    }
 
    // =========================================================================
    // Wait operations
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] flags<E> wait(flags<E> bits, wait_mode mode, bool clear_on_exit = true) {
        return unwrap(try_wait(bits, mode, clear_on_exit));
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] flags<E>
    wait(flags<E> bits, wait_mode mode, const std::chrono::duration<Rep, Period>& timeout, bool clear_on_exit = true) {
        return unwrap(try_wait(bits, mode, timeout, clear_on_exit));
    }
 
    template<typename Clock, typename Duration>
    [[nodiscard]] flags<E> wait_until(
        flags<E> bits,
        wait_mode mode,
        const std::chrono::time_point<Clock, Duration>& deadline,
        bool clear_on_exit = true
    ) {
        return unwrap(try_wait_until(bits, mode, deadline, clear_on_exit));
    }
#endif
 
    [[nodiscard]] result<flags<E>> try_wait(flags<E> bits, wait_mode mode, bool clear_on_exit = true) {
        return _try_wait(bits, mode, clear_on_exit, portMAX_DELAY);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<flags<E>> try_wait(
        flags<E> bits,
        wait_mode mode,
        const std::chrono::duration<Rep, Period>& timeout,
        bool clear_on_exit = true
    ) {
        return _try_wait(bits, mode, clear_on_exit, chrono::ticks(timeout));
    }
 
    template<typename Clock, typename Duration>
    [[nodiscard]] result<flags<E>> try_wait_until(
        flags<E> bits,
        wait_mode mode,
        const std::chrono::time_point<Clock, Duration>& deadline,
        bool clear_on_exit = true
    ) {
        auto remaining = deadline - Clock::now();
        if (remaining <= decltype(remaining)::zero()) {
            return _try_wait(bits, mode, clear_on_exit, 0);
        }
        return _try_wait(bits, mode, clear_on_exit, chrono::ticks(remaining));
    }
 
    // =========================================================================
    // Sync operations
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] flags<E> sync(flags<E> set_bits, flags<E> wait_bits) { return unwrap(try_sync(set_bits, wait_bits)); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] flags<E>
    sync(flags<E> set_bits, flags<E> wait_bits, const std::chrono::duration<Rep, Period>& timeout) {
        return unwrap(try_sync(set_bits, wait_bits, timeout));
    }
 
    template<typename Clock, typename Duration>
    [[nodiscard]] flags<E>
    sync_until(flags<E> set_bits, flags<E> wait_bits, const std::chrono::time_point<Clock, Duration>& deadline) {
        return unwrap(try_sync_until(set_bits, wait_bits, deadline));
    }
#endif
 
    [[nodiscard]] result<flags<E>> try_sync(flags<E> set_bits, flags<E> wait_bits) {
        return _try_sync(set_bits, wait_bits, portMAX_DELAY);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<flags<E>>
    try_sync(flags<E> set_bits, flags<E> wait_bits, const std::chrono::duration<Rep, Period>& timeout) {
        return _try_sync(set_bits, wait_bits, chrono::ticks(timeout));
    }
 
    template<typename Clock, typename Duration>
    [[nodiscard]] result<flags<E>>
    try_sync_until(flags<E> set_bits, flags<E> wait_bits, const std::chrono::time_point<Clock, Duration>& deadline) {
        auto remaining = deadline - Clock::now();
        if (remaining <= decltype(remaining)::zero()) {
            return _try_sync(set_bits, wait_bits, 0);
        }
        return _try_sync(set_bits, wait_bits, chrono::ticks(remaining));
    }
 
    // =========================================================================
    // ISR operations
    // =========================================================================
 
    struct isr_set_result {
        bool success; 
        bool yield;   
    };
 
    [[nodiscard]] isr_set_result IRAM_ATTR set_from_isr(flags<E> bits) noexcept {
        BaseType_t woken = pdFALSE;
        BaseType_t ret = xEventGroupSetBitsFromISR(_handle, bits.value(), &woken);
        return {ret == pdPASS, woken == pdTRUE};
    }
 
    [[nodiscard]] flags<E> IRAM_ATTR clear_from_isr(flags<E> bits) noexcept {
        return flags<E>::from_raw(
            static_cast<std::underlying_type_t<E>>(xEventGroupClearBitsFromISR(_handle, bits.value()))
        );
    }
 
    [[nodiscard]] flags<E> IRAM_ATTR get_from_isr() const noexcept {
        return flags<E>::from_raw(static_cast<std::underlying_type_t<E>>(xEventGroupGetBitsFromISR(_handle)));
    }
 
    // =========================================================================
    // Handle access
    // =========================================================================
 
    [[nodiscard]] EventGroupHandle_t idf_handle() const noexcept { return _handle; }
 
private:
    struct private_tag {};
 
    event_group(private_tag) noexcept
        : _handle(xEventGroupCreate()) {}
 
    [[nodiscard]] result<flags<E>> _try_wait(flags<E> bits, wait_mode mode, bool clear_on_exit, TickType_t ticks) {
        EventBits_t result_bits = xEventGroupWaitBits(
            _handle, bits.value(), clear_on_exit ? pdTRUE : pdFALSE, mode == wait_mode::all ? pdTRUE : pdFALSE, ticks
        );
        auto result_flags = flags<E>::from_raw(static_cast<std::underlying_type_t<E>>(result_bits));
        bool satisfied = (mode == wait_mode::all) ? result_flags.contains(bits) : result_flags.contains_any(bits);
        if (!satisfied) {
            return error(errc::timeout);
        }
        return result_flags;
    }
 
    [[nodiscard]] result<flags<E>> _try_sync(flags<E> set_bits, flags<E> wait_bits, TickType_t ticks) {
        EventBits_t result_bits = xEventGroupSync(_handle, set_bits.value(), wait_bits.value(), ticks);
        auto result_flags = flags<E>::from_raw(static_cast<std::underlying_type_t<E>>(result_bits));
        if (!result_flags.contains(wait_bits)) {
            return error(errc::timeout);
        }
        return result_flags;
    }
 
    EventGroupHandle_t _handle;
};
 
 
} // namespace idfxx