High-resolution timer with microsecond precision. More...

Classes
struct	clock
	Monotonic clock based on boot time. More...

struct	config
	Timer configuration parameters. More...

Public Types
enum class	dispatch_method : int { task = ESP_TIMER_TASK }
	Callback dispatch type. More...

Public Member Functions
	timer (const config &cfg, std::move_only_function< void()> callback)
	Creates a timer with a std::move_only_function callback.

	timer (const config &cfg, void(callback)(void ), void *arg)
	Creates a timer with a raw function pointer callback.

	~timer ()
	Destroys the timer.

	timer (const timer &)=delete

timer &	operator= (const timer &)=delete

	timer (timer &&)=delete

timer &	operator= (timer &&)=delete

esp_timer_handle_t	idf_handle () const noexcept
	Returns the underlying ESP-IDF timer handle.

const std::string &	name () const noexcept
	Returns the timer name.

template<typename Rep , typename Period >
void	start_once (const std::chrono::duration< Rep, Period > &timeout)
	Starts the timer as a one-shot timer.

void	start_once (clock::time_point time)
	Starts the timer as a one-shot timer at an absolute time.

template<typename Rep , typename Period >
void	start_periodic (const std::chrono::duration< Rep, Period > &interval)
	Starts the timer as a periodic timer.

template<typename Rep , typename Period >
result< void >	try_start_once (const std::chrono::duration< Rep, Period > &timeout)
	Starts the timer as a one-shot timer.

result< void >	try_start_once (clock::time_point time)
	Starts the timer as a one-shot timer at an absolute time.

esp_err_t	try_start_once_isr (uint64_t timeout_us)
	Starts the timer as a one-shot timer (ISR-compatible).

template<typename Rep , typename Period >
result< void >	try_start_periodic (const std::chrono::duration< Rep, Period > &interval)
	Starts the timer as a periodic timer.

esp_err_t	try_start_periodic_isr (uint64_t interval_us)
	Starts the timer as a periodic timer (ISR-compatible).

template<typename Rep , typename Period >
void	restart (const std::chrono::duration< Rep, Period > &timeout)
	Restarts the timer with a new timeout.

template<typename Rep , typename Period >
result< void >	try_restart (const std::chrono::duration< Rep, Period > &timeout)
	Restarts the timer with a new timeout.

esp_err_t	try_restart_isr (uint64_t timeout_us)
	Restarts the timer with a new timeout (ISR-compatible).

void	stop ()
	Stops the timer.

result< void >	try_stop ()
	Stops the timer.

esp_err_t	try_stop_isr ()
	Stops the timer (ISR-compatible).

bool	is_active () const noexcept
	Checks if the timer is currently running.

std::chrono::microseconds	period () const noexcept
	Returns the period of a periodic timer.

clock::time_point	expiry_time () const noexcept
	Returns the absolute expiry time for a one-shot timer.

Static Public Member Functions
static result< std::unique_ptr< timer > >	make (config cfg, std::move_only_function< void()> callback)
	Creates a timer with a std::move_only_function callback.

static result< std::unique_ptr< timer > >	make (config cfg, void(callback)(void ), void *arg)
	Creates a timer with a raw function pointer callback.

template<typename Rep , typename Period >
static std::unique_ptr< timer >	start_once (config cfg, const std::chrono::duration< Rep, Period > &timeout, std::move_only_function< void()> callback)
	Creates and starts a one-shot timer with a std::move_only_function callback.

template<typename Rep , typename Period >
static std::unique_ptr< timer >	start_once (config cfg, const std::chrono::duration< Rep, Period > &timeout, void(callback)(void ), void *arg)
	Creates and starts a one-shot timer with a raw function pointer callback.

static std::unique_ptr< timer >	start_once (config cfg, clock::time_point time, std::move_only_function< void()> callback)
	Creates and starts a one-shot timer at an absolute time with a std::move_only_function callback.

static std::unique_ptr< timer >	start_once (config cfg, clock::time_point time, void(callback)(void ), void *arg)
	Creates and starts a one-shot timer at an absolute time with a raw function pointer callback.

template<typename Rep , typename Period >
static std::unique_ptr< timer >	start_periodic (config cfg, const std::chrono::duration< Rep, Period > &interval, std::move_only_function< void()> callback)
	Creates and starts a periodic timer with a std::move_only_function callback.

template<typename Rep , typename Period >
static std::unique_ptr< timer >	start_periodic (config cfg, const std::chrono::duration< Rep, Period > &interval, void(callback)(void ), void *arg)
	Creates and starts a periodic timer with a raw function pointer callback.

template<typename Rep , typename Period >
static result< std::unique_ptr< timer > >	try_start_once (config cfg, const std::chrono::duration< Rep, Period > &timeout, std::move_only_function< void()> callback)
	Creates and starts a one-shot timer with a std::move_only_function callback.

template<typename Rep , typename Period >
static result< std::unique_ptr< timer > >	try_start_once (config cfg, const std::chrono::duration< Rep, Period > &timeout, void(callback)(void ), void *arg)
	Creates and starts a one-shot timer with a raw function pointer callback.

static result< std::unique_ptr< timer > >	try_start_once (config cfg, clock::time_point time, std::move_only_function< void()> callback)
	Creates and starts a one-shot timer at an absolute time with a std::move_only_function callback.

static result< std::unique_ptr< timer > >	try_start_once (config cfg, clock::time_point time, void(callback)(void ), void *arg)
	Creates and starts a one-shot timer at an absolute time with a raw function pointer callback.

template<typename Rep , typename Period >
static result< std::unique_ptr< timer > >	try_start_periodic (config cfg, const std::chrono::duration< Rep, Period > &interval, std::move_only_function< void()> callback)
	Creates and starts a periodic timer with a std::move_only_function callback.

template<typename Rep , typename Period >
static result< std::unique_ptr< timer > >	try_start_periodic (config cfg, const std::chrono::duration< Rep, Period > &interval, void(callback)(void ), void *arg)
	Creates and starts a periodic timer with a raw function pointer callback.

static clock::time_point	next_alarm ()
	Returns the time of the next scheduled timer event.

Detailed Description

High-resolution timer with microsecond precision.

Supports both one-shot and periodic timers with callbacks dispatched either from a dedicated timer task or directly from ISR context.

Timers are non-copyable and non-movable. Use the factory method make() for result-based construction or the throwing constructor when exceptions are enabled.

Definition at line 41 of file timer.hpp.

Member Enumeration Documentation

◆ dispatch_method

enum class idfxx::timer::dispatch_method : int

strong

Callback dispatch type.

Determines whether the timer callback runs in a high-priority timer task or directly in ISR context.

Note: ISR dispatch is only available when CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD is enabled in menuconfig.

Enumerator
task	Callback runs in high-priority timer task (default)

Definition at line 73 of file timer.hpp.

Constructor & Destructor Documentation

◆ timer() [1/4]

idfxx::timer::timer	(	const config &	cfg,
		std::move_only_function< void()>	callback
	)

explicit

Creates a timer with a std::move_only_function callback.

Warning: This overload cannot be used with dispatch_method::isr.

Parameters

cfg	Timer configuration.
callback	Function to call when timer fires.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

◆ timer() [2/4]

idfxx::timer::timer	(	const config &	cfg,
		void()(void )	callback,
		void *	arg
	)

explicit

Creates a timer with a raw function pointer callback.

Parameters

cfg	Timer configuration.
callback	Function to call when timer fires.
arg	Argument passed to the callback.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

◆ ~timer()

idfxx::timer::~timer ( )

Destroys the timer.

Stops the timer if running and waits for any in-flight callback to complete before releasing resources.

◆ timer() [3/4]

idfxx::timer::timer ( const timer & )

delete

◆ timer() [4/4]

idfxx::timer::timer ( timer && )

delete

Member Function Documentation

◆ expiry_time()

clock::time_point idfxx::timer::expiry_time ( ) const

inlinenoexcept

Returns the absolute expiry time for a one-shot timer.

For periodic timers, returns clock::time_point::max() as a sentinel value since periodic timers do not have a single expiry time.

Returns: The expiry time.

Return values

clock::time_point::max() For periodic timers.

Definition at line 803 of file timer.hpp.

◆ idf_handle()

esp_timer_handle_t idfxx::timer::idf_handle ( ) const

inlinenoexcept

Returns the underlying ESP-IDF timer handle.

Returns: The esp_timer handle.

Definition at line 543 of file timer.hpp.

◆ is_active()

bool idfxx::timer::is_active ( ) const

inlinenoexcept

Checks if the timer is currently running.

Returns: true if the timer is active, false otherwise.

Definition at line 777 of file timer.hpp.

◆ make() [1/2]

static result< std::unique_ptr< timer > > idfxx::timer::make	(	config	cfg,
		std::move_only_function< void()>	callback
	)

static

Creates a timer with a std::move_only_function callback.

Warning: This method cannot be used with dispatch_method::isr. Use the raw function pointer overload for ISR dispatch.

Parameters

cfg	Timer configuration.
callback	Function to call when timer fires.

Returns: The new timer, or an error.

Return values

no_mem	Memory allocation failed.
invalid_arg	Invalid configuration.

Referenced by try_start_once(), try_start_once(), try_start_once(), try_start_once(), try_start_periodic(), and try_start_periodic().

◆ make() [2/2]

static result< std::unique_ptr< timer > > idfxx::timer::make	(	config	cfg,
		void()(void )	callback,
		void *	arg
	)

static

Creates a timer with a raw function pointer callback.

Note: This overload is suitable for ISR dispatch.

Parameters

cfg	Timer configuration.
callback	Function to call when timer fires.
arg	Argument passed to the callback.

Returns: The new timer, or an error.

Return values

no_mem	Memory allocation failed.
invalid_arg	Invalid configuration.

◆ name()

const std::string & idfxx::timer::name ( ) const

inlinenoexcept

Returns the timer name.

Returns: The timer name.

Definition at line 549 of file timer.hpp.

◆ next_alarm()

static clock::time_point idfxx::timer::next_alarm ( )

inlinestatic

Returns the time of the next scheduled timer event.

Returns the absolute time of the next timer alarm across all timers in the system.

Returns: The time of the next alarm.

Definition at line 822 of file timer.hpp.

◆ operator=() [1/2]

timer & idfxx::timer::operator= ( const timer & )

delete

◆ operator=() [2/2]

timer & idfxx::timer::operator= ( timer && )

delete

◆ period()

std::chrono::microseconds idfxx::timer::period ( ) const

inlinenoexcept

Returns the period of a periodic timer.

For periodic timers, returns the configured interval. For one-shot timers returns zero.

Returns: The timer period as a duration, or zero on error.

Return values

0ms	For one-shot timers.

Definition at line 788 of file timer.hpp.

◆ restart()

template<typename Rep , typename Period >

void idfxx::timer::restart ( const std::chrono::duration< Rep, Period > & timeout )

inline

Restarts the timer with a new timeout.

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

timeout Time until the callback is invoked.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 699 of file timer.hpp.

References idfxx::timeout, try_restart(), and idfxx::unwrap().

◆ start_once() [1/6]

void idfxx::timer::start_once ( clock::time_point time )

inline

Starts the timer as a one-shot timer at an absolute time.

The callback will be invoked once at the specified time point. If the time point is in the past, the timer fires as soon as possible.

using namespace std::chrono_literals;
auto t = idfxx::timer(
    {.name = "alarm"},
    []() { idfxx::log::info("timer", "Alarm!"); });
t.start_once(idfxx::timer::clock::now() + 500ms);

Parameters

time	Absolute time at which the callback should be invoked.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 584 of file timer.hpp.

References try_start_once(), and idfxx::unwrap().

◆ start_once() [2/6]

static std::unique_ptr< timer > idfxx::timer::start_once	(	config	cfg,
		clock::time_point	time,
		std::move_only_function< void()>	callback
	)

inlinestatic

Creates and starts a one-shot timer at an absolute time with a std::move_only_function callback.

Combines timer creation and one-shot start into a single operation. The timer fires at the specified time point. If the time point is in the past, the timer fires as soon as possible.

Warning: This overload cannot be used with dispatch_method::isr.

auto t = idfxx::timer::start_once(
    {.name = "alarm"}, idfxx::timer::clock::now() + 500ms,
    []() { idfxx::log::info("timer", "Alarm!"); });

Parameters

cfg	Timer configuration.
time	Absolute time at which the callback should be invoked.
callback	Function to call when timer fires.

Returns: The new running timer.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 228 of file timer.hpp.

References try_start_once(), and idfxx::unwrap().

◆ start_once() [3/6]

static std::unique_ptr< timer > idfxx::timer::start_once	(	config	cfg,
		clock::time_point	time,
		void()(void )	callback,
		void *	arg
	)

inlinestatic

Creates and starts a one-shot timer at an absolute time with a raw function pointer callback.

Combines timer creation and one-shot start into a single operation. The timer fires at the specified time point. If the time point is in the past, the timer fires as soon as possible.

auto t = idfxx::timer::start_once(
    {.name = "alarm"}, idfxx::timer::clock::now() + 500ms,
    [](void* arg) { *static_cast<bool*>(arg) = true; }, &flag);

Parameters

cfg	Timer configuration.
time	Absolute time at which the callback should be invoked.
callback	Function to call when timer fires.
arg	Argument passed to the callback.

Returns: The new running timer.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 254 of file timer.hpp.

References try_start_once(), and idfxx::unwrap().

◆ start_once() [4/6]

template<typename Rep , typename Period >

static std::unique_ptr< timer > idfxx::timer::start_once	(	config	cfg,
		const std::chrono::duration< Rep, Period > &	timeout,
		std::move_only_function< void()>	callback
	)

inlinestatic

Creates and starts a one-shot timer with a std::move_only_function callback.

Combines timer creation and one-shot start into a single operation. If creation succeeds but starting fails, the timer is automatically cleaned up via RAII.

Warning: This overload cannot be used with dispatch_method::isr.

using namespace std::chrono_literals;
auto t = idfxx::timer::start_once(
    {.name = "my_timer"}, 100ms,
    []() { idfxx::log::info("timer", "Fired!"); });

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

cfg	Timer configuration.
timeout	Time until the callback is invoked.
callback	Function to call when timer fires.

Returns: The new running timer.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 168 of file timer.hpp.

References idfxx::timeout, try_start_once(), and idfxx::unwrap().

◆ start_once() [5/6]

template<typename Rep , typename Period >

static std::unique_ptr< timer > idfxx::timer::start_once	(	config	cfg,
		const std::chrono::duration< Rep, Period > &	timeout,
		void()(void )	callback,
		void *	arg
	)

inlinestatic

Creates and starts a one-shot timer with a raw function pointer callback.

Combines timer creation and one-shot start into a single operation. If creation succeeds but starting fails, the timer is automatically cleaned up via RAII.

using namespace std::chrono_literals;
auto t = idfxx::timer::start_once(
    {.name = "my_timer"}, 100ms,
    [](void* arg) { *static_cast<bool*>(arg) = true; }, &flag);

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

cfg	Timer configuration.
timeout	Time until the callback is invoked.
callback	Function to call when timer fires.
arg	Argument passed to the callback.

Returns: The new running timer.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 201 of file timer.hpp.

References idfxx::timeout, try_start_once(), and idfxx::unwrap().

◆ start_once() [6/6]

template<typename Rep , typename Period >

void idfxx::timer::start_once ( const std::chrono::duration< Rep, Period > & timeout )

inline

Starts the timer as a one-shot timer.

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

timeout Time until the callback is invoked.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 562 of file timer.hpp.

References idfxx::timeout, try_start_once(), and idfxx::unwrap().

◆ start_periodic() [1/3]

template<typename Rep , typename Period >

static std::unique_ptr< timer > idfxx::timer::start_periodic	(	config	cfg,
		const std::chrono::duration< Rep, Period > &	interval,
		std::move_only_function< void()>	callback
	)

inlinestatic

Creates and starts a periodic timer with a std::move_only_function callback.

Combines timer creation and periodic start into a single operation. If creation succeeds but starting fails, the timer is automatically cleaned up via RAII.

Warning: This overload cannot be used with dispatch_method::isr.

using namespace std::chrono_literals;
auto t = idfxx::timer::start_periodic(
    {.name = "heartbeat"}, 100ms,
    []() { idfxx::log::info("timer", "Tick!"); });

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

cfg	Timer configuration.
interval	Time between callback invocations.
callback	Function to call when timer fires.

Returns: The new running timer.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 283 of file timer.hpp.

References try_start_periodic(), and idfxx::unwrap().

◆ start_periodic() [2/3]

template<typename Rep , typename Period >

static std::unique_ptr< timer > idfxx::timer::start_periodic	(	config	cfg,
		const std::chrono::duration< Rep, Period > &	interval,
		void()(void )	callback,
		void *	arg
	)

inlinestatic

Creates and starts a periodic timer with a raw function pointer callback.

Combines timer creation and periodic start into a single operation. If creation succeeds but starting fails, the timer is automatically cleaned up via RAII.

using namespace std::chrono_literals;
auto t = idfxx::timer::start_periodic(
    {.name = "heartbeat"}, 100ms,
    [](void* arg) { (*static_cast<int*>(arg))++; }, &count);

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

cfg	Timer configuration.
interval	Time between callback invocations.
callback	Function to call when timer fires.
arg	Argument passed to the callback.

Returns: The new running timer.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 316 of file timer.hpp.

References try_start_periodic(), and idfxx::unwrap().

◆ start_periodic() [3/3]

template<typename Rep , typename Period >

void idfxx::timer::start_periodic ( const std::chrono::duration< Rep, Period > & interval )

inline

Starts the timer as a periodic timer.

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

interval Time between callback invocations.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 596 of file timer.hpp.

References try_start_periodic(), and idfxx::unwrap().

◆ stop()

void idfxx::timer::stop ( )

inline

Stops the timer.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 750 of file timer.hpp.

References try_stop(), and idfxx::unwrap().

◆ try_restart()

template<typename Rep , typename Period >

result< void > idfxx::timer::try_restart ( const std::chrono::duration< Rep, Period > & timeout )

inline

Restarts the timer with a new timeout.

If the timer is running, it will be stopped and restarted. If not running, it will be started as a one-shot timer.

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

timeout Time until the callback is invoked.

Returns: Success, or an error.

Return values

invalid_arg Invalid timeout value.

Definition at line 717 of file timer.hpp.

References idfxx::timeout, and idfxx::wrap().

Referenced by restart().

◆ try_restart_isr()

esp_err_t idfxx::timer::try_restart_isr ( uint64_t timeout_us )

Restarts the timer with a new timeout (ISR-compatible).

This method returns the underlying ESP-IDF esp_err_t directly to avoid flash-resident code paths. When CONFIG_ESP_TIMER_IN_IRAM is enabled, this method is placed in IRAM and can be called from ISR context.

using namespace std::chrono_literals;
constexpr uint64_t timeout_us = std::chrono::microseconds(100ms).count();
timer->try_restart_isr(timeout_us);

Parameters

timeout_us Timeout in microseconds.

Returns: ESP_OK on success, or an esp_err_t error code.

◆ try_start_once() [1/6]

result< void > idfxx::timer::try_start_once ( clock::time_point time )

inline

Starts the timer as a one-shot timer at an absolute time.

The callback will be invoked once at the specified time point. If the time point is in the past, the timer fires as soon as possible.

Parameters

time	Absolute time at which the callback should be invoked.

Returns: Success, or an error.

Return values

invalid_state Timer is already running.

Definition at line 628 of file timer.hpp.

References idfxx::timer::clock::now(), and idfxx::wrap().

◆ try_start_once() [2/6]

static result< std::unique_ptr< timer > > idfxx::timer::try_start_once	(	config	cfg,
		clock::time_point	time,
		std::move_only_function< void()>	callback
	)

inlinestatic

Creates and starts a one-shot timer at an absolute time with a std::move_only_function callback.

Combines timer creation and one-shot start into a single operation. The timer fires at the specified time point. If the time point is in the past, the timer fires as soon as possible.

Warning: This method cannot be used with dispatch_method::isr. Use the raw function pointer overload for ISR dispatch.

Parameters

cfg	Timer configuration.
time	Absolute time at which the callback should be invoked.
callback	Function to call when timer fires.

Returns: The new running timer, or an error.

Return values

no_mem	Memory allocation failed.
invalid_arg	Invalid configuration.
invalid_state	Timer could not be started.

Definition at line 409 of file timer.hpp.

References idfxx::error(), and make().

◆ try_start_once() [3/6]

static result< std::unique_ptr< timer > > idfxx::timer::try_start_once	(	config	cfg,
		clock::time_point	time,
		void()(void )	callback,
		void *	arg
	)

inlinestatic

Creates and starts a one-shot timer at an absolute time with a raw function pointer callback.

Combines timer creation and one-shot start into a single operation. The timer fires at the specified time point. If the time point is in the past, the timer fires as soon as possible.

Note: This overload is suitable for ISR dispatch.

Parameters

cfg	Timer configuration.
time	Absolute time at which the callback should be invoked.
callback	Function to call when timer fires.
arg	Argument passed to the callback.

Returns: The new running timer, or an error.

Return values

no_mem	Memory allocation failed.
invalid_arg	Invalid configuration.
invalid_state	Timer could not be started.

Definition at line 440 of file timer.hpp.

References idfxx::error(), and make().

◆ try_start_once() [4/6]

template<typename Rep , typename Period >

static result< std::unique_ptr< timer > > idfxx::timer::try_start_once	(	config	cfg,
		const std::chrono::duration< Rep, Period > &	timeout,
		std::move_only_function< void()>	callback
	)

inlinestatic

Creates and starts a one-shot timer with a std::move_only_function callback.

Combines timer creation and one-shot start into a single operation. If creation succeeds but starting fails, the timer is automatically cleaned up via RAII.

Warning: This method cannot be used with dispatch_method::isr. Use the raw function pointer overload for ISR dispatch.

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

cfg	Timer configuration.
timeout	Time until the callback is invoked.
callback	Function to call when timer fires.

Returns: The new running timer, or an error.

Return values

no_mem	Memory allocation failed.
invalid_arg	Invalid configuration or timeout value.
invalid_state	Timer could not be started.

Definition at line 341 of file timer.hpp.

References idfxx::error(), make(), and idfxx::timeout.

Referenced by start_once(), start_once(), start_once(), start_once(), start_once(), and start_once().

◆ try_start_once() [5/6]

template<typename Rep , typename Period >

static result< std::unique_ptr< timer > > idfxx::timer::try_start_once	(	config	cfg,
		const std::chrono::duration< Rep, Period > &	timeout,
		void()(void )	callback,
		void *	arg
	)

inlinestatic

Creates and starts a one-shot timer with a raw function pointer callback.

Combines timer creation and one-shot start into a single operation. If creation succeeds but starting fails, the timer is automatically cleaned up via RAII.

Note: This overload is suitable for ISR dispatch.

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

cfg	Timer configuration.
timeout	Time until the callback is invoked.
callback	Function to call when timer fires.
arg	Argument passed to the callback.

Returns: The new running timer, or an error.

Return values

no_mem	Memory allocation failed.
invalid_arg	Invalid configuration or timeout value.
invalid_state	Timer could not be started.

Definition at line 378 of file timer.hpp.

References idfxx::error(), make(), and idfxx::timeout.

◆ try_start_once() [6/6]

template<typename Rep , typename Period >

result< void > idfxx::timer::try_start_once ( const std::chrono::duration< Rep, Period > & timeout )

inline

Starts the timer as a one-shot timer.

The callback will be invoked once after the specified timeout.

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

timeout Time until the callback is invoked.

Returns: Success, or an error.

Return values

invalid_state	Timer is already running.
invalid_arg	Invalid timeout value.

Definition at line 614 of file timer.hpp.

References idfxx::timeout, and idfxx::wrap().

◆ try_start_once_isr()

esp_err_t idfxx::timer::try_start_once_isr ( uint64_t timeout_us )

Starts the timer as a one-shot timer (ISR-compatible).

This method returns the underlying ESP-IDF esp_err_t directly to avoid flash-resident code paths. When CONFIG_ESP_TIMER_IN_IRAM is enabled, this method is placed in IRAM and can be called from ISR context.

using namespace std::chrono_literals;
constexpr uint64_t timeout_us = std::chrono::microseconds(100ms).count();
timer->try_start_once_isr(timeout_us);

Parameters

timeout_us Timeout in microseconds.

Returns: ESP_OK on success, or an esp_err_t error code.

Return values

ESP_ERR_INVALID_STATE	Timer is already running.
ESP_ERR_INVALID_ARG	Invalid timeout value.

◆ try_start_periodic() [1/3]

template<typename Rep , typename Period >

static result< std::unique_ptr< timer > > idfxx::timer::try_start_periodic	(	config	cfg,
		const std::chrono::duration< Rep, Period > &	interval,
		std::move_only_function< void()>	callback
	)

inlinestatic

Creates and starts a periodic timer with a std::move_only_function callback.

Combines timer creation and periodic start into a single operation. If creation succeeds but starting fails, the timer is automatically cleaned up via RAII.

Warning: This method cannot be used with dispatch_method::isr. Use the raw function pointer overload for ISR dispatch.

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

cfg	Timer configuration.
interval	Time between callback invocations.
callback	Function to call when timer fires.

Returns: The new running timer, or an error.

Return values

no_mem	Memory allocation failed.
invalid_arg	Invalid configuration or interval value.
invalid_state	Timer could not be started.

Definition at line 472 of file timer.hpp.

References idfxx::error(), and make().

Referenced by start_periodic(), start_periodic(), and start_periodic().

◆ try_start_periodic() [2/3]

template<typename Rep , typename Period >

static result< std::unique_ptr< timer > > idfxx::timer::try_start_periodic	(	config	cfg,
		const std::chrono::duration< Rep, Period > &	interval,
		void()(void )	callback,
		void *	arg
	)

inlinestatic

Creates and starts a periodic timer with a raw function pointer callback.

Combines timer creation and periodic start into a single operation. If creation succeeds but starting fails, the timer is automatically cleaned up via RAII.

Note: This overload is suitable for ISR dispatch.

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

cfg	Timer configuration.
interval	Time between callback invocations.
callback	Function to call when timer fires.
arg	Argument passed to the callback.

Returns: The new running timer, or an error.

Return values

no_mem	Memory allocation failed.
invalid_arg	Invalid configuration or interval value.
invalid_state	Timer could not be started.

Definition at line 508 of file timer.hpp.

References idfxx::error(), and make().

◆ try_start_periodic() [3/3]

template<typename Rep , typename Period >

result< void > idfxx::timer::try_start_periodic ( const std::chrono::duration< Rep, Period > & interval )

inline

Starts the timer as a periodic timer.

The callback will be invoked repeatedly at the specified interval.

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

interval Time between callback invocations.

Returns: Success, or an error.

Return values

invalid_state	Timer is already running.
invalid_arg	Invalid interval value.

Definition at line 666 of file timer.hpp.

References idfxx::wrap().

◆ try_start_periodic_isr()

esp_err_t idfxx::timer::try_start_periodic_isr ( uint64_t interval_us )

Starts the timer as a periodic timer (ISR-compatible).

This method returns the underlying ESP-IDF esp_err_t directly to avoid flash-resident code paths. When CONFIG_ESP_TIMER_IN_IRAM is enabled, this method is placed in IRAM and can be called from ISR context.

using namespace std::chrono_literals;
constexpr uint64_t interval_us = std::chrono::microseconds(100ms).count();
timer->try_start_periodic_isr(interval_us);

Parameters

interval_us Interval in microseconds.

Returns: ESP_OK on success, or an esp_err_t error code.

◆ try_stop()

result< void > idfxx::timer::try_stop ( )

inline

Stops the timer.

Returns: Success, or an error.

Return values

invalid_state Timer is not running.

Definition at line 759 of file timer.hpp.

References idfxx::wrap().

Referenced by stop().

◆ try_stop_isr()

esp_err_t idfxx::timer::try_stop_isr ( )

Stops the timer (ISR-compatible).

This method returns the underlying ESP-IDF esp_err_t directly to avoid flash-resident code paths. When CONFIG_ESP_TIMER_IN_IRAM is enabled, this method is placed in IRAM and can be called from ISR context.

Returns: ESP_OK on success, or an esp_err_t error code.

Return values

ESP_ERR_INVALID_STATE Timer is not running.

The documentation for this class was generated from the following file:

idfxx_timer/include/idfxx/timer.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ dispatch_method

Constructor & Destructor Documentation

◆ timer() [1/4]

◆ timer() [2/4]

◆ ~timer()

◆ timer() [3/4]

◆ timer() [4/4]

Member Function Documentation

◆ expiry_time()

◆ idf_handle()

◆ is_active()

◆ make() [1/2]

◆ make() [2/2]

◆ name()

◆ next_alarm()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ period()

◆ restart()

◆ start_once() [1/6]

◆ start_once() [2/6]

◆ start_once() [3/6]

◆ start_once() [4/6]

◆ start_once() [5/6]

◆ start_once() [6/6]

◆ start_periodic() [1/3]

◆ start_periodic() [2/3]

◆ start_periodic() [3/3]

◆ stop()

◆ try_restart()

◆ try_restart_isr()

◆ try_start_once() [1/6]

◆ try_start_once() [2/6]

◆ try_start_once() [3/6]

◆ try_start_once() [4/6]

◆ try_start_once() [5/6]

◆ try_start_once() [6/6]

◆ try_start_once_isr()

◆ try_start_periodic() [1/3]

◆ try_start_periodic() [2/3]

◆ try_start_periodic() [3/3]

◆ try_start_periodic_isr()

◆ try_stop()

◆ try_stop_isr()