event.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/cpu>
#include <idfxx/error>
 
#include <concepts>
#include <esp_event.h>
#include <functional>
#include <type_traits>
#include <utility>
 
#define IDFXX_EVENT_DEFINE_BASE(name, id_enum)                                                                         \
    inline constexpr char _##name##_base[] = #name;                                                                    \
    inline constexpr ::idfxx::event_base<id_enum> name{_##name##_base};                                                \
    constexpr ::idfxx::event_base<id_enum> idfxx_get_event_base(id_enum*) {                                            \
        return name;                                                                                                   \
    }
 
namespace idfxx {
 
template<typename IdEnum>
class event_base;
 
template<typename IdEnum>
class event_base {
public:
    using id_type = IdEnum;
 
    constexpr event_base(esp_event_base_t base) noexcept
        : _base(base) {}
 
    [[nodiscard]] constexpr esp_event_base_t idf_base() const noexcept { return _base; }
 
private:
    esp_event_base_t _base;
};
 
template<typename T>
concept receivable_event_data = std::is_trivially_copyable_v<T> || requires(const void* data) {
    { T::from_opaque(data) } -> std::same_as<T>;
};
 
template<typename T>
concept event_data = receivable_event_data<T> && std::is_trivially_copyable_v<T>;
 
template<typename IdEnum, typename DataType = void>
    requires(std::is_void_v<DataType> || receivable_event_data<DataType>)
struct event {
    static_assert(sizeof(IdEnum) <= sizeof(int32_t), "event ID enum must fit in int32_t");
 
    IdEnum id;
};
 
 
template<typename IdEnum>
constexpr event_base<IdEnum> event_base_lookup() {
    return idfxx_get_event_base(static_cast<IdEnum*>(nullptr));
}
 
template<typename T>
T from_opaque_data(const void* data) {
    if constexpr (requires {
                      { T::from_opaque(data) } -> std::same_as<T>;
                  }) {
        return T::from_opaque(data);
    } else {
        return *static_cast<const T*>(data);
    }
}
 
 
template<typename DataType>
struct event_handler_traits {
    using type = std::move_only_function<void(const DataType&) const>;
};
 
template<>
struct event_handler_traits<void> {
    using type = std::move_only_function<void() const>;
};
 
template<typename DataType>
using event_handler = typename event_handler_traits<DataType>::type;
 
template<typename IdEnum>
using opaque_event_handler = std::move_only_function<void(event_base<IdEnum> base, IdEnum id, void* event_data) const>;
 
class user_event_loop;
 
class event_loop {
public:
    class listener_handle;
    class unique_listener_handle;
 
    // =========================================================================
    // System (default) loop lifecycle
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    inline static void create_system() { unwrap(try_create_system()); }
 
    inline static void destroy_system() { unwrap(try_destroy_system()); }
#endif
 
    [[nodiscard]] static result<void> try_create_system();
 
    [[nodiscard]] static result<void> try_destroy_system();
 
    [[nodiscard]] static event_loop& system();
 
    // =========================================================================
    // Event loop creation (with dedicated task)
    // =========================================================================
 
    struct task_config {
        std::string_view name;
        size_t stack_size = 2048;
        task_priority priority = 5;
        std::optional<core_id> core_affinity = std::nullopt;
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit event_loop(task_config task, size_t queue_size = 32);
#endif
 
    [[nodiscard]] static result<event_loop> make(task_config task, size_t queue_size = 32);
 
    // =========================================================================
    // Listener registration (typed event)
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    template<typename IdEnum, typename DataType>
    listener_handle listener_add(event<IdEnum, DataType> event, event_handler<DataType> callback);
 
    template<typename IdEnum>
    listener_handle listener_add(event_base<IdEnum> base, opaque_event_handler<std::type_identity_t<IdEnum>> callback);
#endif
 
    template<typename IdEnum, typename DataType>
    [[nodiscard]] result<listener_handle>
    try_listener_add(event<IdEnum, DataType> event, event_handler<DataType> callback);
 
    template<typename IdEnum>
    [[nodiscard]] result<listener_handle>
    try_listener_add(event_base<IdEnum> base, opaque_event_handler<std::type_identity_t<IdEnum>> callback);
 
    // =========================================================================
    // Listener removal
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void listener_remove(listener_handle handle);
#endif
 
    [[nodiscard]] result<void> try_listener_remove(listener_handle handle);
 
    // =========================================================================
    // Event posting
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    template<typename IdEnum>
    void post(event<IdEnum> evt) {
        unwrap(try_post(evt));
    }
 
    template<typename IdEnum, typename Rep, typename Period>
    void post(event<IdEnum> evt, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_post(evt, timeout));
    }
 
    template<typename IdEnum, typename DataType>
        requires event_data<DataType>
    void post(event<IdEnum, DataType> evt, const DataType& data) {
        unwrap(try_post(evt, data));
    }
 
    template<typename IdEnum, typename DataType, typename Rep, typename Period>
        requires event_data<DataType>
    void post(event<IdEnum, DataType> evt, const DataType& data, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_post(evt, data, timeout));
    }
#endif
 
    template<typename IdEnum>
    [[nodiscard]] result<void> try_post(event<IdEnum> evt) {
        return _post(event_base_lookup<IdEnum>().idf_base(), static_cast<int32_t>(evt.id), nullptr, 0, portMAX_DELAY);
    }
 
    template<typename IdEnum, typename Rep, typename Period>
    [[nodiscard]] result<void> try_post(event<IdEnum> evt, const std::chrono::duration<Rep, Period>& timeout) {
        return _post(
            event_base_lookup<IdEnum>().idf_base(), static_cast<int32_t>(evt.id), nullptr, 0, chrono::ticks(timeout)
        );
    }
 
    template<typename IdEnum, typename DataType>
        requires event_data<DataType>
    [[nodiscard]] result<void> try_post(event<IdEnum, DataType> evt, const DataType& data) {
        return _post(
            event_base_lookup<IdEnum>().idf_base(), static_cast<int32_t>(evt.id), &data, sizeof(data), portMAX_DELAY
        );
    }
 
    template<typename IdEnum, typename DataType, typename Rep, typename Period>
        requires event_data<DataType>
    [[nodiscard]] result<void>
    try_post(event<IdEnum, DataType> evt, const DataType& data, const std::chrono::duration<Rep, Period>& timeout) {
        return _post(
            event_base_lookup<IdEnum>().idf_base(),
            static_cast<int32_t>(evt.id),
            &data,
            sizeof(data),
            chrono::ticks(timeout)
        );
    }
 
    [[nodiscard]] esp_event_loop_handle_t idf_handle() const { return _handle; }
 
    ~event_loop();
 
    event_loop(const event_loop&) = delete;
    event_loop& operator=(const event_loop&) = delete;
 
    event_loop(event_loop&& other) noexcept;
 
    event_loop& operator=(event_loop&& other) noexcept;
 
protected:
    event_loop() = default;
 
    explicit event_loop(esp_event_loop_handle_t handle, bool system = false)
        : _handle(handle)
        , _system(system) {}
 
private:
    static result<listener_handle> register_listener(
        esp_event_loop_handle_t loop,
        esp_event_base_t base,
        int32_t id,
        std::move_only_function<void(esp_event_base_t, int32_t, void*) const> callback
    );
 
    template<typename IdEnum>
    static result<listener_handle> register_listener(
        esp_event_loop_handle_t loop,
        esp_event_base_t base,
        int32_t id,
        opaque_event_handler<IdEnum> callback
    );
 
    static result<void> unregister_listener(
        esp_event_loop_handle_t loop,
        esp_event_handler_instance_t instance,
        esp_event_base_t base,
        int32_t id
    );
 
    void _delete() noexcept;
    result<void> _post(esp_event_base_t base, int32_t id, const void* data, size_t size, TickType_t ticks);
 
    esp_event_loop_handle_t _handle = nullptr;
    bool _system = false;
};
 
class event_loop::listener_handle {
    friend class event_loop;
    friend class unique_listener_handle;
 
public:
    listener_handle() = default;
 
private:
    listener_handle(
        esp_event_loop_handle_t loop,
        esp_event_handler_instance_t instance,
        esp_event_base_t base,
        int32_t id
    )
        : _loop(loop)
        , _instance(instance)
        , _base(base)
        , _id(id) {}
 
    esp_event_loop_handle_t _loop = nullptr;
    esp_event_handler_instance_t _instance = nullptr;
    esp_event_base_t _base = nullptr;
    int32_t _id = 0;
};
 
class event_loop::unique_listener_handle {
public:
    unique_listener_handle() noexcept = default;
 
    explicit unique_listener_handle(listener_handle handle) noexcept
        : _handle(handle) {}
 
    unique_listener_handle(unique_listener_handle&& other) noexcept
        : _handle(std::exchange(other._handle, listener_handle{})) {}
 
    unique_listener_handle& operator=(unique_listener_handle&& other) noexcept {
        if (this != &other) {
            reset();
            _handle = std::exchange(other._handle, listener_handle{});
        }
        return *this;
    }
 
    unique_listener_handle(const unique_listener_handle&) = delete;
    unique_listener_handle& operator=(const unique_listener_handle&) = delete;
 
    ~unique_listener_handle() { reset(); }
 
    [[nodiscard]] listener_handle release() noexcept {
        auto h = _handle;
        _handle = listener_handle{};
        return h;
    }
 
    void reset() noexcept;
 
    [[nodiscard]] explicit operator bool() const noexcept { return _handle._instance != nullptr; }
 
private:
    listener_handle _handle;
};
 
class user_event_loop : public event_loop {
public:
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit user_event_loop(size_t queue_size);
#endif
 
    [[nodiscard]] static result<user_event_loop> make(size_t queue_size = 32);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    // =========================================================================
    // Manual dispatch (for loops without dedicated task)
    // =========================================================================
 
    template<typename Rep, typename Period>
    void run(const std::chrono::duration<Rep, Period>& duration) {
        unwrap(try_run(duration));
    }
#endif
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_run(const std::chrono::duration<Rep, Period>& duration) {
        if (idf_handle() == nullptr) {
            return error(errc::invalid_state);
        }
        return wrap(esp_event_loop_run(idf_handle(), chrono::ticks(duration)));
    }
 
    user_event_loop(const user_event_loop&) = delete;
    user_event_loop& operator=(const user_event_loop&) = delete;
    user_event_loop(user_event_loop&&) noexcept = default;
    user_event_loop& operator=(user_event_loop&&) noexcept = default;
 
private:
    user_event_loop() = default;
 
    explicit user_event_loop(esp_event_loop_handle_t handle)
        : event_loop(handle) {}
};
 
// =============================================================================
// event_loop template implementations
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
template<typename IdEnum, typename DataType>
event_loop::listener_handle event_loop::listener_add(event<IdEnum, DataType> event, event_handler<DataType> callback) {
    return unwrap(try_listener_add(event, std::move(callback)));
}
 
template<typename IdEnum>
event_loop::listener_handle
event_loop::listener_add(event_base<IdEnum> base, opaque_event_handler<std::type_identity_t<IdEnum>> callback) {
    return unwrap(try_listener_add(base, std::move(callback)));
}
 
inline void event_loop::listener_remove(listener_handle handle) {
    unwrap(try_listener_remove(handle));
}
#endif
 
template<typename IdEnum>
result<event_loop::listener_handle> event_loop::register_listener(
    esp_event_loop_handle_t loop,
    esp_event_base_t base,
    int32_t id,
    opaque_event_handler<IdEnum> callback
) {
    return register_listener(loop, base, id, [cb = std::move(callback)](esp_event_base_t b, int32_t i, void* data) {
        cb(event_base<IdEnum>{b}, static_cast<IdEnum>(i), data);
    });
}
 
template<typename IdEnum, typename DataType>
result<event_loop::listener_handle>
event_loop::try_listener_add(event<IdEnum, DataType> event, event_handler<DataType> callback) {
    if (!_system && _handle == nullptr) {
        return error(errc::invalid_state);
    }
    if constexpr (std::is_void_v<DataType>) {
        return register_listener(
            _handle,
            event_base_lookup<IdEnum>().idf_base(),
            static_cast<int32_t>(event.id),
            [cb = std::move(callback)](esp_event_base_t, int32_t, void*) { cb(); }
        );
    } else {
        return register_listener(
            _handle,
            event_base_lookup<IdEnum>().idf_base(),
            static_cast<int32_t>(event.id),
            [cb = std::move(callback)](esp_event_base_t, int32_t, void* data) { cb(from_opaque_data<DataType>(data)); }
        );
    }
}
 
template<typename IdEnum>
result<event_loop::listener_handle>
event_loop::try_listener_add(event_base<IdEnum> base, opaque_event_handler<std::type_identity_t<IdEnum>> callback) {
    if (!_system && _handle == nullptr) {
        return error(errc::invalid_state);
    }
    return register_listener<IdEnum>(_handle, base.idf_base(), ESP_EVENT_ANY_ID, std::move(callback));
}
 
 
} // namespace idfxx