LibXR::Event Class Reference

事件管理系统，允许基于事件 ID 注册和触发回调函数。 Event management system that allows registration and triggering of callbacks based on event IDs. More...

#include <event.hpp>

Collaboration diagram for LibXR::Event:

Data Structures
struct	Block
	用于存储事件回调的数据结构。 Data structure for storing event callbacks. More...

Public Types
using	Callback = LibXR::Callback<uint32_t>
using	CallbackList = LockFreeList*
	回调链表指针类型，用于事件触发时从 ISR 中安全调用。 Pointer to the callback list, safe to use in ISR after acquired in non-interrupt context.

Public Member Functions
	Event ()
	构造函数，初始化用于存储事件的红黑树。 Constructs an Event object with an empty red-black tree for event storage.
void	Register (uint32_t event, const Callback &cb)
	为特定事件注册回调函数。 Registers a callback function for a specific event.
void	Active (uint32_t event)
	触发与特定事件关联的所有回调函数（非中断上下文）。 Triggers all callbacks associated with a specific event (non-interrupt context).
void	ActiveFromCallback (CallbackList list, uint32_t event, bool in_isr=true)
	从 callback-safe 路径触发与特定事件关联的所有回调函数。 Triggers all callbacks associated with a specific event from a callback-safe path.
CallbackList	GetList (uint32_t event)
	获取指定事件的回调链表指针（必须在非中断上下文中调用）。 Returns the callback list pointer for the given event (must be called outside ISR).
void	Bind (Event &sources, uint32_t source_event, uint32_t target_event)
	将源事件绑定到当前事件实例中的目标事件。 Binds an event from a source Event instance to a target event in the current instance.

Private Attributes
RBTree< uint32_t >	rbt_

Detailed Description

事件管理系统，允许基于事件 ID 注册和触发回调函数。 Event management system that allows registration and triggering of callbacks based on event IDs.

Definition at line 17 of file event.hpp.

Member Typedef Documentation

Callback

using LibXR::Event::Callback = LibXR::Callback<uint32_t>

Definition at line 20 of file event.hpp.

CallbackList

using LibXR::Event::CallbackList = LockFreeList*

回调链表指针类型，用于事件触发时从 ISR 中安全调用。 Pointer to the callback list, safe to use in ISR after acquired in non-interrupt context.

Definition at line 27 of file event.hpp.

Constructor & Destructor Documentation

Event()

Event::Event

(

)

构造函数，初始化用于存储事件的红黑树。 Constructs an Event object with an empty red-black tree for event storage.

Definition at line 25 of file event.cpp.

    : rbt_([](const uint32_t& a, const uint32_t& b) { return CompareEventId(a, b); })
{
}

Member Function Documentation

Active()

void Event::Active

(

uint32_t

event

)

触发与特定事件关联的所有回调函数（非中断上下文）。 Triggers all callbacks associated with a specific event (non-interrupt context).

Parameters

event

要激活的事件 ID。 The event ID to activate.

Definition at line 47 of file event.cpp.

{
  auto list = rbt_.Search<LockFreeList>(event);
  if (!list)
  {
    return;
  }
 
  auto foreach_fun = [=](Block& block)
  {
    block.cb.Run(false, event);
    return ErrorCode::OK;
  };
 
  list->data_.Foreach<LibXR::Event::Block>(foreach_fun);
}

ActiveFromCallback()

void Event::ActiveFromCallback	(	CallbackList	list,
		uint32_t	event,
		bool	in_isr = true )

从 callback-safe 路径触发与特定事件关联的所有回调函数。 Triggers all callbacks associated with a specific event from a callback-safe path.

Parameters

list	在非回调函数中获取的事件回调链表指针。 The event callback list pointer obtained from the non-callback function.
event	要激活的事件 ID。 The event ID to activate.
in_isr	当前 callback-safe 路径是否实际位于 ISR。 Whether the current callback-safe path is actually in ISR context.

Note

默认值为 true，用于兼容旧代码中“FromCallback 等价于 ISR=true”的调用习惯。 The default remains true for backward compatibility with older callers that treated FromCallback as ISR=true.

Definition at line 64 of file event.cpp.

{
  if (!list)
  {
    return;
  }
 
  auto foreach_fun = [=](Block& block)
  {
    block.cb.Run(in_isr, event);
    return ErrorCode::OK;
  };
 
  list->Foreach<Block>(foreach_fun);
}

Bind()

void Event::Bind	(	Event &	sources,
		uint32_t	source_event,
		uint32_t	target_event )

将源事件绑定到当前事件实例中的目标事件。 Binds an event from a source Event instance to a target event in the current instance.

Parameters

sources	包含原始事件的源 Event 实例。 The source Event instance.
source_event	源事件实例中的事件 ID。 The source event ID.
target_event	当前实例中的目标事件 ID。 The target event ID in this instance.

Note

包含动态内存分配。 Contains dynamic memory allocation.

当前实现会在绑定时预先拿到目标事件的回调链表指针，因此后续 callback-safe 触发路径不需要再为这个绑定做惰性查找或分配。 The current implementation acquires the target event's callback-list pointer during binding, so later callback-safe activation does not need an extra lazy lookup or allocation for this binding.

这依赖 GetList() 的稳定性约束：当前 Event 不支持删除或替换某个事件的回调 链表，因此绑定后缓存的目标链表指针会一直指向同一个链表，直到目标 Event 对象 自身结束生命周期。 This relies on GetList() stability: Event does not support removing or replacing one event's callback list, so the cached target-list pointer keeps referring to the same list until the target Event object itself reaches the end of its lifetime.

Definition at line 92 of file event.cpp.

{
  struct BindBlock
  {
    Event* target;
    Event::CallbackList list;
    uint32_t event;
  };
 
  auto block = new BindBlock{this, GetList(target_event), target_event};
 
  auto bind_fun = [](bool in_isr, BindBlock* block, uint32_t event)
  {
    UNUSED(event);
    block->target->ActiveFromCallback(block->list, block->event, in_isr);
  };
 
  auto cb = Callback::Create(bind_fun, block);
 
  sources.Register(source_event, cb);
}

GetList()

Event::CallbackList Event::GetList

(

uint32_t

event

)

获取指定事件的回调链表指针（必须在非中断上下文中调用）。 Returns the callback list pointer for the given event (must be called outside ISR).

Parameters

event

要查询的事件 ID。 The event ID to search.

Returns

回调链表指针，如果未注册则主动创建。 The callback list pointer, if not registered, it is actively created.

Note

当前 Event 只支持“查找或创建”回调链表，不提供删除或替换某个事件链表的接口； 因此在 Event 对象存活期间，这个函数返回的链表指针保持稳定。 The current Event API only supports finding or creating a callback list; it does not provide any way to remove or replace one event's list, so the returned pointer stays stable for the lifetime of the Event object.

Definition at line 80 of file event.cpp.

{
  auto node = rbt_.Search<LockFreeList>(event);
  if (!node)
  {
    auto list = new RBTree<uint32_t>::Node<LockFreeList>;
    rbt_.Insert(*list, event);
    node = list;
  }
  return &node->data_;
}

Register()

void Event::Register	(	uint32_t	event,
		const Callback &	cb )

为特定事件注册回调函数。 Registers a callback function for a specific event.

Parameters

event	要注册回调的事件 ID。 The event ID to register the callback for.
cb	事件触发时执行的回调函数。 The callback function to be executed when the event occurs.

Note

包含动态内存分配。 Contains dynamic memory allocation.

Definition at line 30 of file event.cpp.

{
  auto list = rbt_.Search<LockFreeList>(event);
 
  if (!list)
  {
    list = new RBTree<uint32_t>::Node<LockFreeList>;
    rbt_.Insert(*list, event);
  }
 
  LockFreeList::Node<Block>* node = new LockFreeList::Node<Block>;
 
  node->data_.event = event;
  node->data_.cb = cb;
  list->data_.Add(*node);
}

Field Documentation

rbt_

RBTree<uint32_t> LibXR::Event::rbt_

private

用于管理已注册事件的红黑树。 Red-black tree for managing registered events.

Definition at line 126 of file event.hpp.

---

The documentation for this class was generated from the following files:

• src/middleware/event.hpp
• src/middleware/event.cpp