---
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