looper：面向嵌入式MCU的毫秒级无依赖任务调度器

1. 项目概述looper是一个轻量级、无依赖的原型级任务调度器proto-scheduler专为资源受限的嵌入式微控制器如 Arduino AVR、ESP32、STM32G0 等设计。其核心思想极为简洁完全基于millis()的毫秒级时间戳实现非阻塞、事件驱动的周期性与一次性任务调度不引入任何操作系统内核、RTOS 任务、系统滴答中断扩展或动态内存分配malloc/free。它并非替代 FreeRTOS 或 Zephyr 的完整调度器而是一个“够用即止”的底层时序协调层——适用于快速验证控制逻辑、构建传感器轮询框架、实现 LED 呼吸灯节拍、管理串口命令超时、或作为更复杂调度器的初始化前置模块。在嵌入式开发实践中开发者常面临两类典型痛点裸机轮询陷阱在loop()中反复if (millis() - last_time interval)判断代码分散、状态变量杂乱、可维护性差RTOS 过度设计为仅需 3 个定时回调的简单应用引入整个 FreeRTOS增加 Flash 占用8–15 KB、RAM 开销任务栈 内核结构体、上下文切换开销及学习成本。looper正是针对这一中间地带而生——它提供类 RTOS 的“注册-回调”抽象却保持裸机级的零开销与确定性。所有调度逻辑在loop()中单线程顺序执行无抢占、无优先级、无阻塞等待仅通过时间戳比较与函数指针调用完成任务分发。这种设计使其具备极高的可预测性任意任务执行时间均可静态估算不会因调度器本身引入不可控延迟。1.1 设计哲学与工程定位looper的设计严格遵循嵌入式开发的黄金法则KISSKeep It Simple, Stupid与 YAGNIYou Aren’t Gonna Need It。无状态全局变量不维护任务链表、不管理任务句柄、不提供任务挂起/恢复接口。用户只需注册函数指针与触发时间点调度器仅负责“到点调用”。零动态内存所有任务注册均通过编译期确定的静态数组或栈上结构体完成避免堆碎片与分配失败风险。毫秒级精度妥协millis()在 AVR 上存在约 0.05% 累积误差每分钟偏差 30 ms但对大多数传感器采样、LED 控制、人机交互等场景完全可接受。若需更高精度可无缝替换为micros()或硬件定时器捕获值需修改时间源接口。无中断上下文安全限制所有回调均在主循环上下文中执行因此可安全调用Serial.print()、digitalWrite()、HAL_UART_Transmit()等非重入函数无需信号量保护。该库的本质是一个时间复用器Time Multiplexer将单一的millis()时间轴映射为多个逻辑上并行的定时通道。其价值不在于“并发”而在于“解耦”——将时间敏感逻辑从业务主循环中剥离提升代码模块化程度。2. 核心机制解析looper的运行机制建立在三个原子操作之上时间戳快照、条件判断、函数调用。其核心数据结构极简通常仅需一个struct描述单个任务typedef struct { uint32_t next_run_ms; // 下次执行的绝对时间戳单位ms uint32_t interval_ms; // 执行间隔0 表示一次性任务 void (*callback)(void); // 回调函数指针 } looper_task_t;2.1 调度流程详解调度器主体逻辑封装于一个内联函数或宏中典型实现如下以 Arduino 风格为例// looper.h static inline void looper_run(void) { const uint32_t now millis(); // 获取当前时间快照关键避免多次调用导致时间漂移 for (uint8_t i 0; i LOOPER_TASK_MAX; i) { looper_task_t* task g_looper_tasks[i]; if (task-callback NULL) continue; // 空槽位跳过 if (now task-next_run_ms) { // 时间到 task-callback(); // 执行回调 if (task-interval_ms 0) { // 周期性任务计算下次执行时间使用“追赶模式”而非“固定偏移” // 避免因回调执行耗时导致后续周期整体偏移 task-next_run_ms now task-interval_ms; } else { // 一次性任务注销自身 task-callback NULL; } } } }此处需重点强调两个工程细节now快照的必要性若在循环中每次if判断都调用millis()当loop()执行较慢时millis()返回值可能在循环内递增导致同一任务被重复触发或漏触发。单次快照确保所有任务基于同一时间基准判断。“追赶模式”时间更新task-next_run_ms now task-interval_ms而非task-next_run_ms task-interval_ms。前者保证任务周期严格对齐now即使回调执行耗时 5 ms下一次仍从当前时刻起算 100 ms 后执行后者则会累积延迟如耗时 5 ms则下次在now5100now105执行再下次now110持续偏移。这对需要严格节拍的应用如音频 PWM 同步至关重要。2.2 任务注册与生命周期管理looper不提供动态注册 API如looper_add_task()因其违背零动态内存原则。任务注册通过两种方式完成方式一静态数组预定义推荐用于固定功能设备// 定义任务数组编译期确定大小 #define LOOPER_TASK_MAX 8 static looper_task_t g_looper_tasks[LOOPER_TASK_MAX] {0}; // 初始化任务通常在 setup() 中 void setup() { // 任务0LED 每 500ms 翻转 g_looper_tasks[0] (looper_task_t){ .next_run_ms millis() 500, .interval_ms 500, .callback led_toggle_callback }; // 任务1传感器每 2s 读取一次一次性初始化 g_looper_tasks[1] (looper_task_t){ .next_run_ms millis() 100, .interval_ms 0, // 一次性 .callback sensor_init_callback }; } void loop() { looper_run(); // 主循环中调用 // 其他业务逻辑... }方式二栈上临时注册适用于动态场景void start_blinking(uint32_t interval_ms) { looper_task_t blink_task { .next_run_ms millis() interval_ms, .interval_ms interval_ms, .callback led_toggle_callback }; // 将任务压入全局数组需保证数组有空位 for (uint8_t i 0; i LOOPER_TASK_MAX; i) { if (g_looper_tasks[i].callback NULL) { g_looper_tasks[i] blink_task; return; } } // 数组满处理错误如返回错误码或触发断言 }任务生命周期由interval_ms字段隐式管理interval_ms 0→ 一次性任务执行后自动注销callback置为NULLinterval_ms 0→ 周期性任务持续调度直至手动注销将callback置为NULL。无任务删除 API 的设计深意强制用户通过直接操作数组元素来管理任务消除隐藏状态使生命周期完全透明。这符合嵌入式开发中“显式优于隐式”的调试友好原则。3. API 接口规范与参数详解looper的 API 极其精简仅包含 3 个核心接口全部为 C 函数或内联函数函数名原型功能说明关键参数说明looper_init()void looper_init(void)初始化调度器通常为空实现或清零任务数组无参数looper_run()void looper_run(void)执行一轮调度检查所有任务时间戳并触发回调无参数必须在主循环中高频调用建议 ≥1 kHzlooper_set_task()bool looper_set_task(uint8_t idx, uint32_t next_ms, uint32_t interval_ms, void (*cb)(void))安全设置指定索引的任务带边界检查idx: 数组索引0~LOOPER_TASK_MAX-1next_ms: 绝对触发时间interval_ms: 0一次性0周期cb: 非 NULL 回调函数3.1looper_run()的调用频率要求这是looper使用中最易被忽视的关键约束。由于调度器不使用中断其时间分辨率完全取决于looper_run()的调用频率。例如若loop()平均耗时 10 ms即每秒执行 100 次则最短可调度周期为 10 ms若某任务设为interval_ms1但looper_run()每 5 ms 才执行一次则该任务实际以 5 ms 周期触发精度损失 5×。工程实践建议对于 ≤100 ms 周期任务确保loop()执行时间 10 ms即looper_run()调用频率 100 Hz对于 ≤10 ms 周期任务需优化loop()内其他逻辑或改用硬件定时器中断触发looper_run()见 4.2 节可在loop()开头添加while(millis() - last_loop_ms 1) { /* 空转或低功耗等待 */ }实现恒定 1 ms 调度粒度AVR 上需注意delayMicroseconds(1000)精度。3.2 时间参数的工程选型指南next_run_ms与interval_ms的取值需结合硬件特性权衡参数推荐取值范围选型依据风险提示interval_ms1–60000 ms大多数传感器DHT22: 2s, BME280: 100ms、LED10–1000ms、通信超时100–5000ms均在此范围1ms 易受millis()分辨率限制AVR 为 1.024ms60s 需考虑millis()溢出49.7天next_run_msmillis() offset必须使用millis()当前值计算禁止硬编码如1000否则启动后首次触发时间不确定直接赋值1000会导致设备上电后等待 1000ms 才触发而非“启动后 1s 触发”溢出安全处理是looper的隐含能力uint32_t的无符号减法天然支持跨溢出比较。now next_run_ms在now0xFFFFFFFF、next_run_ms10时仍正确返回true因0xFFFFFFFF - 10产生大正数但比较逻辑无误。此特性无需额外代码是 C 语言无符号算术的馈赠。4. 高级集成与工程实践4.1 与 HAL 库协同工作STM32 示例在 STM32CubeIDE 项目中looper可无缝替代HAL_Delay()的轮询式等待实现非阻塞外设管理。以下为 UART 接收超时处理示例// 全局变量 static uint8_t rx_buffer[64]; static uint16_t rx_len 0; static bool uart_rx_complete false; // UART 接收完成回调HAL_UART_RxCpltCallback void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { if (huart huart2) { rx_len sizeof(rx_buffer) - huart-RxXferCount; uart_rx_complete true; // 启动 500ms 超时监测 looper_set_task(2, millis() 500, 0, uart_timeout_handler); } } // 超时处理函数 void uart_timeout_handler(void) { if (!uart_rx_complete) { // 超时未收到完整帧执行错误处理 HAL_UART_AbortReceive(huart2); // 清空缓冲区重置状态 memset(rx_buffer, 0, sizeof(rx_buffer)); rx_len 0; } uart_rx_complete false; // 无论是否超时均重置标志 } // 主循环 void loop() { looper_run(); if (uart_rx_complete) { // 处理接收到的数据 process_uart_frame(rx_buffer, rx_len); // 重新启动接收非阻塞 HAL_UART_Receive_IT(huart2, rx_buffer, sizeof(rx_buffer)); uart_rx_complete false; } }此方案优势避免在HAL_UART_RxCpltCallback中调用HAL_Delay()会阻塞中断超时逻辑与接收逻辑解耦process_uart_frame()可专注业务无需关心超时占用资源极少仅 1 个任务槽位 3 个字节状态变量。4.2 与 FreeRTOS 混合部署looper可作为 FreeRTOS 任务内的子调度器管理该任务内部的细粒度定时事件避免为每个小定时器创建独立任务节省 RAM 与上下文切换开销。典型场景一个sensor_task需同时读取温度、湿度、气压且各传感器采样周期不同。// FreeRTOS 任务函数 void sensor_task(void *pvParameters) { // 在任务内初始化 looper使用局部任务数组 looper_task_t local_tasks[4] {0}; // 注册温度读取2s 周期 local_tasks[0] (looper_task_t){ .next_run_ms xTaskGetTickCount() * portTICK_PERIOD_MS 2000, .interval_ms 2000, .callback read_temperature }; // 注册湿度读取1s 周期 local_tasks[1] (looper_task_t){ .next_run_ms xTaskGetTickCount() * portTICK_PERIOD_MS 1000, .interval_ms 1000, .callback read_humidity }; for(;;) { // 在 FreeRTOS 任务中调用 looper_run使用局部数组 uint32_t now xTaskGetTickCount() * portTICK_PERIOD_MS; for (int i 0; i 4; i) { if (local_tasks[i].callback now local_tasks[i].next_run_ms) { local_tasks[i].callback(); if (local_tasks[i].interval_ms) { local_tasks[i].next_run_ms now local_tasks[i].interval_ms; } else { local_tasks[i].callback NULL; } } } vTaskDelay(1); // 释放 CPU让出时间片1ms } }此模式将looper降级为“任务内协程调度器”充分发挥其轻量优势同时利用 FreeRTOS 的抢占式多任务能力。4.3 硬件定时器增强高精度场景当millis()精度不足时如需要 100μs 级 PWM 同步可将looper的时间源替换为硬件定时器。以 STM32 HAL 为例// 使用 TIM2 作为高精度时间源1MHz 计数器 uint32_t looper_get_time_us(void) { return __HAL_TIM_GET_COUNTER(htim2); // 返回当前计数值单位μs } // 修改 looper_run() 中的时间获取逻辑 const uint32_t now_us looper_get_time_us(); // 后续比较与更新均使用 us 单位此时需同步调整looper_task_t结构体将next_run_ms和interval_ms改为uint32_t next_run_us和uint32_t interval_us。这种改造保持了looper架构不变仅替换时间源体现了其良好的可扩展性。5. 典型应用场景与代码模板5.1 多传感器融合采集系统// 任务规划 // - BME280环境温湿度气压每 100ms 读取 // - MPU6050加速度/陀螺仪每 10ms 读取需高频率 // - GPSNMEA 数据解析每 1s 处理一次 // 全局任务数组 #define SENSOR_TASKS 3 static looper_task_t sensor_tasks[SENSOR_TASKS]; void setup() { // 初始化传感器... // 注册 BME280 任务索引0 sensor_tasks[0] (looper_task_t){ .next_run_ms millis() 100, .interval_ms 100, .callback bme280_read_callback }; // 注册 MPU6050 任务索引1— 注意10ms 周期要求 loop() 高频 sensor_tasks[1] (looper_task_t){ .next_run_ms millis() 10, .interval_ms 10, .callback mpu6050_read_callback }; // 注册 GPS 任务索引2 sensor_tasks[2] (looper_task_t){ .next_run_ms millis() 1000, .interval_ms 1000, .callback gps_parse_callback }; } void loop() { looper_run(); // 统一调度所有传感器 // 主循环可处理数据聚合、网络上传等低频任务 if (new_sensor_data_ready()) { send_to_cloud(); } }5.2 状态机驱动的用户界面// LED 状态机待机(灭)→唤醒(慢闪)→工作(快闪)→错误(呼吸) typedef enum { STATE_IDLE, STATE_WAKEUP, STATE_WORKING, STATE_ERROR } ui_state_t; static ui_state_t current_state STATE_IDLE; static uint32_t state_start_ms 0; void ui_state_machine(void) { const uint32_t now millis(); switch (current_state) { case STATE_IDLE: if (button_pressed()) { current_state STATE_WAKEUP; state_start_ms now; looper_set_task(0, now 500, 0, ui_wakeup_step); } break; case STATE_WAKEUP: if (now - state_start_ms 2000) { current_state STATE_WORKING; looper_set_task(0, now 200, 200, ui_working_blink); } break; // ... 其他状态 } } // 在 setup() 中注册状态机主循环任务 sensor_tasks[3] (looper_task_t){ .next_run_ms millis(), .interval_ms 10, // 10ms 检查一次状态 .callback ui_state_machine };此模式将传统switch-case状态机与looper的时间调度结合使状态转换条件清晰分离大幅提升 UI 逻辑可维护性。6. 调试技巧与常见问题排查6.1 调度延迟诊断当任务未按预期周期触发时按以下步骤排查确认looper_run()调用频率在loop()开头添加static uint32_t last_check 0; if (millis() - last_check 1000) { Serial.println(looper_run freq OK); last_check millis(); }检查任务数组是否溢出打印g_looper_tasks[i].callback是否为NULL确认任务已成功注册验证时间计算在回调函数开头添加Serial.print(Actual delay: ); Serial.println(millis() - expected_time);排除阻塞操作确保回调函数内无delay()、while(!flag)等阻塞代码否则会拖垮整个调度器。6.2 内存占用优化looper的 RAM 占用 LOOPER_TASK_MAX × sizeof(looper_task_t)。sizeof(looper_task_t)在 32 位 MCU 上为 12 字节3×uint32_t。若仅需 4 个任务LOOPER_TASK_MAX4仅占 48 字节 RAM远低于一个 FreeRTOS 任务栈通常 ≥256 字节。可通过#pragma pack(1)进一步压缩至 11 字节对齐优化但需权衡访问效率。6.3 与delay()的兼容性警告绝对禁止在looper回调函数中调用delay()。delay()本质是忙等循环会冻结整个调度器导致所有后续任务堆积。正确做法是将长延时拆分为多个短周期任务// ❌ 错误阻塞整个调度器 void bad_callback(void) { delay(5000); // 危险 do_something(); } // ✅ 正确分阶段执行 static uint8_t delay_step 0; void good_callback(void) { switch (delay_step) { case 0: delay_step 1; looper_set_task(0, millis()1000, 0, good_callback); break; case 1: delay_step 2; looper_set_task(0, millis()1000, 0, good_callback); break; case 2: delay_step 3; looper_set_task(0, millis()1000, 0, good_callback); break; case 3: delay_step 0; do_something(); break; } }这种“状态机式延时”是嵌入式开发的核心范式looper为其提供了优雅的基础设施。