xt_event（事件管理）

事件发布订阅模块接口（去重匹配、dispatch 上下文栈、临界区保护） 更多...

宏定义
#define	XT_EVENT_INVALID_ID   0
	无效事件 ID，兼作空闲槽位标记
#define	xt_event_get_current()
	兼容旧版 API 名称
#define	xt_event_current_get_param()
	兼容旧版 API 名称

类型定义
typedef uint32_t	xt_event_id_t
	事件 ID 类型，32 位无符号
typedef void(*	xt_event_cb_t) (void *param, void *user_data)
	事件回调函数类型

函数
xt_err_t	xt_event_setup (void)
	初始化事件系统
xt_err_t	xt_event_subscribe (xt_event_id_t event_id, xt_event_cb_t event_cb, void *user_data)
	订阅事件（去重匹配）
xt_err_t	xt_event_unsubscribe (xt_event_id_t event_id, xt_event_cb_t event_cb)
	取消订阅（匹配清除）
xt_err_t	xt_event_publish (xt_event_id_t event_id, void *param)
	发布事件到队列（异步）
xt_err_t	xt_event_publish_sync (xt_event_id_t event_id, void *param)
	同步发布事件（立即分发）
xt_event_id_t	xt_event_get_current_event_id (void)
	获取当前正在处理的事件 ID
void *	xt_event_get_current_event_param (void)
	获取当前事件参数
bool	xt_event_ready (void)
	查询事件队列是否非空
xt_err_t	xt_event_handler (void)
	处理事件队列中的所有事件

详细描述

事件发布订阅模块接口（去重匹配、dispatch 上下文栈、临界区保护）

宏定义说明

xt_event_current_get_param

#define xt_event_current_get_param

(

)

值:

xt_event_get_current_event_param()

兼容旧版 API 名称

在文件 xt_event.h 第 176 行定义.

xt_event_get_current

#define xt_event_get_current

(

)

值:

xt_event_get_current_event_id()

兼容旧版 API 名称

在文件 xt_event.h 第 174 行定义.

XT_EVENT_INVALID_ID

#define XT_EVENT_INVALID_ID   0

无效事件 ID，兼作空闲槽位标记

在文件 xt_event.h 第 37 行定义.

类型定义说明

xt_event_cb_t

typedef void(* xt_event_cb_t) (void *param, void *user_data)

事件回调函数类型

参数

param	事件参数，由 publish / publish_sync 传入
user_data	用户透传数据，subscribe 时设置

在文件 xt_event.h 第 50 行定义.

xt_event_id_t

typedef uint32_t xt_event_id_t

事件 ID 类型，32 位无符号

在文件 xt_event.h 第 42 行定义.

函数说明

xt_event_get_current_event_id()

xt_event_id_t xt_event_get_current_event_id

(

void

)

获取当前正在处理的事件 ID

仅在 xt_event_handler 分发期间有效，非回调中返回 XT_EVENT_INVALID_ID。

返回

当前事件 ID，无当前事件时返回 XT_EVENT_INVALID_ID

xt_event_get_current_event_param()

void * xt_event_get_current_event_param

(

void

)

获取当前事件参数

仅在 xt_event_handler 分发期间有效。无当前事件时触发 assert。

返回

当前事件的参数指针

xt_event_handler()

xt_err_t xt_event_handler

(

void

)

处理事件队列中的所有事件

对事件队列做快照后逐个事件分发。回调中 publish 的新事件留在队列中， 下次 handler 才处理。每个事件分发前同时调用 xt_task_event_handler 唤醒等待该事件的 task。

返回

XT_EOK 成功

xt_event_publish()

xt_err_t xt_event_publish	(	xt_event_id_t	event_id,
		void *	param )

发布事件到队列（异步）

将事件放入事件队列尾部，不立即分发。 由 xt_event_handler() 在后续时刻处理。

参数

event_id	事件 ID
param	事件参数，传给订阅者的回调

返回

XT_EOK 成功

XT_ENOMEM 事件队列满（同时触发 assert）

xt_event_publish_sync()

xt_err_t xt_event_publish_sync	(	xt_event_id_t	event_id,
		void *	param )

同步发布事件（立即分发）

遍历订阅者数组，立即调用所有匹配 event_id 的订阅者回调。 使用 dispatch 上下文栈，嵌套最多 XT_EVENT_DISPATCH_MAX_NESTING 层（默认 5）。 回调中可自由调用 subscribe / unsubscribe / publish_sync / publish。

参数

event_id	事件 ID
param	事件参数，传给订阅者的回调

返回

XT_EOK 成功

XT_EBUSY 嵌套深度超限（同时触发 assert）

xt_event_ready()

bool xt_event_ready

(

void

)

查询事件队列是否非空

遍历事件队列，检查是否有待处理的事件。 返回值为瞬时快照，调用后状态可能立即改变。

返回

true 队列非空，需调用 xt_event_handler

false 队列为空

xt_event_setup()

xt_err_t xt_event_setup

(

void

)

初始化事件系统

清零事件队列和订阅者数组，重置 dispatch 嵌套深度。 若定义了 XT_EVENT_OSAFFINITY_ENABLE，同时记录当前线程 ID 用于后续亲和性检查。

返回

XT_EOK 成功

xt_event_subscribe()

xt_err_t xt_event_subscribe	(	xt_event_id_t	event_id,
		xt_event_cb_t	event_cb,
		void *	user_data )

订阅事件（去重匹配）

按 (event_id, event_cb) 两元组去重。若已存在相同组合，仅更新 user_data； 若不存在，申请新槽位并填充。

subscribe 在回调中调用时，新订阅者不在当前轮次 dispatch 中被调（快照已固定）， 下次 publish_sync / handler 才生效。

参数

event_id	事件 ID
event_cb	回调函数，与 event_id 共同构成去重键
user_data	用户透传数据，回调时传给 event_cb

返回

XT_EOK 成功

XT_ENOMEM 订阅者数组满（同时触发 assert）

xt_event_unsubscribe()

xt_err_t xt_event_unsubscribe	(	xt_event_id_t	event_id,
		xt_event_cb_t	event_cb )

取消订阅（匹配清除）

按 (event_id, event_cb) 两元组查找并清除匹配的槽位。 若在 dispatch 过程中被调用，同时清除所有活跃帧中该槽位的位图 bit， 确保后续 pass 2 遍历不会错误调起该槽位的新订阅者。

参数

event_id	事件 ID
event_cb	回调函数

返回

XT_EOK 成功

XT_EEMPTY 不存在匹配的订阅者