93 lines
3.3 KiB
Markdown
93 lines
3.3 KiB
Markdown
---
|
|
title: "XTimer - A Lightweight Timer Implementation"
|
|
description: "A template-based timer utility for scheduling tasks at specific intervals or times"
|
|
keywords: ["timer", "ESP-32", "embedded", "C++", "scheduling", "task management"]
|
|
---
|
|
|
|
## XTimer
|
|
|
|
**Path**: [`src/modbus/xtimer.h`](../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`](../src/modbus/macros.h)
|
|
- Arduino core (`Arduino.h` or `WProgram.h` for older versions)
|
|
|
|
```mermaid
|
|
graph TD
|
|
XTimer --> Macros
|
|
XTimer --> Arduino["Arduino Core"]
|
|
```
|
|
|
|
## BEHAVIOUR
|
|
|
|
The timer operates by tracking tasks and their scheduled execution times:
|
|
|
|
```mermaid
|
|
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 |