mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Provide Chinese Translation for api-reference/system/esp_event.rst
This commit is contained in:
Cai Xin Ying
parent
8513ea2b22
commit
4df1319ecb
@ -1,14 +1,16 @@
|
||||
Event Loop Library
|
||||
==================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The event loop library allows components to declare events to which other components can register handlers -- code which will execute when those events occur. This allows loosely coupled components to attach desired behavior to state changes of other components without application involvement. This also simplifies event processing by serializing and deferring code execution to another context.
|
||||
The event loop library allows components to declare events so that other components can register handlers -- codes that will execute when those events occur. This allows loosely-coupled components to attach desired behavior to state changes of other components without application involvement. This also simplifies event processing by serializing and deferring code execution to another context.
|
||||
|
||||
.. only:: SOC_WIFI_SUPPORTED
|
||||
|
||||
One common use case is if a high level library is using the WiFi library: it may subscribe to :ref:`events produced by the Wi-Fi subsystem <wifi-programming-model>` directly and act on those events.
|
||||
One common case is, if a high-level library is using the Wi-Fi library: it may subscribe to :ref:`ESP32 Wi-Fi Programming Model <wifi-programming-model>` directly and act on those events.
|
||||
|
||||
.. only:: SOC_BT_SUPPORTED
|
||||
|
||||
@ -21,19 +23,16 @@ Using ``esp_event`` APIs
|
||||
|
||||
There are two objects of concern for users of this library: events and event loops.
|
||||
|
||||
Events are occurrences of note. For example, for Wi-Fi, a successful connection to the access point may be an event.
|
||||
Events are referenced using a two part identifier which are discussed more :ref:`here <esp-event-declaring-defining-events>`.
|
||||
Event loops are the vehicle by which events get posted by event sources and handled by event handler functions.
|
||||
These two appear prominently in the event loop library APIs.
|
||||
An event indicates an important occurrence, such as a successful Wi-Fi connection to an access point. A two-part identifier should be used when referencing events, see :ref:`declaring and defining events <esp-event-declaring-defining-events>` for details. The event loop is the bridge between events and event handlers. The event source publishes events to the event loop using the APIs provided by the event loop library, and event handlers registered to the event loop respond to specific types of events.
|
||||
|
||||
Using this library roughly entails the following flow:
|
||||
|
||||
1. A user defines a function that should run when an event is posted to a loop. This function is referred to as the event handler. It should have the same signature as :cpp:type:`esp_event_handler_t`.
|
||||
2. An event loop is created using :cpp:func:`esp_event_loop_create`, which outputs a handle to the loop of type :cpp:type:`esp_event_loop_handle_t`. Event loops created using this API are referred to as user event loops. There is, however, a special type of event loop called the default event loop which are discussed :ref:`here <esp-event-default-loops>`.
|
||||
3. Components register event handlers to the loop using :cpp:func:`esp_event_handler_register_with`. Handlers can be registered with multiple loops, more on that :ref:`here <esp-event-handler-registration>`.
|
||||
1. The user defines a function that should run when an event is posted to a loop. This function is referred to as the event handler, and should have the same signature as :cpp:type:`esp_event_handler_t`.
|
||||
2. An event loop is created using :cpp:func:`esp_event_loop_create`, which outputs a handle to the loop of type :cpp:type:`esp_event_loop_handle_t`. Event loops created using this API are referred to as user event loops. There is, however, a special type of event loop called the default event loop which is discussed in :ref:`default event loop <esp-event-default-loops>`.
|
||||
3. Components register event handlers to the loop using :cpp:func:`esp_event_handler_register_with`. Handlers can be registered with multiple loops, see :ref:`notes on handler registration <esp-event-handler-registration>`.
|
||||
4. Event sources post an event to the loop using :cpp:func:`esp_event_post_to`.
|
||||
5. Components wanting to remove their handlers from being called can do so by unregistering from the loop using :cpp:func:`esp_event_handler_unregister_with`.
|
||||
6. Event loops which are no longer needed can be deleted using :cpp:func:`esp_event_loop_delete`.
|
||||
6. Event loops that are no longer needed can be deleted using :cpp:func:`esp_event_loop_delete`.
|
||||
|
||||
In code, the flow above may look like as follows:
|
||||
|
||||
@ -47,9 +46,7 @@ In code, the flow above may look like as follows:
|
||||
|
||||
void app_main()
|
||||
{
|
||||
// 2. A configuration structure of type esp_event_loop_args_t is needed to specify the properties of the loop to be
|
||||
// created. A handle of type esp_event_loop_handle_t is obtained, which is needed by the other APIs to reference the loop
|
||||
// to perform their operations on.
|
||||
// 2. A configuration structure of type esp_event_loop_args_t is needed to specify the properties of the loop to be created. A handle of type esp_event_loop_handle_t is obtained, which is needed by the other APIs to reference the loop to perform their operations.
|
||||
esp_event_loop_args_t loop_args = {
|
||||
.queue_size = ...,
|
||||
.task_name = ...
|
||||
@ -62,16 +59,12 @@ In code, the flow above may look like as follows:
|
||||
|
||||
esp_event_loop_create(&loop_args, &loop_handle);
|
||||
|
||||
// 3. Register event handler defined in (1). MY_EVENT_BASE and MY_EVENT_ID specifies a hypothetical
|
||||
// event that handler run_on_event should execute on when it gets posted to the loop.
|
||||
// 3. Register event handler defined in (1). MY_EVENT_BASE and MY_EVENT_ID specify a hypothetical event that handler run_on_event should execute when it gets posted to the loop.
|
||||
esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_on_event, ...);
|
||||
|
||||
...
|
||||
|
||||
// 4. Post events to the loop. This queues the event on the event loop. At some point in time
|
||||
// the event loop executes the event handler registered to the posted event, in this case run_on_event.
|
||||
// For simplicity sake this example calls esp_event_post_to from app_main, but posting can be done from
|
||||
// any other tasks (which is the more interesting use case).
|
||||
// 4. Post events to the loop. This queues the event on the event loop. At some point, the event loop executes the event handler registered to the posted event, in this case, run_on_event. To simplify the process, this example calls esp_event_post_to from app_main, but posting can be done from any other task (which is the more interesting use case).
|
||||
esp_event_post_to(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, ...);
|
||||
|
||||
...
|
||||
@ -87,12 +80,10 @@ In code, the flow above may look like as follows:
|
||||
|
||||
.. _esp-event-declaring-defining-events:
|
||||
|
||||
Declaring and defining events
|
||||
Declaring and Defining Events
|
||||
-----------------------------
|
||||
|
||||
As mentioned previously, events consists of two-part identifiers: the event base and the event ID. The event base identifies an independent group
|
||||
of events; the event ID identifies the event within that group. Think of the event base and event ID as a
|
||||
person's last name and first name, respectively. A last name identifies a family, and the first name identifies a person within that family.
|
||||
As mentioned previously, events consist of two-part identifiers: the event base and the event ID. The event base identifies an independent group of events; the event ID identifies the event within that group. Think of the event base and event ID as a person's last name and first name, respectively. A last name identifies a family, and the first name identifies a person within that family.
|
||||
|
||||
The event loop library provides macros to declare and define the event base easily.
|
||||
|
||||
@ -110,11 +101,9 @@ Event base definition:
|
||||
|
||||
.. note::
|
||||
|
||||
In IDF, the base identifiers for system events are uppercase and are postfixed with ``_EVENT``. For example, the base for Wi-Fi events is declared and defined
|
||||
as ``WIFI_EVENT``, the Ethernet event base ``ETHERNET_EVENT``, and so on. The purpose is to have event bases look like constants (although
|
||||
they are global variables considering the definitions of macros ``ESP_EVENT_DECLARE_BASE`` and ``ESP_EVENT_DEFINE_BASE``).
|
||||
In ESP-IDF, the base identifiers for system events are uppercase and are postfixed with ``_EVENT``. For example, the base for Wi-Fi events is declared and defined as ``WIFI_EVENT``, the Ethernet event base ``ETHERNET_EVENT``, and so on. The purpose is to have event bases look like constants (although they are global variables considering the definitions of macros ``ESP_EVENT_DECLARE_BASE`` and ``ESP_EVENT_DEFINE_BASE``).
|
||||
|
||||
For event ID's, declaring them as enumerations is recommended. Once again, for visibility, these are typically placed in public header files.
|
||||
For event IDs, declaring them as enumerations is recommended. Once again, for visibility, these are typically placed in public header files.
|
||||
|
||||
Event ID:
|
||||
|
||||
@ -132,44 +121,43 @@ Event ID:
|
||||
Default Event Loop
|
||||
------------------
|
||||
|
||||
The default event loop is a special type of loop used for system events (Wi-Fi events, for example). The handle for this
|
||||
loop is hidden from the user. The creation, deletion, handler registration/unregistration and posting of events is done
|
||||
through a variant of the APIs for user event loops. The table below enumerates those variants, and the user event
|
||||
loops equivalent.
|
||||
The default event loop is a special type of loop used for system events (Wi-Fi events, for example). The handle for this loop is hidden from the user, and the creation, deletion, handler registration/deregistration, and posting of events are done through a variant of the APIs for user event loops. The table below enumerates those variants, and the user event loops equivalent.
|
||||
|
||||
+---------------------------------------------------+---------------------------------------------------+
|
||||
| User Event Loops | Default Event Loops |
|
||||
+===================================================+===================================================+
|
||||
| :cpp:func:`esp_event_loop_create` | :cpp:func:`esp_event_loop_create_default` |
|
||||
+---------------------------------------------------+---------------------------------------------------+
|
||||
| :cpp:func:`esp_event_loop_delete` | :cpp:func:`esp_event_loop_delete_default` |
|
||||
+---------------------------------------------------+---------------------------------------------------+
|
||||
| :cpp:func:`esp_event_handler_register_with` | :cpp:func:`esp_event_handler_register` |
|
||||
+---------------------------------------------------+---------------------------------------------------+
|
||||
| :cpp:func:`esp_event_handler_unregister_with` | :cpp:func:`esp_event_handler_unregister` |
|
||||
+---------------------------------------------------+---------------------------------------------------+
|
||||
| :cpp:func:`esp_event_post_to` | :cpp:func:`esp_event_post` |
|
||||
+---------------------------------------------------+---------------------------------------------------+
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 60 60
|
||||
:align: center
|
||||
|
||||
If you compare the signatures for both, they are mostly similar except the for the lack of loop handle
|
||||
specification for the default event loop APIs.
|
||||
* - User Event Loops
|
||||
- Default Event Loops
|
||||
* - :cpp:func:`esp_event_loop_create`
|
||||
- :cpp:func:`esp_event_loop_create_default`
|
||||
* - :cpp:func:`esp_event_loop_delete`
|
||||
- :cpp:func:`esp_event_loop_delete_default`
|
||||
* - :cpp:func:`esp_event_handler_register_with`
|
||||
- :cpp:func:`esp_event_handler_register`
|
||||
* - :cpp:func:`esp_event_handler_unregister_with`
|
||||
- :cpp:func:`esp_event_handler_unregister`
|
||||
* - :cpp:func:`esp_event_post_to`
|
||||
- :cpp:func:`esp_event_post`
|
||||
|
||||
Other than the API difference and the special designation to which system events are posted to, there is no difference
|
||||
to how default event loops and user event loops behave. It is even possible for users to post their own events
|
||||
to the default event loop, should the user opt to not create their own loops to save memory.
|
||||
If you compare the signatures for both, they are mostly similar except for the lack of loop handle specification for the default event loop APIs.
|
||||
|
||||
Other than the API difference and the special designation to which system events are posted, there is no difference in how default event loops and user event loops behave. It is even possible for users to post their own events to the default event loop, should the user opt to not create their own loops to save memory.
|
||||
|
||||
.. _esp-event-handler-registration:
|
||||
|
||||
Notes on Handler Registration
|
||||
-----------------------------
|
||||
|
||||
It is possible to register a single handler to multiple events individually, i.e. using multiple calls to :cpp:func:`esp_event_handler_register_with`.
|
||||
For those multiple calls, the specific event base and event ID can be specified with which the handler should execute.
|
||||
It is possible to register a single handler to multiple events individually by using multiple calls to :cpp:func:`esp_event_handler_register_with`. For those multiple calls, the specific event base and event ID can be specified with which the handler should execute.
|
||||
|
||||
However, in some cases it is desirable for a handler to execute on (1) all events that get posted to a loop or (2) all events
|
||||
of a particular base identifier. This is possible using the special event base identifier ``ESP_EVENT_ANY_BASE`` and
|
||||
special event ID ``ESP_EVENT_ANY_ID``. These special identifiers may be passed as the event base and event ID arguments
|
||||
for :cpp:func:`esp_event_handler_register_with`.
|
||||
However, in some cases, it is desirable for a handler to execute on the following situations:
|
||||
|
||||
(1) all events that get posted to a loop
|
||||
(2) all events of a particular base identifier
|
||||
|
||||
This is possible using the special event base identifier ``ESP_EVENT_ANY_BASE`` and special event ID ``ESP_EVENT_ANY_ID``. These special identifiers may be passed as the event base and event ID arguments for :cpp:func:`esp_event_handler_register_with`.
|
||||
|
||||
Therefore, the valid arguments to :cpp:func:`esp_event_handler_register_with` are:
|
||||
|
||||
@ -185,14 +173,13 @@ As an example, suppose the following handler registrations were performed:
|
||||
esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, ESP_EVENT_ANY_ID, run_on_event_2, ...);
|
||||
esp_event_handler_register_with(loop_handle, ESP_EVENT_ANY_BASE, ESP_EVENT_ANY_ID, run_on_event_3, ...);
|
||||
|
||||
If the hypothetical event ``MY_EVENT_BASE``, ``MY_EVENT_ID`` is posted, all three handlers ``run_on_event_1``, ``run_on_event_2``,
|
||||
and ``run_on_event_3`` would execute.
|
||||
If the hypothetical event ``MY_EVENT_BASE``, ``MY_EVENT_ID`` is posted, all three handlers ``run_on_event_1``, ``run_on_event_2``, and ``run_on_event_3`` would execute.
|
||||
|
||||
If the hypothetical event ``MY_EVENT_BASE``, ``MY_OTHER_EVENT_ID`` is posted, only ``run_on_event_2`` and ``run_on_event_3`` would execute.
|
||||
|
||||
If the hypothetical event ``MY_OTHER_EVENT_BASE``, ``MY_OTHER_EVENT_ID`` is posted, only ``run_on_event_3`` would execute.
|
||||
|
||||
Handler Un-registering Itself
|
||||
Handler Un-Registering Itself
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In general, an event handler run by an event loop is *not allowed to do any (un)registering activity on that event loop*. There is one exception, though: un-registering itself is allowed for the handler. E.g., it is possible to do the following:
|
||||
@ -210,34 +197,27 @@ In general, an event handler run by an event loop is *not allowed to do any (un)
|
||||
esp_event_loop_handle_t loop_handle;
|
||||
esp_event_loop_create(&loop_args, &loop_handle);
|
||||
esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_on_event, &loop_handle);
|
||||
// ... post event MY_EVENT_BASE, MY_EVENT_ID and run loop at some point
|
||||
// ... post-event MY_EVENT_BASE, MY_EVENT_ID and run loop at some point
|
||||
}
|
||||
|
||||
|
||||
Handler Registration and Handler Dispatch Order
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The general rule is that for handlers that match a certain posted event during dispatch, those which are registered first also gets executed first. The user can then control which handlers get executed first by
|
||||
registering them before other handlers, provided that all registrations are performed using a single task.
|
||||
If the user plans to take advantage of this behavior, caution must be exercised if there are multiple tasks registering handlers. While the 'first registered, first executed'
|
||||
behavior still holds true, the task which gets executed first will also get their handlers registered first. Handlers registered one after the other by a single task
|
||||
will still be dispatched in the order relative to each other, but if that task gets pre-empted in between registration by another task which also registers handlers; then during dispatch those
|
||||
handlers will also get executed in between.
|
||||
The general rule is that, for handlers that match a certain posted event during dispatch, those which are registered first also get executed first. The user can then control which handlers get executed first by registering them before other handlers, provided that all registrations are performed using a single task. If the user plans to take advantage of this behavior, caution must be exercised if there are multiple tasks registering handlers. While the 'first registered, first executed' behavior still holds true, the task which gets executed first will also get its handlers registered first. Handlers registered one after the other by a single task will still be dispatched in the order relative to each other, but if that task gets pre-empted in between registration by another task that also registers handlers; then during dispatch those handlers will also get executed in between.
|
||||
|
||||
|
||||
Event loop profiling
|
||||
Event Loop Profiling
|
||||
--------------------
|
||||
|
||||
A configuration option :ref:`CONFIG_ESP_EVENT_LOOP_PROFILING` can be enabled in order to activate statistics collection for all event loops created.
|
||||
The function :cpp:func:`esp_event_dump` can be used to output the collected statistics to a file stream. More details on the information included in the dump
|
||||
can be found in the :cpp:func:`esp_event_dump` API Reference.
|
||||
A configuration option :ref:`CONFIG_ESP_EVENT_LOOP_PROFILING` can be enabled in order to activate statistics collection for all event loops created. The function :cpp:func:`esp_event_dump` can be used to output the collected statistics to a file stream. More details on the information included in the dump can be found in the :cpp:func:`esp_event_dump` API Reference.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
Examples on using the ``esp_event`` library can be found in :example:`system/esp_event`. The examples cover event declaration, loop creation, handler registration and unregistration and event posting.
|
||||
Examples of using the ``esp_event`` library can be found in :example:`system/esp_event`. The examples cover event declaration, loop creation, handler registration and deregistration, and event posting.
|
||||
|
||||
Other examples which also adopt esp_event library:
|
||||
Other examples which also adopt ``esp_event`` library:
|
||||
|
||||
* :example:`NMEA Parser <peripherals/uart/nmea0183_parser>`, which will decode the statements received from GPS.
|
||||
|
||||
|
||||
@ -1 +1,234 @@
|
||||
.. include:: ../../../en/api-reference/system/esp_event.rst
|
||||
事件循环库
|
||||
==================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
概述
|
||||
--------
|
||||
|
||||
事件循环库使组件能够声明事件，允许其他组件注册处理程序（即在事件发生时执行的代码片段）。此时，无需直接涉及应用程序，松散耦合组件也能够在其他组件状态变化时附加所需的行为。此外，通过将代码执行序列化，在指定的任务中运行事件循环库，可以简化事件处理程序，实现更高效的事件处理。
|
||||
|
||||
.. only:: SOC_WIFI_SUPPORTED
|
||||
|
||||
例如，当某个高级库要使用 Wi-Fi 库时，它可以直接订阅 :ref:`ESP32 Wi-Fi 编程模型 <wifi-programming-model>`，对有关事件做出相应。
|
||||
|
||||
.. only:: SOC_BT_SUPPORTED
|
||||
|
||||
.. note::
|
||||
|
||||
蓝牙栈各模块通过调用专用回调函数向应用程序传递事件，而非通过事件循环库传递。
|
||||
|
||||
调用 ``esp_event`` API
|
||||
-----------------------------
|
||||
|
||||
使用事件循环库时应注意区分“事件”与“事件循环”。
|
||||
|
||||
事件表示重要的发生事件，如 Wi-Fi 成功连接到接入点。引用事件时应使用由两部分组成的标识符，详情请参阅 :ref:`事件定义与事件声明 <esp-event-declaring-defining-events>`。事件循环是连接事件和事件处理程序之间的桥梁，事件源通过使用事件循环库提供的 API 将事件发布到事件循环中，注册到事件循环中的事件处理程序会响应特定类型的事件。
|
||||
|
||||
以下为事件循环库的使用流程：
|
||||
|
||||
1. 定义一个函数，并在事件发布到事件循环中时运行该函数。此函数被称为事件处理程序，应具有与 :cpp:type:`esp_event_handler_t` 同类型的签名。
|
||||
2. 调用 :cpp:func:`esp_event_loop_create` 创建事件循环，该函数输出类型为 :cpp:type:`esp_event_loop_handle_t` 的循环句柄，使用此 API 创建的事件循环称为用户事件循环。另有一种特殊事件循环，请参阅 :ref:`默认事件循环 <esp-event-default-loops>`。
|
||||
3. 调用 :cpp:func:`esp_event_handler_register_with` 将事件处理程序注册到循环中。处理程序可以注册到多个循环中，请参阅 :ref:`注册处理程序注意事项 <esp-event-handler-registration>`。
|
||||
4. 事件源调用 :cpp:func:`esp_event_post_to` 将事件发布到事件循环中。
|
||||
5. 调用 :cpp:func:`esp_event_handler_unregister_with` ，组件可以在事件循环中取消注册事件处理程序。
|
||||
6. 调用 :cpp:func:`esp_event_loop_delete` 删除不再需要的事件循环。
|
||||
|
||||
上述流程代码如下：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
// 1. 定义事件处理程序
|
||||
void run_on_event(void* handler_arg, esp_event_base_t base, int32_t id, void* event_data)
|
||||
{
|
||||
// 事件处理程序逻辑
|
||||
}
|
||||
|
||||
void app_main()
|
||||
{
|
||||
// 2. 用一个类型为 esp_event_loop_args_t 的配置结构体，指定所创建循环的属性。获取一个类型为 esp_event_loop_handle_t 的句柄，用于其他 API 引用循环、执行操作。
|
||||
esp_event_loop_args_t loop_args = {
|
||||
.queue_size = ...,
|
||||
.task_name = ...
|
||||
.task_priority = ...,
|
||||
.task_stack_size = ...,
|
||||
.task_core_id = ...
|
||||
};
|
||||
|
||||
esp_event_loop_handle_t loop_handle;
|
||||
|
||||
esp_event_loop_create(&loop_args, &loop_handle);
|
||||
|
||||
// 3. 注册在 (1) 中定义的事件处理程序。MY_EVENT_BASE 和 MY_EVENT_ID 指定了一个假设事件：将处理程序 run_on_event 发布到循环中时，执行该处理程序。
|
||||
esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_on_event, ...);
|
||||
|
||||
...
|
||||
|
||||
// 4. 将事件发布到循环中。此时，事件排入事件循环队列，在某个时刻，事件循环会执行已注册到发布事件的事件处理程序，例如此处的 run_on_event。为简化过程，此示例从 app_main 调用 esp_event_post_to，实际应用中可从任何其他任务中发布事件。
|
||||
esp_event_post_to(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, ...);
|
||||
|
||||
...
|
||||
|
||||
// 5. 注销无用的处理程序。
|
||||
esp_event_handler_unregister_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_on_event);
|
||||
|
||||
...
|
||||
|
||||
// 6. 删除无用的事件循环。
|
||||
esp_event_loop_delete(loop_handle);
|
||||
}
|
||||
|
||||
.. _esp-event-declaring-defining-events:
|
||||
|
||||
事件定义与事件声明
|
||||
-----------------------------
|
||||
|
||||
如前所述，事件标识符由两部分组成：事件根基和事件 ID。事件根基标识独立的事件组；事件 ID 标识组中的特定事件。可以将事件根基和事件 ID 类比为人的姓和名，姓表示一个家族，名表示家族中的某个人。
|
||||
|
||||
事件循环库提供了宏以便声明和定义事件根基。
|
||||
|
||||
声明事件根基：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
ESP_EVENT_DECLARE_BASE(EVENT_BASE)
|
||||
|
||||
定义事件根基：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
ESP_EVENT_DEFINE_BASE(EVENT_BASE)
|
||||
|
||||
.. note::
|
||||
|
||||
在 ESP-IDF 中，系统事件的根基标识符为大写字母，并以 ``_EVENT`` 结尾。例如，Wi-Fi 事件的根基声明为 ``WIFI_EVENT``，以太网的事件根基声明为 ``ETHERNET_EVENT`` 等。这样一来，事件根基与常量类似（尽管根据宏 ``ESP_EVENT_DECLARE_BASE`` 和 ``ESP_EVENT_DEFINE_BASE`` 的定义，它们属于全局变量）。
|
||||
|
||||
建议以枚举类型声明事件 ID，它们通常放在公共头文件中。
|
||||
|
||||
事件 ID：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
enum {
|
||||
EVENT_ID_1,
|
||||
EVENT_ID_2,
|
||||
EVENT_ID_3,
|
||||
...
|
||||
}
|
||||
|
||||
.. _esp-event-default-loops:
|
||||
|
||||
默认事件循环
|
||||
------------------
|
||||
|
||||
默认事件循环是一种特殊循环，用于处理系统事件（如 Wi-Fi 事件）。用户无法使用该循环的句柄，创建、删除、注册/注销处理程序以及事件发布均通过用户事件循环 API 的变体完成，下表列出了这些变体及其对应用户事件循环。
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 60 60
|
||||
:align: center
|
||||
|
||||
* - 用户事件循环
|
||||
- 默认事件循环
|
||||
* - :cpp:func:`esp_event_loop_create`
|
||||
- :cpp:func:`esp_event_loop_create_default`
|
||||
* - :cpp:func:`esp_event_loop_delete`
|
||||
- :cpp:func:`esp_event_loop_delete_default`
|
||||
* - :cpp:func:`esp_event_handler_register_with`
|
||||
- :cpp:func:`esp_event_handler_register`
|
||||
* - :cpp:func:`esp_event_handler_unregister_with`
|
||||
- :cpp:func:`esp_event_handler_unregister`
|
||||
* - :cpp:func:`esp_event_post_to`
|
||||
- :cpp:func:`esp_event_post`
|
||||
|
||||
比较二者签名可知，它们大部分是相似的，唯一区别在于默认事件循环的 API 不需要指定循环句柄。
|
||||
|
||||
除了 API 的差异和用于系统事件的特殊分类外，默认事件循环和用户事件循环的行为并无差异。实际上，用户甚至可以将自己的事件发布到默认事件循环中，以节省内存而无需创建自己的循环。
|
||||
|
||||
.. _esp-event-handler-registration:
|
||||
|
||||
注册处理程序注意事项
|
||||
----------------------------------
|
||||
|
||||
通过重复调用 :cpp:func:`esp_event_handler_register_with`，可以将单个处理程序独立注册到多个事件中，且每次调用均可指定处理程序应执行的具体事件根基和事件 ID。
|
||||
|
||||
然而，在某些情况下，您可能希望处理程序在以下情况时执行：
|
||||
|
||||
(1) 所有发布到循环的事件
|
||||
(2) 特定基本标识符的所有事件
|
||||
|
||||
为此，可调用特殊的事件根基标识符 ``ESP_EVENT_ANY_BASE`` 和特殊的事件 ``ESP_EVENT_ANY_ID`` 实现，这些特殊标识符可以作为 :cpp:func:`esp_event_handler_register_with` 的事件根基和事件 ID 参数传递。
|
||||
|
||||
因此 :cpp:func:`esp_event_handler_register_with` 的有效参数为：
|
||||
|
||||
1. <event base>, <event ID> - 根基为 <event base> 且 ID 为 <event ID> 的事件发布到循环中时，执行处理程序。
|
||||
2. <event base>, ESP_EVENT_ANY_ID - 任何根基为 <event base> 的事件发布到循环中时，执行处理程序。
|
||||
3. ESP_EVENT_ANY_BASE, ESP_EVENT_ANY_ID - 任何事件发布到循环中时，执行处理程序。
|
||||
|
||||
例如，如果注册了以下处理程序：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_on_event_1, ...);
|
||||
esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, ESP_EVENT_ANY_ID, run_on_event_2, ...);
|
||||
esp_event_handler_register_with(loop_handle, ESP_EVENT_ANY_BASE, ESP_EVENT_ANY_ID, run_on_event_3, ...);
|
||||
|
||||
如果假设事件由 ``MY_EVENT_BASE`` 和 ``MY_EVENT_ID`` 组成，则三个处理程序 ``run_on_event_1``、 ``run_on_event_2`` 和 ``run_on_event_3`` 都会执行。
|
||||
|
||||
如果假设事件由 ``MY_EVENT_BASE`` 和 ``MY_OTHER_EVENT_ID`` 组成，则仅执行处理程序 ``run_on_event_2`` 和 ``run_on_event_3``。
|
||||
|
||||
如果假设事件由 ``MY_OTHER_EVENT_BASE`` 和 ``MY_OTHER_EVENT_ID`` 组成，则仅执行处理程序 ``run_on_event_3``。
|
||||
|
||||
处理程序自行注销
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
通常情况下，由事件循环运行的事件处理程序 *不允许在该事件循环上执行任何注册/注销活动* ，但允许处理程序自行注销。例如，可以执行以下操作：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
void run_on_event(void* handler_arg, esp_event_base_t base, int32_t id, void* event_data)
|
||||
{
|
||||
esp_event_loop_handle_t *loop_handle = (esp_event_loop_handle_t*) handler_arg;
|
||||
esp_event_handler_unregister_with(*loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_on_event);
|
||||
}
|
||||
|
||||
void app_main(void)
|
||||
{
|
||||
esp_event_loop_handle_t loop_handle;
|
||||
esp_event_loop_create(&loop_args, &loop_handle);
|
||||
esp_event_handler_register_with(loop_handle, MY_EVENT_BASE, MY_EVENT_ID, run_on_event, &loop_handle);
|
||||
// ... 发布事件 MY_EVENT_BASE 和 MY_EVENT_ID，并在某些时候运行循环
|
||||
}
|
||||
|
||||
|
||||
注册处理程序及处理程序调度顺序
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
一般而言，对于在调度期间与某个已发布事件匹配的处理程序，先注册的也会先执行。在所有注册均使用单个任务执行的情况下，可以通过在其他处理程序注册前注册目标处理程序，控制处理程序的执行顺序。如果计划利用这一规则，在有多个任务注册处理程序的情况下要多加小心。此时，虽然“先注册，先执行”的规则仍然成立，但率先执行的任务也会率先注册其处理程序，而由单个任务连续注册的处理函数仍然按相对顺序调度。但如果该任务在注册期间被另一个任务抢占，而该任务还注册了处理程序，则在调度期间，那些处理程序也将在处理其他任务时执行。
|
||||
|
||||
|
||||
事件循环性能分析
|
||||
--------------------
|
||||
|
||||
要启动数据收集，统计所有已创建事件循环的数据，请激活配置选项 :ref:`CONFIG_ESP_EVENT_LOOP_PROFILING`，函数 :cpp:func:`esp_event_dump` 可将收集的统计数据输出到文件流中。有关转储信息的更多详情，请参阅 :cpp:func:`esp_event_dump` API 参考。
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
使用 ``esp_event`` 库的示例存放在 :example:`system/esp_event` 中，涵盖事件声明、循环创建、处理程序注册和注销以及事件发布。
|
||||
|
||||
其他使用 ``esp_event`` 库的示例:
|
||||
|
||||
* :example:`NMEA Parser <peripherals/uart/nmea0183_parser>`，该示例将解码从 GPS 接收到的语句。
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_event.inc
|
||||
.. include-build-file:: inc/esp_event_base.inc
|
||||
|
||||
相关文档
|
||||
-----------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Loading…
Reference in New Issue
Block a user