firmware-base/docs-c/core/xtimer.md

title	description	keywords
XTimer - A Lightweight Timer Implementation	A template-based timer utility for scheduling tasks at specific intervals or times	timer ESP-32 embedded C++ scheduling task management

XTimer

Path: src/modbus/xtimer.h

Revision History:

• Initial documentation

A lightweight, template-based timer implementation designed for embedded systems, specifically targeting ESP-32. The timer provides functionality for scheduling tasks to run after a delay, at a specific time, or at regular intervals. It avoids using the standard library, making it suitable for resource-constrained environments.

REQUIREMENTS

• No specific hardware pins required
• C++17 support
• Arduino framework or equivalent (millis() function)

PROVIDES

• Timer<size_t max_tasks, unsigned long (*time_func)()> - Main timer class template
• handler_t - Function pointer type for task callbacks
• timer_create_default() - Utility function to create a timer with default settings
• task struct - Internal structure to represent scheduled tasks

FEATURES

• Schedule tasks to run after a specified delay
• Schedule tasks to run at specific time points
• Schedule recurring tasks at regular intervals
• Configurable number of maximum concurrent tasks
• Customizable time function (defaults to millis())
• Small memory footprint with fixed-size task array
• No dynamic memory allocation

DEPENDENCIES

• src/modbus/macros.h
• Arduino core (Arduino.h or WProgram.h for older versions)

graph TD
    XTimer --> Macros
    XTimer --> Arduino["Arduino Core"]

BEHAVIOUR

The timer operates by tracking tasks and their scheduled execution times:

graph TD
    Start[Initialize Timer] --> AddTask[Add Task to Queue]
    AddTask --> Tick[Timer Tick]
    Tick --> CheckTasks[Check Task Expiry]
    CheckTasks --> TaskExpired{Task Expired?}
    TaskExpired -- Yes --> Execute[Execute Task Handler]
    TaskExpired -- No --> Tick
    Execute --> IsRepeat{Is Recurring?}
    IsRepeat -- Yes --> ResetTask[Reset Timer for Next Run]
    ResetTask --> Tick
    IsRepeat -- No --> RemoveTask[Remove Task from Queue]
    RemoveTask --> Tick

TODOS

PERFORMANCE

• Consider a more efficient data structure than a simple array for tasks, especially for systems with many scheduled tasks
• Implement a priority queue to optimize the tick() function when handling many tasks
• Provide options to reduce memory usage for systems with very limited RAM

SECURITY

• No major security concerns as this is a local timer implementation
• Ensure task handlers do not introduce timing vulnerabilities in security-critical applications

COMPLIANCE

• Review for MISRA C++ compliance if used in safety-critical applications
• Ensure thread safety if used in multi-threaded environments

RECOMMENDATIONS

• Keep task handlers lightweight to avoid blocking the main loop
• Avoid using too many concurrent tasks as it may impact performance
• For time-critical operations, consider using hardware timers instead
• When using the every() function for periodic tasks, be aware of potential timing drift over long periods
• Consider implementing a task ID return value to allow for cancellation of scheduled tasks