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 <type_traits>
#include <utility>
 
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:
    [[nodiscard]] event_group()
        : _handle(xEventGroupCreate()) {
        if (_handle == nullptr) {
            raise_no_mem();
        }
    }
 
    ~event_group() {
        if (_handle != nullptr) {
            vEventGroupDelete(_handle);
        }
    }
 
    event_group(const event_group&) = delete;
    event_group& operator=(const event_group&) = delete;
 
    event_group(event_group&& other) noexcept
        : _handle(std::exchange(other._handle, nullptr)) {}
 
    event_group& operator=(event_group&& other) noexcept {
        if (this != &other) {
            if (_handle != nullptr) {
                vEventGroupDelete(_handle);
            }
            _handle = std::exchange(other._handle, nullptr);
        }
        return *this;
    }
 
    // =========================================================================
    // Set operations
    // =========================================================================
 
    flags<E> set(flags<E> bits) noexcept {
        if (_handle == nullptr) {
            return {};
        }
        return _from_bits(xEventGroupSetBits(_handle, to_underlying(bits)));
    }
 
    // =========================================================================
    // Clear operations
    // =========================================================================
 
    flags<E> clear(flags<E> bits) noexcept {
        if (_handle == nullptr) {
            return {};
        }
        return _from_bits(xEventGroupClearBits(_handle, to_underlying(bits)));
    }
 
    // =========================================================================
    // Get operations
    // =========================================================================
 
    [[nodiscard]] flags<E> get() const noexcept {
        if (_handle == nullptr) {
            return {};
        }
        return _from_bits(xEventGroupGetBits(_handle));
    }
 
    // =========================================================================
    // Wait operations
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    flags<E> wait(flags<E> bits, wait_mode mode = wait_mode::all, bool clear_on_exit = true) {
        return unwrap(try_wait(bits, mode, clear_on_exit));
    }
 
    template<typename Rep, typename Period>
    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 Rep, typename Period>
    flags<E> wait(flags<E> bits, const std::chrono::duration<Rep, Period>& timeout, bool clear_on_exit = true) {
        return unwrap(try_wait(bits, wait_mode::all, timeout, clear_on_exit));
    }
 
    template<typename Clock, typename Duration>
    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));
    }
 
    template<typename Clock, typename Duration>
    flags<E>
    wait_until(flags<E> bits, const std::chrono::time_point<Clock, Duration>& deadline, bool clear_on_exit = true) {
        return unwrap(try_wait_until(bits, wait_mode::all, deadline, clear_on_exit));
    }
#endif
 
    result<flags<E>> try_wait(flags<E> bits, wait_mode mode = wait_mode::all, 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 Rep, typename Period>
    [[nodiscard]] result<flags<E>>
    try_wait(flags<E> bits, const std::chrono::duration<Rep, Period>& timeout, bool clear_on_exit = true) {
        return _try_wait(bits, wait_mode::all, 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));
    }
 
    template<typename Clock, typename Duration>
    [[nodiscard]] result<flags<E>>
    try_wait_until(flags<E> bits, const std::chrono::time_point<Clock, Duration>& deadline, bool clear_on_exit = true) {
        return try_wait_until(bits, wait_mode::all, deadline, clear_on_exit);
    }
 
    // =========================================================================
    // Sync operations
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    flags<E> sync(flags<E> set_bits, flags<E> wait_bits) { return unwrap(try_sync(set_bits, wait_bits)); }
 
    template<typename Rep, typename Period>
    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>
    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
 
    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 {
        if (_handle == nullptr) {
            return {false, false};
        }
        BaseType_t woken = pdFALSE;
        BaseType_t ret = xEventGroupSetBitsFromISR(_handle, to_underlying(bits), &woken);
        return {ret == pdPASS, woken == pdTRUE};
    }
 
    [[nodiscard]] flags<E> IRAM_ATTR clear_from_isr(flags<E> bits) noexcept {
        if (_handle == nullptr) {
            return {};
        }
        return _from_bits(xEventGroupClearBitsFromISR(_handle, to_underlying(bits)));
    }
 
    [[nodiscard]] flags<E> IRAM_ATTR get_from_isr() const noexcept {
        if (_handle == nullptr) {
            return {};
        }
        return _from_bits(xEventGroupGetBitsFromISR(_handle));
    }
 
    // =========================================================================
    // Handle access
    // =========================================================================
 
    [[nodiscard]] EventGroupHandle_t idf_handle() const noexcept { return _handle; }
 
private:
    static flags<E> _from_bits(EventBits_t bits) noexcept {
        return flags<E>(static_cast<std::underlying_type_t<E>>(bits));
    }
 
    [[nodiscard]] result<flags<E>> _try_wait(flags<E> bits, wait_mode mode, bool clear_on_exit, TickType_t ticks) {
        if (_handle == nullptr) {
            return error(errc::invalid_state);
        }
        EventBits_t result_bits = xEventGroupWaitBits(
            _handle,
            to_underlying(bits),
            clear_on_exit ? pdTRUE : pdFALSE,
            mode == wait_mode::all ? pdTRUE : pdFALSE,
            ticks
        );
        auto result_flags = _from_bits(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) {
        if (_handle == nullptr) {
            return error(errc::invalid_state);
        }
        EventBits_t result_bits = xEventGroupSync(_handle, to_underlying(set_bits), to_underlying(wait_bits), ticks);
        auto result_flags = _from_bits(result_bits);
        if (!result_flags.contains(wait_bits)) {
            return error(errc::timeout);
        }
        return result_flags;
    }
 
    EventGroupHandle_t _handle = nullptr;
};
 
 
} // namespace idfxx