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 <esp_event.h>
#include <functional>
#include <memory>
#include <type_traits>
 
#define IDFXX_EVENT_DEFINE_BASE(name, id_enum)                                                                         \
    inline constexpr char _##name##_base[] = #name;                                                                    \
    inline constexpr ::idfxx::event_base<id_enum> name {                                                               \
        _##name##_base                                                                                                 \
    }
 
namespace idfxx {
 
template<typename IdEnum>
class event_base;
 
template<typename IdEnum>
struct event_type;
 
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; }
 
    [[nodiscard]] constexpr event_type<IdEnum> operator()(IdEnum id) const;
 
private:
    esp_event_base_t _base;
};
 
template<typename IdEnum>
struct event_type {
    event_base<IdEnum> base;
    IdEnum id;
 
    [[nodiscard]] constexpr esp_event_base_t idf_base() const { return base.idf_base(); }
 
    [[nodiscard]] constexpr int32_t idf_id() const { return static_cast<int32_t>(id); }
};
 
// CTAD guide
template<typename IdEnum>
event_type(event_base<IdEnum>, IdEnum) -> event_type<IdEnum>;
 
// Implement operator() after event_type is defined
template<typename IdEnum>
constexpr event_type<IdEnum> event_base<IdEnum>::operator()(IdEnum id) const {
    return {*this, id};
}
 
template<typename IdEnum>
using event_callback = 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();
 
    // =========================================================================
    // User event loop creation
    // =========================================================================
 
    struct task_config {
        std::string_view name;
        size_t stack_size = 2048;
        unsigned int priority = 5;
        std::optional<core_id> core_affinity = std::nullopt;
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    static std::unique_ptr<user_event_loop> make_user(size_t queue_size = 32);
 
    static std::unique_ptr<event_loop> make_user(task_config task, size_t queue_size = 32);
#endif
 
    [[nodiscard]] static result<std::unique_ptr<user_event_loop>> try_make_user(size_t queue_size = 32);
 
    [[nodiscard]] static result<std::unique_ptr<event_loop>> try_make_user(task_config task, size_t queue_size = 32);
 
    // =========================================================================
    // Listener registration (base + specific id)
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    template<typename IdEnum>
    listener_handle
    listener_add(event_base<IdEnum> base, IdEnum id, event_callback<std::type_identity_t<IdEnum>> callback);
 
    template<typename IdEnum>
    listener_handle listener_add(event_type<IdEnum> event, event_callback<std::type_identity_t<IdEnum>> callback);
 
    template<typename IdEnum>
    listener_handle listener_add(event_base<IdEnum> base, event_callback<std::type_identity_t<IdEnum>> callback);
#endif
 
    template<typename IdEnum>
    [[nodiscard]] result<listener_handle>
    try_listener_add(event_base<IdEnum> base, IdEnum id, event_callback<std::type_identity_t<IdEnum>> callback);
 
    template<typename IdEnum>
    [[nodiscard]] result<listener_handle>
    try_listener_add(event_type<IdEnum> event, event_callback<std::type_identity_t<IdEnum>> callback);
 
    template<typename IdEnum>
    [[nodiscard]] result<listener_handle>
    try_listener_add(event_base<IdEnum> base, event_callback<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_base<IdEnum> base, IdEnum id, const void* data = nullptr, size_t size = 0) {
        unwrap(try_post(base, id, data, size));
    }
 
    template<typename IdEnum, typename Rep, typename Period>
    void post(
        event_base<IdEnum> base,
        IdEnum id,
        const void* data,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        unwrap(try_post(base, id, data, size, timeout));
    }
 
    template<typename IdEnum>
    void post(event_type<IdEnum> event, const void* data = nullptr, size_t size = 0) {
        unwrap(try_post(event, data, size));
    }
 
    template<typename IdEnum, typename Rep, typename Period>
    void
    post(event_type<IdEnum> event, const void* data, size_t size, const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_post(event, data, size, timeout));
    }
#endif
 
    template<typename IdEnum>
    [[nodiscard]] result<void>
    try_post(event_base<IdEnum> base, IdEnum id, const void* data = nullptr, size_t size = 0) {
        if (_handle == nullptr) {
            return wrap(esp_event_post(base.idf_base(), static_cast<int32_t>(id), data, size, portMAX_DELAY));
        }
        return wrap(esp_event_post_to(_handle, base.idf_base(), static_cast<int32_t>(id), data, size, portMAX_DELAY));
    }
 
    template<typename IdEnum, typename Rep, typename Period>
    [[nodiscard]] result<void> try_post(
        event_base<IdEnum> base,
        IdEnum id,
        const void* data,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        auto ticks = chrono::ticks(timeout);
        if (_handle == nullptr) {
            return wrap(esp_event_post(base.idf_base(), static_cast<int32_t>(id), data, size, ticks));
        }
        return wrap(esp_event_post_to(_handle, base.idf_base(), static_cast<int32_t>(id), data, size, ticks));
    }
 
    template<typename IdEnum>
    [[nodiscard]] result<void> try_post(event_type<IdEnum> event, const void* data = nullptr, size_t size = 0) {
        return try_post(event.base, event.id, data, size);
    }
 
    template<typename IdEnum, typename Rep, typename Period>
    [[nodiscard]] result<void> try_post(
        event_type<IdEnum> event,
        const void* data,
        size_t size,
        const std::chrono::duration<Rep, Period>& timeout
    ) {
        return try_post(event.base, event.id, data, size, timeout);
    }
 
    [[nodiscard]] esp_event_loop_handle_t idf_handle() const { return _handle; }
 
    virtual ~event_loop();
 
    event_loop(const event_loop&) = delete;
    event_loop& operator=(const event_loop&) = delete;
    event_loop(event_loop&&) = delete;
    event_loop& operator=(event_loop&&) = delete;
 
protected:
    explicit event_loop(esp_event_loop_handle_t handle)
        : _handle(handle) {}
 
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, event_callback<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
    );
 
    esp_event_loop_handle_t _handle;
};
 
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(other._handle) {
        other._handle = listener_handle{};
    }
 
    unique_listener_handle& operator=(unique_listener_handle&& other) noexcept {
        if (this != &other) {
            reset();
            _handle = other._handle;
            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 {
    friend class event_loop;
 
public:
#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) {
        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&&) = delete;
    user_event_loop& operator=(user_event_loop&&) = delete;
 
private:
    explicit user_event_loop(esp_event_loop_handle_t handle)
        : event_loop(handle) {}
};
 
// =============================================================================
// event_loop template implementations
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
inline std::unique_ptr<user_event_loop> event_loop::make_user(size_t queue_size) {
    auto result = try_make_user(queue_size);
    return std::move(result).transform_error([](auto ec) -> std::error_code { throw std::system_error(ec); }).value();
}
 
inline std::unique_ptr<event_loop> event_loop::make_user(task_config task, size_t queue_size) {
    auto result = try_make_user(std::move(task), queue_size);
    return std::move(result).transform_error([](auto ec) -> std::error_code { throw std::system_error(ec); }).value();
}
 
template<typename IdEnum>
event_loop::listener_handle
event_loop::listener_add(event_base<IdEnum> base, IdEnum id, event_callback<std::type_identity_t<IdEnum>> callback) {
    return unwrap(try_listener_add(base, id, std::move(callback)));
}
 
template<typename IdEnum>
event_loop::listener_handle
event_loop::listener_add(event_base<IdEnum> base, event_callback<std::type_identity_t<IdEnum>> callback) {
    return unwrap(try_listener_add(base, std::move(callback)));
}
 
template<typename IdEnum>
event_loop::listener_handle
event_loop::listener_add(event_type<IdEnum> event, event_callback<std::type_identity_t<IdEnum>> callback) {
    return unwrap(try_listener_add(event, 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,
    event_callback<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>
result<event_loop::listener_handle> event_loop::try_listener_add(
    event_base<IdEnum> base,
    IdEnum id,
    event_callback<std::type_identity_t<IdEnum>> callback
) {
    return register_listener<IdEnum>(_handle, base.idf_base(), static_cast<int32_t>(id), std::move(callback));
}
 
template<typename IdEnum>
result<event_loop::listener_handle>
event_loop::try_listener_add(event_base<IdEnum> base, event_callback<std::type_identity_t<IdEnum>> callback) {
    return register_listener<IdEnum>(_handle, base.idf_base(), ESP_EVENT_ANY_ID, std::move(callback));
}
 
template<typename IdEnum>
result<event_loop::listener_handle>
event_loop::try_listener_add(event_type<IdEnum> event, event_callback<std::type_identity_t<IdEnum>> callback) {
    return try_listener_add(event.base, event.id, std::move(callback));
}
 
 
} // namespace idfxx