ESP-ADF esp_dispatcher组件之dispatcher介绍

ESP-ADF esp_dispatcher组件之dispatcher介绍

版本信息: v2.7-65-gcf908721

子模块概览

基本功能与定位

dispatcher子模块是ESP-ADF中esp_dispatcher组件的核心部分，它提供了基础的事件调度框架，使系统能够统一管理各种事件并灵活调度执行相应的处理函数。该模块处于ESP-ADF架构的中间层，连接上层应用逻辑和底层系统服务。

这个综合图表展示了dispatcher子模块在整个ESP-ADF架构中的关键位置：它既是连接上下层的桥梁(ESP-dispatcher模块)，也是内部的核心基础组件，为delegate、periph_service和audio_service子模块提供事件调度服务。

工作原理

dispatcher子模块基于FreeRTOS的任务和队列机制实现，它的工作原理如下：

1. 事件注册：应用程序通过API注册事件ID和对应的处理函数
2. 事件提交：事件发生时，通过dispatcher接口将事件放入队列
3. 事件分发：dispatcher后台任务从队列取出事件，查找对应处理函数
4. 执行回调：调用事件对应的处理函数，完成实际操作
5. 结果返回：同步或异步方式将执行结果返回给调用方

核心特性

• 统一事件处理：提供统一的事件分发机制
• 同步/异步模式：支持同步调用和异步回调两种执行模式
• 资源管理：自动管理任务、队列等资源的创建和销毁
• 线程安全：使用互斥锁保证多线程环境下的安全访问
• 可扩展性：易于注册新的事件类型和处理函数

公开接口

以下接口定义来自 /components/esp_dispatcher/include/esp_dispatcher.h

数据类型与结构体

// 调度器配置
typedef struct {int                         task_stack;             // >0 任务堆栈大小; =0 不创建任务int                         task_prio;              // 任务优先级(基于FreeRTOS优先级)int                         task_core;              // 任务运行的核心(0或1)bool                        stack_in_ext;           // 尝试在外部内存分配堆栈
} esp_dispatcher_config_t;// 调度器句柄
typedef struct esp_dispatcher *esp_dispatcher_handle_t;// 回调函数结果类型
typedef void (*func_ret_cb_t)(action_result_t ret, void *user_data);#define DEFAULT_ESP_DISPATCHER_STACK_SIZE      (4*1024)  // 默认堆栈大小
#define DEFAULT_ESP_DISPATCHER_TASK_PRIO       (10)      // 默认任务优先级
#define DEFAULT_ESP_DISPATCHER_TASK_CORE       (0)       // 默认运行核心// 调度器默认配置
#define ESP_DISPATCHER_CONFIG_DEFAULT() { \.task_stack = DEFAULT_ESP_DISPATCHER_STACK_SIZE, \.task_prio = DEFAULT_ESP_DISPATCHER_TASK_PRIO, \.task_core = DEFAULT_ESP_DISPATCHER_TASK_CORE, \.stack_in_ext = false, \
}

公开函数

esp_dispatcher_create

/*** @brief 创建ESP调度器实例** @param cfg 调度器实例的配置** @return*     - NULL，失败*     - 其他，成功*/
esp_dispatcher_handle_t esp_dispatcher_create(esp_dispatcher_config_t *cfg);

esp_dispatcher_destroy

/*** @brief 销毁ESP调度器实例** @param handle ESP调度器实例** @return*     - ESP_OK*     - ESP_ERR_INVALID_ARG*/
esp_err_t esp_dispatcher_destroy(esp_dispatcher_handle_t handle);

esp_dispatcher_reg_exe_func

/*** @brief 向ESP调度器实例注册事件索引和执行函数** @param handle          ESP调度器实例* @param exe_inst        执行实例* @param sub_event_index 事件索引* @param func            执行函数** @return*     - ESP_OK*     - ESP_ERR_ADF_ALREADY_EXISTS*     - ESP_ERR_INVALID_ARG*/
esp_err_t esp_dispatcher_reg_exe_func(esp_dispatcher_handle_t handle, void *exe_inst, int sub_event_index, esp_action_exe func);

esp_dispatcher_execute

/*** @brief 执行具有特定事件索引的函数。*        这是一个同步接口。** @param handle          ESP调度器实例* @param sub_event_index 事件索引* @param arg             执行函数的参数* @param result          执行函数的结果** @return*     - ESP_OK*     - ESP_ERR_INVALID_ARG*     - ESP_ERR_ADF_TIMEOUT, 发送请求命令超时*     - 其他，执行函数结果*/
esp_err_t esp_dispatcher_execute(esp_dispatcher_handle_t handle, int sub_event_index,action_arg_t *arg, action_result_t *result);

esp_dispatcher_execute_async

/*** @brief 执行具有特定事件索引的函数。*        这是一个异步接口。** @param handle          ESP调度器实例* @param sub_event_index 事件索引* @param arg             执行函数的参数* @param ret_cb          用于接收函数执行结果的回调* @param user_data       回调中使用的数据** @return*     - ESP_OK*     - ESP_ERR_INVALID_ARG*     - ESP_ERR_ADF_TIMEOUT, 发送请求命令超时*     - 其他，执行函数结果*/
esp_err_t esp_dispatcher_execute_async(esp_dispatcher_handle_t dh, int sub_event_index,action_arg_t *in_para, func_ret_cb_t ret_cb, void* user_data);

esp_dispatcher_execute_with_func

/*** @brief 执行具有特定事件索引的函数。*        这是一个同步接口。** @param handle          ESP调度器实例* @param sub_event_index 事件索引* @param arg             执行函数的参数* @param result          执行函数的结果** @return*     - ESP_OK*     - ESP_ERR_INVALID_ARG*     - ESP_ERR_ADF_TIMEOUT, 发送请求命令超时*     - 其他，执行函数结果*/
esp_err_t esp_dispatcher_execute_with_func(esp_dispatcher_handle_t handle, int sub_event_index,action_arg_t *arg, action_result_t *result);

esp_dispatcher_execute_with_func_async

/*** @brief 执行具有特定事件索引的函数。*        这是一个异步接口。** @param handle          ESP调度器实例* @param sub_event_index 事件索引* @param arg             执行函数的参数* @param ret_cb          用于接收函数执行结果的回调* @param user_data       回调中使用的数据** @return*     - ESP_OK*     - ESP_ERR_INVALID_ARG*     - ESP_ERR_ADF_TIMEOUT, 发送请求命令超时*     - 其他，执行函数结果*/
esp_err_t esp_dispatcher_execute_with_func_async(esp_dispatcher_handle_t dh, int sub_event_index,action_arg_t *in_para, func_ret_cb_t ret_cb, void* user_data);

接口总结

概述

ESP-ADF的dispatcher子模块提供了一套完整的事件调度接口，主要用于创建和管理调度器实例、注册事件处理函数、以及执行事件处理。这些接口设计遵循了以下原则：

1. 资源生命周期管理：通过create/destroy函数对调度器资源进行完整生命周期管理
2. 事件注册机制：提供注册函数将事件ID与处理函数关联
3. 同步/异步执行模式：支持阻塞式同步调用和基于回调的异步调用
4. 灵活的参数传递：通过通用参数结构支持不同类型的参数传递

函数分类

根据功能，dispatcher子模块的公开函数可以分为以下几类：

1. 资源管理函数

函数名	功能描述
esp_dispatcher_create	创建调度器实例，分配必要资源
esp_dispatcher_destroy	销毁调度器实例，释放所有资源

2. 事件注册函数

函数名	功能描述
esp_dispatcher_reg_exe_func	注册事件索引和对应的处理函数

3. 事件执行函数

函数名	执行方式	特点
esp_dispatcher_execute	同步	基本同步执行接口，阻塞等待结果
esp_dispatcher_execute_async	异步	基本异步执行接口，通过回调返回结果
esp_dispatcher_execute_with_func	同步	扩展同步执行接口，支持更多功能
esp_dispatcher_execute_with_func_async	异步	扩展异步执行接口，支持更多功能

通过这些接口，应用程序可以灵活地创建事件处理机制，实现复杂的事件驱动型应用。调度器的设计使得事件处理逻辑与业务逻辑分离，提高了代码的模块化程度和可维护性。