timer.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/error>
 
#include <algorithm>
#include <chrono>
#include <esp_timer.h>
#include <functional>
#include <memory>
#include <string>
 
namespace idfxx {
 
class timer {
public:
    struct clock {
        using rep = int64_t;
        using period = std::micro;
        using duration = std::chrono::microseconds;
        using time_point = std::chrono::time_point<clock>;
        static constexpr bool is_steady = true;
 
        [[nodiscard]] static time_point now() noexcept { return time_point{duration{esp_timer_get_time()}}; }
    };
 
    enum class dispatch_method : int {
        task = ESP_TIMER_TASK, 
#if CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD || __DOXYGEN__
        isr = ESP_TIMER_ISR, 
#endif
    };
 
    struct config {
        std::string_view name = "";                            
        enum dispatch_method dispatch = dispatch_method::task; 
        bool skip_unhandled_events = false;                    
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit timer(const config& cfg, std::move_only_function<void()> callback);
 
    [[nodiscard]] explicit timer(const config& cfg, void (*callback)(void*), void* arg);
#endif
 
    [[nodiscard]] static result<std::unique_ptr<timer>> make(config cfg, std::move_only_function<void()> callback);
 
    [[nodiscard]] static result<std::unique_ptr<timer>> make(config cfg, void (*callback)(void*), void* arg);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    template<typename Rep, typename Period>
    [[nodiscard]] static std::unique_ptr<timer> start_once(
        config cfg,
        const std::chrono::duration<Rep, Period>& timeout,
        std::move_only_function<void()> callback
    ) {
        return unwrap(try_start_once(std::move(cfg), timeout, std::move(callback)));
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] static std::unique_ptr<timer>
    start_once(config cfg, const std::chrono::duration<Rep, Period>& timeout, void (*callback)(void*), void* arg) {
        return unwrap(try_start_once(std::move(cfg), timeout, callback, arg));
    }
 
    [[nodiscard]] static std::unique_ptr<timer>
    start_once(config cfg, clock::time_point time, std::move_only_function<void()> callback) {
        return unwrap(try_start_once(std::move(cfg), time, std::move(callback)));
    }
 
    [[nodiscard]] static std::unique_ptr<timer>
    start_once(config cfg, clock::time_point time, void (*callback)(void*), void* arg) {
        return unwrap(try_start_once(std::move(cfg), time, callback, arg));
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] static std::unique_ptr<timer> start_periodic(
        config cfg,
        const std::chrono::duration<Rep, Period>& interval,
        std::move_only_function<void()> callback
    ) {
        return unwrap(try_start_periodic(std::move(cfg), interval, std::move(callback)));
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] static std::unique_ptr<timer>
    start_periodic(config cfg, const std::chrono::duration<Rep, Period>& interval, void (*callback)(void*), void* arg) {
        return unwrap(try_start_periodic(std::move(cfg), interval, callback, arg));
    }
#endif
 
    template<typename Rep, typename Period>
    [[nodiscard]] static result<std::unique_ptr<timer>> try_start_once(
        config cfg,
        const std::chrono::duration<Rep, Period>& timeout,
        std::move_only_function<void()> callback
    ) {
        auto t = make(std::move(cfg), std::move(callback));
        if (!t) {
            return t;
        }
        auto r = (*t)->try_start_once(timeout);
        if (!r) {
            return error(r.error());
        }
        return t;
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] static result<std::unique_ptr<timer>>
    try_start_once(config cfg, const std::chrono::duration<Rep, Period>& timeout, void (*callback)(void*), void* arg) {
        auto t = make(std::move(cfg), callback, arg);
        if (!t) {
            return t;
        }
        auto r = (*t)->try_start_once(timeout);
        if (!r) {
            return error(r.error());
        }
        return t;
    }
 
    [[nodiscard]] static result<std::unique_ptr<timer>>
    try_start_once(config cfg, clock::time_point time, std::move_only_function<void()> callback) {
        auto t = make(std::move(cfg), std::move(callback));
        if (!t) {
            return t;
        }
        auto r = (*t)->try_start_once(time);
        if (!r) {
            return error(r.error());
        }
        return t;
    }
 
    [[nodiscard]] static result<std::unique_ptr<timer>>
    try_start_once(config cfg, clock::time_point time, void (*callback)(void*), void* arg) {
        auto t = make(std::move(cfg), callback, arg);
        if (!t) {
            return t;
        }
        auto r = (*t)->try_start_once(time);
        if (!r) {
            return error(r.error());
        }
        return t;
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] static result<std::unique_ptr<timer>> try_start_periodic(
        config cfg,
        const std::chrono::duration<Rep, Period>& interval,
        std::move_only_function<void()> callback
    ) {
        auto t = make(std::move(cfg), std::move(callback));
        if (!t) {
            return t;
        }
        auto r = (*t)->try_start_periodic(interval);
        if (!r) {
            return error(r.error());
        }
        return t;
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] static result<std::unique_ptr<timer>> try_start_periodic(
        config cfg,
        const std::chrono::duration<Rep, Period>& interval,
        void (*callback)(void*),
        void* arg
    ) {
        auto t = make(std::move(cfg), callback, arg);
        if (!t) {
            return t;
        }
        auto r = (*t)->try_start_periodic(interval);
        if (!r) {
            return error(r.error());
        }
        return t;
    }
 
    ~timer();
 
    // Non-copyable and non-movable
    timer(const timer&) = delete;
    timer& operator=(const timer&) = delete;
    timer(timer&&) = delete;
    timer& operator=(timer&&) = delete;
 
    [[nodiscard]] esp_timer_handle_t idf_handle() const noexcept { return _handle; }
 
    [[nodiscard]] const std::string& name() const noexcept { return _name; }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    template<typename Rep, typename Period>
    void start_once(const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_start_once(timeout));
    }
 
    void start_once(clock::time_point time) { unwrap(try_start_once(time)); }
 
    template<typename Rep, typename Period>
    void start_periodic(const std::chrono::duration<Rep, Period>& interval) {
        unwrap(try_start_periodic(interval));
    }
#endif
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_start_once(const std::chrono::duration<Rep, Period>& timeout) {
        return wrap(esp_timer_start_once(_handle, to_us(timeout)));
    }
 
    [[nodiscard]] result<void> try_start_once(clock::time_point time) {
        auto timeout_us = std::max(int64_t{0}, (time - clock::now()).count());
        return wrap(esp_timer_start_once(_handle, static_cast<uint64_t>(timeout_us)));
    }
 
    esp_err_t try_start_once_isr(uint64_t timeout_us);
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_start_periodic(const std::chrono::duration<Rep, Period>& interval) {
        return wrap(esp_timer_start_periodic(_handle, to_us(interval)));
    }
 
    esp_err_t try_start_periodic_isr(uint64_t interval_us);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    template<typename Rep, typename Period>
    void restart(const std::chrono::duration<Rep, Period>& timeout) {
        unwrap(try_restart(timeout));
    }
#endif
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<void> try_restart(const std::chrono::duration<Rep, Period>& timeout) {
        auto err = esp_timer_restart(_handle, to_us(timeout));
        if (err == ESP_ERR_INVALID_STATE) {
            return wrap(esp_timer_start_once(_handle, to_us(timeout)));
        }
        return wrap(err);
    }
 
    esp_err_t try_restart_isr(uint64_t timeout_us);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void stop() { unwrap(try_stop()); }
#endif
 
    result<void> try_stop() { return wrap(esp_timer_stop(_handle)); }
 
    esp_err_t try_stop_isr();
 
    [[nodiscard]] bool is_active() const noexcept { return esp_timer_is_active(_handle); }
 
    [[nodiscard]] std::chrono::microseconds period() const noexcept {
        uint64_t period_us = 0;
        esp_timer_get_period(_handle, &period_us);
        return std::chrono::microseconds{static_cast<int64_t>(period_us)};
    }
 
    [[nodiscard]] clock::time_point expiry_time() const noexcept {
        uint64_t expiry;
        if (esp_timer_get_expiry_time(_handle, &expiry) != ESP_OK) {
            return clock::time_point::max();
        }
        if (expiry > static_cast<uint64_t>(std::numeric_limits<int64_t>::max())) {
            return clock::time_point::max();
        }
        return clock::time_point{clock::duration{static_cast<int64_t>(expiry)}};
    }
 
    [[nodiscard]] static clock::time_point next_alarm() {
        return clock::time_point{clock::duration{esp_timer_get_next_alarm()}};
    }
 
private:
    struct context;
 
    explicit timer(esp_timer_handle_t handle, std::string name, context* ctx);
    explicit timer(esp_timer_handle_t handle, std::string name);
 
    template<typename Rep, typename Period>
    static constexpr int64_t to_us(const std::chrono::duration<Rep, Period>& d) {
        return std::chrono::duration_cast<std::chrono::microseconds>(d).count();
    }
 
    static void trampoline(void* arg);
 
    esp_timer_handle_t _handle;
    std::string _name;
    context* _context = nullptr;
};
 
 
} // namespace idfxx