Task Management
Relevant source files
The following files were used as context for generating this wiki page:
Task Management in FlxOS provides a robust framework for scheduling, monitoring, and controlling background processes on ESP32 microcontrollers. It leverages FreeRTOS to handle multitasking, enabling efficient parallel processing for core system functions and modular applications.
The system is centered around a centralized TaskManager that handles task registration, watchdog monitoring, and system integrity checks. This architecture ensures that both core services (like the GUI or Connectivity) and user-facing applications run reliably with defined priorities and resource constraints.
Sources: README.md:25-33, main/core/tasks/TaskManager.hpp:81-105
Architecture and Components
The task management architecture consists of a base Task class that abstracts FreeRTOS primitives and a singleton TaskManager that maintains a registry of all active tasks.
The Task Class
The Task class acts as a wrapper for FreeRTOS task handles and configuration. It provides a standardized interface for starting, stopping, and monitoring execution. Key features include:
- Heartbeat Mechanism: Tasks can signal they are still alive using the
heartbeat()method. - Watchdog Integration: Supports per-task watchdog timeouts and restart policies.
- Core Affinity: Allows pinning tasks to specific CPU cores (0 or 1) or allowing FreeRTOS to manage affinity (
tskNO_AFFINITY).
Sources: main/core/tasks/TaskManager.hpp:13-79, main/core/tasks/TaskManager.cpp:20-25
The TaskManager Singleton
The TaskManager is responsible for global task orchestration and system health monitoring. It tracks all Task instances in a std::vector and provides thread-safe access via a std::mutex.
The diagram shows the relationship between individual Task instances and the central Manager.
Sources: main/core/tasks/TaskManager.hpp:81-105, main/core/tasks/TaskManager.cpp:88-112
Task Lifecycle and Scheduling
Tasks in FlxOS follow a defined lifecycle from registration to execution. The start() method utilizes xTaskCreate or xTaskCreatePinnedToCore to spawn the execution thread.
Lifecycle States
| State | Description |
|---|---|
| Registered | The Task object exists and is known to the TaskManager but the thread is not yet created. |
| Running | The FreeRTOS task is active and executing its run() implementation. |
| Stopped | The task has been deleted via vTaskDelete and its handle is cleared. |
Sources: main/core/tasks/TaskManager.cpp:32-75, main/core/tasks/TaskManager.hpp:67-70
Execution Flow
When a task starts, it executes a static taskEntry which delegates to the virtual run() method implemented by subclasses.
Execution flow from task initiation to termination.
Sources: main/core/tasks/TaskManager.cpp:32-86
System Health and Watchdog
The TaskManager implements a software watchdog system that monitors the "heartbeat" of registered tasks to prevent system hangs.
Watchdog Mechanism
The TaskManager runs a dedicated high-priority watchdog task (tm_watchdog). This task periodically checks the last heartbeat timestamp of every task that has watchdog monitoring enabled. If a task exceeds its m_watchdogTimeoutMs, the manager triggers a recovery action based on the task's RestartPolicy.
| Policy | Action |
|---|---|
NEVER | No action taken. |
RESTART_TASK | Stops and restarts the specific task (Warning: may orphan resources). |
REBOOT_SYSTEM | Triggers a full hardware esp_restart(). |
Sources: main/core/tasks/TaskManager.hpp:17-22, main/core/tasks/TaskManager.cpp:114-162
Watchdog Process Flow
Sequence of events during a watchdog check cycle.
Sources: main/core/tasks/TaskManager.cpp:131-162
Monitoring and Introspection
FlxOS provides multiple tools for monitoring task performance, including CPU usage and stack memory consumption.
Metrics Collected
Through the SystemInfoService, the OS retrieves detailed metrics for every FreeRTOS task:
- CPU Usage: Normalized percentage across available cores.
- Stack High Water Mark: The minimum amount of remaining stack space (in bytes) since the task started.
- State: Current task state (RUN, RDY, BLK, SUS, or DEL).
- Priority: Current and base execution priority.
Sources: main/core/services/system_info/SystemInfoService.cpp:337-414, main/core/apps/system_info/SystemInfoApp.cpp:249-277
Monitoring Interfaces
- System Info App: A GUI-based table displaying real-time task statistics, sorted by stack usage.
- CLI Service: Provides terminal commands like
tasksandtopto output task lists to the serial console. - TaskManager::printTasks(): A debug function that logs the stack High Water Mark for all registered tasks.
Sources: main/core/apps/system_info/SystemInfoApp.cpp:197-217, main/core/services/cli/CliService.cpp:109-122, main/core/tasks/TaskManager.cpp:173-179
Conclusion
Task Management in FlxOS serves as the foundation for its multitasking stability. By combining FreeRTOS's preemptive scheduling with a structured Task abstraction and a central watchdog monitor, FlxOS ensures that background services and applications remain responsive while providing developers with deep introspection into system resource utilization.